NVIDIA DRIVE 5.0 Linux SDK API Reference

5.0.5.0 Release

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Direct Rendering Manager

Detailed Description

DRM-NVDC is a compatibility library which implements the Direct Rendering Manager API (DRM) on top of the Tegra Display Controller kernel driver (NVDC).

It replaces the Mesa DRM wrapper library libdrm.so.2 on NVIDIA DRIVE™ platforms. It is a special purpose library designed to provide Tegra support for EGLOutput-DRM extensions.

The functions implemented in DRM-NVDC are binary compatible with Mesa's libdrm, with some limitations that are documented here. Unsupported functions are implemented as no-ops. Unsupported parameters of supported functions are ignored.

Like Mesa DRM, DRM-NVDC can be used to query display resources, allocate simple non-accelerated "dumb" buffer objects, set display modes, and control display overlay planes.

DRM-NVDC only supports display control, not GPU command queues. Its primary purpose is to enumerate display resources, and to perform setup for those display resources, for example, setting display modes and overlay positions.

Functions

int drmOpen (const char *name, const char *busid)
 Opens a DRM device and creates a file descriptor handle. More...
 
int drmClose (int fd)
 Closes a DRM device. More...
 
int drmGetCap (int fd, uint64_t capability, uint64_t *value)
 Gets capabilities of the DRM driver. More...
 
int drmSetClientCap (int fd, uint64_t capability, uint64_t value)
 Enables or disables DRM features (capabilities). More...
 
int drmSetMaster (int fd)
 Requests master controls for a DRM device. More...
 
int drmDropMaster (int fd)
 Releases master controls for a DRM device. More...
 
int drmGetMagic (int fd, drm_magic_t *magic)
 Retrieves a magic cookie. More...
 
int drmAuthMagic (int fd, drm_magic_t magic)
 Authenticates a magic cookie. More...
 
drmVersionPtr drmGetVersion (int fd)
 Retrieves version information for the DRM driver. More...
 
void drmFreeVersion (drmVersionPtr version)
 Frees a version information structure. More...
 
int drmHandleEvent (int fd, drmEventContextPtr evctx)
 Polls for an event, specifying a callback function. More...
 
int drmIoctl (int fd, unsigned long request, void *arg)
 Issues a DRM input/output control (IOCTL). More...
 
int drmWaitVBlank (int fd, drmVBlankPtr vbl)
 Waits for a vertical blanking interval (vblank). More...
 
int drmModeAddFB (int fd, uint32_t width, uint32_t height, uint8_t depth, uint8_t bpp, uint32_t pitch, uint32_t bo_handle, uint32_t *buf_id)
 Creates a framebuffer. More...
 
int drmModeAddFB2 (int fd, uint32_t width, uint32_t height, uint32_t pixel_format, uint32_t bo_handles[4], uint32_t pitches[4], uint32_t offsets[4], uint32_t *buf_id, uint32_t flags)
 Creates a framebuffer, specifying format and planes. More...
 
int drmModeRmFB (int fd, uint32_t fb_id)
 Destroys a framebuffer. More...
 
drmModeConnectorPtr drmModeGetConnector (int fd, uint32_t connector_id)
 Gets information for a connector. More...
 
void drmModeFreeConnector (drmModeConnectorPtr ptr)
 Frees a connector. More...
 
int drmModeConnectorSetProperty (int fd, uint32_t connector_id, uint32_t property_id, uint64_t value)
 Sets a connector property. More...
 
drmModeCrtcPtr drmModeGetCrtc (int fd, uint32_t crtc_id)
 Gets information for a CRTC. More...
 
void drmModeFreeCrtc (drmModeCrtcPtr ptr)
 Frees a CRTC. More...
 
int drmModeSetCrtc (int fd, uint32_t crtc_id, uint32_t fb_id, uint32_t x, uint32_t y, uint32_t *connectors, int count, drmModeModeInfoPtr drm_mode)
 Sets a CRTC configuration. More...
 
int drmModeCrtcSetGamma (int fd, uint32_t crtc_id, uint32_t size, uint16_t *red, uint16_t *green, uint16_t *blue)
 Sets the display gamma. More...
 
int drmModeCrtcGetGamma (int fd, uint32_t crtc_id, uint32_t size, uint16_t *red, uint16_t *green, uint16_t *blue)
 Gets the current display gamma ramp. More...
 
int drmModePageFlip (int fd, uint32_t crtc_id, uint32_t fb_id, uint32_t flags, void *user_data)
 Requests a page flip (framebuffer change) on the specified CRTC. More...
 
int drmModeSetCursor (int fd, uint32_t crtc_id, uint32_t bo_handle, uint32_t width, uint32_t height)
 Sets a cursor image. More...
 
int drmModeMoveCursor (int fd, uint32_t crtc_id, int x, int y)
 Moves a cursor. More...
 
drmModeEncoderPtr drmModeGetEncoder (int fd, uint32_t encoder_id)
 Gets information for an encoder. More...
 
void drmModeFreeEncoder (drmModeEncoderPtr ptr)
 Frees an encoder. More...
 
drmModePlanePtr drmModeGetPlane (int fd, uint32_t plane_id)
 Gets information about a plane. More...
 
void drmModeFreePlane (drmModePlanePtr ptr)
 Frees a plane. More...
 
int drmModeSetPlane (int fd, uint32_t plane_id, uint32_t crtc_id, uint32_t fb_id, uint32_t flags, uint32_t crtc_x, uint32_t crtc_y, uint32_t crtc_w, uint32_t crtc_h, uint32_t src_x, uint32_t src_y, uint32_t src_w, uint32_t src_h)
 Changes a plane's framebuffer and position. More...
 
drmModeObjectPropertiesPtr drmModeObjectGetProperties (int fd, uint32_t object_id, uint32_t object_type)
 Gets all properties of a DRM object. More...
 
void drmModeFreeObjectProperties (drmModeObjectPropertiesPtr ptr)
 Frees an object properties structure. More...
 
drmModePropertyPtr drmModeGetProperty (int fd, uint32_t propertyId)
 Gets a property structure that describes a property of a DRM object. More...
 
int drmModeObjectSetProperty (int fd, uint32_t object_id, uint32_t object_type, uint32_t property_id, uint64_t value)
 Set the current value of an object's property. More...
 
void drmModeFreeProperty (drmModePropertyPtr ptr)
 Frees a property structure. More...
 
drmModeResPtr drmModeGetResources (int fd)
 Gets information about a DRM device's CRTCs, encoders, and connectors. More...
 
void drmModeFreeResources (drmModeResPtr ptr)
 Frees a resource information structure. More...
 
drmModePlaneResPtr drmModeGetPlaneResources (int fd)
 Gets information about planes. More...
 
void drmModeFreePlaneResources (drmModePlaneResPtr ptr)
 Frees a plane resource information structure. More...
 
int drmPrimeFDToHandle (int fd, int prime_fd, uint32_t *handle)
 Imports a dma-buf. More...
 
int drmPrimeHandleToFD (int fd, uint32_t handle, uint32_t flags, int *prime_fd) drmModeAtomicReqPtr drmModeAtomicAlloc(void)
 Exports a dma-buf. More...
 
int drmModeAtomicAddProperty (drmModeAtomicReqPtr req, uint32_t object_id, uint32_t property_id, uint64_t value)
 Adds a property to an atomic request. More...
 
int drmModeAtomicCommit (int fd, drmModeAtomicReqPtr req, uint32_t flags, void *user_data)
 Commits an atomic property change request to hardware. More...
 
void drmModeAtomicFree (drmModeAtomicReqPtr req)
 Frees an atomic request. More...
 
int drmSetInterfaceVersion (int fd, drmSetVersion *version)
 Sets the interface version. More...
 
char * drmGetBusid (int fd)
 Gets the bus ID of a device. More...
 
void drmFreeBusid (const char *busid)
 Frees bus ID information. More...
 
int drmModeCreatePropertyBlob (int fd, const void *data, size_t size, uint32_t *id)
 Creates a property blob. More...
 
int drmModeDestroyPropertyBlob (int fd, uint32_t id)
 Destroys a property blob. More...
 
drmModePropertyBlobPtr drmModeGetPropertyBlob (int fd, uint32_t blob_id)
 Allocates and retrieves a userspace property blob pointer. More...
 
void drmModeFreePropertyBlob (drmModePropertyBlobPtr ptr)
 Frees a userspace property blob pointer. More...
 
char * drmGetDeviceNameFromFd (int fd)
 Gets a DRM device's name string. More...
 
void drmFree (void *p)
 Frees a block of memory. More...
 
int drmCommandWriteRead (int fd, unsigned long drmCommandIndex, void *data, unsigned long size)
 Send a device-specific read-write command. More...
 

Function Documentation

int drmAuthMagic ( int  fd,
drm_magic_t  magic 
)

Authenticates a magic cookie.

Note
This function has no effect in DRM-NVDC.
Parameters
fdThe file descriptor of an open DRM device.
magicThe magic token retrieved from fd by drmGetMagic.
Returns
0 if successful, or -1 otherwise.
int drmClose ( int  fd)

Closes a DRM device.

Parameters
fdThe file descriptor of an open DRM device.
Returns
0 if successful, or -1 otherwise.
int drmCommandWriteRead ( int  fd,
unsigned long  drmCommandIndex,
void *  data,
unsigned long  size 
)

Send a device-specific read-write command.

DRM-NVDC supports these commands for application use:

  • DRM_TEGRA_GEM_SET_TILING Sets tiling mode. Supported tiling modes are - DRM_TEGRA_GEM_TILING_MODE_BLOCK and DRM_TEGRA_GEM_TILING_MODE_PITCH.
Parameters
[in]fdThe file descriptor of an open DRM device.
[in]drmCommandIndexOne of supported read-write command.
[in,out]dataA pointer to the data to be read and written.
[in]sizeSize of the data to be read and written.
Returns
0 if successful, or -1 otherwise.
int drmDropMaster ( int  fd)

Releases master controls for a DRM device.

Note
This function has no effect in DRM-NVDC.
Parameters
fdThe file descriptor of an open DRM device.
Returns
0 if successful, or -1 otherwise.
void drmFree ( void *  p)

Frees a block of memory.

This is a generic freeing routine; a wrapper for the free function.

Parameters
pA pointer to a block of memory to be freed.
void drmFreeBusid ( const char *  busid)

Frees bus ID information.

Frees a bus ID string allocated by a call to drmGetBusid.

Parameters
busidA pointer to the bus ID information string returned by drmGetBusid.
void drmFreeVersion ( drmVersionPtr  version)

Frees a version information structure.

Frees a drmVersionPtr structure allocated by drmGetVersion.

Parameters
versionA drmVersionPtr to be freed.
char* drmGetBusid ( int  fd)

Gets the bus ID of a device.

Gets the bus ID information string for a DRM device.

Note
DRM-NVDC currently does not support the bus ID. It returns a zero-length string.
Postcondition
If the call is successful, the application must free the bus ID string by calling drmFreeBusid.
Parameters
fdThe file descriptor of an open DRM device.
Returns
A pointer to the bus ID if successful, or NULL if the string cannot be allocated.
int drmGetCap ( int  fd,
uint64_t  capability,
uint64_t *  value 
)

Gets capabilities of the DRM driver.

Parameters
[in]fdThe file descriptor of an open DRM device.
[in]capabilityThe DRM capability to be obtained from the device. Supported capabilities are:
  • DRM_CAP_ASYNC_PAGE_FLIP: value is set to 0 if unsupported, 1 if supported.
  • DRM_CAP_DUMB_BUFFER: value is set to 0 if unsupported, 1 if supported.
  • DRM_CAP_CURSOR_WIDTH: Stores the maximum cursor width allowed by DRM-NVDC in value if the capability is supported, 0 if unsupported.
  • DRM_CAP_CURSOR_HEIGHT: Stores the maximum cursor height allowed by DRM-NVDC in value if the capability is supported, 0 if unsupported.
  • DRM_CAP_TIMESTAMP_MONOTONIC: value is set to 0 if unsupported, 1 if supported. Only supported on Linux.
[out]valueReturns a capability value as specified by capability.
Returns
0 if successful, or -EINVAL otherwise.
char* drmGetDeviceNameFromFd ( int  fd)

Gets a DRM device's name string.

Returns the file path of a specified DRM device, e.g. "/dev/dri/card0".

Note
DRM-NVDC currently does not support the device file path. It returns the string "drm-nvdc" as a placeholder.
If the call is successful, the application must calling drmFree to free the name string.
Parameters
fdThe file descriptor of an open DRM device.
Returns
A DRM device name string if successful, or NULL if the device name string cannot be allocated.
int drmGetMagic ( int  fd,
drm_magic_t *  magic 
)

Retrieves a magic cookie.

Note
This function has no effect in DRM-NVDC.
Parameters
[in]fdThe file descriptor of an open DRM device.
[out]magicAn opaque 'magic' token.
Returns
0 if successful, or -1 otherwise.
drmVersionPtr drmGetVersion ( int  fd)

Retrieves version information for the DRM driver.

The function allocates and returns a drmVersionPtr structure that contains the DRM driver's build version information and a driver description string.

The application can provide conditional support for DRM-NVDC by confirming that the drmVersionPtr structure's name field contains the string "drm-nvdc". If name does not contain this value, the application can fall back to a kernel DRM implementation.

DRM-NVDC does not populate the drmVersionPtr structure's date, major, minor, and patchlevel fields.

Postcondition
If the call is successful, the application must free the version information structure by calling drmFreeVersion.
Parameters
fdThe file descriptor of an open DRM device.
Returns
A pointer to a drmVersionPtr structure if successful, or NULL otherwise.
int drmHandleEvent ( int  fd,
drmEventContextPtr  evctx 
)

Polls for an event, specifying a callback function.

Calls a callback function if an event of a specified type has occurred.

Note
DRM-NVDC supports this function only on Linux. The evctx structure's vblank_handler field is supported.
Parameters
fdThe file descriptor of an open DRM device.
evctxAn event context containing callback pointers.
Returns
0 if successful, or -1 otherwise.
int drmIoctl ( int  fd,
unsigned long  request,
void *  arg 
)

Issues a DRM input/output control (IOCTL).

This function is used primarily in cases where LIBDRM does not support a function that performs a desired operation. LIBDRM may lag behind kernel interfaces in features, and this function allows early access new interfaces.

Note
DRM-NVDC does not support all of the functionality of kernel DRM, so only a small set of IOCTL operations is implemented.

DRM-NVDC supports these IOCTL operations for application use:

  • DRM_IOCTL_MODE_CREATE_DUMB: Creates a dumb (CPU) buffer. Useful for debugging and for simple display tests. Accelerated rendering is not available.
  • DRM_IOCTL_MODE_MAP_DUMB: Maps a dumb buffer for CPU access. Unlike kernel DRM, DRM-NVDC maps the dumb buffer with the mmap function and returns a valid memory pointer in the returned offset. The application must not call mmap on the returned offset.
  • DRM_IOCTL_MODE_DESTROY_DUMB: Destroys a dumb buffer.
  • DRM_IOCTL_TEGRA_GEM_CREATE: Creates a HW buffer.
Parameters
[in]fdThe file descriptor of an open DRM device.
[in]requestOne of supported DRM_IOCTL_... constants.
[in,out]argA pointer to the ioctl data structure:
  • If request is DRM_IOCTL_MODE_CREATE_DUMB, a drm_mode_create_dumb structure
  • If request is DRM_IOCTL_MODE_MAP_DUMB, a drm_mode_map_dumb structure
  • If request is DRM_IOCTL_MODE_DESTROY_DUMB, a drm_mode_destroy_dumb structure
Returns
0 if successful, or -1 otherwise.
int drmModeAddFB ( int  fd,
uint32_t  width,
uint32_t  height,
uint8_t  depth,
uint8_t  bpp,
uint32_t  pitch,
uint32_t  bo_handle,
uint32_t *  buf_id 
)

Creates a framebuffer.

The function creates a framebuffer with a specified size and format, using the specified buffer object as the memory backing store. The buffer object can be a "dumb buffer" created by a call to drmIoctl with the request parameter set to DRM_IOCTL_MODE_CREATE_DUMB, or it can be a dma-buf imported by a call to the drmPrimeFDToHandle function.

Postcondition
If the call is successful, the application must remove (free) the framebuffer by calling drmModeRmFB.
Parameters
[in]fdThe file descriptor of an open DRM device.
[in]widthFramebuffer width in pixels.
[in]heightFramebuffer height in pixels.
[in]depthFramebuffer depth in bits.
[in]bppFramebuffer bits per pixel.
[in]pitchFramebuffer pitch in bytes.
[in]bo_handleA handle for a buffer object to provide memory backing.
[out]buf_idReceives the framebuffer ID of the created framebuffer if framebuffer creation is successful.
Returns
0 if framebuffer creation is successful, or -1 otherwise.
int drmModeAddFB2 ( int  fd,
uint32_t  width,
uint32_t  height,
uint32_t  pixel_format,
uint32_t  bo_handles[4],
uint32_t  pitches[4],
uint32_t  offsets[4],
uint32_t *  buf_id,
uint32_t  flags 
)

Creates a framebuffer, specifying format and planes.

This function is similar to :drmModeAddFB, but offers more options. The buffer objects' pixel format is specified explicitly, instead of being depth+bpp as in drmModeAddFB. Also, multiplanar YUV formats are supported. As for drmModeAddFB, the buffer object handle(s) can be a dumb buffers or imported dma-bufs.

Postcondition
If the call is successful, the application must remove (free) the framebuffer by calling drmModeRmFB.
Note
The flags parameter is not currently supported.
Parameters
[in]fdThe file descriptor of an open DRM device.
[in]widthFramebuffer width in pixels.
[in]heightFramebuffer height in pixels.
[in]pixel_formatPixel format of the bo_handle(s).
[in]bo_handlesAn array of four handles for buffer objects to provide memory backing. Unused array elements must be NULL.
[in]pitchesAn array containing the pitches of the buffer objects in bytes.
[in]offsetsAn array containing the offsets of the buffer objects in bytes.
[out]buf_idReceives the framebuffer ID of the created framebuffer if framebuffer creation is successful.
[in]flagsCreation flags.
Returns
0 if successful, or -1 otherwise.
int drmModeAtomicAddProperty ( drmModeAtomicReqPtr  req,
uint32_t  object_id,
uint32_t  property_id,
uint64_t  value 
)

Adds a property to an atomic request.

Adds a property and value to an atomic request.

Parameters
reqAn atomic request.
object_idObject ID of a CRTC, plane, or connector to be modified.
property_idProperty ID of the property to be modified.
valueThe new value for the property.
Return values
0if successful.
-1if req is NULL or the API is out of memory.
-EINVALif DRM_CLIENT_CAP_ATOMIC is not enabled.
int drmModeAtomicCommit ( int  fd,
drmModeAtomicReqPtr  req,
uint32_t  flags,
void *  user_data 
)

Commits an atomic property change request to hardware.

Sends all of the property changes in a drmModeAtomicReqPtr structure to hardware.

Parameters
fdThe file descriptor of an open DRM device.
reqThe request object describing properties to commit.
flagsFlags which influence the operation. The supported flags are:
  • DRM_MODE_PAGE_FLIP_ASYNC: Commits values immediately when possible; does not latch new properties at the next vblank.
  • DRM_MODE_ATOMIC_NONBLOCK: Commits values to hardware but does not wait for hardware to accept the new values.
  • DRM_MODE_ATOMIC_TEST_ONLY: Validates input, but does not commit the values to hardware.
user_dataUnused.
Return values
0if successful.
-1if req is NULL.
-EINVALif DRM_CLIENT_CAP_ATOMIC is not enabled, the value of flags is illegal, or atomic property IDs in the request are not recognized.
void drmModeAtomicFree ( drmModeAtomicReqPtr  req)

Frees an atomic request.

Frees a drmModeAtomicReqPtr object allocated by drmModeAtomicAlloc, and all of the associated drmModeAtomicReqItemPtr objects.

Parameters
reqThe atomic request object to be freed.
int drmModeConnectorSetProperty ( int  fd,
uint32_t  connector_id,
uint32_t  property_id,
uint64_t  value 
)

Sets a connector property.

Note
This function currently has no effect in DRM-NVDC.
Parameters
fdThe file descriptor of an open DRM device.
connector_idThe ID of a connector whose property is to be set.
property_idThe ID of the property to be set.
valueA new value for the property.
Returns
0 if successful, or -1 otherwise.
int drmModeCreatePropertyBlob ( int  fd,
const void *  data,
size_t  size,
uint32_t *  id 
)

Creates a property blob.

Stores an opaque blob of memory and returns an ID for it. The ID can then be used for atomic mode setting.

Note
In DRM-NVDC, data must be a drmModeModeInfoPtr. When a property blob is created from a drmModeModeInfoPtr, the returned ID becomes a valid value to set on CRTC properties matching the name MODE_ID. Atomically committing a MODE_ID property to the ID of the created blob causes a mode set on that CRTC. The new CRTC mode will be that of the drmModeModeInfoPtr used as input to drmModeCreatePropertyBlob.
Postcondition
If the call is successful, the application must destroy (free) the property blob by calling drmModeDestroyPropertyBlob.
Parameters
[in]fdThe file descriptor of an open DRM device.
[in]dataContent of the property blob. What data is acceptable depends on the implementation. In DRM-NVDC, data must be a drmModeModeInfoPtr structure.
[in]sizeSize of data.
[out]idReturns a property ID for the blob.
Return values
0if operation is successful.
-1if data is not a valid pointer, or if size or id is invalid.
-ENOMEMif blob memory could not be allocated.
int drmModeCrtcGetGamma ( int  fd,
uint32_t  crtc_id,
uint32_t  size,
uint16_t *  red,
uint16_t *  green,
uint16_t *  blue 
)

Gets the current display gamma ramp.

Parameters
[in]fdThe file descriptor of an open DRM device.
[in]crtc_idCRTC ID of the CRTC to be queried.
[in]sizeNumber of elements in each of the red, green, and blue LUTs.
[out]redA pointer to an array in which the red LUT will be stored.
[out]greenA pointer to an array in which the green LUT will be stored.
[out]blueA pointer to an array in which the blue LUT will be stored.
Returns
0 if successful, or -1 otherwise.
int drmModeCrtcSetGamma ( int  fd,
uint32_t  crtc_id,
uint32_t  size,
uint16_t *  red,
uint16_t *  green,
uint16_t *  blue 
)

Sets the display gamma.

Sets custom display LUT (look up table) for each primary color. Each table is indexed by a value that represents input intensity, and yields a value that represents output intensity. Custom LUTs are most often used to adjust the display gamma ramp. size should be less than or equal to the gamma_size reported by drmModeGetCrtc.

Parameters
fdThe file descriptor of an open DRM device.
crtc_idCRTC ID of the CRTC to be adjusted.
sizeNumber of elements in each of the red, green, and blue LUTs.
redLUT for red intensity.
greenLUT for green intensity.
blueLUT for blue intensity.
Returns
0 if successful, or -1 otherwise.
int drmModeDestroyPropertyBlob ( int  fd,
uint32_t  id 
)

Destroys a property blob.

Destroys a property blob created by a call to drmModeCreatePropertyBlob.

Parameters
fdThe file descriptor of an open DRM device.
idThe ID of the property blob to be destroyed.
Returns
0 if successful, or -EINVAL if no property blob with specified ID is found.
void drmModeFreeConnector ( drmModeConnectorPtr  ptr)

Frees a connector.

Frees a drmModeConnectorPtr structure allocated by drmModeGetConnector.

Parameters
ptrA pointer to the connector to be freed.
void drmModeFreeCrtc ( drmModeCrtcPtr  ptr)

Frees a CRTC.

Frees a drmModeCrtcPtr structure allocated by drmModeGetCrtc.

Parameters
ptrA pointer to the CRTC to be freed.
void drmModeFreeEncoder ( drmModeEncoderPtr  ptr)

Frees an encoder.

Frees a drmModeEncoderPtr structure allocated by drmModeGetEncoder.

Parameters
ptrA pointer to encoder to be freed.
void drmModeFreeObjectProperties ( drmModeObjectPropertiesPtr  ptr)

Frees an object properties structure.

Frees a drmModeObjectPropertiesPtr structure allocated by drmModeObjectGetProperties.

Parameters
ptrA pointer to the object properties structure to be freed.
void drmModeFreePlane ( drmModePlanePtr  ptr)

Frees a plane.

Frees a drmModePlanePtr structure allocated by drmModeGetPlane.

Parameters
ptrA pointer to the plane to be freed.
void drmModeFreePlaneResources ( drmModePlaneResPtr  ptr)

Frees a plane resource information structure.

Frees a drmModePlaneResPtr structure allocated by drmModeGetPlaneResources.

Parameters
ptrA pointer to the plane resource structure to free.
void drmModeFreeProperty ( drmModePropertyPtr  ptr)

Frees a property structure.

Frees a drmModePropertyPtr structure allocated by drmModeGetProperty.

Parameters
ptrA pointer to a property structure returned by drmModeGetProperty.
void drmModeFreePropertyBlob ( drmModePropertyBlobPtr  ptr)

Frees a userspace property blob pointer.

Note
This function has no effect in DRM-NVDC.
Parameters
ptrThe pointer to the property blob returned by drmModeGetPropertyBlob
void drmModeFreeResources ( drmModeResPtr  ptr)

Frees a resource information structure.

Frees a drmModeResPtr structure allocated by drmModeGetResources.

Parameters
ptrA pointer to the resource to be freed.
drmModeConnectorPtr drmModeGetConnector ( int  fd,
uint32_t  connector_id 
)

Gets information for a connector.

If connector_id is valid, fetches a drmModeConnectorPtr structure which contains information about a connector, such as available modes, connection status, connector type, and which encoder (if any) is attached.

Postcondition
If the call is successful, the application must free the connector information structure by calling drmModeFreeConnector.
Note
connector->mmWidth and connector->mmHeight are currently set to placeholder values.
Parameters
fdThe file descriptor of an open DRM device.
connector_idThe connector ID of the connector to be retrieved.
Returns
A drmModeConnectorPtr structure if successful, or NULL if the connector is not found or the API is out of memory.
drmModeCrtcPtr drmModeGetCrtc ( int  fd,
uint32_t  crtc_id 
)

Gets information for a CRTC.

If the specified CRTC ID is valid, fetches a drmModeCrtcPtr structure which contains information about the CRTC, such as the current framebuffer, mode, position, size, and number of gamma LUT elements.

Postcondition
If a call is successful, the application must call drmModeFreeCrtc to free the structure it returns.
Parameters
fdThe file descriptor of an open DRM device.
crtc_idThe CRTC ID of the CRTC to retrieved.
Returns
A drmModeCrtcPtr structure if successful, or NULL if the CRTC is not found or the API is out of memory.
drmModeEncoderPtr drmModeGetEncoder ( int  fd,
uint32_t  encoder_id 
)

Gets information for an encoder.

Fetches a drmModeEncoderPtr structure which contains information about a specified encoder, such as the current CRTC and compatible CRTCs.

Note
Encoders in DRM-NVDC are connected to a single CRTC at startup, and are not reconfigurable. There is only one bit set in possible_crtcs, and none in possible_clones (i.e. the value of possible_clones is 0).
Postcondition
If the call is successful, the application must call drmModeFreeEncoder to free the allocated structure.
Parameters
fdThe file descriptor of an open DRM device.
encoder_idEncoder ID of the encoder to be retrieved.
Returns
A drmModeEncoderPtr structure if successful, or NULL if the encoder is not found or the API is out of memory.
drmModePlanePtr drmModeGetPlane ( int  fd,
uint32_t  plane_id 
)

Gets information about a plane.

If plane_id is valid, fetches a drmModePlanePtr structure which contains information about the specified plane, such as its current CRTC and compatible CRTCs, the currently bound framebuffer, the number of gamma steps, and the position of the plane.

Postcondition
If the call is successful, the application must free the plane information structure by calling drmModeFreePlane.
Note
In DRM-NVDC planes are connected to a single CRTC at startup, and are not reconfigurable. The drmModePlanePtr structure's possible_crtc member always has exactly one bit set.
Parameters
fdThe file descriptor of an open DRM device.
plane_idPlane ID of the plane to be retrieved.
Returns
A drmModePlanePtr structure if successful, or NULL if the plane is not found or the API out of memory.
drmModePlaneResPtr drmModeGetPlaneResources ( int  fd)

Gets information about planes.

Gets a list of plane resources for a DRM device. A DRM application typically calls this function early to identify the available display layers.

By default, the information returned includes only "Overlay" type (regular) planes – not "Primary" and "Cursor" planes. If DRM_CLIENT_CAP_UNIVERSAL_PLANES has been enabled with drmSetClientCap, the information returned includes "Primary" planes representing CTRCs, and "Cursor" planes representing Cursors. This allows CRTCs and Cursors to be manipulated with plane functions such as drmModeSetPlane.

Note
DRM-NVDC currently does not implement "Cursor" type planes.
Postcondition
If the call is successful, the application must free the plane information structure by calling drmModeFreePlaneResources.
Parameters
fdThe file descriptor of an open DRM device.
Returns
A drmModeResPtr structure if successful, or NULL otherwise.
drmModePropertyPtr drmModeGetProperty ( int  fd,
uint32_t  propertyId 
)

Gets a property structure that describes a property of a DRM object.

The DRM object can be a plane, a CRTC, or a connector.

This function operates on a drmModeObjectPropertiesPtr structure returned by drmModeObjectGetProperties().

The modifiable properties depend on the DRM object type:

  • For a plane (object type DRM_MODE_OBJECT_PLANE):
    "SRC_X", "SRC_Y", "SRC_W", "SRC_H", "zpos", "alpha" "CRTC_X",
    "CRTC_Y", "CRTC_W", "CRTC_H", "CRTC_ID", "FB_ID"
    
  • For a CRTC (object type DRM_MODE_OBJECT_CRTC), supported values are:
    "MODE_ID", "ACTIVE", "HDR_SUPPORTED"
    
  • For a connector (object type DRM_MODE_OBJECT_CONNECTOR), the supported value is:
    "CRTC_ID"
    

For DRM planes, the enums field holds a list of key-word pairs (name : value) that defines the properties.

drmModePropertyPtr->enums[ ].name
drmModePropertyPtr->enums[ ].value
  • Supported values for the name field are defined above (i.e., "SRC_X", "SRC_Y", or "SRC_W"). This field is modifiable.
  • Supported values for the value fields are:
    "Primary", "Overlay", "Cursor"
    This field is read-only.

To identify the plane type, iterate through the following list to locate the enum whose value field matches the one you seek. Then, get the value from corresponding name field.

drmModePropertyPtr->enums[ ]

For example:

for (j = 0; j < props->count_enums; j++) {
printf("\t\t%lld = %s\n", props->enums[j].value, props->enums[j].name);
if (props->enums[j].value == value)
name = props->enums[j].name;
}
if (props->count_enums && name) {
/* The specified plane property value appears in the DRM properties. */
/* Print the property name, which will be "Primary", "Overlay", or "Cursor". */
printf("\tcon_value : %s\n", name);
} else {
/* The specified plane property value does not appear in the DRM properties. */
/* Print the property value for which we were looking. */
printf("\tcon_value : %" PRIu64 "\n", value);
}
Note
The zpos value for a plane is initialized with an offset of 10 relative to the next plane. This is to allow for flexible configuration of heads. For example:
  • "Primary" type Plane zpos = 10
  • First "Overlay" Plane zpos = 20
  • Next "Overlay" Plane zpos = 30
  • Etc.
The allowed range for zpos is [0, 255]. Planes with numerically greater values for zpos occlude planes with numerically lesser values.
The alpha value for a plane causes a plane-wide transparency to be applied as well as the per-pixel alpha contained in the buffer object. The allowed range for alpha is [0, 255], where 0 is fully transparent and 255 indicates that only per-pixel alpha has an effect. For non-alpha pixel formats, there is no per-pixel alpha, so 255 indicates fully opaque.
Postcondition
If the call is successful, the application must free the property information structure by calling drmModeFreeProperty.
Parameters
fdThe file descriptor of an open DRM device.
propertyIdProperty ID of the property object to be fetched.
Returns
A drmModePropertyPtr if successful, or NULL otherwise.
drmModePropertyBlobPtr drmModeGetPropertyBlob ( int  fd,
uint32_t  blob_id 
)

Allocates and retrieves a userspace property blob pointer.

Note
This function has no effect in DRM-NVDC.
Parameters
fdThe file descriptor of an open DRM device.
blob_idID of the property blob to be retrived.
Returns
Pointer to the corresponding property blob if successful, or NULL otherwise.
drmModeResPtr drmModeGetResources ( int  fd)

Gets information about a DRM device's CRTCs, encoders, and connectors.

Gets a list of a DRM device's major resources. A DRM application typically calls this function early to identify available displays and other resources. The function does not report plane resources, though. These can be queried with drmModeGetPlaneResources.

Note
The drmModeResPtr structure's min_width, min_height, max_width, and max_height members are set to placeholder values.
Postcondition
If the call is successful, the application must free the resource information structure by calling drmModeFreeResources.
Parameters
fdThe file descriptor of an open DRM device.
Returns
A drmModeResPtr structure if successful, or NULL otherwise.
int drmModeMoveCursor ( int  fd,
uint32_t  crtc_id,
int  x,
int  y 
)

Moves a cursor.

Parameters
fdThe file descriptor of an open DRM device.
crtc_idCRTC ID of the CRTC whose cursor is to be moved.
xPosition of the cursor from left.
yPosition of the cursor from top.
Returns
0 if successful.
-EINVAL if crtc_id is invalid.
-errno otherwise.
drmModeObjectPropertiesPtr drmModeObjectGetProperties ( int  fd,
uint32_t  object_id,
uint32_t  object_type 
)

Gets all properties of a DRM object.

Gets an object properties structure that describes all of the atomically modifiable properties of a specified DRM object, as well as read-only properties not included in the corresponding drmModeCrtcPtr, drmModeConnectorPtr, and drmModePlanePtr structures. You can then retrieve individual properties with drmModeGetProperty and change their values with drmModeAtomicAddProperty.

The drmModeObjectPropertiesPtr structure contains an array of property IDs (props), an array of corresponding property values (prop_values), and the number of elements in each array (count_props). You can get the name of a property by calling drmModeGetProperty on the property ID and looking at the returned drmModePropertyPtr structure's name field.

To modify a property atomically, create a drmModeAtomicReqPtr request object by calling drmModeAtomicAlloc, then call drmModeAtomicAddProperty, specifying the drmModeAtomicReqPtr object, the object ID of the object to modify, the property ID of the property to modify, and the property's new value. Then commit the request with drmModeAtomicCommit. You can set several properties in an atomic request and commit them in a single operation.

Note
Not all object types are supported.
Postcondition
If the call is successful, the application must free the drmModeObjectPropertiesPtr structure by calling drmModeFreeObjectProperties.
Parameters
fdThe file descriptor of an open DRM device.
object_idThe object ID of the DRM object whose properties are to be retrieved.
object_typeA symbol representing an object type. The following object types are supported:
  • DRM_MODE_OBJECT_CRTC
  • DRM_MODE_OBJECT_CONNECTOR
  • DRM_MODE_OBJECT_PLANE
Returns
A drmModeObjectPropertiesPtr object if successful, or NULL otherwise.
int drmModeObjectSetProperty ( int  fd,
uint32_t  object_id,
uint32_t  object_type,
uint32_t  property_id,
uint64_t  value 
)

Set the current value of an object's property.

Parameters
[in]fdThe file descriptor of an open DRM device.
object_idThe object ID of the DRM object whose properties are to be set.
object_typeA symbol representing an object type. The following object types are supported:
  • DRM_MODE_OBJECT_CRTC
property_idThe ID of the property to be set.
valueA new value for the property.
Returns
0 if successful, or -1 otherwise.
int drmModePageFlip ( int  fd,
uint32_t  crtc_id,
uint32_t  fb_id,
uint32_t  flags,
void *  user_data 
)

Requests a page flip (framebuffer change) on the specified CRTC.

Schedules a page flip on the specified CRTC. By default, the CRTC will be reprogrammed to display the specified framebuffer after the next vertical refresh.

Note
drmModePageFlip does not wait for rendering to complete, nor is future rendering blocked until the flip completes. This differs from KMS based implementations that utilize implicit synchronization. When using EGLOutput together with DRM-NVDC, synchronization is handled internally.
Parameters
fdThe file descriptor of an open DRM device.
crtc_idCRTC ID of the CRTC whose framebuffer is to be changed.
fb_idFramebuffer ID of the framebuffer to be displayed.
flagsFlags affecting the operation. Supported values are:
  • DRM_MODE_PAGE_FLIP_ASYNC: Flip immediately, not at vblank.
  • DRM_MODE_PAGE_FLIP_EVENT: Send page flip event.
user_dataData used by the page flip handler if vblank event was requested.
Return values
0if successful.
-EINVALif crtc_id or fb_id is invalid.
-errnootherwise.
int drmModeRmFB ( int  fd,
uint32_t  fb_id 
)

Destroys a framebuffer.

Destroys (frees) a framebuffer allocated by drmModeAddFB or drmModeAddFB2.

Parameters
fdThe file descriptor of an open DRM device.
fb_idThe ID of the framebuffer to destroy.
Returns
0 if destruction is successful, or -ENOENT if the framebuffer is not found.
int drmModeSetCrtc ( int  fd,
uint32_t  crtc_id,
uint32_t  fb_id,
uint32_t  x,
uint32_t  y,
uint32_t *  connectors,
int  count,
drmModeModeInfoPtr  drm_mode 
)

Sets a CRTC configuration.

If the DRM mode is specified (if drm_mode is not NULL), sets the display mode on the CRTC and specified connector(s). New fb_id, x, and y properties will set at vblank.

Note
The fb_id, x, and y parameters accept the special input value -1, which indicates that the hardware window framebuffer or the corresponding offset is not to be changed. (Kernel based DRM drivers accept -1 only for fb_id. They return error code -ERANGE if given -1 for x or y.)
It is permitted to specify a valid mode and fb_id==-1, even if no framebuffer is currently attached to the CRTC. The function will set the display mode but will leave the CRTC framebuffer undefined.
Framebuffers set on a CRTC, whether by drmModeSetCrtc, drmModePageFlip, or any other means, are displayed behind planes. The CRTC display layer is the lowest in stacking order.
Parameters
fdThe file descriptor of an open DRM device.
crtc_idThe ID of the CRTC to be set.
fb_idID of the framebuffer to display with this CRTC, or -1 to use the same CRTC as the previous operation.
xOffset from left of active display region to place the framebuffer. If x is -1, the X offset is not changed.
yOffset from top of active display region to place the framebuffer. If y is -1, the Y offset is not changed.
connectorsA pointer to a list of connectors to bind to the CRTC.
countNumber of connectors in the connectors list.
drm_modeMode to set, or NULL to use the same mode as the previous operation.
Return values
0if successful.
-EINVALif crtc_id is invalid.
-1if count is invalid, or the list specified by connectors is incompatible with the CRTC.
-errnootherwise.
int drmModeSetCursor ( int  fd,
uint32_t  crtc_id,
uint32_t  bo_handle,
uint32_t  width,
uint32_t  height 
)

Sets a cursor image.

Note
Supported cursor image sizes: 32 x 32 64 x 64 128 x 128 256 x 256
Passing 0 as the bo_handle will disable the cursor
Parameters
fdThe file descriptor of an open DRM device.
crtc_idCRTC ID of the CRTC whose cursor is to be changed.
bo_handleHandle of a buffer object to use as cursor image.
widthWidth of the cursor image.
heightHeight of the cursor image.
Returns
0 if successful.
-EINVAL if either crtc_id or bo_handle are invalid, or an invalid cursor size has been requested.
-errno otherwise.
int drmModeSetPlane ( int  fd,
uint32_t  plane_id,
uint32_t  crtc_id,
uint32_t  fb_id,
uint32_t  flags,
uint32_t  crtc_x,
uint32_t  crtc_y,
uint32_t  crtc_w,
uint32_t  crtc_h,
uint32_t  src_x,
uint32_t  src_y,
uint32_t  src_w,
uint32_t  src_h 
)

Changes a plane's framebuffer and position.

Note
The crtc_... and src_... parameters accept the special input value -1, which indicates that the hardware offset value is not to be changed. (Kernel based DRM drivers return the error code -ERANGE when given this value.)
Framebuffers set on planes are displayed on top of CRTCs. The stacking order of planes is indicated by the order that the planes are reported by drmModeGetPlaneResources.
All drmModeSetPlane operations are synced to vblank and are blocking.
Parameters
fdThe file descriptor of an open DRM device.
plane_idPlane ID of the plane to be changed.
crtc_idCRTC ID of the CRTC that the plane is on.
fb_idFramebuffer ID of the framebuffer to display on the plane, or -1 to leave the framebuffer unchanged.
flagsFlags that control function behavior. No flags are currently supported for external use.
crtc_xOffset from left of active display region to show plane.
crtc_yOffset from top of active display region to show plane.
crtc_wWidth of output rectangle on display.
crtc_hHeight of output rectangle on display.
src_xClip offset from left of source framebuffer (Q16.16 fixed point).
src_yClip offset from top of source framebuffer (Q16.16 fixed point).
src_wWidth of source rectangle (Q16.16 fixed point).
src_hHeight of source rectangle (Q16.16 fixed point).
Return values
0if successful.
-EINVALif plane_id or crtc_id is invalid.
-errnootherwise.
int drmOpen ( const char *  name,
const char *  busid 
)

Opens a DRM device and creates a file descriptor handle.

Note
DRM-NVDC does not interface with DRM kernel devices, so the name and bus ID parameters are not used. DRM-NVDC will always return an open device handle for the current Tegra NVDC based display driver.
Parameters
nameNot currently used.
busidNot currently used.
Returns
The file descriptor of the open device node if successful, or -1 otherwise.
int drmPrimeFDToHandle ( int  fd,
int  prime_fd,
uint32_t *  handle 
)

Imports a dma-buf.

Given a dma-buf file descriptor, returns a corresponding handle.

Parameters
[in]fdThe file descriptor of an open DRM device.
[in]prime_fdThe file descriptor of a dma-buf.
[out]handleA handle for the dma-buf.
Returns
0 if successful, or -1 otherwise.
int drmPrimeHandleToFD ( int  fd,
uint32_t  handle,
uint32_t  flags,
int *  prime_fd 
)

Exports a dma-buf.

Given a handle, returns a corresponding dma-buf file descriptor.

Parameters
[in]fdThe file descriptor of an open DRM device.
[in]handleA handle for the dma-buf.
[in]flagsFlags like DRM_CLOEXEC and DRM_RDWR.
[out]prime_fdThe file descriptor of a dma-buf.
Returns
0 if successful, or -1 otherwise. Allocates an atomic request.

Allocates a drmModeAtomicReq structure for an atomic mode setting request. The initially empty structure can be populated with properties and values by calls to drmModeAtomicAddProperty, and can then be committed to hardware by a call to drmModeAtomicCommit.

Postcondition
If the call is successful, the application must free the request structure by calling drmModeAtomicFree.
Returns
A drmModeAtomicReqPtr structure if successful, or NULL if DRM_CLIENT_CAP_ATOMIC is not enabled or the API is out of memory.
int drmSetClientCap ( int  fd,
uint64_t  capability,
uint64_t  value 
)

Enables or disables DRM features (capabilities).

Parameters
fdThe file descriptor of an open DRM device.
capabilitySpecifies the capability to be enabled or disabled. Supported values are:
  • DRM_CLIENT_CAP_ATOMIC (disabled by default)
  • DRM_CLIENT_CAP_UNIVERSAL_PLANES (disabled by default)
value0 to disable the capability, or 1 to enable it.
Returns
0 if successful, or -EINVAL otherwise.
int drmSetInterfaceVersion ( int  fd,
drmSetVersion *  version 
)

Sets the interface version.

Limits the exposed DRM interface to the features that would be exposed in a specified version.

Note
This function currently has no effect in DRM-NVDC.
Parameters
fdThe file descriptor of an open DRM device.
versionVersion information to be used to limit DRM interface. version->drm_di_major, version->drm_di_minor, version->drm_dd_major, and version->drm_dd_minor can be set to -1 as a "don't care" value.
Returns
0 if successful, or -1 otherwise.
int drmSetMaster ( int  fd)

Requests master controls for a DRM device.

In DRM drivers that support master mode, requests that a file descriptor be granted master permission for operations that require it, such as the drmModeSet... functions.

Note
This function currently has no effect in DRM-NVDC. Master permissions are granted by default to all clients.
Parameters
fdThe file descriptor of an open DRM device.
Returns
0 if successful, or -1 otherwise.
int drmWaitVBlank ( int  fd,
drmVBlankPtr  vbl 
)

Waits for a vertical blanking interval (vblank).

Waits for a specified vblank, or requests that the registered vblank handler be called when a specified vblank occurs.

Note
DRM-NVDC currently does not support all drmVblankPtr fields.
Parameters
fdThe file descriptor of an open DRM device.
vblA description of the requested vblank. The vbl->type field must contain one of these values:
  • DRM_VBLANK_ABSOLUTE: request.sequence is the vblank count since some point in the past, e.g. system boot.
  • DRM_VBLANK_RELATIVE: request.sequence is the vblank count from the current value. e.g. 1 specifies the next vblank. The value may be bitwise ORed with any combination of these values:
  • DRM_VBLANK_SECONDARY: Uses the secondary display's vblank.
  • DRM_VBLANK_EVENT: Returns immediately and triggers the event callback instead of waiting for a specified vblank.
Returns
0 if successful, or -1 otherwise.