DRM exposes many UAPI and structure definitions to have a consistent
and standardized interface with users.
Userspace can refer to these structure definitions and UAPI formats
to communicate to drivers.
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 ()
-
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 ()
-
DRM_PRIME_CAP_IMPORT
DRM_PRIME_CAP_IMPORT ()
-
DRM_PRIME_CAP_EXPORT
DRM_PRIME_CAP_EXPORT ()
-
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 ()
-
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 ()
-
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 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 Sync Objects.
-
DRM_CAP_ATOMIC_ASYNC_PAGE_FLIP
DRM_CAP_ATOMIC_ASYNC_PAGE_FLIP ()
-
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_CLIENT_CAP_CURSOR_PLANE_HOTSPOT
DRM_CLIENT_CAP_CURSOR_PLANE_HOTSPOT ()
Parameters
Description
Drivers for para-virtualized hardware (e.g. vmwgfx, qxl, virtio and
virtualbox) have additional restrictions for cursor planes (thus
making cursor planes on those drivers not truly universal,) e.g.
they need cursor planes to act like one would expect from a mouse
cursor and have correctly set hotspot properties.
If this client cap is not set the DRM core will hide cursor plane on
those virtualized drivers because not setting it implies that the
client is not capable of dealing with those extra restictions.
Clients which do set cursor hotspot and treat the cursor plane
like a mouse cursor should set this property.
The client must enable DRM_CLIENT_CAP_ATOMIC
first.
Setting this property on drivers which do not special case
cursor planes (i.e. non-virtualized drivers) will return
EOPNOTSUPP, which can be used by userspace to gauge
requirements of the hardware/drivers they’re running on.
This capability is always supported for atomic-capable virtualized
drivers starting from kernel version 6.6.
-
struct drm_syncobj_eventfd
Definition:
struct drm_syncobj_eventfd {
__u32 handle;
__u32 flags;
__u64 point;
__s32 fd;
__u32 pad;
};
Members
handle
syncobj handle.
flags
Zero to wait for the point to be signalled, or
DRM_SYNCOBJ_WAIT_FLAGS_WAIT_AVAILABLE
to wait for a fence to be
available for the point.
point
syncobj timeline point (set to zero for binary syncobjs).
fd
Existing eventfd to sent events to.
pad
Must be zero.
Description
Register an eventfd to be signalled by a syncobj. The eventfd counter will
be incremented by one.
-
DRM_IOCTL_GEM_CLOSE
DRM_IOCTL_GEM_CLOSE ()
Parameters
Description
GEM handles are not reference-counted by the kernel. User-space is
responsible for managing their lifetime. For example, if user-space imports
the same memory object twice on the same DRM file description, the same GEM
handle is returned by both imports, and user-space needs to ensure
DRM_IOCTL_GEM_CLOSE
is performed once only. The same situation can happen
when a memory object is allocated, then exported and imported again on the
same DRM file description. The DRM_IOCTL_MODE_GETFB2
IOCTL is an exception
and always returns fresh new GEM handles even if an existing GEM handle
already refers to the same memory object before the IOCTL is performed.
-
DRM_IOCTL_PRIME_HANDLE_TO_FD
DRM_IOCTL_PRIME_HANDLE_TO_FD ()
Convert a GEM handle to a DMA-BUF FD.
Parameters
Description
User-space sets drm_prime_handle.handle
with the GEM handle to export and
drm_prime_handle.flags
, and gets back a DMA-BUF file descriptor in
drm_prime_handle.fd
.
The export can fail for any driver-specific reason, e.g. because export is
not supported for this specific GEM handle (but might be for others).
Support for exporting DMA-BUFs is advertised via DRM_PRIME_CAP_EXPORT
.
-
DRM_IOCTL_PRIME_FD_TO_HANDLE
DRM_IOCTL_PRIME_FD_TO_HANDLE ()
Convert a DMA-BUF FD to a GEM handle.
Parameters
Description
User-space sets drm_prime_handle.fd
with a DMA-BUF file descriptor to
import, and gets back a GEM handle in drm_prime_handle.handle
.
drm_prime_handle.flags
is unused.
If an existing GEM handle refers to the memory object backing the DMA-BUF,
that GEM handle is returned. Therefore user-space which needs to handle
arbitrary DMA-BUFs must have a user-space lookup data structure to manually
reference-count duplicated GEM handles. For more information see
DRM_IOCTL_GEM_CLOSE
.
The import can fail for any driver-specific reason, e.g. because import is
only supported for DMA-BUFs allocated on this DRM device.
Support for importing DMA-BUFs is advertised via DRM_PRIME_CAP_IMPORT
.
-
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).
-
DRM_IOCTL_MODE_CREATE_DUMB
DRM_IOCTL_MODE_CREATE_DUMB ()
Create a new dumb buffer object.
Parameters
Description
KMS dumb buffers provide a very primitive way to allocate a buffer object
suitable for scanout and map it for software rendering. KMS dumb buffers are
not suitable for hardware-accelerated rendering nor video decoding. KMS dumb
buffers are not suitable to be displayed on any other device than the KMS
device where they were allocated from. Also see
Dumb Buffer Objects.
The IOCTL argument is a struct drm_mode_create_dumb
.
User-space is expected to create a KMS dumb buffer via this IOCTL, then add
it as a KMS framebuffer via DRM_IOCTL_MODE_ADDFB
and map it via
DRM_IOCTL_MODE_MAP_DUMB
.
DRM_CAP_DUMB_BUFFER
indicates whether this IOCTL is supported.
DRM_CAP_DUMB_PREFERRED_DEPTH
and DRM_CAP_DUMB_PREFER_SHADOW
indicate
driver preferences for dumb buffers.
-
DRM_IOCTL_MODE_GETFB2
DRM_IOCTL_MODE_GETFB2 ()
Get framebuffer metadata.
Parameters
Description
This queries metadata about a framebuffer. User-space fills
drm_mode_fb_cmd2.fb_id
as the input, and the kernels fills the rest of the
struct as the output.
If the client is DRM master or has CAP_SYS_ADMIN
, drm_mode_fb_cmd2.handles
will be filled with GEM buffer handles. Fresh new GEM handles are always
returned, even if another GEM handle referring to the same memory object
already exists on the DRM file description. The caller is responsible for
removing the new handles, e.g. via the DRM_IOCTL_GEM_CLOSE
IOCTL. The same
new handle will be returned for multiple planes in case they use the same
memory object. Planes are valid until one has a zero handle -- this can be
used to compute the number of planes.
Otherwise, drm_mode_fb_cmd2.handles
will be zeroed and planes are valid
until one has a zero drm_mode_fb_cmd2.pitches
.
If the framebuffer has a format modifier, DRM_MODE_FB_MODIFIERS
will be set
in drm_mode_fb_cmd2.flags
and drm_mode_fb_cmd2.modifier
will contain the
modifier. Otherwise, user-space must ignore drm_mode_fb_cmd2.modifier
.
To obtain DMA-BUF FDs for each plane without leaking GEM handles, user-space
can export each handle via DRM_IOCTL_PRIME_HANDLE_TO_FD
, then immediately
close each unique handle via DRM_IOCTL_GEM_CLOSE
, making sure to not
double-close handles which are specified multiple times in the array.
-
DRM_IOCTL_MODE_CLOSEFB
DRM_IOCTL_MODE_CLOSEFB ()
Parameters
Description
This closes a framebuffer previously added via ADDFB/ADDFB2. The IOCTL
argument is a framebuffer object ID.
This IOCTL is similar to DRM_IOCTL_MODE_RMFB
, except it doesn’t disable
planes and CRTCs. As long as the framebuffer is used by a plane, it’s kept
alive. When the plane no longer uses the framebuffer (because the
framebuffer is replaced with another one, or the plane is disabled), the
framebuffer is cleaned up.
This is useful to implement flicker-free transitions between two processes.
Depending on the threat model, user-space may want to ensure that the
framebuffer doesn’t expose any sensitive user information: closed
framebuffers attached to a plane can be read back by the next DRM master.
-
struct drm_event
Header for DRM events
Definition:
struct drm_event {
__u32 type;
__u32 length;
};
Members
type
event type.
length
total number of payload bytes (including header).
Description
This struct is a header for events written back to user-space on the DRM FD.
A read on the DRM FD will always only return complete events: e.g. if the
read buffer is 100 bytes large and there are two 64 byte events pending,
only one will be returned.
Event types 0 - 0x7fffffff are generic DRM events, 0x80000000 and
up are chipset specific. Generic DRM events include DRM_EVENT_VBLANK
,
DRM_EVENT_FLIP_COMPLETE
and DRM_EVENT_CRTC_SEQUENCE
.
-
DRM_EVENT_VBLANK
DRM_EVENT_VBLANK ()
Parameters
Description
This event is sent in response to DRM_IOCTL_WAIT_VBLANK
with the
_DRM_VBLANK_EVENT
flag set.
The event payload is a struct drm_event_vblank.
-
DRM_EVENT_FLIP_COMPLETE
DRM_EVENT_FLIP_COMPLETE ()
page-flip completion event
Parameters
Description
This event is sent in response to an atomic commit or legacy page-flip with
the DRM_MODE_PAGE_FLIP_EVENT
flag set.
The event payload is a struct drm_event_vblank.
-
DRM_EVENT_CRTC_SEQUENCE
DRM_EVENT_CRTC_SEQUENCE ()
Parameters
Description
This event is sent in response to DRM_IOCTL_CRTC_QUEUE_SEQUENCE
.
The event payload is a struct drm_event_crtc_sequence.
-
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.
The (type, type_id) combination is not a stable identifier: the
type_id can change depending on the driver probe order.
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 drm_mode_fb_cmd2
Frame-buffer metadata.
Definition:
struct drm_mode_fb_cmd2 {
__u32 fb_id;
__u32 width;
__u32 height;
__u32 pixel_format;
__u32 flags;
__u32 handles[4];
__u32 pitches[4];
__u32 offsets[4];
__u64 modifier[4];
};
Members
fb_id
Object ID of the frame-buffer.
width
Width of the frame-buffer.
height
Height of the frame-buffer.
pixel_format
FourCC format code, see DRM_FORMAT_*
constants in
drm_fourcc.h
.
flags
Frame-buffer flags (see DRM_MODE_FB_INTERLACED
and
DRM_MODE_FB_MODIFIERS
).
handles
GEM buffer handle, one per plane. Set to 0 if the plane is
unused. The same handle can be used for multiple planes.
pitches
Pitch (aka. stride) in bytes, one per plane.
offsets
Offset into the buffer in bytes, one per plane.
modifier
Format modifier, one per plane. See DRM_FORMAT_MOD_*
constants in drm_fourcc.h
. All planes must use the same
modifier. Ignored unless DRM_MODE_FB_MODIFIERS
is set in flags.
Description
This struct holds frame-buffer metadata. There are two ways to use it:
User-space can fill this struct and perform a DRM_IOCTL_MODE_ADDFB2
ioctl to register a new frame-buffer. The new frame-buffer object ID will
be set by the kernel in fb_id.
User-space can set fb_id and perform a DRM_IOCTL_MODE_GETFB2
ioctl to
fetch metadata about an existing frame-buffer.
In case of planar formats, this struct allows up to 4 buffer objects with
offsets and pitches per plane. The pitch and offset order are dictated by
the format FourCC as defined by drm_fourcc.h
, e.g. NV12 is described as:
YUV 4:2:0 image with a plane of 8-bit Y samples followed by an
interleaved U/V plane containing 8-bit 2x2 subsampled colour difference
samples.
So it would consist of a Y plane at offsets[0]
and a UV plane at
offsets[1]
.
To accommodate tiled, compressed, etc formats, a modifier can be specified.
For more information see the “Format Modifiers” section. Note that even
though it looks like we have a modifier per-plane, we in fact do not. The
modifier for each plane must be identical. Thus all combinations of
different data layouts for multi-plane formats must be enumerated as
separate modifiers.
All of the entries in handles, pitches, offsets and modifier must be
zero when unused. Warning, for offsets and modifier zero can’t be used to
figure out whether the entry is used or not since it’s a valid value (a zero
offset is common, and a zero modifier is DRM_FORMAT_MOD_LINEAR
).
-
struct drm_plane_size_hint
Plane size hints
Definition:
struct drm_plane_size_hint {
__u16 width;
__u16 height;
};
Members
Description
The plane SIZE_HINTS property blob contains an
array of struct drm_plane_size_hint
.
-
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 coordinate of color primary.
display_primaries.y: Y coordinate 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 coordinate of whitepoint of color primary.
white_point.y: Y coordinate 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
-
DRM_MODE_PAGE_FLIP_EVENT
DRM_MODE_PAGE_FLIP_EVENT ()
Parameters
Description
Request that the kernel sends back a vblank event (see
struct drm_event_vblank) with the DRM_EVENT_FLIP_COMPLETE
type when the
page-flip is done.
-
DRM_MODE_PAGE_FLIP_ASYNC
DRM_MODE_PAGE_FLIP_ASYNC ()
Parameters
Description
Request that the page-flip is performed as soon as possible, ie. with no
delay due to waiting for vblank. This may cause tearing to be visible on
the screen.
When used with atomic uAPI, the driver will return an error if the hardware
doesn’t support performing an asynchronous page-flip for this update.
User-space should handle this, e.g. by falling back to a regular page-flip.
Note, some hardware might need to perform one last synchronous page-flip
before being able to switch to asynchronous page-flips. As an exception,
the driver will return success even though that first page-flip is not
asynchronous.
-
DRM_MODE_PAGE_FLIP_FLAGS
DRM_MODE_PAGE_FLIP_FLAGS ()
Parameters
Description
Bitmask of flags suitable for drm_mode_crtc_page_flip_target.flags
.
-
struct drm_mode_create_dumb
Create a KMS dumb buffer for scanout.
Definition:
struct drm_mode_create_dumb {
__u32 height;
__u32 width;
__u32 bpp;
__u32 flags;
__u32 handle;
__u32 pitch;
__u64 size;
};
Members
height
buffer height in pixels
width
buffer width in pixels
bpp
bits per pixel
flags
must be zero
handle
buffer object handle
pitch
number of bytes between two consecutive lines
size
size of the whole buffer in bytes
Description
User-space fills height, width, bpp and flags. If the IOCTL succeeds,
the kernel fills handle, pitch and size.
-
DRM_MODE_ATOMIC_TEST_ONLY
DRM_MODE_ATOMIC_TEST_ONLY ()
Parameters
Description
Do not apply the atomic commit, instead check whether the hardware supports
this configuration.
See drm_mode_config_funcs.atomic_check
for more details on test-only
commits.
-
DRM_MODE_ATOMIC_NONBLOCK
DRM_MODE_ATOMIC_NONBLOCK ()
Parameters
Description
Do not block while applying the atomic commit. The DRM_IOCTL_MODE_ATOMIC
IOCTL returns immediately instead of waiting for the changes to be applied
in hardware. Note, the driver will still check that the update can be
applied before retuning.
-
DRM_MODE_ATOMIC_ALLOW_MODESET
DRM_MODE_ATOMIC_ALLOW_MODESET ()
Parameters
Description
Allow the update to result in temporary or transient visible artifacts while
the update is being applied. Applying the update may also take significantly
more time than a page flip. All visual artifacts will disappear by the time
the update is completed, as signalled through the vblank event’s timestamp
(see struct drm_event_vblank).
This flag must be set when the KMS update might cause visible artifacts.
Without this flag such KMS update will return a EINVAL error. What kind of
update may cause visible artifacts depends on the driver and the hardware.
User-space that needs to know beforehand if an update might cause visible
artifacts can use DRM_MODE_ATOMIC_TEST_ONLY
without
DRM_MODE_ATOMIC_ALLOW_MODESET
to see if it fails.
To the best of the driver’s knowledge, visual artifacts are guaranteed to
not appear when this flag is not set. Some sinks might display visual
artifacts outside of the driver’s control.
-
DRM_MODE_ATOMIC_FLAGS
DRM_MODE_ATOMIC_FLAGS ()
Parameters
Description
Bitfield of flags accepted by the DRM_IOCTL_MODE_ATOMIC
IOCTL in
drm_mode_atomic.flags
.
-
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.
The object_ids array must reference at least one CRTC, one connector and
one plane if DRM_CLIENT_CAP_UNIVERSAL_PLANES
is enabled. Alternatively,
the lease can be completely empty.
-
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.
-
struct drm_mode_closefb
Definition:
struct drm_mode_closefb {
__u32 fb_id;
__u32 pad;
};
Members
fb_id
Framebuffer ID.
pad
Must be zero.