DRM exposes many UAPI and structure definition to have a consistent
and standardized interface with user.
Userspace can refer to these structure definitions and UAPI formats
to communicate to driver
CRTC index
CRTC’s have both an object ID and an index, and they are not the same thing.
The index is used in cases where a densely packed identifier for a CRTC is
needed, for instance a bitmask of CRTC’s. The member possible_crtcs of struct
drm_mode_get_plane
is an example.
DRM_IOCTL_MODE_GETRESOURCES populates a structure with an array of CRTC ID’s,
and the CRTC index is its position in this array.
-
DRM_CAP_DUMB_BUFFER
DRM_CAP_DUMB_BUFFER ()
Parameters
Description
If set to 1, the driver supports creating dumb buffers via the
DRM_IOCTL_MODE_CREATE_DUMB
ioctl.
-
DRM_CAP_VBLANK_HIGH_CRTC
DRM_CAP_VBLANK_HIGH_CRTC ()
Parameters
Description
If set to 1, the kernel supports specifying a CRTC index
in the high bits of drm_wait_vblank_request.type
.
Starting kernel version 2.6.39, this capability is always set to 1.
-
DRM_CAP_DUMB_PREFERRED_DEPTH
DRM_CAP_DUMB_PREFERRED_DEPTH ()
Parameters
Description
The preferred bit depth for dumb buffers.
The bit depth is the number of bits used to indicate the color of a single
pixel excluding any padding. This is different from the number of bits per
pixel. For instance, XRGB8888 has a bit depth of 24 but has 32 bits per
pixel.
Note that this preference only applies to dumb buffers, it’s irrelevant for
other types of buffers.
-
DRM_CAP_DUMB_PREFER_SHADOW
DRM_CAP_DUMB_PREFER_SHADOW ()
Parameters
Description
If set to 1, the driver prefers userspace to render to a shadow buffer
instead of directly rendering to a dumb buffer. For best speed, userspace
should do streaming ordered memory copies into the dumb buffer and never
read from it.
Note that this preference only applies to dumb buffers, it’s irrelevant for
other types of buffers.
-
DRM_CAP_PRIME
DRM_CAP_PRIME ()
Parameters
Description
Bitfield of supported PRIME sharing capabilities. See DRM_PRIME_CAP_IMPORT
and DRM_PRIME_CAP_EXPORT
.
PRIME buffers are exposed as dma-buf file descriptors. See
DRM Memory Management, section “PRIME Buffer Sharing”.
-
DRM_PRIME_CAP_IMPORT
DRM_PRIME_CAP_IMPORT ()
Parameters
Description
If this bit is set in DRM_CAP_PRIME
, the driver supports importing PRIME
buffers via the DRM_IOCTL_PRIME_FD_TO_HANDLE
ioctl.
-
DRM_PRIME_CAP_EXPORT
DRM_PRIME_CAP_EXPORT ()
Parameters
Description
If this bit is set in DRM_CAP_PRIME
, the driver supports exporting PRIME
buffers via the DRM_IOCTL_PRIME_HANDLE_TO_FD
ioctl.
-
DRM_CAP_TIMESTAMP_MONOTONIC
DRM_CAP_TIMESTAMP_MONOTONIC ()
Parameters
Description
If set to 0, the kernel will report timestamps with CLOCK_REALTIME
in
struct drm_event_vblank. If set to 1, the kernel will report timestamps with
CLOCK_MONOTONIC
. See clock_gettime(2)
for the definition of these
clocks.
Starting from kernel version 2.6.39, the default value for this capability
is 1. Starting kernel version 4.15, this capability is always set to 1.
-
DRM_CAP_ASYNC_PAGE_FLIP
DRM_CAP_ASYNC_PAGE_FLIP ()
Parameters
Description
If set to 1, the driver supports DRM_MODE_PAGE_FLIP_ASYNC
.
-
DRM_CAP_CURSOR_WIDTH
DRM_CAP_CURSOR_WIDTH ()
Parameters
Description
The CURSOR_WIDTH
and CURSOR_HEIGHT
capabilities return a valid
width x height combination for the hardware cursor. The intention is that a
hardware agnostic userspace can query a cursor plane size to use.
Note that the cross-driver contract is to merely return a valid size;
drivers are free to attach another meaning on top, eg. i915 returns the
maximum plane size.
-
DRM_CAP_CURSOR_HEIGHT
DRM_CAP_CURSOR_HEIGHT ()
Parameters
Description
See DRM_CAP_CURSOR_WIDTH
.
-
DRM_CAP_ADDFB2_MODIFIERS
DRM_CAP_ADDFB2_MODIFIERS ()
Parameters
Description
If set to 1, the driver supports supplying modifiers in the
DRM_IOCTL_MODE_ADDFB2
ioctl.
-
DRM_CAP_PAGE_FLIP_TARGET
DRM_CAP_PAGE_FLIP_TARGET ()
Parameters
Description
If set to 1, the driver supports the DRM_MODE_PAGE_FLIP_TARGET_ABSOLUTE
and
DRM_MODE_PAGE_FLIP_TARGET_RELATIVE
flags in
drm_mode_crtc_page_flip_target.flags
for the DRM_IOCTL_MODE_PAGE_FLIP
ioctl.
-
DRM_CAP_CRTC_IN_VBLANK_EVENT
DRM_CAP_CRTC_IN_VBLANK_EVENT ()
Parameters
Description
If set to 1, the kernel supports reporting the CRTC ID in
drm_event_vblank.crtc_id
for the DRM_EVENT_VBLANK
and
DRM_EVENT_FLIP_COMPLETE
events.
Starting kernel version 4.12, this capability is always set to 1.
-
DRM_CAP_SYNCOBJ
DRM_CAP_SYNCOBJ ()
Parameters
Description
If set to 1, the driver supports sync objects. See
DRM Memory Management, section “DRM Sync Objects”.
-
DRM_CAP_SYNCOBJ_TIMELINE
DRM_CAP_SYNCOBJ_TIMELINE ()
Parameters
Description
If set to 1, the driver supports timeline operations on sync objects. See
DRM Memory Management, section “DRM Sync Objects”.
-
DRM_CLIENT_CAP_STEREO_3D
DRM_CLIENT_CAP_STEREO_3D ()
Parameters
Description
If set to 1, the DRM core will expose the stereo 3D capabilities of the
monitor by advertising the supported 3D layouts in the flags of struct
drm_mode_modeinfo
. See DRM_MODE_FLAG_3D_*
.
This capability is always supported for all drivers starting from kernel
version 3.13.
-
DRM_CLIENT_CAP_UNIVERSAL_PLANES
DRM_CLIENT_CAP_UNIVERSAL_PLANES ()
Parameters
Description
If set to 1, the DRM core will expose all planes (overlay, primary, and
cursor) to userspace.
This capability has been introduced in kernel version 3.15. Starting from
kernel version 3.17, this capability is always supported for all drivers.
-
DRM_CLIENT_CAP_ATOMIC
DRM_CLIENT_CAP_ATOMIC ()
Parameters
Description
If set to 1, the DRM core will expose atomic properties to userspace. This
implicitly enables DRM_CLIENT_CAP_UNIVERSAL_PLANES
and
DRM_CLIENT_CAP_ASPECT_RATIO
.
If the driver doesn’t support atomic mode-setting, enabling this capability
will fail with -EOPNOTSUPP.
This capability has been introduced in kernel version 4.0. Starting from
kernel version 4.2, this capability is always supported for atomic-capable
drivers.
-
DRM_CLIENT_CAP_ASPECT_RATIO
DRM_CLIENT_CAP_ASPECT_RATIO ()
Parameters
Description
If set to 1, the DRM core will provide aspect ratio information in modes.
See DRM_MODE_FLAG_PIC_AR_*
.
This capability is always supported for all drivers starting from kernel
version 4.18.
-
DRM_CLIENT_CAP_WRITEBACK_CONNECTORS
DRM_CLIENT_CAP_WRITEBACK_CONNECTORS ()
Parameters
Description
If set to 1, the DRM core will expose special connectors to be used for
writing back to memory the scene setup in the commit. The client must enable
DRM_CLIENT_CAP_ATOMIC
first.
This capability is always supported for atomic-capable drivers starting from
kernel version 4.19.
-
DRM_IOCTL_MODE_RMFB
DRM_IOCTL_MODE_RMFB ()
Parameters
Description
This removes a framebuffer previously added via ADDFB/ADDFB2. The IOCTL
argument is a framebuffer object ID.
Warning: removing a framebuffer currently in-use on an enabled plane will
disable that plane. The CRTC the plane is linked to may also be disabled
(depending on driver capabilities).
-
struct
drm_mode_modeinfo
Display mode information.
Definition
struct drm_mode_modeinfo {
__u32 clock;
__u16 hdisplay;
__u16 hsync_start;
__u16 hsync_end;
__u16 htotal;
__u16 hskew;
__u16 vdisplay;
__u16 vsync_start;
__u16 vsync_end;
__u16 vtotal;
__u16 vscan;
__u32 vrefresh;
__u32 flags;
__u32 type;
char name[DRM_DISPLAY_MODE_LEN];
};
Members
clock
pixel clock in kHz
hdisplay
horizontal display size
hsync_start
horizontal sync start
hsync_end
horizontal sync end
htotal
horizontal total size
hskew
horizontal skew
vdisplay
vertical display size
vsync_start
vertical sync start
vsync_end
vertical sync end
vtotal
vertical total size
vscan
vertical scan
vrefresh
approximate vertical refresh rate in Hz
flags
bitmask of misc. flags, see DRM_MODE_FLAG_* defines
type
bitmask of type flags, see DRM_MODE_TYPE_* defines
name
string describing the mode resolution
Description
This is the user-space API display mode information structure. For the
kernel version see struct drm_display_mode
.
-
struct
drm_mode_get_plane
Get plane metadata.
Definition
struct drm_mode_get_plane {
__u32 plane_id;
__u32 crtc_id;
__u32 fb_id;
__u32 possible_crtcs;
__u32 gamma_size;
__u32 count_format_types;
__u64 format_type_ptr;
};
Members
plane_id
Object ID of the plane whose information should be
retrieved. Set by caller.
crtc_id
Object ID of the current CRTC.
fb_id
Object ID of the current fb.
possible_crtcs
Bitmask of CRTC’s compatible with the plane. CRTC’s
are created and they receive an index, which corresponds to their
position in the bitmask. Bit N corresponds to
CRTC index N.
gamma_size
Never used.
count_format_types
Number of formats.
format_type_ptr
Pointer to __u32
array of formats that are
supported by the plane. These formats do not require modifiers.
Description
Userspace can perform a GETPLANE ioctl to retrieve information about a
plane.
To retrieve the number of formats supported, set count_format_types to zero
and call the ioctl. count_format_types will be updated with the value.
To retrieve these formats, allocate an array with the memory needed to store
count_format_types formats. Point format_type_ptr to this array and call
the ioctl again (with count_format_types still set to the value returned in
the first ioctl call).
-
struct
drm_mode_get_connector
Get connector metadata.
Definition
struct drm_mode_get_connector {
__u64 encoders_ptr;
__u64 modes_ptr;
__u64 props_ptr;
__u64 prop_values_ptr;
__u32 count_modes;
__u32 count_props;
__u32 count_encoders;
__u32 encoder_id;
__u32 connector_id;
__u32 connector_type;
__u32 connector_type_id;
__u32 connection;
__u32 mm_width;
__u32 mm_height;
__u32 subpixel;
__u32 pad;
};
Members
encoders_ptr
Pointer to __u32
array of object IDs.
modes_ptr
Pointer to struct drm_mode_modeinfo
array.
props_ptr
Pointer to __u32
array of property IDs.
prop_values_ptr
Pointer to __u64
array of property values.
count_modes
Number of modes.
count_props
Number of properties.
count_encoders
Number of encoders.
encoder_id
Object ID of the current encoder.
connector_id
Object ID of the connector.
connector_type
Type of the connector.
See DRM_MODE_CONNECTOR_* defines.
connector_type_id
Type-specific connector number.
This is not an object ID. This is a per-type connector number. Each
(type, type_id) combination is unique across all connectors of a DRM
device.
connection
Status of the connector.
See enum drm_connector_status
.
mm_width
Width of the connected sink in millimeters.
mm_height
Height of the connected sink in millimeters.
subpixel
Subpixel order of the connected sink.
See enum subpixel_order.
pad
Padding, must be zero.
Description
User-space can perform a GETCONNECTOR ioctl to retrieve information about a
connector. User-space is expected to retrieve encoders, modes and properties
by performing this ioctl at least twice: the first time to retrieve the
number of elements, the second time to retrieve the elements themselves.
To retrieve the number of elements, set count_props and count_encoders to
zero, set count_modes to 1, and set modes_ptr to a temporary struct
drm_mode_modeinfo
element.
To retrieve the elements, allocate arrays for encoders_ptr, modes_ptr,
props_ptr and prop_values_ptr, then set count_modes, count_props and
count_encoders to their capacity.
Performing the ioctl only twice may be racy: the number of elements may have
changed with a hotplug event in-between the two ioctls. User-space is
expected to retry the last ioctl until the number of elements stabilizes.
The kernel won’t fill any array which doesn’t have the expected length.
Force-probing a connector
If the count_modes field is set to zero and the DRM client is the current
DRM master, the kernel will perform a forced probe on the connector to
refresh the connector status, modes and EDID. A forced-probe can be slow,
might cause flickering and the ioctl will block.
User-space needs to force-probe connectors to ensure their metadata is
up-to-date at startup and after receiving a hot-plug event. User-space
may perform a forced-probe when the user explicitly requests it. User-space
shouldn’t perform a forced-probe in other situations.
-
struct
drm_mode_property_enum
Description for an enum/bitfield entry.
Definition
struct drm_mode_property_enum {
__u64 value;
char name[DRM_PROP_NAME_LEN];
};
Members
value
numeric value for this enum entry.
name
symbolic name for this enum entry.
Description
See struct drm_property_enum
for details.
-
struct
drm_mode_get_property
Get property metadata.
Definition
struct drm_mode_get_property {
__u64 values_ptr;
__u64 enum_blob_ptr;
__u32 prop_id;
__u32 flags;
char name[DRM_PROP_NAME_LEN];
__u32 count_values;
__u32 count_enum_blobs;
};
Members
values_ptr
Pointer to a __u64
array.
enum_blob_ptr
Pointer to a struct drm_mode_property_enum
array.
prop_id
Object ID of the property which should be retrieved. Set
by the caller.
flags
DRM_MODE_PROP_*
bitfield. See drm_property.flags
for
a definition of the flags.
name
Symbolic property name. User-space should use this field to
recognize properties.
count_values
Number of elements in values_ptr.
count_enum_blobs
Number of elements in enum_blob_ptr.
Description
User-space can perform a GETPROPERTY ioctl to retrieve information about a
property. The same property may be attached to multiple objects, see
“Modeset Base Object Abstraction”.
The meaning of the values_ptr field changes depending on the property type.
See drm_property.flags
for more details.
The enum_blob_ptr and count_enum_blobs fields are only meaningful when the
property has the type DRM_MODE_PROP_ENUM
or DRM_MODE_PROP_BITMASK
. For
backwards compatibility, the kernel will always set count_enum_blobs to
zero when the property has the type DRM_MODE_PROP_BLOB
. User-space must
ignore these two fields if the property has a different type.
User-space is expected to retrieve values and enums by performing this ioctl
at least twice: the first time to retrieve the number of elements, the
second time to retrieve the elements themselves.
To retrieve the number of elements, set count_values and count_enum_blobs
to zero, then call the ioctl. count_values will be updated with the number
of elements. If the property has the type DRM_MODE_PROP_ENUM
or
DRM_MODE_PROP_BITMASK
, count_enum_blobs will be updated as well.
To retrieve the elements themselves, allocate an array for values_ptr and
set count_values to its capacity. If the property has the type
DRM_MODE_PROP_ENUM
or DRM_MODE_PROP_BITMASK
, allocate an array for
enum_blob_ptr and set count_enum_blobs to its capacity. Calling the ioctl
again will fill the arrays.
-
struct
hdr_metadata_infoframe
HDR Metadata Infoframe Data.
Definition
struct hdr_metadata_infoframe {
__u8 eotf;
__u8 metadata_type;
struct {
__u16 x, y;
} display_primaries[3];
struct {
__u16 x, y;
} white_point;
__u16 max_display_mastering_luminance;
__u16 min_display_mastering_luminance;
__u16 max_cll;
__u16 max_fall;
};
Members
eotf
Electro-Optical Transfer Function (EOTF)
used in the stream.
metadata_type
Static_Metadata_Descriptor_ID.
display_primaries
Color Primaries of the Data.
These are coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
display_primaries.x: X cordinate of color primary.
display_primaries.y: Y cordinate of color primary.
white_point
White Point of Colorspace Data.
These are coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
white_point.x: X cordinate of whitepoint of color primary.
white_point.y: Y cordinate of whitepoint of color primary.
max_display_mastering_luminance
Max Mastering Display Luminance.
This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
min_display_mastering_luminance
Min Mastering Display Luminance.
This value is coded as an unsigned 16-bit value in units of
0.0001 cd/m2, where 0x0001 represents 0.0001 cd/m2 and 0xFFFF
represents 6.5535 cd/m2.
max_cll
Max Content Light Level.
This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
max_fall
Max Frame Average Light Level.
This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
Description
HDR Metadata Infoframe as per CTA 861.G spec. This is expected
to match exactly with the spec.
Userspace is expected to pass the metadata information as per
the format described in this structure.
-
struct
hdr_output_metadata
HDR output metadata
Definition
struct hdr_output_metadata {
__u32 metadata_type;
union {
struct hdr_metadata_infoframe hdmi_metadata_type1;
};
};
Members
metadata_type
Static_Metadata_Descriptor_ID.
{unnamed_union}
anonymous
hdmi_metadata_type1
HDR Metadata Infoframe.
Description
Metadata Information to be passed from userspace
-
struct
drm_mode_create_blob
Create New blob property
Definition
struct drm_mode_create_blob {
__u64 data;
__u32 length;
__u32 blob_id;
};
Members
data
Pointer to data to copy.
length
Length of data to copy.
blob_id
Return: new property ID.
Description
Create a new ‘blob’ data property, copying length bytes from data pointer,
and returning new blob ID.
-
struct
drm_mode_destroy_blob
Destroy user blob
Definition
struct drm_mode_destroy_blob {
__u32 blob_id;
};
Members
blob_id
blob_id to destroy
Description
Destroy a user-created blob property.
User-space can release blobs as soon as they do not need to refer to them by
their blob object ID. For instance, if you are using a MODE_ID blob in an
atomic commit and you will not make another commit re-using the same ID, you
can destroy the blob as soon as the commit has been issued, without waiting
for it to complete.
-
struct
drm_mode_create_lease
Create lease
Definition
struct drm_mode_create_lease {
__u64 object_ids;
__u32 object_count;
__u32 flags;
__u32 lessee_id;
__u32 fd;
};
Members
object_ids
Pointer to array of object ids (__u32)
object_count
Number of object ids
flags
flags for new FD (O_CLOEXEC, etc)
lessee_id
Return: unique identifier for lessee.
fd
Return: file descriptor to new drm_master file
Description
Lease mode resources, creating another drm_master.
-
struct
drm_mode_list_lessees
List lessees
Definition
struct drm_mode_list_lessees {
__u32 count_lessees;
__u32 pad;
__u64 lessees_ptr;
};
Members
count_lessees
Number of lessees.
On input, provides length of the array.
On output, provides total number. No
more than the input number will be written
back, so two calls can be used to get
the size and then the data.
pad
Padding.
lessees_ptr
Pointer to lessees.
Pointer to __u64 array of lessee ids
Description
List lesses from a drm_master.
-
struct
drm_mode_get_lease
Get Lease
Definition
struct drm_mode_get_lease {
__u32 count_objects;
__u32 pad;
__u64 objects_ptr;
};
Members
count_objects
Number of leased objects.
On input, provides length of the array.
On output, provides total number. No
more than the input number will be written
back, so two calls can be used to get
the size and then the data.
pad
Padding.
objects_ptr
Pointer to objects.
Pointer to __u32 array of object ids.
Description
Get leased objects.
-
struct
drm_mode_revoke_lease
Revoke lease
Definition
struct drm_mode_revoke_lease {
__u32 lessee_id;
};
Members
lessee_id
Unique ID of lessee
-
struct
drm_mode_rect
Two dimensional rectangle.
Definition
struct drm_mode_rect {
__s32 x1;
__s32 y1;
__s32 x2;
__s32 y2;
};
Members
x1
Horizontal starting coordinate (inclusive).
y1
Vertical starting coordinate (inclusive).
x2
Horizontal ending coordinate (exclusive).
y2
Vertical ending coordinate (exclusive).
Description
With drm subsystem using struct drm_rect
to manage rectangular area this
export it to user-space.
Currently used by drm_mode_atomic blob property FB_DAMAGE_CLIPS.