Kernel Mode Setting (KMS)¶

Drivers must initialize the mode setting core by callingdrmm_mode_config_init() on the DRM device. The functioninitializes thestructdrm_devicemode_config field and never fails. Once done, mode configuration mustbe setup by initializing the following fields.

int min_width, min_height; int max_width, max_height;Minimum and maximum width and height of the frame buffers in pixelunits.
struct drm_mode_config_funcs *funcs;Mode setting functions.

Overview¶

KMS Display Pipeline Overview

The basic object structure KMS presents to userspace is fairly simple.Framebuffers (represented bystructdrm_framebuffer,seeFrame Buffer Abstraction) feed into planes. Planes are represented bystructdrm_plane, seePlane Abstraction for moredetails. One or more (or even no) planes feed their pixel data into a CRTC(represented bystructdrm_crtc, seeCRTC Abstraction)for blending. The precise blending step is explained in more detail inPlaneComposition Properties and related chapters.

For the output routing the first step is encoders (represented bystructdrm_encoder, seeEncoder Abstraction). Thoseare really just internal artifacts of the helper libraries used to implement KMSdrivers. Besides that they make it unecessarily more complicated for userspaceto figure out which connections between a CRTC and a connector are possible, andwhat kind of cloning is supported, they serve no purpose in the userspace API.Unfortunately encoders have been exposed to userspace, hence can’t remove themat this point. Futhermore the exposed restrictions are often wrongly set bydrivers, and in many cases not powerful enough to express the real restrictions.A CRTC can be connected to multiple encoders, and for an active CRTC there mustbe at least one encoder.

The final, and real, endpoint in the display chain is the connector (representedbystructdrm_connector, seeConnectorAbstraction). Connectors can have different possible encoders, but the kerneldriver selects which encoder to use for each connector. The use case is DVI,which could switch between an analog and a digital encoder. Encoders can alsodrive multiple different connectors. There is exactly one active connector forevery active encoder.

Internally the output pipeline is a bit more complex and matches today’shardware more closely:

KMS Output Pipeline

Internally two additional helper objects come into play. First, to be able toshare code for encoders (sometimes on the same SoC, sometimes off-chip) one ormoreBridges (represented bystructdrm_bridge) can be linked to an encoder. This link is static and cannot bechanged, which means the cross-bar (if there is any) needs to be mapped betweenthe CRTC and any encoders. Often for drivers with bridges there’s no code leftat the encoder level. Atomic drivers can leave out all the encoder callbacks toessentially only leave a dummy routing object behind, which is needed forbackwards compatibility since encoders are exposed to userspace.

The second object is for panels, represented bystructdrm_panel, seePanel Helper Reference. Panels do not have a fixed bindingpoint, but are generally linked to the driver private structure that embedsstructdrm_connector.

Note that currently the bridge chaining and interactions with connectors andpanels are still in-flux and not really fully sorted out yet.

KMS Core Structures and Functions¶

structdrm_mode_config_funcs¶: basic driver provided mode setting functions

Definition

struct drm_mode_config_funcs {  struct drm_framebuffer *(*fb_create)(struct drm_device *dev,struct drm_file *file_priv, const struct drm_mode_fb_cmd2 *mode_cmd);  const struct drm_format_info *(*get_format_info)(const struct drm_mode_fb_cmd2 *mode_cmd);  void (*output_poll_changed)(struct drm_device *dev);  enum drm_mode_status (*mode_valid)(struct drm_device *dev, const struct drm_display_mode *mode);  int (*atomic_check)(struct drm_device *dev, struct drm_atomic_state *state);  int (*atomic_commit)(struct drm_device *dev,struct drm_atomic_state *state, bool nonblock);  struct drm_atomic_state *(*atomic_state_alloc)(struct drm_device *dev);  void (*atomic_state_clear)(struct drm_atomic_state *state);  void (*atomic_state_free)(struct drm_atomic_state *state);};

Members

fb_create

Create a new framebuffer object. The core does basic checks on therequested metadata, but most of that is left to the driver. Seestructdrm_mode_fb_cmd2 for details.

To validate the pixel format and modifier drivers can usedrm_any_plane_has_format() to make sure at least one plane supportsthe requested values. Note that the driver must first determine theactual modifier used if the request doesn’t have it specified,ie. when (mode_cmd->flags & DRM_MODE_FB_MODIFIERS) == 0.

If the parameters are deemed valid and the backing storage objects inthe underlying memory manager all exist, then the driver allocatesa newdrm_framebuffer structure, subclassed to containdriver-specific information (like the internal native buffer objectreferences). It also needs to fill out all relevant metadata, whichshould be done by callingdrm_helper_mode_fill_fb_struct().

The initialization is finalized by callingdrm_framebuffer_init(),which registers the framebuffer and makes it accessible to otherthreads.

RETURNS:

A new framebuffer with an initial reference count of 1 or a negativeerror code encoded with ERR_PTR().

get_format_info

Allows a driver to return custom format information for specialfb layouts (eg. ones with auxiliary compression control planes).

RETURNS:

The format information specific to the given fb metadata, orNULL if none is found.

output_poll_changed

Callback used by helpers to inform the driver of output configurationchanges.

Drivers implementing fbdev emulation with the helpers can calldrm_fb_helper_hotplug_changed from this hook to inform the fbdevhelper of output changes.

FIXME:

Except that there’s no vtable for device-level helper callbacksthere’s no reason this is a core function.

mode_valid

Device specific validation of display modes. Can be used to rejectmodes that can never be supported. Only device wide constraints canbe checked here. crtc/encoder/bridge/connector specific constraintsshould be checked in the .mode_valid() hook for each specific object.

atomic_check

This is the only hook to validate an atomic modeset update. Thisfunction must reject any modeset and state changes which the hardwareor driver doesn’t support. This includes but is of course not limitedto:

Checking that the modes, framebuffers, scaling and placementrequirements and so on are within the limits of the hardware.
Checking that any hidden shared resources are not oversubscribed.This can be shared PLLs, shared lanes, overall memory bandwidth,display fifo space (where shared between planes or maybe evenCRTCs).
Checking that virtualized resources exported to userspace are notoversubscribed. For various reasons it can make sense to exposemore planes, crtcs or encoders than which are physically there. Oneexample is dual-pipe operations (which generally should be hiddenfrom userspace if when lockstepped in hardware, exposed otherwise),where a plane might need 1 hardware plane (if it’s just on onepipe), 2 hardware planes (when it spans both pipes) or maybe evenshared a hardware plane with a 2nd plane (if there’s a compatibleplane requested on the area handled by the other pipe).
Check that any transitional state is possible and that ifrequested, the update can indeed be done in the vblank periodwithout temporarily disabling some functions.
Check any other constraints the driver or hardware might have.
This callback also needs to correctly fill out thedrm_crtc_statein this update to make sure thatdrm_atomic_crtc_needs_modeset()reflects the nature of the possible update and returns true if andonly if the update cannot be applied without tearing within onevblank on that CRTC. The core uses that information to rejectupdates which require a full modeset (i.e. blanking the screen, orat least pausing updates for a substantial amount of time) ifuserspace has disallowed that in its request.
The driver also does not need to repeat basic input validationlike done for the corresponding legacy entry points. The core doesthat before calling this hook.

See the documentation ofatomic_commit for an exhaustive list oferror conditions which don’t have to be checked at the in thiscallback.

See the documentation forstructdrm_atomic_state for how exactlyan atomic modeset update is described.

Drivers using the atomic helpers can implement this hook usingdrm_atomic_helper_check(), or one of the exported sub-functions ofit.

RETURNS:

0 on success or one of the below negative error codes:

-EINVAL, if any of the above constraints are violated.
-EDEADLK, when returned from an attempt to acquire an additionaldrm_modeset_lock throughdrm_modeset_lock().
-ENOMEM, if allocating additional state sub-structures failed dueto lack of memory.
-EINTR, -EAGAIN or -ERESTARTSYS, if the IOCTL should be restarted.This can either be due to a pending signal, or because the driverneeds to completely bail out to recover from an exceptionalsituation like a GPU hang. From a userspace point all errors aretreated equally.

atomic_commit

This is the only hook to commit an atomic modeset update. The coreguarantees thatatomic_check has been called successfully beforecalling this function, and that nothing has been changed in theinterim.

See the documentation forstructdrm_atomic_state for how exactlyan atomic modeset update is described.

Drivers using the atomic helpers can implement this hook usingdrm_atomic_helper_commit(), or one of the exported sub-functions ofit.

Nonblocking commits (as indicated with the nonblock parameter) mustdo any preparatory work which might result in an unsuccessful commitin the context of this callback. The only exceptions are hardwareerrors resulting in -EIO. But even in that case the driver mustensure that the display pipe is at least running, to avoidcompositors crashing when pageflips don’t work. Anything else,specifically committing the update to the hardware, should be donewithout blocking the caller. For updates which do not require amodeset this must be guaranteed.

The driver must wait for any pending rendering to the newframebuffers to complete before executing the flip. It should alsowait for any pending rendering from other drivers if the underlyingbuffer is a shared dma-buf. Nonblocking commits must not wait forrendering in the context of this callback.

An application can request to be notified when the atomic commit hascompleted. These events are per-CRTC and can be distinguished by theCRTC index supplied indrm_event to userspace.

The drm core will supply astructdrm_event in each CRTC’sdrm_crtc_state.event. See the documentation fordrm_crtc_state.event for more details about the precise semantics ofthis event.

NOTE:

Drivers are not allowed to shut down any display pipe successfullyenabled through an atomic commit on their own. Doing so can result incompositors crashing if a page flip is suddenly rejected because thepipe is off.

RETURNS:

0 on success or one of the below negative error codes:

-EBUSY, if a nonblocking updated is requested and there isan earlier updated pending. Drivers are allowed to support a queueof outstanding updates, but currently no driver supports that.Note that drivers must wait for preceding updates to complete if asynchronous update is requested, they are not allowed to fail thecommit in that case.
-ENOMEM, if the driver failed to allocate memory. Specificallythis can happen when trying to pin framebuffers, which must onlybe done when committing the state.
-ENOSPC, as a refinement of the more generic -ENOMEM to indicatethat the driver has run out of vram, iommu space or similar GPUaddress space needed for framebuffer.
-EIO, if the hardware completely died.
-EINTR, -EAGAIN or -ERESTARTSYS, if the IOCTL should be restarted.This can either be due to a pending signal, or because the driverneeds to completely bail out to recover from an exceptionalsituation like a GPU hang. From a userspace point of view all errors aretreated equally.

This list is exhaustive. Specifically this hook is not allowed toreturn -EINVAL (any invalid requests should be caught inatomic_check) or -EDEADLK (this function must not acquireadditional modeset locks).

atomic_state_alloc

This optional hook can be used by drivers that want to subclass structdrm_atomic_state to be able to track their own driver-private globalstate easily. If this hook is implemented, drivers must alsoimplementatomic_state_clear andatomic_state_free.

Subclassing ofdrm_atomic_state is deprecated in favour of usingdrm_private_state anddrm_private_obj.

RETURNS:

A newdrm_atomic_state on success or NULL on failure.

atomic_state_clear

This hook must clear any driver private state duplicated into thepassed-indrm_atomic_state. This hook is called when the callerencountered adrm_modeset_lock deadlock and needs to drop allalready acquired locks as part of the deadlock avoidance danceimplemented indrm_modeset_backoff().

Any duplicated state must be invalidated since a concurrent atomicupdate might change it, and the drm atomic interfaces always applyupdates as relative changes to the current state.

Drivers that implement this must calldrm_atomic_state_default_clear()to clear common state.

Subclassing ofdrm_atomic_state is deprecated in favour of usingdrm_private_state anddrm_private_obj.

atomic_state_free

This hook needs driver private resources and thedrm_atomic_stateitself. Note that the core first callsdrm_atomic_state_clear() toavoid code duplicate between the clear and free hooks.

Drivers that implement this must calldrm_atomic_state_default_release() to release common resources.

Subclassing ofdrm_atomic_state is deprecated in favour of usingdrm_private_state anddrm_private_obj.

Description

Some global (i.e. not per-CRTC, connector, etc) mode setting functions thatinvolve drivers.

structdrm_mode_config¶: Mode configuration control structure

Definition

struct drm_mode_config {  struct mutex mutex;  struct drm_modeset_lock connection_mutex;  struct drm_modeset_acquire_ctx *acquire_ctx;  struct mutex idr_mutex;  struct idr object_idr;  struct idr tile_idr;  struct mutex fb_lock;  int num_fb;  struct list_head fb_list;  spinlock_t connector_list_lock;  int num_connector;  struct ida connector_ida;  struct list_head connector_list;  struct llist_head connector_free_list;  struct work_struct connector_free_work;  int num_encoder;  struct list_head encoder_list;  int num_total_plane;  struct list_head plane_list;  int num_crtc;  struct list_head crtc_list;  struct list_head property_list;  struct list_head privobj_list;  int min_width, min_height;  int max_width, max_height;  const struct drm_mode_config_funcs *funcs;  resource_size_t fb_base;  bool poll_enabled;  bool poll_running;  bool delayed_event;  struct delayed_work output_poll_work;  struct mutex blob_lock;  struct list_head property_blob_list;  struct drm_property *edid_property;  struct drm_property *dpms_property;  struct drm_property *path_property;  struct drm_property *tile_property;  struct drm_property *link_status_property;  struct drm_property *plane_type_property;  struct drm_property *prop_src_x;  struct drm_property *prop_src_y;  struct drm_property *prop_src_w;  struct drm_property *prop_src_h;  struct drm_property *prop_crtc_x;  struct drm_property *prop_crtc_y;  struct drm_property *prop_crtc_w;  struct drm_property *prop_crtc_h;  struct drm_property *prop_fb_id;  struct drm_property *prop_in_fence_fd;  struct drm_property *prop_out_fence_ptr;  struct drm_property *prop_crtc_id;  struct drm_property *prop_fb_damage_clips;  struct drm_property *prop_active;  struct drm_property *prop_mode_id;  struct drm_property *prop_vrr_enabled;  struct drm_property *dvi_i_subconnector_property;  struct drm_property *dvi_i_select_subconnector_property;  struct drm_property *tv_subconnector_property;  struct drm_property *tv_select_subconnector_property;  struct drm_property *tv_mode_property;  struct drm_property *tv_left_margin_property;  struct drm_property *tv_right_margin_property;  struct drm_property *tv_top_margin_property;  struct drm_property *tv_bottom_margin_property;  struct drm_property *tv_brightness_property;  struct drm_property *tv_contrast_property;  struct drm_property *tv_flicker_reduction_property;  struct drm_property *tv_overscan_property;  struct drm_property *tv_saturation_property;  struct drm_property *tv_hue_property;  struct drm_property *scaling_mode_property;  struct drm_property *aspect_ratio_property;  struct drm_property *content_type_property;  struct drm_property *degamma_lut_property;  struct drm_property *degamma_lut_size_property;  struct drm_property *ctm_property;  struct drm_property *gamma_lut_property;  struct drm_property *gamma_lut_size_property;  struct drm_property *suggested_x_property;  struct drm_property *suggested_y_property;  struct drm_property *non_desktop_property;  struct drm_property *panel_orientation_property;  struct drm_property *writeback_fb_id_property;  struct drm_property *writeback_pixel_formats_property;  struct drm_property *writeback_out_fence_ptr_property;  struct drm_property *hdr_output_metadata_property;  struct drm_property *content_protection_property;  struct drm_property *hdcp_content_type_property;  uint32_t preferred_depth, prefer_shadow;  bool prefer_shadow_fbdev;  bool fbdev_use_iomem;  bool quirk_addfb_prefer_xbgr_30bpp;  bool quirk_addfb_prefer_host_byte_order;  bool async_page_flip;  bool allow_fb_modifiers;  bool normalize_zpos;  struct drm_property *modifiers_property;  uint32_t cursor_width, cursor_height;  struct drm_atomic_state *suspend_state;  const struct drm_mode_config_helper_funcs *helper_private;};

Members

mutex

This is the big scary modeset BKL which protects everything thatisn’t protect otherwise. Scope is unclear and fuzzy, try to removeanything from under its protection and move it into more well-scopedlocks.

The one important thing this protects is the use ofacquire_ctx.

connection_mutex

This protects connector state and the connector to encoder to CRTCrouting chain.

For atomic drivers specifically this protectsdrm_connector.state.

acquire_ctx

Global implicit acquire context used by atomic drivers for legacyIOCTLs. Deprecated, since implicit locking contexts make itimpossible to use driver-privatestructdrm_modeset_lock. Users ofthis must holdmutex.

idr_mutex

Mutex for KMS ID allocation and management. Protects bothobject_idrandtile_idr.

object_idr

Main KMS ID tracking object. Use this idr for all IDs, fb, crtc,connector, modes - just makes life easier to have only one.

tile_idr

Use this idr for allocating new IDs for tiled sinks like use in somehigh-res DP MST screens.

fb_lock

Mutex to protect fb the globalfb_list andnum_fb.

num_fb

Number of entries onfb_list.

fb_list

List of allstructdrm_framebuffer.

connector_list_lock

Protectsnum_connector andconnector_list andconnector_free_list.

num_connector

Number of connectors on this device. Protected byconnector_list_lock.

connector_ida

ID allocator for connector indices.

connector_list

List of connector objects linked withdrm_connector.head. Protectedbyconnector_list_lock. Only usedrm_for_each_connector_iter() andstructdrm_connector_list_iter to walk this list.

connector_free_list

List of connector objects linked withdrm_connector.free_head.Protected byconnector_list_lock. Used bydrm_for_each_connector_iter() andstructdrm_connector_list_iter to savely free connectors usingconnector_free_work.

connector_free_work

Work to clean upconnector_free_list.

num_encoder

Number of encoders on this device. This is invariant over thelifetime of a device and hence doesn’t need any locks.

encoder_list

List of encoder objects linked withdrm_encoder.head. This isinvariant over the lifetime of a device and hence doesn’t need anylocks.

num_total_plane

Number of universal (i.e. with primary/curso) planes on this device.This is invariant over the lifetime of a device and hence doesn’tneed any locks.

plane_list

List of plane objects linked withdrm_plane.head. This is invariantover the lifetime of a device and hence doesn’t need any locks.

num_crtc

Number of CRTCs on this device linked withdrm_crtc.head. This is invariant over the lifetimeof a device and hence doesn’t need any locks.

crtc_list

List of CRTC objects linked withdrm_crtc.head. This is invariantover the lifetime of a device and hence doesn’t need any locks.

property_list

List of property type objects linked withdrm_property.head. This isinvariant over the lifetime of a device and hence doesn’t need anylocks.

privobj_list

List of private objects linked withdrm_private_obj.head. This isinvariant over the lifetime of a device and hence doesn’t need anylocks.

min_width

minimum fb pixel width on this device

min_height

minimum fb pixel height on this device

max_width

maximum fb pixel width on this device

max_height

maximum fb pixel height on this device

funcs

core driver provided mode setting functions

fb_base

base address of the framebuffer

poll_enabled

track polling support for this device

poll_running

track polling status for this device

delayed_event

track delayed poll uevent deliver for this device

output_poll_work

delayed work for polling in process context

blob_lock

Mutex for blob property allocation and management, protectsproperty_blob_list anddrm_file.blobs.

property_blob_list

List of all the blob property objects linked withdrm_property_blob.head. Protected byblob_lock.

edid_property

Default connector property to hold the EDID of thecurrently connected sink, if any.

dpms_property

Default connector property to control theconnector’s DPMS state.

path_property

Default connector property to hold the DP MST pathfor the port.

tile_property

Default connector property to store the tileposition of a tiled screen, for sinks which need to be driven withmultiple CRTCs.

link_status_property

Default connector property for link statusof a connector

plane_type_property

Default plane property to differentiateCURSOR, PRIMARY and OVERLAY legacy uses of planes.

prop_src_x

Default atomic plane property for the plane sourceposition in the connecteddrm_framebuffer.

prop_src_y

Default atomic plane property for the plane sourceposition in the connecteddrm_framebuffer.

prop_src_w

Default atomic plane property for the plane sourceposition in the connecteddrm_framebuffer.

prop_src_h

Default atomic plane property for the plane sourceposition in the connecteddrm_framebuffer.

prop_crtc_x

Default atomic plane property for the plane destinationposition in thedrm_crtc is being shown on.

prop_crtc_y

Default atomic plane property for the plane destinationposition in thedrm_crtc is being shown on.

prop_crtc_w

Default atomic plane property for the plane destinationposition in thedrm_crtc is being shown on.

prop_crtc_h

Default atomic plane property for the plane destinationposition in thedrm_crtc is being shown on.

prop_fb_id

Default atomic plane property to specify thedrm_framebuffer.

prop_in_fence_fd

Sync File fd representing the incoming fencesfor a Plane.

prop_out_fence_ptr

Sync File fd pointer representing theoutgoing fences for a CRTC. Userspace should provide a pointer to avalue of type s32, and then cast that pointer to u64.

prop_crtc_id

Default atomic plane property to specify thedrm_crtc.

prop_fb_damage_clips

Optional plane property to mark damagedregions on the plane in framebuffer coordinates of the framebufferattached to the plane.

The layout of blob data is simply an array ofdrm_mode_rect. Unlikeplane src coordinates, damage clips are not in 16.16 fixed point.

prop_active

Default atomic CRTC property to control the activestate, which is the simplified implementation for DPMS in atomicdrivers.

prop_mode_id

Default atomic CRTC property to set the mode for aCRTC. A 0 mode implies that the CRTC is entirely disabled - allconnectors must be of and active must be set to disabled, too.

prop_vrr_enabled

Default atomic CRTC property to indicatewhether variable refresh rate should be enabled on the CRTC.

dvi_i_subconnector_property

Optional DVI-I property todifferentiate between analog or digital mode.

dvi_i_select_subconnector_property

Optional DVI-I property toselect between analog or digital mode.

tv_subconnector_property

Optional TV property to differentiatebetween different TV connector types.

tv_select_subconnector_property

Optional TV property to selectbetween different TV connector types.

tv_mode_property

Optional TV property to selectthe output TV mode.

tv_left_margin_property

Optional TV property to set the leftmargin (expressed in pixels).

tv_right_margin_property

Optional TV property to set the rightmargin (expressed in pixels).

tv_top_margin_property

Optional TV property to set the rightmargin (expressed in pixels).

tv_bottom_margin_property

Optional TV property to set the rightmargin (expressed in pixels).

tv_brightness_property

Optional TV property to set thebrightness.

tv_contrast_property

Optional TV property to set thecontrast.

tv_flicker_reduction_property

Optional TV property to control theflicker reduction mode.

tv_overscan_property

Optional TV property to control the overscansetting.

tv_saturation_property

Optional TV property to set thesaturation.

tv_hue_property

Optional TV property to set the hue.

scaling_mode_property

Optional connector property to control theupscaling, mostly used for built-in panels.

aspect_ratio_property

Optional connector property to control theHDMI infoframe aspect ratio setting.

content_type_property

Optional connector property to control theHDMI infoframe content type setting.

degamma_lut_property

Optional CRTC property to set the LUT used toconvert the framebuffer’s colors to linear gamma.

degamma_lut_size_property

Optional CRTC property for the size ofthe degamma LUT as supported by the driver (read-only).

ctm_property

Optional CRTC property to set thematrix used to convert colors after the lookup in thedegamma LUT.

gamma_lut_property

Optional CRTC property to set the LUT used toconvert the colors, after the CTM matrix, to the gamma space of theconnected screen.

gamma_lut_size_property

Optional CRTC property for the size of thegamma LUT as supported by the driver (read-only).

suggested_x_property

Optional connector property with a hint forthe position of the output on the host’s screen.

suggested_y_property

Optional connector property with a hint forthe position of the output on the host’s screen.

non_desktop_property

Optional connector property with a hintthat device isn’t a standard display, and the console/desktop,should not be displayed on it.

panel_orientation_property

Optional connector property indicatinghow the lcd-panel is mounted inside the casing (e.g. normal orupside-down).

writeback_fb_id_property

Property for writeback connectors, storingthe ID of the output framebuffer.See also:drm_writeback_connector_init()

writeback_pixel_formats_property

Property for writeback connectors,storing an array of the supported pixel formats for the writebackengine (read-only).See also:drm_writeback_connector_init()

writeback_out_fence_ptr_property

Property for writeback connectors,fd pointer representing the outgoing fences for a writebackconnector. Userspace should provide a pointer to a value of type s32,and then cast that pointer to u64.See also:drm_writeback_connector_init()

hdr_output_metadata_property

Connector property containing hdrmetatada. This will be provided by userspace compositors basedon HDR content

content_protection_property

DRM ENUM property for contentprotection. Seedrm_connector_attach_content_protection_property().

hdcp_content_type_property

DRM ENUM property for type ofProtected Content.

preferred_depth

preferred RBG pixel depth, used by fb helpers

prefer_shadow

hint to userspace to prefer shadow-fb rendering

prefer_shadow_fbdev

Hint to framebuffer emulation to prefer shadow-fb rendering.

fbdev_use_iomem

Set to true if framebuffer reside in iomem.When set to true memcpy_toio() is used when copying the framebuffer indrm_fb_helper.drm_fb_helper_dirty_blit_real().

FIXME: This should be replaced with a per-mapping is_iomemflag (like ttm does), and then used everywhere in fbdev code.

quirk_addfb_prefer_xbgr_30bpp

Special hack for legacy ADDFB to keep nouveau userspace happy. Shouldonly ever be set by the nouveau kernel driver.

quirk_addfb_prefer_host_byte_order

When set to true drm_mode_addfb() will pick host byte orderpixel_format when calling drm_mode_addfb2(). This is howdrm_mode_addfb() should have worked from day one. Itdidn’t though, so we ended up with quirks in both kerneland userspace drivers to deal with the broken behavior.Simply fixing drm_mode_addfb() unconditionally would breakthese drivers, so add a quirk bit here to allow driversopt-in.

async_page_flip

Does this device support async flips on the primaryplane?

allow_fb_modifiers

Whether the driver supports fb modifiers in the ADDFB2.1 ioctl call.

normalize_zpos

If true the drm core will calldrm_atomic_normalize_zpos() as part ofatomic mode checking fromdrm_atomic_helper_check()

modifiers_property

Plane property to list support modifier/formatcombination.

cursor_width

hint to userspace for max cursor width

cursor_height

hint to userspace for max cursor height

suspend_state

Atomic state when suspended.Set bydrm_mode_config_helper_suspend() and cleared bydrm_mode_config_helper_resume().

helper_private

mid-layer private data

Description

Core mode resource tracking structure. All CRTC, encoders, and connectorsenumerated by the driver are added here, as are global properties. Someglobal restrictions are also here, e.g. dimension restrictions.

intdrm_mode_config_init(structdrm_device * dev)¶: DRM mode_configuration structure initialization

Parameters

structdrm_device*dev: DRM device

Description

This is the unmanaged version ofdrmm_mode_config_init() for drivers whichstill explicitly calldrm_mode_config_cleanup().

FIXME: This function is deprecated and drivers should be converted over todrmm_mode_config_init().

voiddrm_mode_config_reset(structdrm_device * dev)¶: call ->reset callbacks

Parameters

structdrm_device*dev: drm device

Description

This functions calls all the crtc’s, encoder’s and connector’s ->resetcallback. Drivers can use this in e.g. their driver load or resume code toreset hardware and software state.

intdrmm_mode_config_init(structdrm_device * dev)¶: managed DRM mode_configuration structure initialization

Parameters

structdrm_device*dev: DRM device

Description

Initializedev’s mode_config structure, used for tracking the graphicsconfiguration ofdev.

Since this initializes the modeset locks, no locking is possible. Which is noproblem, since this should happen single threaded at init time. It is thedriver’s problem to ensure this guarantee.

Cleanup is automatically handled through registering drm_mode_config_cleanupwithdrmm_add_action().

Return

0 on success, negative error value on failure.

voiddrm_mode_config_cleanup(structdrm_device * dev)¶: free up DRM mode_config info

Parameters

structdrm_device*dev: DRM device

Description

Free up all the connectors and CRTCs associated with this DRM device, thenfree up the framebuffers and associated buffer objects.

Note that since this /should/ happen single-threaded at driver/deviceteardown time, no locking is required. It’s the driver’s job to ensure thatthis guarantee actually holds true.

FIXME: With the manageddrmm_mode_config_init() it is no longer necessary fordrivers to explicitly call this function.

Modeset Base Object Abstraction¶

Mode Objects and Properties

The base structure for all KMS objects isstructdrm_mode_object. One of the base services it provides is tracking properties,which are especially important for the atomic IOCTL (seeAtomic ModeSetting). The somewhat surprising part here is that properties are notdirectly instantiated on each object, but free-standing mode objects themselves,represented bystructdrm_property, which only specifythe type and value range of a property. Any given property can be attachedmultiple times to different objects usingdrm_object_attach_property().

structdrm_mode_object¶: base structure for modeset objects

Definition

struct drm_mode_object {  uint32_t id;  uint32_t type;  struct drm_object_properties *properties;  struct kref refcount;  void (*free_cb)(struct kref *kref);};

Members

id: userspace visible identifier
type: type of the object, one of DRM_MODE_OBJECT_*
properties: properties attached to this object, including values
refcount: reference count for objects which with dynamic lifetime
free_cb: free function callback, only set for objects with dynamic lifetime

Description

Base structure for modeset objects visible to userspace. Objects can belooked up usingdrm_mode_object_find(). Besides basic uapi interfaceproperties likeid andtype it provides two services:

It tracks attached properties and their values. This is used bydrm_crtc,drm_plane anddrm_connector. Properties are attached by callingdrm_object_attach_property() before the object is visible to userspace.
For objects with dynamic lifetimes (as indicated by a non-NULLfree_cb) itprovides reference counting throughdrm_mode_object_get() anddrm_mode_object_put(). This is used bydrm_framebuffer,drm_connectoranddrm_property_blob. These objects provide specialized referencecounting wrappers.

structdrm_object_properties¶: property tracking fordrm_mode_object

Definition

struct drm_object_properties {  int count;  struct drm_property *properties[DRM_OBJECT_MAX_PROPERTY];  uint64_t values[DRM_OBJECT_MAX_PROPERTY];};

Members

count

number of valid properties, must be less than or equal toDRM_OBJECT_MAX_PROPERTY.

properties

Array of pointers todrm_property.

NOTE: if we ever start dynamically destroying properties (ie.not atdrm_mode_config_cleanup() time), then we’d have to doa better job of detaching property from mode objects to avoiddangling property pointers:

values

Array to store the property values, matchingproperties. Donot read/write values directly, but usedrm_object_property_get_value() anddrm_object_property_set_value().

Note that atomic drivers do not store mutable properties in thisarray, but only the decoded values in the corresponding statestructure. The decoding is done using thedrm_crtc.atomic_get_property anddrm_crtc.atomic_set_property hooks forstructdrm_crtc. Forstructdrm_plane the hooks aredrm_plane_funcs.atomic_get_property anddrm_plane_funcs.atomic_set_property. And forstructdrm_connectorthe hooks aredrm_connector_funcs.atomic_get_property anddrm_connector_funcs.atomic_set_property .

Hence atomic drivers should not usedrm_object_property_set_value()anddrm_object_property_get_value() on mutable objects, i.e. thosewithout the DRM_MODE_PROP_IMMUTABLE flag set.

structdrm_mode_object *drm_mode_object_find(structdrm_device * dev, structdrm_file * file_priv, uint32_t id, uint32_t type)¶: look up a drm object with static lifetime

Parameters

structdrm_device*dev: drm device
structdrm_file*file_priv: drm file
uint32_tid: id of the mode object
uint32_ttype: type of the mode object

Description

This function is used to look up a modeset object. It will acquire areference for reference counted objects. This reference must be dropped againby callinddrm_mode_object_put().

voiddrm_mode_object_put(structdrm_mode_object * obj)¶: release a mode object reference

Parameters

structdrm_mode_object*obj: DRM mode object

Description

This function decrements the object’s refcount if it is a refcounted modesetobject. It is a no-op on any other object. This is used to drop referencesacquired withdrm_mode_object_get().

voiddrm_mode_object_get(structdrm_mode_object * obj)¶: acquire a mode object reference

Parameters

structdrm_mode_object*obj: DRM mode object

Description

This function increments the object’s refcount if it is a refcounted modesetobject. It is a no-op on any other object. References should be dropped againby callingdrm_mode_object_put().

voiddrm_object_attach_property(structdrm_mode_object * obj, structdrm_property * property, uint64_t init_val)¶: attach a property to a modeset object

Parameters

structdrm_mode_object*obj: drm modeset object
structdrm_property*property: property to attach
uint64_tinit_val: initial value of the property

Description

This attaches the given property to the modeset object with the given initialvalue. Currently this function cannot fail since the properties are stored ina statically sized array.

Note that all properties must be attached before the object itself isregistered and accessible from userspace.

intdrm_object_property_set_value(structdrm_mode_object * obj, structdrm_property * property, uint64_t val)¶: set the value of a property

Parameters

structdrm_mode_object*obj: drm mode object to set property value for
structdrm_property*property: property to set
uint64_tval: value the property should be set to

Description

This function sets a given property on a given object. This function onlychanges the software state of the property, it does not call into thedriver’s ->set_property callback.

Note that atomic drivers should not have any need to call this, the core willensure consistency of values reported back to userspace through theappropriate ->atomic_get_property callback. Only legacy drivers should callthis function to update the tracked value (after clamping and otherrestrictions have been applied).

Return

Zero on success, error code on failure.

intdrm_object_property_get_value(structdrm_mode_object * obj, structdrm_property * property, uint64_t * val)¶: retrieve the value of a property

Parameters

structdrm_mode_object*obj: drm mode object to get property value from
structdrm_property*property: property to retrieve
uint64_t*val: storage for the property value

Description

This function retrieves the softare state of the given property for the givenproperty. Since there is no driver callback to retrieve the current propertyvalue this might be out of sync with the hardware, depending upon the driverand property.

Atomic drivers should never call this function directly, the core will readout property values through the various ->atomic_get_property callbacks.

Return

Zero on success, error code on failure.

Atomic Mode Setting¶

Mode Objects and Properties

Atomic provides transactional modeset (including planes) updates, but abit differently from the usual transactional approach of try-commit androllback:

Firstly, no hardware changes are allowed when the commit would fail. Thisallows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allowsuserspace to explore whether certain configurations would work or not.
This would still allow setting and rollback of just the software state,simplifying conversion of existing drivers. But auditing drivers forcorrectness of the atomic_check code becomes really hard with that: Rollingback changes in data structures all over the place is hard to get right.
Lastly, for backwards compatibility and to support all use-cases, atomicupdates need to be incremental and be able to execute in parallel. Hardwaredoesn’t always allow it, but where possible plane updates on different CRTCsshould not interfere, and not get stalled due to output routing changing ondifferent CRTCs.

Taken all together there’s two consequences for the atomic design:

The overall state is split up into per-object state structures:structdrm_plane_state for planes,structdrm_crtc_state for CRTCs andstructdrm_connector_state for connectors. These are the onlyobjects with userspace-visible and settable state. For internal state driverscan subclass these structures through embeddeding, or add entirely new statestructures for their globally shared hardware functions, seestructdrm_private_state.
An atomic update is assembled and validated as an entirely free-standing pileof structures within thedrm_atomic_statecontainer. Driver private state structures are also tracked in the samestructure; see the next chapter. Only when a state is committed is it appliedto the driver and modeset objects. This way rolling back an update boils downto releasing memory and unreferencing objects like framebuffers.

Locking of atomic state structures is internally usingstructdrm_modeset_lock. As a general rule the locking shouldn’t beexposed to drivers, instead the right locks should be automatically acquired byany function that duplicates or peeks into a state, like e.g.drm_atomic_get_crtc_state(). Locking only protects the software datastructure, ordering of committing state changes to hardware is sequenced usingstructdrm_crtc_commit.

Read on in this chapter, and also inAtomic Modeset Helper Functions Reference for more detailedcoverage of specific topics.

Handling Driver Private State¶

Very often the DRM objects exposed to userspace in the atomic modeset api(drm_connector,drm_crtc anddrm_plane) do not map neatly to theunderlying hardware. Especially for any kind of shared resources (e.g. sharedclocks, scaler units, bandwidth and fifo limits shared among a group ofplanes or CRTCs, and so on) it makes sense to model these as independentobjects. Drivers then need to do similar state tracking and commit ordering forsuch private (since not exposed to userpace) objects as the atomic core andhelpers already provide for connectors, planes and CRTCs.

To make this easier on drivers the atomic core provides some support to trackdriver private state objects using structdrm_private_obj, with theassociated state structdrm_private_state.

Similar to userspace-exposed objects, private state structures can beacquired by callingdrm_atomic_get_private_obj_state(). This also takes careof locking, hence drivers should not have a need to calldrm_modeset_lock()directly. Sequence of the actual hardware state commit is not handled,drivers might need to keep track of struct drm_crtc_commit within subclassedstructure ofdrm_private_state as necessary, e.g. similar todrm_plane_state.commit. See alsodrm_atomic_state.fake_commit.

All private state structures contained in adrm_atomic_state update can beiterated usingfor_each_oldnew_private_obj_in_state(),for_each_new_private_obj_in_state() andfor_each_old_private_obj_in_state().Drivers are recommended to wrap these for each type of driver private stateobject they have, filtering ondrm_private_obj.funcs usingfor_each_if(), atleast if they want to iterate over all objects of a given type.

An earlier way to handle driver private state was by subclassing structdrm_atomic_state. But since that encourages non-standard ways to implementthe check/commit split atomic requires (by using e.g. “check and rollback orcommit instead” of “duplicate state, check, then either commit or releaseduplicated state) it is deprecated in favour of usingdrm_private_state.

Atomic Mode Setting Function Reference¶

structdrm_crtc_commit¶: track modeset commits on a CRTC

Definition

struct drm_crtc_commit {  struct drm_crtc *crtc;  struct kref ref;  struct completion flip_done;  struct completion hw_done;  struct completion cleanup_done;  struct list_head commit_entry;  struct drm_pending_vblank_event *event;  bool abort_completion;};

Members

crtc

DRM CRTC for this commit.

ref

Reference count for this structure. Needed to allow blocking oncompletions without the risk of the completion disappearingmeanwhile.

flip_done

Will be signaled when the hardware has flipped to the new set ofbuffers. Signals at the same time as when the drm event for thiscommit is sent to userspace, or when an out-fence is singalled. Notethat for most hardware, in most cases this happens afterhw_done issignalled.

Completion of this stage is signalled implicitly by callingdrm_crtc_send_vblank_event() ondrm_crtc_state.event.

hw_done

Will be signalled when all hw register changes for this commit havebeen written out. Especially when disabling a pipe this can be muchlater thanflip_done, since that can signal already when thescreen goes black, whereas to fully shut down a pipe more registerI/O is required.

Note that this does not need to include separately reference-countedresources like backing storage buffer pinning, or runtime pmmanagement.

Drivers should calldrm_atomic_helper_commit_hw_done() to signalcompletion of this stage.

cleanup_done

Will be signalled after old buffers have been cleaned up by callingdrm_atomic_helper_cleanup_planes(). Since this can only happen aftera vblank wait completed it might be a bit later. This completion isuseful to throttle updates and avoid hardware updates getting aheadof the buffer cleanup too much.

Drivers should calldrm_atomic_helper_commit_cleanup_done() to signalcompletion of this stage.

commit_entry

Entry on the per-CRTCdrm_crtc.commit_list. Protected by$drm_crtc.commit_lock.

event

drm_pending_vblank_event pointer to clean up private events.

abort_completion

A flag that’s set afterdrm_atomic_helper_setup_commit() takes asecond reference for the completion of $drm_crtc_state.event. It’sused by the free code to remove the second reference if commit fails.

Description

This structure is used to track pending modeset changes and atomic commit ona per-CRTC basis. Since updating the list should never block, this structureis reference counted to allow waiters to safely wait on an event to complete,without holding any locks.

It has 3 different events in total to allow a fine-grained synchronizationbetween outstanding updates:

atomic commit thread                    hardwarewrite new state into hardware   ---->   ...signal hw_done                                        switch to new state on next...                                     v/hblankwait for buffers to show up             ......                                     send completion irq                                        irq handler signals flip_donecleanup old bufferssignal cleanup_donewait for flip_done              <----clean up atomic state

The important bit to know is thatcleanup_done is the terminal event, but theordering betweenflip_done andhw_done is entirely up to the specific driverand modeset state change.

For an implementation of how to use this look atdrm_atomic_helper_setup_commit() from the atomic helper library.

structdrm_private_state_funcs¶: atomic state functions for private objects

Definition

struct drm_private_state_funcs {  struct drm_private_state *(*atomic_duplicate_state)(struct drm_private_obj *obj);  void (*atomic_destroy_state)(struct drm_private_obj *obj, struct drm_private_state *state);};

Members

atomic_duplicate_state

Duplicate the current state of the private object and return it. Itis an error to call this before obj->state has been initialized.

RETURNS:

Duplicated atomic state or NULL when obj->state is notinitialized or allocation failed.

atomic_destroy_state

Frees the private object state created withatomic_duplicate_state.

Description

These hooks are used by atomic helpers to create, swap and destroy states ofprivate objects. The structure itself is used as a vtable to identify theassociated private object type. Each private object type that needs to beadded to the atomic states is expected to have an implementation of thesehooks and pass a pointer to its drm_private_state_funcs struct todrm_atomic_get_private_obj_state().

structdrm_private_obj¶: base struct for driver private atomic object

Definition

struct drm_private_obj {  struct list_head head;  struct drm_modeset_lock lock;  struct drm_private_state *state;  const struct drm_private_state_funcs *funcs;};

Members

head: List entry used to attach a private object to adrm_device(queued todrm_mode_config.privobj_list).
lock: Modeset lock to protect the state object.
state: Current atomic state for this driver private object.
funcs: Functions to manipulate the state of this driver private object, seedrm_private_state_funcs.

Description

A driver private object is initialized by callingdrm_atomic_private_obj_init() and cleaned up by callingdrm_atomic_private_obj_fini().

Currently only tracks the state update functions and the opaque driverprivate state itself, but in the future might also track whichdrm_modeset_lock is required to duplicate and update this object’s state.

All private objects must be initialized before the DRM device they areattached to is registered to the DRM subsystem (call todrm_dev_register())and should stay around until this DRM device is unregistered (call todrm_dev_unregister()). In other words, private objects lifetime is tiedto the DRM device lifetime. This implies that:

1/ all calls to drm_atomic_private_obj_init() must be done before calling: drm_dev_register()
2/ all calls to drm_atomic_private_obj_fini() must be done after calling: drm_dev_unregister()

drm_for_each_privobj(privobj,dev)¶: private object iterator

Parameters

privobj: pointer to the current private object. Updated after eachiteration
dev: the DRM device we want get private objects from

Description

Allows one to iterate over all private objects attached todev

structdrm_private_state¶: base struct for driver private object state

Definition

struct drm_private_state {  struct drm_atomic_state *state;};

Members

state: backpointer to global drm_atomic_state

Description

Currently only contains a backpointer to the overall atomic update, but inthe future also might hold synchronization information similar to e.g.drm_crtc.commit.

structdrm_atomic_state¶: the global state object for atomic updates

Definition

struct drm_atomic_state {  struct kref ref;  struct drm_device *dev;  bool allow_modeset : 1;  bool legacy_cursor_update : 1;  bool async_update : 1;  bool duplicated : 1;  struct __drm_planes_state *planes;  struct __drm_crtcs_state *crtcs;  int num_connector;  struct __drm_connnectors_state *connectors;  int num_private_objs;  struct __drm_private_objs_state *private_objs;  struct drm_modeset_acquire_ctx *acquire_ctx;  struct drm_crtc_commit *fake_commit;  struct work_struct commit_work;};

Members

ref

count of all references to this state (will not be freed until zero)

dev

parent DRM device

allow_modeset

Allow full modeset. This is used by the ATOMIC IOCTL handler toimplement the DRM_MODE_ATOMIC_ALLOW_MODESET flag. Drivers shouldnever consult this flag, instead looking at the output ofdrm_atomic_crtc_needs_modeset().

legacy_cursor_update

hint to enforce legacy cursor IOCTL semantics

async_update

hint for asynchronous plane update

duplicated

Indicates whether or not this atomic state was duplicated usingdrm_atomic_helper_duplicate_state(). Drivers and atomic helpersshould use this to fixup normal inconsistencies in duplicatedstates.

planes

pointer to array of structures with per-plane data

crtcs

pointer to array of CRTC pointers

num_connector

size of theconnectors andconnector_states arrays

connectors

pointer to array of structures with per-connector data

num_private_objs

size of theprivate_objs array

private_objs

pointer to array of private object pointers

acquire_ctx

acquire context for this atomic modeset state update

fake_commit

Used for signaling unbound planes/connectors.When a connector or plane is not bound to any CRTC, it’s still importantto preserve linearity to prevent the atomic states from being freed to early.

This commit (if set) is not bound to any CRTC, but will be completed whendrm_atomic_helper_commit_hw_done() is called.

commit_work

Work item which can be used by the driver or helpers to execute thecommit without blocking.

Description

States are added to an atomic update by callingdrm_atomic_get_crtc_state(),drm_atomic_get_plane_state(),drm_atomic_get_connector_state(), or forprivate state structures,drm_atomic_get_private_obj_state().

structdrm_crtc_commit *drm_crtc_commit_get(structdrm_crtc_commit * commit)¶: acquire a reference to the CRTC commit

Parameters

structdrm_crtc_commit*commit: CRTC commit

Description

Increases the reference ofcommit.

Return

The pointer tocommit, with reference increased.

voiddrm_crtc_commit_put(structdrm_crtc_commit * commit)¶: release a reference to the CRTC commmit

Parameters

structdrm_crtc_commit*commit: CRTC commit

Description

This releases a reference tocommit which is freed after removing thefinal reference. No locking required and callable from any context.

structdrm_atomic_state *drm_atomic_state_get(structdrm_atomic_state * state)¶: acquire a reference to the atomic state

Parameters

structdrm_atomic_state*state: The atomic state

Description

Returns a new reference to thestate

voiddrm_atomic_state_put(structdrm_atomic_state * state)¶: release a reference to the atomic state

Parameters

structdrm_atomic_state*state: The atomic state

Description

This releases a reference tostate which is freed after removing thefinal reference. No locking required and callable from any context.

structdrm_crtc_state *drm_atomic_get_existing_crtc_state(structdrm_atomic_state * state, structdrm_crtc * crtc)¶: get CRTC state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_crtc*crtc: CRTC to grab

Description

This function returns the CRTC state for the given CRTC, or NULLif the CRTC is not part of the global atomic state.

This function is deprecated,drm_atomic_get_old_crtc_state ordrm_atomic_get_new_crtc_state should be used instead.

structdrm_crtc_state *drm_atomic_get_old_crtc_state(structdrm_atomic_state * state, structdrm_crtc * crtc)¶: get old CRTC state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_crtc*crtc: CRTC to grab

Description

This function returns the old CRTC state for the given CRTC, orNULL if the CRTC is not part of the global atomic state.

structdrm_crtc_state *drm_atomic_get_new_crtc_state(structdrm_atomic_state * state, structdrm_crtc * crtc)¶: get new CRTC state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_crtc*crtc: CRTC to grab

Description

This function returns the new CRTC state for the given CRTC, orNULL if the CRTC is not part of the global atomic state.

structdrm_plane_state *drm_atomic_get_existing_plane_state(structdrm_atomic_state * state, structdrm_plane * plane)¶: get plane state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_plane*plane: plane to grab

Description

This function returns the plane state for the given plane, or NULLif the plane is not part of the global atomic state.

This function is deprecated,drm_atomic_get_old_plane_state ordrm_atomic_get_new_plane_state should be used instead.

structdrm_plane_state *drm_atomic_get_old_plane_state(structdrm_atomic_state * state, structdrm_plane * plane)¶: get plane state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_plane*plane: plane to grab

Description

This function returns the old plane state for the given plane, orNULL if the plane is not part of the global atomic state.

structdrm_plane_state *drm_atomic_get_new_plane_state(structdrm_atomic_state * state, structdrm_plane * plane)¶: get plane state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_plane*plane: plane to grab

Description

This function returns the new plane state for the given plane, orNULL if the plane is not part of the global atomic state.

structdrm_connector_state *drm_atomic_get_existing_connector_state(structdrm_atomic_state * state, structdrm_connector * connector)¶: get connector state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_connector*connector: connector to grab

Description

This function returns the connector state for the given connector,or NULL if the connector is not part of the global atomic state.

This function is deprecated,drm_atomic_get_old_connector_state ordrm_atomic_get_new_connector_state should be used instead.

structdrm_connector_state *drm_atomic_get_old_connector_state(structdrm_atomic_state * state, structdrm_connector * connector)¶: get connector state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_connector*connector: connector to grab

Description

This function returns the old connector state for the given connector,or NULL if the connector is not part of the global atomic state.

structdrm_connector_state *drm_atomic_get_new_connector_state(structdrm_atomic_state * state, structdrm_connector * connector)¶: get connector state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_connector*connector: connector to grab

Description

This function returns the new connector state for the given connector,or NULL if the connector is not part of the global atomic state.

const structdrm_plane_state *__drm_atomic_get_current_plane_state(structdrm_atomic_state * state, structdrm_plane * plane)¶: get current plane state

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_plane*plane: plane to grab

Description

This function returns the plane state for the given plane, either fromstate, or if the plane isn’t part of the atomic state update, fromplane.This is useful in atomic check callbacks, when drivers need to peek at, butnot change, state of other planes, since it avoids threading an error codeback up the call chain.

WARNING:

Note that this function is in general unsafe since it doesn’t check for therequired locking for access state structures. Drivers must ensure that it issafe to access the returned state structure through other means. One commonexample is when planes are fixed to a single CRTC, and the driver knows thatthe CRTC lock is held already. In that case holding the CRTC lock gives aread-lock on all planes connected to that CRTC. But if planes can bereassigned things get more tricky. In that case it’s better to usedrm_atomic_get_plane_state and wire up full error handling.

Read-only pointer to the current plane state.

Return

for_each_oldnew_connector_in_state(__state,connector,old_connector_state,new_connector_state,__i)¶: iterate over all connectors in an atomic update

Parameters

__state: structdrm_atomic_state pointer
connector: structdrm_connector iteration cursor
old_connector_state: structdrm_connector_state iteration cursor for theold state
new_connector_state: structdrm_connector_state iteration cursor for thenew state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all connectors in an atomic update, tracking both old andnew state. This is useful in places where the state delta needs to beconsidered, for example in atomic check functions.

for_each_old_connector_in_state(__state,connector,old_connector_state,__i)¶: iterate over all connectors in an atomic update

Parameters

__state: structdrm_atomic_state pointer
connector: structdrm_connector iteration cursor
old_connector_state: structdrm_connector_state iteration cursor for theold state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all connectors in an atomic update, tracking only the oldstate. This is useful in disable functions, where we need the old state thehardware is still in.

for_each_new_connector_in_state(__state,connector,new_connector_state,__i)¶: iterate over all connectors in an atomic update

Parameters

__state: structdrm_atomic_state pointer
connector: structdrm_connector iteration cursor
new_connector_state: structdrm_connector_state iteration cursor for thenew state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all connectors in an atomic update, tracking only the newstate. This is useful in enable functions, where we need the new state thehardware should be in when the atomic commit operation has completed.

for_each_oldnew_crtc_in_state(__state,crtc,old_crtc_state,new_crtc_state,__i)¶: iterate over all CRTCs in an atomic update

Parameters

__state: structdrm_atomic_state pointer
crtc: structdrm_crtc iteration cursor
old_crtc_state: structdrm_crtc_state iteration cursor for the old state
new_crtc_state: structdrm_crtc_state iteration cursor for the new state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all CRTCs in an atomic update, tracking both old andnew state. This is useful in places where the state delta needs to beconsidered, for example in atomic check functions.

for_each_old_crtc_in_state(__state,crtc,old_crtc_state,__i)¶: iterate over all CRTCs in an atomic update

Parameters

__state: structdrm_atomic_state pointer
crtc: structdrm_crtc iteration cursor
old_crtc_state: structdrm_crtc_state iteration cursor for the old state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all CRTCs in an atomic update, tracking only the oldstate. This is useful in disable functions, where we need the old state thehardware is still in.

for_each_new_crtc_in_state(__state,crtc,new_crtc_state,__i)¶: iterate over all CRTCs in an atomic update

Parameters

__state: structdrm_atomic_state pointer
crtc: structdrm_crtc iteration cursor
new_crtc_state: structdrm_crtc_state iteration cursor for the new state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all CRTCs in an atomic update, tracking only the newstate. This is useful in enable functions, where we need the new state thehardware should be in when the atomic commit operation has completed.

for_each_oldnew_plane_in_state(__state,plane,old_plane_state,new_plane_state,__i)¶: iterate over all planes in an atomic update

Parameters

__state: structdrm_atomic_state pointer
plane: structdrm_plane iteration cursor
old_plane_state: structdrm_plane_state iteration cursor for the old state
new_plane_state: structdrm_plane_state iteration cursor for the new state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all planes in an atomic update, tracking both old andnew state. This is useful in places where the state delta needs to beconsidered, for example in atomic check functions.

for_each_oldnew_plane_in_state_reverse(__state,plane,old_plane_state,new_plane_state,__i)¶: iterate over all planes in an atomic update in reverse order

Parameters

__state: structdrm_atomic_state pointer
plane: structdrm_plane iteration cursor
old_plane_state: structdrm_plane_state iteration cursor for the old state
new_plane_state: structdrm_plane_state iteration cursor for the new state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all planes in an atomic update in reverse order,tracking both old and new state. This is useful in places where thestate delta needs to be considered, for example in atomic check functions.

for_each_old_plane_in_state(__state,plane,old_plane_state,__i)¶: iterate over all planes in an atomic update

Parameters

__state: structdrm_atomic_state pointer
plane: structdrm_plane iteration cursor
old_plane_state: structdrm_plane_state iteration cursor for the old state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all planes in an atomic update, tracking only the oldstate. This is useful in disable functions, where we need the old state thehardware is still in.

for_each_new_plane_in_state(__state,plane,new_plane_state,__i)¶: iterate over all planes in an atomic update

Parameters

__state: structdrm_atomic_state pointer
plane: structdrm_plane iteration cursor
new_plane_state: structdrm_plane_state iteration cursor for the new state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all planes in an atomic update, tracking only the newstate. This is useful in enable functions, where we need the new state thehardware should be in when the atomic commit operation has completed.

for_each_oldnew_private_obj_in_state(__state,obj,old_obj_state,new_obj_state,__i)¶: iterate over all private objects in an atomic update

Parameters

__state: structdrm_atomic_state pointer
obj: structdrm_private_obj iteration cursor
old_obj_state: structdrm_private_state iteration cursor for the old state
new_obj_state: structdrm_private_state iteration cursor for the new state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all private objects in an atomic update, tracking bothold and new state. This is useful in places where the state delta needsto be considered, for example in atomic check functions.

for_each_old_private_obj_in_state(__state,obj,old_obj_state,__i)¶: iterate over all private objects in an atomic update

Parameters

__state: structdrm_atomic_state pointer
obj: structdrm_private_obj iteration cursor
old_obj_state: structdrm_private_state iteration cursor for the old state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all private objects in an atomic update, tracking onlythe old state. This is useful in disable functions, where we need the oldstate the hardware is still in.

for_each_new_private_obj_in_state(__state,obj,new_obj_state,__i)¶: iterate over all private objects in an atomic update

Parameters

__state: structdrm_atomic_state pointer
obj: structdrm_private_obj iteration cursor
new_obj_state: structdrm_private_state iteration cursor for the new state
__i: int iteration cursor, for macro-internal use

Description

This iterates over all private objects in an atomic update, tracking onlythe new state. This is useful in enable functions, where we need the new state thehardware should be in when the atomic commit operation has completed.

booldrm_atomic_crtc_needs_modeset(const structdrm_crtc_state * state)¶: compute combined modeset need

Parameters

conststructdrm_crtc_state*state: drm_crtc_state for the CRTC

Description

To give drivers flexibilitystructdrm_crtc_state has 3 booleans to trackwhether the state CRTC changed enough to need a full modeset cycle:mode_changed, active_changed and connectors_changed. This helper simplycombines these three to compute the overall need for a modeset forstate.

The atomic helper code sets these booleans, but drivers can and shouldchange them appropriately to accurately represent whether a modeset isreally needed. In general, drivers should avoid full modesets wheneverpossible.

For example if the CRTC mode has changed, and the hardware is able to enactthe requested mode change without going through a full modeset, the drivershould clear mode_changed in itsdrm_mode_config_funcs.atomic_checkimplementation.

booldrm_atomic_crtc_effectively_active(const structdrm_crtc_state * state)¶: compute whether CRTC is actually active

Parameters

conststructdrm_crtc_state*state: drm_crtc_state for the CRTC

Description

When in self refresh mode, the crtc_state->active value will be false, sincethe CRTC is off. However in some cases we’re interested in whether the CRTCis active, or effectively active (ie: it’s connected to an active display).In these cases, use this function instead of just checking active.

structdrm_bus_cfg¶: bus configuration

Definition

struct drm_bus_cfg {  u32 format;  u32 flags;};

Members

format

format used on this bus (one of the MEDIA_BUS_FMT_* format)

This field should not be directly modified by drivers(drm_atomic_bridge_chain_select_bus_fmts() takes care of the busformat negotiation).

flags

DRM_BUS_* flags used on this bus

Description

This structure stores the configuration of a physical bus between twocomponents in an output pipeline, usually between two bridges, an encoderand a bridge, or a bridge and a connector.

The bus configuration is stored indrm_bridge_state separately for theinput and output buses, as seen from the point of view of each bridge. Thebus configuration of a bridge output is usually identical to theconfiguration of the next bridge’s input, but may differ if the signals aremodified between the two bridges, for instance by an inverter on the board.The input and output configurations of a bridge may differ if the bridgemodifies the signals internally, for instance by performing formatconversion, or modifying signals polarities.

structdrm_bridge_state¶: Atomic bridge state object

Definition

struct drm_bridge_state {  struct drm_private_state base;  struct drm_bridge *bridge;  struct drm_bus_cfg input_bus_cfg;  struct drm_bus_cfg output_bus_cfg;};

Members

base: inherit fromdrm_private_state
bridge: the bridge this state refers to
input_bus_cfg: input bus configuration
output_bus_cfg: input bus configuration

voiddrm_atomic_state_default_release(structdrm_atomic_state * state)¶: release memory initialized by drm_atomic_state_init

Parameters

structdrm_atomic_state*state: atomic state

Description

Free all the memory allocated by drm_atomic_state_init.This should only be used by drivers which are still subclassingdrm_atomic_state and haven’t switched todrm_private_state yet.

intdrm_atomic_state_init(structdrm_device * dev, structdrm_atomic_state * state)¶: init new atomic state

Parameters

structdrm_device*dev: DRM device
structdrm_atomic_state*state: atomic state

Description

Default implementation for filling in a new atomic state.This should only be used by drivers which are still subclassingdrm_atomic_state and haven’t switched todrm_private_state yet.

structdrm_atomic_state *drm_atomic_state_alloc(structdrm_device * dev)¶: allocate atomic state

Parameters

structdrm_device*dev: DRM device

Description

This allocates an empty atomic state to track updates.

voiddrm_atomic_state_default_clear(structdrm_atomic_state * state)¶: clear base atomic state

Parameters

structdrm_atomic_state*state: atomic state

Description

Default implementation for clearing atomic state.This should only be used by drivers which are still subclassingdrm_atomic_state and haven’t switched todrm_private_state yet.

voiddrm_atomic_state_clear(structdrm_atomic_state * state)¶: clear state object

Parameters

structdrm_atomic_state*state: atomic state

Description

When the w/w mutex algorithm detects a deadlock we need to back off and dropall locks. So someone else could sneak in and change the current modesetconfiguration. Which means that all the state assembled instate is nolonger an atomic update to the current state, but to some arbitrary earlierstate. Which could break assumptions the driver’sdrm_mode_config_funcs.atomic_check likely relies on.

Hence we must clear all cached state and completely start over, using thisfunction.

void__drm_atomic_state_free(struct kref * ref)¶: free all memory for an atomic state

Parameters

structkref*ref: This atomic state to deallocate

Description

This frees all memory associated with an atomic state, including all theper-object state for planes, CRTCs and connectors.

structdrm_crtc_state *drm_atomic_get_crtc_state(structdrm_atomic_state * state, structdrm_crtc * crtc)¶: get CRTC state

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_crtc*crtc: CRTC to get state object for

Description

This function returns the CRTC state for the given CRTC, allocating it ifneeded. It will also grab the relevant CRTC lock to make sure that the stateis consistent.

Either the allocated state or the error code encoded into the pointer. Whenthe error is EDEADLK then the w/w mutex code has detected a deadlock and theentire atomic sequence must be restarted. All other errors are fatal.

Return

structdrm_plane_state *drm_atomic_get_plane_state(structdrm_atomic_state * state, structdrm_plane * plane)¶: get plane state

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_plane*plane: plane to get state object for

Description

This function returns the plane state for the given plane, allocating it ifneeded. It will also grab the relevant plane lock to make sure that the stateis consistent.

Return

voiddrm_atomic_private_obj_init(structdrm_device * dev, structdrm_private_obj * obj, structdrm_private_state * state, const structdrm_private_state_funcs * funcs)¶: initialize private object

Parameters

structdrm_device*dev: DRM device this object will be attached to
structdrm_private_obj*obj: private object
structdrm_private_state*state: initial private object state
conststructdrm_private_state_funcs*funcs: pointer to the struct of function pointers that identify the objecttype

Description

Initialize the private object, which can be embedded into anydriver private object that needs its own atomic state.

voiddrm_atomic_private_obj_fini(structdrm_private_obj * obj)¶: finalize private object

Parameters

structdrm_private_obj*obj: private object

Description

Finalize the private object.

structdrm_private_state *drm_atomic_get_private_obj_state(structdrm_atomic_state * state, structdrm_private_obj * obj)¶: get private object state

Parameters

structdrm_atomic_state*state: global atomic state
structdrm_private_obj*obj: private object to get the state for

Description

This function returns the private object state for the given private object,allocating the state if needed. It will also grab the relevant privateobject lock to make sure that the state is consistent.

Either the allocated state or the error code encoded into a pointer.

Return

structdrm_private_state *drm_atomic_get_old_private_obj_state(structdrm_atomic_state * state, structdrm_private_obj * obj)¶

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_private_obj*obj: private_obj to grab

Description

This function returns the old private object state for the given private_obj,or NULL if the private_obj is not part of the global atomic state.

structdrm_private_state *drm_atomic_get_new_private_obj_state(structdrm_atomic_state * state, structdrm_private_obj * obj)¶

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_private_obj*obj: private_obj to grab

Description

This function returns the new private object state for the given private_obj,or NULL if the private_obj is not part of the global atomic state.

structdrm_connector *drm_atomic_get_old_connector_for_encoder(structdrm_atomic_state * state, structdrm_encoder * encoder)¶: Get old connector for an encoder

Parameters

structdrm_atomic_state*state: Atomic state
structdrm_encoder*encoder: The encoder to fetch the connector state for

Description

This function finds and returns the connector that was connected toencoderas specified by thestate.

If there is no connector instate which previously hadencoder connected toit, this function will return NULL. While this may seem like an invalid usecase, it is sometimes useful to differentiate commits which had no priorconnectors attached toencoder vs ones that did (and to inspect theirstate). This is especially true in enable hooks because the pipeline haschanged.

Return

The old connector connected toencoder, or NULL if the encoder isnot connected.

structdrm_connector *drm_atomic_get_new_connector_for_encoder(structdrm_atomic_state * state, structdrm_encoder * encoder)¶: Get new connector for an encoder

Parameters

structdrm_atomic_state*state: Atomic state
structdrm_encoder*encoder: The encoder to fetch the connector state for

Description

This function finds and returns the connector that will be connected toencoder as specified by thestate.

If there is no connector instate which will haveencoder connected to it,this function will return NULL. While this may seem like an invalid use case,it is sometimes useful to differentiate commits which have no connectorsattached toencoder vs ones that do (and to inspect their state). This isespecially true in disable hooks because the pipeline will change.

Return

The new connector connected toencoder, or NULL if the encoder isnot connected.

structdrm_connector_state *drm_atomic_get_connector_state(structdrm_atomic_state * state, structdrm_connector * connector)¶: get connector state

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_connector*connector: connector to get state object for

Description

This function returns the connector state for the given connector,allocating it if needed. It will also grab the relevant connector lock tomake sure that the state is consistent.

Return

structdrm_bridge_state *drm_atomic_get_bridge_state(structdrm_atomic_state * state, structdrm_bridge * bridge)¶: get bridge state

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_bridge*bridge: bridge to get state object for

Description

This function returns the bridge state for the given bridge, allocating itif needed. It will also grab the relevant bridge lock to make sure that thestate is consistent.

Either the allocated state or the error code encoded into the pointer. Whenthe error is EDEADLK then the w/w mutex code has detected a deadlock and theentire atomic sequence must be restarted.

Return

structdrm_bridge_state *drm_atomic_get_old_bridge_state(structdrm_atomic_state * state, structdrm_bridge * bridge)¶: get old bridge state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_bridge*bridge: bridge to grab

Description

This function returns the old bridge state for the given bridge, or NULL ifthe bridge is not part of the global atomic state.

structdrm_bridge_state *drm_atomic_get_new_bridge_state(structdrm_atomic_state * state, structdrm_bridge * bridge)¶: get new bridge state, if it exists

Parameters

structdrm_atomic_state*state: global atomic state object
structdrm_bridge*bridge: bridge to grab

Description

This function returns the new bridge state for the given bridge, or NULL ifthe bridge is not part of the global atomic state.

intdrm_atomic_add_encoder_bridges(structdrm_atomic_state * state, structdrm_encoder * encoder)¶: add bridges attached to an encoder

Parameters

structdrm_atomic_state*state: atomic state
structdrm_encoder*encoder: DRM encoder

Description

This function adds all bridges attached toencoder. This is needed to addbridge states tostate and make them available whendrm_bridge_funcs.atomic_check(),drm_bridge_funcs.atomic_pre_enable(),drm_bridge_funcs.atomic_enable(),drm_bridge_funcs.atomic_disable_post_disable() are called.

Return

0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLKthen the w/w mutex code has detected a deadlock and the entire atomicsequence must be restarted. All other errors are fatal.

intdrm_atomic_add_affected_connectors(structdrm_atomic_state * state, structdrm_crtc * crtc)¶: add connectors for CRTC

Parameters

structdrm_atomic_state*state: atomic state
structdrm_crtc*crtc: DRM CRTC

Description

This function walks the current configuration and adds all connectorscurrently usingcrtc to the atomic configurationstate. Note that thisfunction must acquire the connection mutex. This can potentially causeunneeded seralization if the update is just for the planes on one CRTC. Hencedrivers and helpers should only call this when really needed (e.g. when afull modeset needs to happen due to some change).

Return

intdrm_atomic_add_affected_planes(structdrm_atomic_state * state, structdrm_crtc * crtc)¶: add planes for CRTC

Parameters

structdrm_atomic_state*state: atomic state
structdrm_crtc*crtc: DRM CRTC

Description

This function walks the current configuration and adds all planescurrently used bycrtc to the atomic configurationstate. This is usefulwhen an atomic commit also needs to check all currently enabled plane oncrtc, e.g. when changing the mode. It’s also useful when re-enabling a CRTCto avoid special code to force-enable all planes.

Since acquiring a plane state will always also acquire the w/w mutex of thecurrent CRTC for that plane (if there is any) adding all the plane states fora CRTC will not reduce parallism of atomic updates.

Return

intdrm_atomic_check_only(structdrm_atomic_state * state)¶: check whether a given config would work

Parameters

structdrm_atomic_state*state: atomic configuration to check

Description

Note that this function can return -EDEADLK if the driver needed to acquiremore locks but encountered a deadlock. The caller must then do the usual w/wbackoff dance and restart. All other errors are fatal.

Return

0 on success, negative error code on failure.

intdrm_atomic_commit(structdrm_atomic_state * state)¶: commit configuration atomically

Parameters

structdrm_atomic_state*state: atomic configuration to check

Description

This function will take its own reference onstate.Callers should always release their reference withdrm_atomic_state_put().

Return

0 on success, negative error code on failure.

intdrm_atomic_nonblocking_commit(structdrm_atomic_state * state)¶: atomic nonblocking commit

Parameters

structdrm_atomic_state*state: atomic configuration to check

Description

This function will take its own reference onstate.Callers should always release their reference withdrm_atomic_state_put().

Return

0 on success, negative error code on failure.

voiddrm_state_dump(structdrm_device * dev, structdrm_printer * p)¶: dump entire device atomic state

Parameters

structdrm_device*dev: the drm device
structdrm_printer*p: where to print the state to

Description

Just for debugging. Drivers might want an option to dump stateto dmesg in case of error irq’s. (Hint, you probably want toratelimit this!)

The caller mustdrm_modeset_lock_all(), or if this is calledfrom error irq handler, it should not be enabled by default.(Ie. if you are debugging errors you might not care that thisis racey. But calling this without all modeset locks held isnot inherently safe.)

Atomic Mode Setting IOCTL and UAPI Functions¶

This file contains the marshalling and demarshalling glue for the atomic UAPIin all its forms: The monster ATOMIC IOCTL itself, code for GET_PROPERTY andSET_PROPERTY IOCTLs. Plus interface functions for compatibility helpers anddrivers which have special needs to construct their own atomic updates, e.g.for load detect or similiar.

intdrm_atomic_set_mode_for_crtc(structdrm_crtc_state * state, const structdrm_display_mode * mode)¶: set mode for CRTC

Parameters

structdrm_crtc_state*state: the CRTC whose incoming state to update
conststructdrm_display_mode*mode: kernel-internal mode to use for the CRTC, or NULL to disable

Description

Set a mode (originating from the kernel) on the desired CRTC state and updatethe enable property.

Return

Zero on success, error code on failure. Cannot return -EDEADLK.

intdrm_atomic_set_mode_prop_for_crtc(structdrm_crtc_state * state, structdrm_property_blob * blob)¶: set mode for CRTC

Parameters

structdrm_crtc_state*state: the CRTC whose incoming state to update
structdrm_property_blob*blob: pointer to blob property to use for mode

Description

Set a mode (originating from a blob property) on the desired CRTC state.This function will take a reference on the blob property for the CRTC state,and release the reference held on the state’s existing mode property, if anywas set.

Return

Zero on success, error code on failure. Cannot return -EDEADLK.

intdrm_atomic_set_crtc_for_plane(structdrm_plane_state * plane_state, structdrm_crtc * crtc)¶: set CRTC for plane

Parameters

structdrm_plane_state*plane_state: the plane whose incoming state to update
structdrm_crtc*crtc: CRTC to use for the plane

Description

Changing the assigned CRTC for a plane requires us to grab the lock and statefor the new CRTC, as needed. This function takes care of all these detailsbesides updating the pointer in the state object itself.

Return

voiddrm_atomic_set_fb_for_plane(structdrm_plane_state * plane_state, structdrm_framebuffer * fb)¶: set framebuffer for plane

Parameters

structdrm_plane_state*plane_state: atomic state object for the plane
structdrm_framebuffer*fb: fb to use for the plane

Description

Changing the assigned framebuffer for a plane requires us to grab a referenceto the new fb and drop the reference to the old fb, if there is one. Thisfunction takes care of all these details besides updating the pointer in thestate object itself.

voiddrm_atomic_set_fence_for_plane(structdrm_plane_state * plane_state, structdma_fence * fence)¶: set fence for plane

Parameters

structdrm_plane_state*plane_state: atomic state object for the plane
structdma_fence*fence: dma_fence to use for the plane

Description

Helper to setup the plane_state fence in case it is not set yet.By using this drivers doesn’t need to worry if the user chooseimplicit or explicit fencing.

This function will not set the fence to the state if it was setvia explicit fencing interfaces on the atomic ioctl. In that case it willdrop the reference to the fence as we are not storing it anywhere.Otherwise, ifdrm_plane_state.fence is not set this function we just set itwith the received implicit fence. In both cases this function consumes areference forfence.

This way explicit fencing can be used to overrule implicit fencing, which isimportant to make explicit fencing use-cases work: One example is using onebuffer for 2 screens with different refresh rates. Implicit fencing willclamp rendering to the refresh rate of the slower screen, whereas explicitfence allows 2 independent render and display loops on a single buffer. If adriver allows obeys both implicit and explicit fences for plane updates, thenit will break all the benefits of explicit fencing.

intdrm_atomic_set_crtc_for_connector(structdrm_connector_state * conn_state, structdrm_crtc * crtc)¶: set CRTC for connector

Parameters

structdrm_connector_state*conn_state: atomic state object for the connector
structdrm_crtc*crtc: CRTC to use for the connector

Description

Changing the assigned CRTC for a connector requires us to grab the lock andstate for the new CRTC, as needed. This function takes care of all thesedetails besides updating the pointer in the state object itself.

Return

CRTC Abstraction¶

A CRTC represents the overall display pipeline. It receives pixel data fromdrm_plane and blends them together. Thedrm_display_mode is also attachedto the CRTC, specifying display timings. On the output side the data is fedto one or moredrm_encoder, which are then each connected to onedrm_connector.

To create a CRTC, a KMS drivers allocates and zeroes an instances ofstructdrm_crtc (possibly as part of a larger structure) and registers itwith a call todrm_crtc_init_with_planes().

The CRTC is also the entry point for legacy modeset operations, seedrm_crtc_funcs.set_config, legacy plane operations, seedrm_crtc_funcs.page_flip anddrm_crtc_funcs.cursor_set2, and other legacyoperations likedrm_crtc_funcs.gamma_set. For atomic drivers all thesefeatures are controlled throughdrm_property anddrm_mode_config_funcs.atomic_check anddrm_mode_config_funcs.atomic_check.

CRTC Functions Reference¶

structdrm_crtc_state¶: mutable CRTC state

Definition

struct drm_crtc_state {  struct drm_crtc *crtc;  bool enable;  bool active;  bool planes_changed : 1;  bool mode_changed : 1;  bool active_changed : 1;  bool connectors_changed : 1;  bool zpos_changed : 1;  bool color_mgmt_changed : 1;  bool no_vblank : 1;  u32 plane_mask;  u32 connector_mask;  u32 encoder_mask;  struct drm_display_mode adjusted_mode;  struct drm_display_mode mode;  struct drm_property_blob *mode_blob;  struct drm_property_blob *degamma_lut;  struct drm_property_blob *ctm;  struct drm_property_blob *gamma_lut;  u32 target_vblank;  bool async_flip;  bool vrr_enabled;  bool self_refresh_active;  struct drm_pending_vblank_event *event;  struct drm_crtc_commit *commit;  struct drm_atomic_state *state;};

Members

crtc

backpointer to the CRTC

enable

Whether the CRTC should be enabled, gates all other state.This controls reservations of shared resources. Actual hardware stateis controlled byactive.

active

Whether the CRTC is actively displaying (used for DPMS).Implies thatenable is set. The driver must not release any sharedresources ifactive is set to false butenable still true, becauseuserspace expects that a DPMS ON always succeeds.

Hence drivers must not consultactive in their variousdrm_mode_config_funcs.atomic_check callback to reject an atomiccommit. They can consult it to aid in the computation of derivedhardware state, since even in the DPMS OFF state the display hardwareshould be as much powered down as when the CRTC is completelydisabled through settingenable to false.

planes_changed

Planes on this crtc are updated. Used by the atomichelpers and drivers to steer the atomic commit control flow.

mode_changed

mode orenable has been changed. Used by the atomichelpers and drivers to steer the atomic commit control flow. See alsodrm_atomic_crtc_needs_modeset().

Drivers are supposed to set this for any CRTC state changes thatrequire a full modeset. They can also reset it to false if e.g. amode change can be done without a full modeset by only changingscaler settings.

active_changed

active has been toggled. Used by the atomichelpers and drivers to steer the atomic commit control flow. See alsodrm_atomic_crtc_needs_modeset().

connectors_changed

Connectors to this crtc have been updated,either in their state or routing. Used by the atomichelpers and drivers to steer the atomic commit control flow. See alsodrm_atomic_crtc_needs_modeset().

Drivers are supposed to set this as-needed from their own atomiccheck code, e.g. fromdrm_encoder_helper_funcs.atomic_check

zpos_changed

zpos values of planes on this crtc have been updated.Used by the atomic helpers and drivers to steer the atomic commitcontrol flow.

color_mgmt_changed

Color management properties have changed(gamma_lut,degamma_lut orctm). Used by the atomic helpers anddrivers to steer the atomic commit control flow.

no_vblank

Reflects the ability of a CRTC to send VBLANK events. This stateusually depends on the pipeline configuration. If set to true, DRMatomic helpers will send out a fake VBLANK event during displayupdates after all hardware changes have been committed. This isimplemented indrm_atomic_helper_fake_vblank().

One usage is for drivers and/or hardware without support for VBLANKinterrupts. Such drivers typically do not initialize vblanking(i.e., calldrm_vblank_init() with the number of CRTCs). For CRTCswithout initialized vblanking, this field is set to true indrm_atomic_helper_check_modeset(), and a fake VBLANK event will besend out on each update of the display pipeline bydrm_atomic_helper_fake_vblank().

Another usage is CRTCs feeding a writeback connector operating inoneshot mode. In this case the fake VBLANK event is only generatedwhen a job is queued to the writeback connector, and we want thecore to fake VBLANK events when this part of the pipeline hasn’tchanged but others had or when the CRTC and connectors are beingdisabled.

__drm_atomic_helper_crtc_duplicate_state() will not reset the valuefrom the current state, the CRTC driver is then responsible forupdating this field when needed.

Note that the combination ofdrm_crtc_state.event == NULL anddrm_crtc_state.no_blank == true is valid and usually used when thewriteback connector attached to the CRTC has a new job queued. Inthis case the driver will send the VBLANK event on its own when thewriteback job is complete.

plane_mask

Bitmask of drm_plane_mask(plane) of planes attached tothis CRTC.

connector_mask

Bitmask of drm_connector_mask(connector) ofconnectors attached to this CRTC.

encoder_mask

Bitmask of drm_encoder_mask(encoder) of encodersattached to this CRTC.

adjusted_mode

Internal display timings which can be used by the driver to handledifferences between the mode requested by userspace inmode and whatis actually programmed into the hardware.

For drivers usingdrm_bridge, this stores hardware display timingsused between the CRTC and the first bridge. For other drivers, themeaning of the adjusted_mode field is purely driver implementationdefined information, and will usually be used to store the hardwaredisplay timings used between the CRTC and encoder blocks.

mode

Display timings requested by userspace. The driver should try tomatch the refresh rate as close as possible (but note that it’sundefined what exactly is close enough, e.g. some of the HDMI modesonly differ in less than 1% of the refresh rate). The active widthand height as observed by userspace for positioning planes must matchexactly.

For external connectors where the sink isn’t fixed (like with abuilt-in panel), this mode here should match the physical mode on thewire to the last details (i.e. including sync polarities andeverything).

mode_blob

drm_property_blob formode, for exposing the mode toatomic userspace.

degamma_lut

Lookup table for converting framebuffer pixel data before apply thecolor conversion matrixctm. Seedrm_crtc_enable_color_mgmt(). Theblob (if not NULL) is an array ofstructdrm_color_lut.

ctm

Color transformation matrix. Seedrm_crtc_enable_color_mgmt(). Theblob (if not NULL) is astructdrm_color_ctm.

gamma_lut

Lookup table for converting pixel data after the color conversionmatrixctm. Seedrm_crtc_enable_color_mgmt(). The blob (if notNULL) is an array ofstructdrm_color_lut.

target_vblank

Target vertical blank period when a page flipshould take effect.

async_flip

This is set when DRM_MODE_PAGE_FLIP_ASYNC is set in the legacyPAGE_FLIP IOCTL. It’s not wired up for the atomic IOCTL itself yet.

vrr_enabled

Indicates if variable refresh rate should be enabled for the CRTC.Support for the requested vrr state will depend on driver andhardware capabiltiy - lacking support is not treated as failure.

self_refresh_active

Used by the self refresh helpers to denote when a self refreshtransition is occurring. This will be set on enable/disable callbackswhen self refresh is being enabled or disabled. In some cases, it maynot be desirable to fully shut off the crtc during self refresh.CRTC’s can inspect this flag and determine the best course of action.

event

Optional pointer to a DRM event to signal upon completion of thestate update. The driver must send out the event when the atomiccommit operation completes. There are two cases:

The event is for a CRTC which is being disabled through thisatomic commit. In that case the event can be send out any timeafter the hardware has stopped scanning out the currentframebuffers. It should contain the timestamp and counter for thelast vblank before the display pipeline was shut off. The simplestway to achieve that is callingdrm_crtc_send_vblank_event()somewhen afterdrm_crtc_vblank_off() has been called.
For a CRTC which is enabled at the end of the commit (even when itundergoes an full modeset) the vblank timestamp and counter mustbe for the vblank right before the first frame that scans out thenew set of buffers. Again the event can only be sent out after thehardware has stopped scanning out the old buffers.
Events for disabled CRTCs are not allowed, and drivers can ignorethat case.

For very simple hardware without VBLANK interrupt, enablingstructdrm_crtc_state.no_vblank makes DRM’s atomic commit helperssend a fake VBLANK event at the end of the display update after allhardware changes have been applied. Seedrm_atomic_helper_fake_vblank().

For more complex hardware thiscan be handled by thedrm_crtc_send_vblank_event() function,which the driver should call on the provided event upon completion ofthe atomic commit. Note that if the driver supports vblank signallingand timestamping the vblank counters and timestamps must agree withthe ones returned from page flip events. With the current vblankhelper infrastructure this can be achieved by holding a vblankreference while the page flip is pending, acquired throughdrm_crtc_vblank_get() and released withdrm_crtc_vblank_put().Drivers are free to implement their own vblank counter and timestamptracking though, e.g. if they have accurate timestamp registers inhardware.

For hardware which supports some means to synchronize vblankinterrupt delivery with committing display state there’s alsodrm_crtc_arm_vblank_event(). See the documentation of that functionfor a detailed discussion of the constraints it needs to be usedsafely.

If the device can’t notify of flip completion in a race-free wayat all, then the event should be armed just after the page flip iscommitted. In the worst case the driver will send the event touserspace one frame too late. This doesn’t allow for a real atomicupdate, but it should avoid tearing.

commit

This tracks how the commit for this update proceeds through thevarious phases. This is never cleared, except when we destroy thestate, so that subsequent commits can synchronize with previous ones.

state

backpointer to global drm_atomic_state

Description

Note that the distinction betweenenable andactive is rather subtle:Flippingactive whileenable is set without changing anything else maynever return in a failure from thedrm_mode_config_funcs.atomic_checkcallback. Userspace assumes that a DPMS On will always succeed. In otherwords:enable controls resource assignment,active controls the actualhardware state.

The three booleans active_changed, connectors_changed and mode_changed areintended to indicate whether a full modeset is needed, rather than strictlydescribing what has changed in a commit. See also:drm_atomic_crtc_needs_modeset()

WARNING: Transitional helpers (like drm_helper_crtc_mode_set() ordrm_helper_crtc_mode_set_base()) do not maintain many of the derived controlstate likeplane_mask so drivers not converted over to atomic helpers shouldnot rely on these being accurate!

structdrm_crtc_funcs¶: control CRTCs for a given device

Definition

struct drm_crtc_funcs {  void (*reset)(struct drm_crtc *crtc);  int (*cursor_set)(struct drm_crtc *crtc, struct drm_file *file_priv, uint32_t handle, uint32_t width, uint32_t height);  int (*cursor_set2)(struct drm_crtc *crtc, struct drm_file *file_priv,uint32_t handle, uint32_t width, uint32_t height, int32_t hot_x, int32_t hot_y);  int (*cursor_move)(struct drm_crtc *crtc, int x, int y);  int (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,uint32_t size, struct drm_modeset_acquire_ctx *ctx);  void (*destroy)(struct drm_crtc *crtc);  int (*set_config)(struct drm_mode_set *set, struct drm_modeset_acquire_ctx *ctx);  int (*page_flip)(struct drm_crtc *crtc,struct drm_framebuffer *fb,struct drm_pending_vblank_event *event,uint32_t flags, struct drm_modeset_acquire_ctx *ctx);  int (*page_flip_target)(struct drm_crtc *crtc,struct drm_framebuffer *fb,struct drm_pending_vblank_event *event,uint32_t flags, uint32_t target, struct drm_modeset_acquire_ctx *ctx);  int (*set_property)(struct drm_crtc *crtc, struct drm_property *property, uint64_t val);  struct drm_crtc_state *(*atomic_duplicate_state)(struct drm_crtc *crtc);  void (*atomic_destroy_state)(struct drm_crtc *crtc, struct drm_crtc_state *state);  int (*atomic_set_property)(struct drm_crtc *crtc,struct drm_crtc_state *state,struct drm_property *property, uint64_t val);  int (*atomic_get_property)(struct drm_crtc *crtc,const struct drm_crtc_state *state,struct drm_property *property, uint64_t *val);  int (*late_register)(struct drm_crtc *crtc);  void (*early_unregister)(struct drm_crtc *crtc);  int (*set_crc_source)(struct drm_crtc *crtc, const char *source);  int (*verify_crc_source)(struct drm_crtc *crtc, const char *source, size_t *values_cnt);  const char *const *(*get_crc_sources)(struct drm_crtc *crtc, size_t *count);  void (*atomic_print_state)(struct drm_printer *p, const struct drm_crtc_state *state);  u32 (*get_vblank_counter)(struct drm_crtc *crtc);  int (*enable_vblank)(struct drm_crtc *crtc);  void (*disable_vblank)(struct drm_crtc *crtc);  bool (*get_vblank_timestamp)(struct drm_crtc *crtc,int *max_error,ktime_t *vblank_time, bool in_vblank_irq);};

Members

reset

Reset CRTC hardware and software state to off. This function isn’tcalled by the core directly, only throughdrm_mode_config_reset().It’s not a helper hook only for historical reasons.

Atomic drivers can usedrm_atomic_helper_crtc_reset() to resetatomic state using this hook.

cursor_set

Update the cursor image. The cursor position is relative to the CRTCand can be partially or fully outside of the visible area.

Note that contrary to all other KMS functions the legacy cursor entrypoints don’t take a framebuffer object, but instead take directly araw buffer object id from the driver’s buffer manager (which iseither GEM or TTM for current drivers).

This entry point is deprecated, drivers should instead implementuniversal plane support and register a proper cursor plane usingdrm_crtc_init_with_planes().

This callback is optional

RETURNS:

0 on success or a negative error code on failure.

cursor_set2

Update the cursor image, including hotspot information. The hotspotmust not affect the cursor position in CRTC coordinates, but is onlymeant as a hint for virtualized display hardware to coordinate theguests and hosts cursor position. The cursor hotspot is relative tothe cursor image. Otherwise this works exactly likecursor_set.

This entry point is deprecated, drivers should instead implementuniversal plane support and register a proper cursor plane usingdrm_crtc_init_with_planes().

This callback is optional.

RETURNS:

0 on success or a negative error code on failure.

cursor_move

Update the cursor position. The cursor does not need to be visiblewhen this hook is called.

This entry point is deprecated, drivers should instead implementuniversal plane support and register a proper cursor plane usingdrm_crtc_init_with_planes().

This callback is optional.

RETURNS:

0 on success or a negative error code on failure.

gamma_set

Set gamma on the CRTC.

This callback is optional.

Atomic drivers who want to support gamma tables should implement theatomic color management support, enabled by callingdrm_crtc_enable_color_mgmt(), which then supports the legacy gammainterface through thedrm_atomic_helper_legacy_gamma_set()compatibility implementation.

destroy

Clean up CRTC resources. This is only called at driver unload timethroughdrm_mode_config_cleanup() since a CRTC cannot be hotpluggedin DRM.

set_config

This is the main legacy entry point to change the modeset state on aCRTC. All the details of the desired configuration are passed in astructdrm_mode_set - see there for details.

Drivers implementing atomic modeset should usedrm_atomic_helper_set_config() to implement this hook.

RETURNS:

0 on success or a negative error code on failure.

page_flip

Legacy entry point to schedule a flip to the given framebuffer.

Page flipping is a synchronization mechanism that replaces the framebuffer being scanned out by the CRTC with a new frame buffer duringvertical blanking, avoiding tearing (except when requested otherwisethrough the DRM_MODE_PAGE_FLIP_ASYNC flag). When an applicationrequests a page flip the DRM core verifies that the new frame bufferis large enough to be scanned out by the CRTC in the currentlyconfigured mode and then calls this hook with a pointer to the newframe buffer.

The driver must wait for any pending rendering to the new framebufferto complete before executing the flip. It should also wait for anypending rendering from other drivers if the underlying buffer is ashared dma-buf.

An application can request to be notified when the page flip hascompleted. The drm core will supply astructdrm_event in the eventparameter in this case. This can be handled by thedrm_crtc_send_vblank_event() function, which the driver should call onthe provided event upon completion of the flip. Note that ifthe driver supports vblank signalling and timestamping the vblankcounters and timestamps must agree with the ones returned from pageflip events. With the current vblank helper infrastructure this canbe achieved by holding a vblank reference while the page flip ispending, acquired throughdrm_crtc_vblank_get() and released withdrm_crtc_vblank_put(). Drivers are free to implement their own vblankcounter and timestamp tracking though, e.g. if they have accuratetimestamp registers in hardware.

This callback is optional.

NOTE:

Very early versions of the KMS ABI mandated that the driver mustblock (but not reject) any rendering to the old framebuffer until theflip operation has completed and the old framebuffer is no longervisible. This requirement has been lifted, and userspace is insteadexpected to request delivery of an event and wait with recycling oldbuffers until such has been received.

RETURNS:

0 on success or a negative error code on failure. Note that if apage flip operation is already pending the callback should return-EBUSY. Pageflips on a disabled CRTC (either by setting a NULL modeor just runtime disabled through DPMS respectively the new atomic“ACTIVE” state) should result in an -EINVAL error code. Note thatdrm_atomic_helper_page_flip() checks this already for atomic drivers.

page_flip_target

Same aspage_flip but with an additional parameter specifying theabsolute target vertical blank period (as reported bydrm_crtc_vblank_count()) when the flip should take effect.

Note that the core code calls drm_crtc_vblank_get before this entrypoint, and will call drm_crtc_vblank_put if this entry point returnsany non-0 error code. It’s the driver’s responsibility to calldrm_crtc_vblank_put after this entry point returns 0, typically whenthe flip completes.

set_property

This is the legacy entry point to update a property attached to theCRTC.

This callback is optional if the driver does not support any legacydriver-private properties. For atomic drivers it is not used becauseproperty handling is done entirely in the DRM core.

RETURNS:

0 on success or a negative error code on failure.

atomic_duplicate_state

Duplicate the current atomic state for this CRTC and return it.The core and helpers guarantee that any atomic state duplicated withthis hook and still owned by the caller (i.e. not transferred to thedriver by callingdrm_mode_config_funcs.atomic_commit) will becleaned up by calling theatomic_destroy_state hook in thisstructure.

This callback is mandatory for atomic drivers.

Atomic drivers which don’t subclassstructdrm_crtc_state should usedrm_atomic_helper_crtc_duplicate_state(). Drivers that subclass thestate structure to extend it with driver-private state should use__drm_atomic_helper_crtc_duplicate_state() to make sure shared state isduplicated in a consistent fashion across drivers.

It is an error to call this hook beforedrm_crtc.state has beeninitialized correctly.

NOTE:

If the duplicate state references refcounted resources this hook mustacquire a reference for each of them. The driver must release thesereferences again inatomic_destroy_state.

RETURNS:

Duplicated atomic state or NULL when the allocation failed.

atomic_destroy_state

Destroy a state duplicated withatomic_duplicate_state and releaseor unreference all resources it references

This callback is mandatory for atomic drivers.

atomic_set_property

Decode a driver-private property value and store the decoded valueinto the passed-in state structure. Since the atomic core decodes allstandardized properties (even for extensions beyond the core set ofproperties which might not be implemented by all drivers) thisrequires drivers to subclass the state structure.

Such driver-private properties should really only be implemented fortruly hardware/vendor specific state. Instead it is preferred tostandardize atomic extension and decode the properties used to exposesuch an extension in the core.

Do not call this function directly, usedrm_atomic_crtc_set_property() instead.

This callback is optional if the driver does not support anydriver-private atomic properties.

NOTE:

This function is called in the state assembly phase of atomicmodesets, which can be aborted for any reason (including onuserspace’s request to just check whether a configuration would bepossible). Drivers MUST NOT touch any persistent state (hardware orsoftware) or data structures except the passed instate parameter.

Also since userspace controls in which order properties are set thisfunction must not do any input validation (since the state update isincomplete and hence likely inconsistent). Instead any such inputvalidation must be done in the various atomic_check callbacks.

RETURNS:

0 if the property has been found, -EINVAL if the property isn’timplemented by the driver (which should never happen, the core onlyasks for properties attached to this CRTC). No other validation isallowed by the driver. The core already checks that the propertyvalue is within the range (integer, valid enum value, …) the driverset when registering the property.

atomic_get_property

Reads out the decoded driver-private property. This is used toimplement the GETCRTC IOCTL.

Do not call this function directly, usedrm_atomic_crtc_get_property() instead.

This callback is optional if the driver does not support anydriver-private atomic properties.

RETURNS:

0 on success, -EINVAL if the property isn’t implemented by thedriver (which should never happen, the core only asks forproperties attached to this CRTC).

late_register

This optional hook can be used to register additional userspaceinterfaces attached to the crtc like debugfs interfaces.It is called late in the driver load sequence fromdrm_dev_register().Everything added from this callback should be unregistered inthe early_unregister callback.

Returns:

0 on success, or a negative error code on failure.

early_unregister

This optional hook should be used to unregister the additionaluserspace interfaces attached to the crtc fromlate_register. It is called fromdrm_dev_unregister(),early in the driver unload sequence to disable userspace accessbefore data structures are torndown.

set_crc_source

Changes the source of CRC checksums of frames at the request ofuserspace, typically for testing purposes. The sources available arespecific of each driver and aNULL value indicates that CRCgeneration is to be switched off.

When CRC generation is enabled, the driver should calldrm_crtc_add_crc_entry() at each frame, providing any informationthat characterizes the frame contents in the crcN arguments, asprovided from the configured source. Drivers must accept an “auto”source name that will select a default source for this CRTC.

This may trigger an atomic modeset commit if necessary, to enable CRCgeneration.

Note that “auto” can depend upon the current modeset configuration,e.g. it could pick an encoder or output specific CRC sampling point.

This callback is optional if the driver does not support any CRCgeneration functionality.

RETURNS:

0 on success or a negative error code on failure.

verify_crc_source

verifies the source of CRC checksums of frames before setting thesource for CRC and during crc open. Source parameter can be NULLwhile disabling crc source.

This callback is optional if the driver does not support any CRCgeneration functionality.

RETURNS:

0 on success or a negative error code on failure.

get_crc_sources

Driver callback for getting a list of all the available sources forCRC generation. This callback depends upon verify_crc_source, Soverify_crc_source callback should be implemented before implementingthis. Driver can pass full list of available crc sources, thiscallback does the verification on each crc-source before passing itto userspace.

This callback is optional if the driver does not support exporting ofpossible CRC sources list.

RETURNS:

a constant character pointer to the list of all the available CRCsources. On failure driver should return NULL. count should beupdated with number of sources in list. if zero we don’t process anysource from the list.

atomic_print_state

If driver subclassesstructdrm_crtc_state, it should implementthis optional hook for printing additional driver specific state.

Do not call this directly, use drm_atomic_crtc_print_state()instead.

get_vblank_counter

Driver callback for fetching a raw hardware vblank counter for theCRTC. It’s meant to be used by new drivers as the replacement ofdrm_driver.get_vblank_counter hook.

This callback is optional. If a device doesn’t have a hardwarecounter, the driver can simply leave the hook as NULL. The DRM corewill account for missed vblank events while interrupts where disabledbased on system timestamps.

Wraparound handling and loss of events due to modesetting is dealtwith in the DRM core code, as long as drivers calldrm_crtc_vblank_off() anddrm_crtc_vblank_on() when disabling orenabling a CRTC.

Returns:

Raw vblank counter value.

enable_vblank

Enable vblank interrupts for the CRTC. It’s meant to be used bynew drivers as the replacement ofdrm_driver.enable_vblank hook.

Returns:

Zero on success, appropriate errno if the vblank interrupt cannotbe enabled.

disable_vblank

Disable vblank interrupts for the CRTC. It’s meant to be used bynew drivers as the replacement ofdrm_driver.disable_vblank hook.

get_vblank_timestamp

Called by drm_get_last_vbltimestamp(). Should return a precisetimestamp when the most recent vblank interval ended or will end.

Specifically, the timestamp invblank_time should correspond asclosely as possible to the time when the first video scanline ofthe video frame after the end of vblank will start scanning out,the time immediately after end of the vblank interval. If thecrtc is currently inside vblank, this will be a time in the future.If thecrtc is currently scanning out a frame, this will be thepast start time of the current scanout. This is meant to adhereto the OpenML OML_sync_control extension specification.

Parameters:

crtc:: CRTC for which timestamp should be returned.
max_error:: Maximum allowable timestamp error in nanoseconds.Implementation should strive to provide timestampwith an error of at most max_error nanoseconds.Returns true upper bound on error for timestamp.
vblank_time:: Target location for returned vblank timestamp.
in_vblank_irq:: True when called fromdrm_crtc_handle_vblank(). Some driversneed to apply some workarounds for gpu-specific vblank irq quirksif flag is set.

Returns:

True on success, false on failure, which means the core shouldfallback to a simple timestamp taken indrm_crtc_handle_vblank().

Description

The drm_crtc_funcs structure is the central CRTC management structurein the DRM. Each CRTC controls one or more connectors (note that the nameCRTC is simply historical, a CRTC may control LVDS, VGA, DVI, TV out, etc.connectors, not just CRTs).

Each driver is responsible for filling out this structure at startup time,in addition to providing other modesetting features, like i2c and DDCbus accessors.

structdrm_crtc¶: central CRTC control structure

Definition

struct drm_crtc {  struct drm_device *dev;  struct device_node *port;  struct list_head head;  char *name;  struct drm_modeset_lock mutex;  struct drm_mode_object base;  struct drm_plane *primary;  struct drm_plane *cursor;  unsigned index;  int cursor_x;  int cursor_y;  bool enabled;  struct drm_display_mode mode;  struct drm_display_mode hwmode;  int x;  int y;  const struct drm_crtc_funcs *funcs;  uint32_t gamma_size;  uint16_t *gamma_store;  const struct drm_crtc_helper_funcs *helper_private;  struct drm_object_properties properties;  struct drm_crtc_state *state;  struct list_head commit_list;  spinlock_t commit_lock;#ifdef CONFIG_DEBUG_FS;  struct dentry *debugfs_entry;#endif;  struct drm_crtc_crc crc;  unsigned int fence_context;  spinlock_t fence_lock;  unsigned long fence_seqno;  char timeline_name[32];  struct drm_self_refresh_data *self_refresh_data;};

Members

dev

parent DRM device

port

OF node used bydrm_of_find_possible_crtcs().

head

List of all CRTCs ondev, linked fromdrm_mode_config.crtc_list.Invariant over the lifetime ofdev and therefore does not needlocking.

name

human readable name, can be overwritten by the driver

mutex

This provides a read lock for the overall CRTC state (mode, dpmsstate, …) and a write lock for everything which can be updatewithout a full modeset (fb, cursor data, CRTC properties …). A fullmodeset also need to grabdrm_mode_config.connection_mutex.

For atomic drivers specifically this protectsstate.

base

base KMS object for ID tracking etc.

primary

Primary plane for this CRTC. Note that this is onlyrelevant for legacy IOCTL, it specifies the plane implicitly used bythe SETCRTC and PAGE_FLIP IOCTLs. It does not have any significancebeyond that.

cursor

Cursor plane for this CRTC. Note that this is only relevant forlegacy IOCTL, it specifies the plane implicitly used by the SETCURSORand SETCURSOR2 IOCTLs. It does not have any significancebeyond that.

index

Position inside the mode_config.list, can be used as an arrayindex. It is invariant over the lifetime of the CRTC.

cursor_x

Current x position of the cursor, used for universalcursor planes because the SETCURSOR IOCTL only can update theframebuffer without supplying the coordinates. Drivers should not usethis directly, atomic drivers should look atdrm_plane_state.crtc_xof the cursor plane instead.

cursor_y

Current y position of the cursor, used for universalcursor planes because the SETCURSOR IOCTL only can update theframebuffer without supplying the coordinates. Drivers should not usethis directly, atomic drivers should look atdrm_plane_state.crtc_yof the cursor plane instead.

enabled

Is this CRTC enabled? Should only be used by legacy drivers, atomicdrivers should instead consultdrm_crtc_state.enable anddrm_crtc_state.active. Atomic drivers can update this by callingdrm_atomic_helper_update_legacy_modeset_state().

mode

Current mode timings. Should only be used by legacy drivers, atomicdrivers should instead consultdrm_crtc_state.mode. Atomic driverscan update this by callingdrm_atomic_helper_update_legacy_modeset_state().

hwmode

Programmed mode in hw, after adjustments for encoders, crtc, panelscaling etc. Should only be used by legacy drivers, for highprecision vblank timestamps indrm_crtc_vblank_helper_get_vblank_timestamp().

Note that atomic drivers should not use this, but instead usedrm_crtc_state.adjusted_mode. And for high-precision timestampsdrm_crtc_vblank_helper_get_vblank_timestamp() useddrm_vblank_crtc.hwmode,which is filled out by callingdrm_calc_timestamping_constants().

x

x position on screen. Should only be used by legacy drivers, atomicdrivers should look atdrm_plane_state.crtc_x of the primary planeinstead. Updated by callingdrm_atomic_helper_update_legacy_modeset_state().

y

y position on screen. Should only be used by legacy drivers, atomicdrivers should look atdrm_plane_state.crtc_y of the primary planeinstead. Updated by callingdrm_atomic_helper_update_legacy_modeset_state().

funcs

CRTC control functions

gamma_size

Size of legacy gamma ramp reported to userspace. Set upby callingdrm_mode_crtc_set_gamma_size().

gamma_store

Gamma ramp values used by the legacy SETGAMMA andGETGAMMA IOCTls. Set up by callingdrm_mode_crtc_set_gamma_size().

helper_private

mid-layer private data

properties

property tracking for this CRTC

state

Current atomic state for this CRTC.

This is protected bymutex. Note that nonblocking atomic commitsaccess the current CRTC state without taking locks. Either by goingthrough thestructdrm_atomic_state pointers, seefor_each_oldnew_crtc_in_state(),for_each_old_crtc_in_state() andfor_each_new_crtc_in_state(). Or through careful ordering of atomiccommit operations as implemented in the atomic helpers, seestructdrm_crtc_commit.

commit_list

List ofdrm_crtc_commit structures tracking pending commits.Protected bycommit_lock. This list holds its own full reference,as does the ongoing commit.

“Note that the commit for a state change is also tracked indrm_crtc_state.commit. For accessing the immediately precedingcommit in an atomic update it is recommended to just use thatpointer in the old CRTC state, since accessing that doesn’t needany locking or list-walking.commit_list should only be used tostall for framebuffer cleanup that’s signalled throughdrm_crtc_commit.cleanup_done.”

commit_lock

Spinlock to protectcommit_list.

debugfs_entry

Debugfs directory for this CRTC.

crc

Configuration settings of CRC capture.

fence_context

timeline context used for fence operations.

fence_lock

spinlock to protect the fences in the fence_context.

fence_seqno

Seqno variable used as monotonic counter for the fencescreated on the CRTC’s timeline.

timeline_name

The name of the CRTC’s fence timeline.

self_refresh_data

Holds the state for the self refresh helpers

Initialized viadrm_self_refresh_helper_init().

Description

Each CRTC may have one or more connectors associated with it. This structureallows the CRTC to be controlled.

structdrm_mode_set¶: new values for a CRTC config change

Definition

struct drm_mode_set {  struct drm_framebuffer *fb;  struct drm_crtc *crtc;  struct drm_display_mode *mode;  uint32_t x;  uint32_t y;  struct drm_connector **connectors;  size_t num_connectors;};

Members

fb: framebuffer to use for new config
crtc: CRTC whose configuration we’re about to change
mode: mode timings to use
x: position of this CRTC relative tofb
y: position of this CRTC relative tofb
connectors: array of connectors to drive with this CRTC if possible
num_connectors: size ofconnectors array

Description

This represents a modeset configuration for the legacy SETCRTC ioctl and isalso used internally. Atomic drivers instead usedrm_atomic_state.

unsigned intdrm_crtc_index(const structdrm_crtc * crtc)¶: find the index of a registered CRTC

Parameters

conststructdrm_crtc*crtc: CRTC to find index for

Description

Given a registered CRTC, return the index of that CRTC within a DRMdevice’s list of CRTCs.

uint32_tdrm_crtc_mask(const structdrm_crtc * crtc)¶: find the mask of a registered CRTC

Parameters

conststructdrm_crtc*crtc: CRTC to find mask for

Description

Given a registered CRTC, return the mask bit of that CRTC for thedrm_encoder.possible_crtcs anddrm_plane.possible_crtcs fields.

structdrm_crtc *drm_crtc_find(structdrm_device * dev, structdrm_file * file_priv, uint32_t id)¶: look up a CRTC object from its ID

Parameters

structdrm_device*dev: DRM device
structdrm_file*file_priv: drm file to check for lease against.
uint32_tid: drm_mode_object ID

Description

This can be used to look up a CRTC from its userspace ID. Only used bydrivers for legacy IOCTLs and interface, nowadays extensions to the KMSuserspace interface should be done usingdrm_property.

drm_for_each_crtc(crtc,dev)¶: iterate over all CRTCs

Parameters

crtc: astructdrm_crtc as the loop cursor
dev: thestructdrm_device

Description

Iterate over all CRTCs ofdev.

structdrm_crtc *drm_crtc_from_index(structdrm_device * dev, int idx)¶: find the registered CRTC at an index

Parameters

structdrm_device*dev: DRM device
intidx: index of registered CRTC to find for

Description

Given a CRTC index, return the registered CRTC from DRM device’slist of CRTCs with matching index. This is the inverse ofdrm_crtc_index().It’s useful in the vblank callbacks (likedrm_driver.enable_vblank ordrm_driver.disable_vblank), since that still deals with indices insteadof pointers tostructdrm_crtc.”

intdrm_crtc_init_with_planes(structdrm_device * dev, structdrm_crtc * crtc, structdrm_plane * primary, structdrm_plane * cursor, const structdrm_crtc_funcs * funcs, const char * name, ...)¶: Initialise a new CRTC object with specified primary and cursor planes.

Parameters

structdrm_device*dev: DRM device
structdrm_crtc*crtc: CRTC object to init
structdrm_plane*primary: Primary plane for CRTC
structdrm_plane*cursor: Cursor plane for CRTC
conststructdrm_crtc_funcs*funcs: callbacks for the new CRTC
constchar*name: printf style format string for the CRTC name, or NULL for default name
...: variable arguments

Description

Inits a new object created as base part of a driver crtc object. Driversshould use this function instead ofdrm_crtc_init(), which is only providedfor backwards compatibility with drivers which do not yet support universalplanes). For really simple hardware which has only 1 plane look atdrm_simple_display_pipe_init() instead.

Return

Zero on success, error code on failure.

voiddrm_crtc_cleanup(structdrm_crtc * crtc)¶: Clean up the core crtc usage

Parameters

structdrm_crtc*crtc: CRTC to cleanup

Description

This function cleans upcrtc and removes it from the DRM mode settingcore. Note that the function doesnot free the crtc structure itself,this is the responsibility of the caller.

intdrm_mode_set_config_internal(structdrm_mode_set * set)¶: helper to calldrm_mode_config_funcs.set_config

Parameters

structdrm_mode_set*set: modeset config to set

Description

This is a little helper to wrap internal calls to thedrm_mode_config_funcs.set_config driver interface. The only thing it adds iscorrect refcounting dance.

This should only be used by non-atomic legacy drivers.

Return

Zero on success, negative errno on failure.

intdrm_crtc_check_viewport(const structdrm_crtc * crtc, int x, int y, const structdrm_display_mode * mode, const structdrm_framebuffer * fb)¶: Checks that a framebuffer is big enough for the CRTC viewport

Parameters

conststructdrm_crtc*crtc: CRTC that framebuffer will be displayed on
intx: x panning
inty: y panning
conststructdrm_display_mode*mode: mode that framebuffer will be displayed under
conststructdrm_framebuffer*fb: framebuffer to check size of

Frame Buffer Abstraction¶

Frame buffers are abstract memory objects that provide a source of pixels toscanout to a CRTC. Applications explicitly request the creation of framebuffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and receive an opaquehandle that can be passed to the KMS CRTC control, plane configuration andpage flip functions.

Frame buffers rely on the underlying memory manager for allocating backingstorage. When creating a frame buffer applications pass a memory handle(or a list of memory handles for multi-planar formats) through thestructdrm_mode_fb_cmd2 argument. For drivers using GEM as their userspacebuffer management interface this would be a GEM handle. Drivers are howeverfree to use their own backing storage object handles, e.g. vmwgfx directlyexposes special TTM handles to userspace and so expects TTM handles in thecreate ioctl and not GEM handles.

Framebuffers are tracked withstructdrm_framebuffer. They are publishedusingdrm_framebuffer_init() - after calling that function userspace can useand access the framebuffer object. The helper functiondrm_helper_mode_fill_fb_struct() can be used to pre-fill the requiredmetadata fields.

The lifetime of a drm framebuffer is controlled with a reference count,drivers can grab additional references withdrm_framebuffer_get() and dropthem again withdrm_framebuffer_put(). For driver-private framebuffers forwhich the last reference is never dropped (e.g. for the fbdev framebufferwhen the structstructdrm_framebuffer is embedded into the fbdev helperstruct) drivers can manually clean up a framebuffer at module unload timewithdrm_framebuffer_unregister_private(). But doing this is notrecommended, and it’s better to have a normal free-standingstructdrm_framebuffer.

Frame Buffer Functions Reference¶

structdrm_framebuffer_funcs¶: framebuffer hooks

Definition

struct drm_framebuffer_funcs {  void (*destroy)(struct drm_framebuffer *framebuffer);  int (*create_handle)(struct drm_framebuffer *fb,struct drm_file *file_priv, unsigned int *handle);  int (*dirty)(struct drm_framebuffer *framebuffer,struct drm_file *file_priv, unsigned flags,unsigned color, struct drm_clip_rect *clips, unsigned num_clips);};

Members

destroy

Clean up framebuffer resources, specifically also unreference thebacking storage. The core guarantees to call this function for everyframebuffer successfully created by callingdrm_mode_config_funcs.fb_create. Drivers must also calldrm_framebuffer_cleanup() to release DRM core resources for thisframebuffer.

create_handle

Create a buffer handle in the driver-specific buffer manager (eitherGEM or TTM) valid for the passed-instructdrm_file. This is used bythe core to implement the GETFB IOCTL, which returns (forsufficiently priviledged user) also a native buffer handle. This canbe used for seamless transitions between modesetting clients bycopying the current screen contents to a private buffer and blendingbetween that and the new contents.

GEM based drivers should calldrm_gem_handle_create() to create thehandle.

RETURNS:

0 on success or a negative error code on failure.

dirty

Optional callback for the dirty fb IOCTL.

Userspace can notify the driver via this callback that an area of theframebuffer has changed and should be flushed to the displayhardware. This can also be used internally, e.g. by the fbdevemulation, though that’s not the case currently.

See documentation in drm_mode.h for the struct drm_mode_fb_dirty_cmdfor more information as all the semantics and arguments have a one toone mapping on this function.

Atomic drivers should usedrm_atomic_helper_dirtyfb() to implementthis hook.

RETURNS:

0 on success or a negative error code on failure.

structdrm_framebuffer¶: frame buffer object

Definition

struct drm_framebuffer {  struct drm_device *dev;  struct list_head head;  struct drm_mode_object base;  char comm[TASK_COMM_LEN];  const struct drm_format_info *format;  const struct drm_framebuffer_funcs *funcs;  unsigned int pitches[4];  unsigned int offsets[4];  uint64_t modifier;  unsigned int width;  unsigned int height;  int flags;  int hot_x;  int hot_y;  struct list_head filp_head;  struct drm_gem_object *obj[4];};

Members

dev

DRM device this framebuffer belongs to

head

Place on thedrm_mode_config.fb_list, access protected bydrm_mode_config.fb_lock.

base

base modeset object structure, contains the reference count.

comm

Name of the process allocating the fb, used for fb dumping.

format

framebuffer format information

funcs

framebuffer vfunc table

pitches

Line stride per buffer. For userspace created object thisis copied from drm_mode_fb_cmd2.

offsets

Offset from buffer start to the actual pixel data in bytes,per buffer. For userspace created object this is copied fromdrm_mode_fb_cmd2.

Note that this is a linear offset and does not take into accounttiling or buffer laytou permodifier. It meant to be used when theactual pixel data for this framebuffer plane starts at an offset,e.g. when multiple planes are allocated within the same backingstorage buffer object. For tiled layouts this generally means itoffsets must at least be tile-size aligned, but hardware often hasstricter requirements.

This should not be used to specifiy x/y pixel offsets into the bufferdata (even for linear buffers). Specifying an x/y pixel offset isinstead done through the source rectangle instructdrm_plane_state.

modifier

Data layout modifier. This is used to describetiling, or also special layouts (like compression) of auxiliarybuffers. For userspace created object this is copied fromdrm_mode_fb_cmd2.

width

Logical width of the visible area of the framebuffer, inpixels.

height

Logical height of the visible area of the framebuffer, inpixels.

flags

Framebuffer flags like DRM_MODE_FB_INTERLACED orDRM_MODE_FB_MODIFIERS.

hot_x

X coordinate of the cursor hotspot. Used by the legacy cursorIOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSORuniversal plane.

hot_y

Y coordinate of the cursor hotspot. Used by the legacy cursorIOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSORuniversal plane.

filp_head

Placed ondrm_file.fbs, protected bydrm_file.fbs_lock.

obj

GEM objects backing the framebuffer, one per plane (optional).

This is used by the GEM framebuffer helpers, see e.g.drm_gem_fb_create().

Description

Note that the fb is refcounted for the benefit of driver internals,for example some hw, disabling a CRTC/plane is asynchronous, andscanout does not actually complete until the next vblank. So somecleanup (like releasing the reference(s) on the backing GEM bo(s))should be deferred. In cases like this, the driver would like tohold a ref to the fb even though it has already been removed fromuserspace perspective. Seedrm_framebuffer_get() anddrm_framebuffer_put().

The refcount is stored inside the mode objectbase.

voiddrm_framebuffer_get(structdrm_framebuffer * fb)¶: acquire a framebuffer reference

Parameters

structdrm_framebuffer*fb: DRM framebuffer

Description

This function increments the framebuffer’s reference count.

voiddrm_framebuffer_put(structdrm_framebuffer * fb)¶: release a framebuffer reference

Parameters

structdrm_framebuffer*fb: DRM framebuffer

Description

This function decrements the framebuffer’s reference count and frees theframebuffer if the reference count drops to zero.

uint32_tdrm_framebuffer_read_refcount(const structdrm_framebuffer * fb)¶: read the framebuffer reference count.

Parameters

conststructdrm_framebuffer*fb: framebuffer

Description

This functions returns the framebuffer’s reference count.

voiddrm_framebuffer_assign(structdrm_framebuffer ** p, structdrm_framebuffer * fb)¶: store a reference to the fb

Parameters

structdrm_framebuffer**p: location to store framebuffer
structdrm_framebuffer*fb: new framebuffer (maybe NULL)

Description

This functions sets the location to store a reference to the framebuffer,unreferencing the framebuffer that was previously stored in that location.

structdrm_afbc_framebuffer¶: a special afbc frame buffer object

Definition

struct drm_afbc_framebuffer {  struct drm_framebuffer base;  u32 block_width;  u32 block_height;  u32 aligned_width;  u32 aligned_height;  u32 offset;  u32 afbc_size;};

Members

base: base framebuffer structure.
block_width: width of a single afbc block
block_height: height of a single afbc block
aligned_width: aligned frame buffer width
aligned_height: aligned frame buffer height
offset: offset of the first afbc header
afbc_size: minimum size of afbc buffer

Description

A derived class of struct drm_framebuffer, dedicated for afbc use cases.

intdrm_framebuffer_init(structdrm_device * dev, structdrm_framebuffer * fb, const structdrm_framebuffer_funcs * funcs)¶: initialize a framebuffer

Parameters

structdrm_device*dev: DRM device
structdrm_framebuffer*fb: framebuffer to be initialized
conststructdrm_framebuffer_funcs*funcs: … with these functions

Description

Allocates an ID for the framebuffer’s parent mode object, sets its modefunctions & device file and adds it to the master fd list.

IMPORTANT:This functions publishes the fb and makes it available for concurrent accessby other users. Which means by this point the fb _must_ be fully set up -since all the fb attributes are invariant over its lifetime, no furtherlocking but only correct reference counting is required.

Return

Zero on success, error code on failure.

structdrm_framebuffer *drm_framebuffer_lookup(structdrm_device * dev, structdrm_file * file_priv, uint32_t id)¶: look up a drm framebuffer and grab a reference

Parameters

structdrm_device*dev: drm device
structdrm_file*file_priv: drm file to check for lease against.
uint32_tid: id of the fb object

Description

If successful, this grabs an additional reference to the framebuffer -callers need to make sure to eventually unreference the returned framebufferagain, usingdrm_framebuffer_put().

voiddrm_framebuffer_unregister_private(structdrm_framebuffer * fb)¶: unregister a private fb from the lookup idr

Parameters

structdrm_framebuffer*fb: fb to unregister

Description

Drivers need to call this when cleaning up driver-private framebuffers, e.g.those used for fbdev. Note that the caller must hold a reference of its own,i.e. the object may not be destroyed through this call (since it’ll lead to alocking inversion).

NOTE

This function is deprecated. For driver-private framebuffers it is notrecommended to embed a framebuffer struct info fbdev struct, instead, aframebuffer pointer is preferred anddrm_framebuffer_put() should be calledwhen the framebuffer is to be cleaned up.

voiddrm_framebuffer_cleanup(structdrm_framebuffer * fb)¶: remove a framebuffer object

Parameters

structdrm_framebuffer*fb: framebuffer to remove

Description

Cleanup framebuffer. This function is intended to be used from the driversdrm_framebuffer_funcs.destroy callback. It can also be used to clean updriver private framebuffers embedded into a larger structure.

Note that this function does not remove the fb from active usage - if it isstill used anywhere, hilarity can ensue since userspace could call getfb onthe id and get back -EINVAL. Obviously no concern at driver unload time.

Also, the framebuffer will not be removed from the lookup idr - foruser-created framebuffers this will happen in in the rmfb ioctl. Fordriver-private objects (e.g. for fbdev) drivers need to explicitly calldrm_framebuffer_unregister_private.

voiddrm_framebuffer_remove(structdrm_framebuffer * fb)¶: remove and unreference a framebuffer object

Parameters

structdrm_framebuffer*fb: framebuffer to remove

Description

Scans all the CRTCs and planes indev’s mode_config. If they’reusingfb, removes it, setting it to NULL. Then drops the reference to thepassed-in framebuffer. Might take the modeset locks.

Note that this function optimizes the cleanup away if the caller holds thelast reference to the framebuffer. It is also guaranteed to not take themodeset locks in this case.

intdrm_framebuffer_plane_width(int width, const structdrm_framebuffer * fb, int plane)¶: width of the plane given the first plane

Parameters

intwidth: width of the first plane
conststructdrm_framebuffer*fb: the framebuffer
intplane: plane index

Return

The width ofplane, given that the width of the first plane iswidth.

intdrm_framebuffer_plane_height(int height, const structdrm_framebuffer * fb, int plane)¶: height of the plane given the first plane

Parameters

intheight: height of the first plane
conststructdrm_framebuffer*fb: the framebuffer
intplane: plane index

Return

The height ofplane, given that the height of the first plane isheight.

DRM Format Handling¶

In the DRM subsystem, framebuffer pixel formats are described using thefourcc codes defined ininclude/uapi/drm/drm_fourcc.h. In addition to thefourcc code, a Format Modifier may optionally be provided, in order tofurther describe the buffer’s format - for example tiling or compression.

Format Modifiers¶

Format modifiers are used in conjunction with a fourcc code, forming aunique fourcc:modifier pair. This format:modifier pair must fully define theformat and data layout of the buffer, and should be the only way to describethat particular buffer.

Having multiple fourcc:modifier pairs which describe the same layout shouldbe avoided, as such aliases run the risk of different drivers exposingdifferent names for the same data format, forcing userspace to understandthat they are aliases.

Format modifiers may change any property of the buffer, including the numberof planes and/or the required allocation size. Format modifiers arevendor-namespaced, and as such the relationship between a fourcc code and amodifier is specific to the modifer being used. For example, some modifiersmay preserve meaning - such as number of planes - from the fourcc code,whereas others may not.

Vendors should document their modifier usage in as much detail aspossible, to ensure maximum compatibility across devices, drivers andapplications.

The authoritative list of format modifier codes is found ininclude/uapi/drm/drm_fourcc.h

Format Functions Reference¶

structdrm_format_info¶: information about a DRM format

Definition

struct drm_format_info {  u32 format;  u8 depth;  u8 num_planes;  union {    u8 cpp[4];    u8 char_per_block[4];  };  u8 block_w[4];  u8 block_h[4];  u8 hsub;  u8 vsub;  bool has_alpha;  bool is_yuv;};

Members

format

4CC format identifier (DRM_FORMAT_*)

depth

Color depth (number of bits per pixel excluding padding bits),valid for a subset of RGB formats only. This is a legacy field, donot use in new code and set to 0 for new formats.

num_planes

Number of color planes (1 to 3)

{unnamed_union}

anonymous

cpp

Number of bytes per pixel (per plane), this is aliased withchar_per_block. It is deprecated in favour of using thetripletchar_per_block,block_w,block_h for betterdescribing the pixel format.

char_per_block

Number of bytes per block (per plane), where blocks aredefined as a rectangle of pixels which are stored next toeach other in a byte aligned memory region. Together withblock_w andblock_h this is used to properly describe tilesin tiled formats or to describe groups of pixels in packedformats for which the memory needed for a single pixel is notbyte aligned.

cpp has been kept for historical reasons because there area lot of places in drivers where it’s used. In drm core forgeneric code paths the preferred way is to usechar_per_block,drm_format_info_block_width() anddrm_format_info_block_height() which allows handling bothblock and non-block formats in the same way.

For formats that are intended to be used only with non-linearmodifiers bothcpp andchar_per_block must be 0 in thegeneric format table. Drivers could supply accurateinformation from their drm_mode_config.get_format_info hookif they want the core to be validating the pitch.

block_w

Block width in pixels, this is intended to be accessed throughdrm_format_info_block_width()

block_h

Block height in pixels, this is intended to be accessed throughdrm_format_info_block_height()

hsub

Horizontal chroma subsampling factor

vsub

Vertical chroma subsampling factor

has_alpha

Does the format embeds an alpha component?

is_yuv

Is it a YUV format?

structdrm_format_name_buf¶: name of a DRM format

Definition

struct drm_format_name_buf {  char str[32];};

Members

str: string buffer containing the format name

booldrm_format_info_is_yuv_packed(const structdrm_format_info * info)¶: check that the format info matches a YUV format with data laid in a single plane

Parameters

conststructdrm_format_info*info: format info

Return

A boolean indicating whether the format info matches a packed YUV format.

booldrm_format_info_is_yuv_semiplanar(const structdrm_format_info * info)¶: check that the format info matches a YUV format with data laid in two planes (luminance and chrominance)

Parameters

conststructdrm_format_info*info: format info

Return

A boolean indicating whether the format info matches a semiplanar YUV format.

booldrm_format_info_is_yuv_planar(const structdrm_format_info * info)¶: check that the format info matches a YUV format with data laid in three planes (one for each YUV component)

Parameters

conststructdrm_format_info*info: format info

Return

A boolean indicating whether the format info matches a planar YUV format.

booldrm_format_info_is_yuv_sampling_410(const structdrm_format_info * info)¶: check that the format info matches a YUV format with 4:1:0 sub-sampling

Parameters

conststructdrm_format_info*info: format info

Return

A boolean indicating whether the format info matches a YUV format with 4:1:0sub-sampling.

booldrm_format_info_is_yuv_sampling_411(const structdrm_format_info * info)¶: check that the format info matches a YUV format with 4:1:1 sub-sampling

Parameters

conststructdrm_format_info*info: format info

Return

A boolean indicating whether the format info matches a YUV format with 4:1:1sub-sampling.

booldrm_format_info_is_yuv_sampling_420(const structdrm_format_info * info)¶: check that the format info matches a YUV format with 4:2:0 sub-sampling

Parameters

conststructdrm_format_info*info: format info

Return

A boolean indicating whether the format info matches a YUV format with 4:2:0sub-sampling.

booldrm_format_info_is_yuv_sampling_422(const structdrm_format_info * info)¶: check that the format info matches a YUV format with 4:2:2 sub-sampling

Parameters

conststructdrm_format_info*info: format info

Return

A boolean indicating whether the format info matches a YUV format with 4:2:2sub-sampling.

booldrm_format_info_is_yuv_sampling_444(const structdrm_format_info * info)¶: check that the format info matches a YUV format with 4:4:4 sub-sampling

Parameters

conststructdrm_format_info*info: format info

Return

A boolean indicating whether the format info matches a YUV format with 4:4:4sub-sampling.

intdrm_format_info_plane_width(const structdrm_format_info * info, int width, int plane)¶: width of the plane given the first plane

Parameters

conststructdrm_format_info*info: pixel format info
intwidth: width of the first plane
intplane: plane index

Return

The width ofplane, given that the width of the first plane iswidth.

intdrm_format_info_plane_height(const structdrm_format_info * info, int height, int plane)¶: height of the plane given the first plane

Parameters

conststructdrm_format_info*info: pixel format info
intheight: height of the first plane
intplane: plane index

Return

The height ofplane, given that the height of the first plane isheight.

uint32_tdrm_mode_legacy_fb_format(uint32_t bpp, uint32_t depth)¶: compute drm fourcc code from legacy description

Parameters

uint32_tbpp: bits per pixels
uint32_tdepth: bit depth per pixel

Description

Computes a drm fourcc pixel format code for the givenbpp/depth values.Useful in fbdev emulation code, since that deals in those values.

uint32_tdrm_driver_legacy_fb_format(structdrm_device * dev, uint32_t bpp, uint32_t depth)¶: compute drm fourcc code from legacy description

Parameters

structdrm_device*dev: DRM device
uint32_tbpp: bits per pixels
uint32_tdepth: bit depth per pixel

Description

Computes a drm fourcc pixel format code for the givenbpp/depth values.Unlikedrm_mode_legacy_fb_format() this looks at the drivers mode_config,and depending on thedrm_mode_config.quirk_addfb_prefer_host_byte_order flagit returns little endian byte order or host byte order framebuffer formats.

const char *drm_get_format_name(uint32_t format, structdrm_format_name_buf * buf)¶: fill a string with a drm fourcc format’s name

Parameters

uint32_tformat: format to compute name of
structdrm_format_name_buf*buf: caller-supplied buffer

const structdrm_format_info *drm_format_info(u32 format): query information for a given format

Parameters

u32format: pixel format (DRM_FORMAT_*)

Description

The caller should only pass a supported pixel format to this function.Unsupported pixel formats will generate a warning in the kernel log.

Return

The instance of struct drm_format_info that describes the pixel format, orNULL if the format is unsupported.

const structdrm_format_info *drm_get_format_info(structdrm_device * dev, const struct drm_mode_fb_cmd2 * mode_cmd)¶: query information for a given framebuffer configuration

Parameters

structdrm_device*dev: DRM device
conststructdrm_mode_fb_cmd2*mode_cmd: metadata from the userspace fb creation request

Return

The instance of struct drm_format_info that describes the pixel format, orNULL if the format is unsupported.

unsigned intdrm_format_info_block_width(const structdrm_format_info * info, int plane)¶: width in pixels of block.

Parameters

conststructdrm_format_info*info: pixel format info
intplane: plane index

Return

The width in pixels of a block, depending on the plane index.

unsigned intdrm_format_info_block_height(const structdrm_format_info * info, int plane)¶: height in pixels of a block

Parameters

conststructdrm_format_info*info: pixel format info
intplane: plane index

Return

The height in pixels of a block, depending on the plane index.

uint64_tdrm_format_info_min_pitch(const structdrm_format_info * info, int plane, unsigned int buffer_width)¶: computes the minimum required pitch in bytes

Parameters

conststructdrm_format_info*info: pixel format info
intplane: plane index
unsignedintbuffer_width: buffer width in pixels

Return

The minimum required pitch in bytes for a buffer by taking into considerationthe pixel format information and the buffer width.

Dumb Buffer Objects¶

The KMS API doesn’t standardize backing storage object creation and leaves itto driver-specific ioctls. Furthermore actually creating a buffer object evenfor GEM-based drivers is done through a driver-specific ioctl - GEM only hasa common userspace interface for sharing and destroying objects. While not anissue for full-fledged graphics stacks that include device-specific userspacecomponents (in libdrm for instance), this limit makes DRM-based early bootgraphics unnecessarily complex.

Dumb objects partly alleviate the problem by providing a standard API tocreate dumb buffers suitable for scanout, which can then be used to createKMS frame buffers.

To support dumb objects drivers must implement thedrm_driver.dumb_createoperation.drm_driver.dumb_destroy defaults todrm_gem_dumb_destroy() ifnot set anddrm_driver.dumb_map_offset defaults todrm_gem_dumb_map_offset(). See the callbacks for further details.

Note that dumb objects may not be used for gpu acceleration, as has beenattempted on some ARM embedded platforms. Such drivers really must havea hardware-specific ioctl to allocate suitable buffer objects.

Plane Abstraction¶

A plane represents an image source that can be blended with or overlayed ontop of a CRTC during the scanout process. Planes take their input data from adrm_framebuffer object. The plane itself specifies the cropping and scalingof that image, and where it is placed on the visible are of a displaypipeline, represented bydrm_crtc. A plane can also have additionalproperties that specify how the pixels are positioned and blended, likerotation or Z-position. All these properties are stored indrm_plane_state.

To create a plane, a KMS drivers allocates and zeroes an instances ofstructdrm_plane (possibly as part of a larger structure) and registers itwith a call todrm_universal_plane_init().

Cursor and overlay planes are optional. All drivers should provide oneprimary plane per CRTC to avoid surprising userspace too much. See enumdrm_plane_type for a more in-depth discussion of these special uapi-relevantplane types. Special planes are associated with their CRTC by callingdrm_crtc_init_with_planes().

The type of a plane is exposed in the immutable “type” enumeration property,which has one of the following values: “Overlay”, “Primary”, “Cursor”.

Plane Functions Reference¶

structdrm_plane_state¶: mutable plane state

Definition

struct drm_plane_state {  struct drm_plane *plane;  struct drm_crtc *crtc;  struct drm_framebuffer *fb;  struct dma_fence *fence;  int32_t crtc_x;  int32_t crtc_y;  uint32_t crtc_w, crtc_h;  uint32_t src_x;  uint32_t src_y;  uint32_t src_h, src_w;  u16 alpha;  uint16_t pixel_blend_mode;  unsigned int rotation;  unsigned int zpos;  unsigned int normalized_zpos;  enum drm_color_encoding color_encoding;  enum drm_color_range color_range;  struct drm_property_blob *fb_damage_clips;  struct drm_rect src, dst;  bool visible;  struct drm_crtc_commit *commit;  struct drm_atomic_state *state;};

Members

plane

backpointer to the plane

crtc

Currently bound CRTC, NULL if disabled. Do not this write directly,usedrm_atomic_set_crtc_for_plane()

fb

Currently bound framebuffer. Do not write this directly, usedrm_atomic_set_fb_for_plane()

fence

Optional fence to wait for before scanning outfb. The core atomiccode will set this when userspace is using explicit fencing. Do notwrite this field directly for a driver’s implicit fence, usedrm_atomic_set_fence_for_plane() to ensure that an explicit fence ispreserved.

Drivers should store any implicit fence in this from theirdrm_plane_helper_funcs.prepare_fb callback. Seedrm_gem_fb_prepare_fb()anddrm_gem_fb_simple_display_pipe_prepare_fb() for suitable helpers.

crtc_x

Left position of visible portion of plane on crtc, signed destlocation allows it to be partially off screen.

crtc_y

Upper position of visible portion of plane on crtc, signed destlocation allows it to be partially off screen.

crtc_w

width of visible portion of plane on crtc

crtc_h

height of visible portion of plane on crtc

src_x

left position of visible portion of plane within plane (in16.16 fixed point).

src_y

upper position of visible portion of plane within plane (in16.16 fixed point).

src_h

height of visible portion of plane (in 16.16)

src_w

width of visible portion of plane (in 16.16)

alpha

Opacity of the plane with 0 as completely transparent and 0xffff ascompletely opaque. Seedrm_plane_create_alpha_property() for moredetails.

pixel_blend_mode

The alpha blending equation selection, describing how the pixels fromthe current plane are composited with the background. Value can beone of DRM_MODE_BLEND_*

rotation

Rotation of the plane. Seedrm_plane_create_rotation_property() formore details.

zpos

Priority of the given plane on crtc (optional).

User-space may set mutable zpos properties so that multiple activeplanes on the same CRTC have identical zpos values. This is auser-space bug, but drivers can solve the conflict by comparing theplane object IDs; the plane with a higher ID is stacked on top of aplane with a lower ID.

Seedrm_plane_create_zpos_property() anddrm_plane_create_zpos_immutable_property() for more details.

normalized_zpos

Normalized value of zpos: unique, range from 0 to N-1 where N is thenumber of active planes for given crtc. Note that the driver must setdrm_mode_config.normalize_zpos or calldrm_atomic_normalize_zpos() toupdate this before it can be trusted.

color_encoding

Color encoding for non RGB formats

color_range

Color range for non RGB formats

fb_damage_clips

Blob representing damage (area in plane framebuffer that changedsince last plane update) as an array ofdrm_mode_rect in framebuffercoodinates of the attached framebuffer. Note that unlike plane src,damage clips are not in 16.16 fixed point.

src

source coordinates of the plane (in 16.16).

When usingdrm_atomic_helper_check_plane_state(),the coordinates are clipped, but the driver may chooseto use unclipped coordinates instead when the hardwareperforms the clipping automatically.

dst

clipped destination coordinates of the plane.

When usingdrm_atomic_helper_check_plane_state(),the coordinates are clipped, but the driver may chooseto use unclipped coordinates instead when the hardwareperforms the clipping automatically.

visible

Visibility of the plane. This can be false even if fb!=NULL andcrtc!=NULL, due to clipping.

commit

Tracks the pending commit to prevent use-after-free conditions,and for async plane updates.

May be NULL.

state

backpointer to global drm_atomic_state

Description

Please not that the destination coordinatescrtc_x,crtc_y,crtc_h andcrtc_w and the source coordinatessrc_x,src_y,src_h andsrc_w are theraw coordinates provided by userspace. Drivers should usedrm_atomic_helper_check_plane_state() and only use the derived rectangles insrc anddst to program the hardware.

structdrm_plane_funcs¶: driver plane control functions

Definition

struct drm_plane_funcs {  int (*update_plane)(struct drm_plane *plane,struct drm_crtc *crtc, struct drm_framebuffer *fb,int crtc_x, int crtc_y,unsigned int crtc_w, unsigned int crtc_h,uint32_t src_x, uint32_t src_y,uint32_t src_w, uint32_t src_h, struct drm_modeset_acquire_ctx *ctx);  int (*disable_plane)(struct drm_plane *plane, struct drm_modeset_acquire_ctx *ctx);  void (*destroy)(struct drm_plane *plane);  void (*reset)(struct drm_plane *plane);  int (*set_property)(struct drm_plane *plane, struct drm_property *property, uint64_t val);  struct drm_plane_state *(*atomic_duplicate_state)(struct drm_plane *plane);  void (*atomic_destroy_state)(struct drm_plane *plane, struct drm_plane_state *state);  int (*atomic_set_property)(struct drm_plane *plane,struct drm_plane_state *state,struct drm_property *property, uint64_t val);  int (*atomic_get_property)(struct drm_plane *plane,const struct drm_plane_state *state,struct drm_property *property, uint64_t *val);  int (*late_register)(struct drm_plane *plane);  void (*early_unregister)(struct drm_plane *plane);  void (*atomic_print_state)(struct drm_printer *p, const struct drm_plane_state *state);  bool (*format_mod_supported)(struct drm_plane *plane, uint32_t format, uint64_t modifier);};

Members

update_plane

This is the legacy entry point to enable and configure the plane forthe given CRTC and framebuffer. It is never called to disable theplane, i.e. the passed-in crtc and fb paramters are never NULL.

The source rectangle in frame buffer memory coordinates is given bythe src_x, src_y, src_w and src_h parameters (as 16.16 fixed pointvalues). Devices that don’t support subpixel plane coordinates canignore the fractional part.

The destination rectangle in CRTC coordinates is given by thecrtc_x, crtc_y, crtc_w and crtc_h parameters (as integer values).Devices scale the source rectangle to the destination rectangle. Ifscaling is not supported, and the source rectangle size doesn’t matchthe destination rectangle size, the driver must return a-<errorname>EINVAL</errorname> error.

Drivers implementing atomic modeset should usedrm_atomic_helper_update_plane() to implement this hook.

RETURNS:

0 on success or a negative error code on failure.

disable_plane

This is the legacy entry point to disable the plane. The DRM corecalls this method in response to a DRM_IOCTL_MODE_SETPLANE IOCTL callwith the frame buffer ID set to 0. Disabled planes must not beprocessed by the CRTC.

Drivers implementing atomic modeset should usedrm_atomic_helper_disable_plane() to implement this hook.

RETURNS:

0 on success or a negative error code on failure.

destroy

Clean up plane resources. This is only called at driver unload timethroughdrm_mode_config_cleanup() since a plane cannot be hotpluggedin DRM.

reset

Reset plane hardware and software state to off. This function isn’tcalled by the core directly, only throughdrm_mode_config_reset().It’s not a helper hook only for historical reasons.

Atomic drivers can usedrm_atomic_helper_plane_reset() to resetatomic state using this hook.

set_property

This is the legacy entry point to update a property attached to theplane.

This callback is optional if the driver does not support any legacydriver-private properties. For atomic drivers it is not used becauseproperty handling is done entirely in the DRM core.

RETURNS:

0 on success or a negative error code on failure.

atomic_duplicate_state

Duplicate the current atomic state for this plane and return it.The core and helpers guarantee that any atomic state duplicated withthis hook and still owned by the caller (i.e. not transferred to thedriver by callingdrm_mode_config_funcs.atomic_commit) will becleaned up by calling theatomic_destroy_state hook in thisstructure.

This callback is mandatory for atomic drivers.

Atomic drivers which don’t subclassstructdrm_plane_state should usedrm_atomic_helper_plane_duplicate_state(). Drivers that subclass thestate structure to extend it with driver-private state should use__drm_atomic_helper_plane_duplicate_state() to make sure shared state isduplicated in a consistent fashion across drivers.

It is an error to call this hook beforedrm_plane.state has beeninitialized correctly.

NOTE:

If the duplicate state references refcounted resources this hook mustacquire a reference for each of them. The driver must release thesereferences again inatomic_destroy_state.

RETURNS:

Duplicated atomic state or NULL when the allocation failed.

atomic_destroy_state

Destroy a state duplicated withatomic_duplicate_state and releaseor unreference all resources it references

This callback is mandatory for atomic drivers.

atomic_set_property

Do not call this function directly, usedrm_atomic_plane_set_property() instead.

This callback is optional if the driver does not support anydriver-private atomic properties.

NOTE:

RETURNS:

0 if the property has been found, -EINVAL if the property isn’timplemented by the driver (which shouldn’t ever happen, the core onlyasks for properties attached to this plane). No other validation isallowed by the driver. The core already checks that the propertyvalue is within the range (integer, valid enum value, …) the driverset when registering the property.

atomic_get_property

Reads out the decoded driver-private property. This is used toimplement the GETPLANE IOCTL.

Do not call this function directly, usedrm_atomic_plane_get_property() instead.

This callback is optional if the driver does not support anydriver-private atomic properties.

RETURNS:

0 on success, -EINVAL if the property isn’t implemented by thedriver (which should never happen, the core only asks forproperties attached to this plane).

late_register

This optional hook can be used to register additional userspaceinterfaces attached to the plane like debugfs interfaces.It is called late in the driver load sequence fromdrm_dev_register().Everything added from this callback should be unregistered inthe early_unregister callback.

Returns:

0 on success, or a negative error code on failure.

early_unregister

This optional hook should be used to unregister the additionaluserspace interfaces attached to the plane fromlate_register. It is called fromdrm_dev_unregister(),early in the driver unload sequence to disable userspace accessbefore data structures are torndown.

atomic_print_state

If driver subclassesstructdrm_plane_state, it should implementthis optional hook for printing additional driver specific state.

Do not call this directly, use drm_atomic_plane_print_state()instead.

format_mod_supported

This optional hook is used for the DRM to determine if the givenformat/modifier combination is valid for the plane. This allows theDRM to generate the correct format bitmask (which formats apply towhich modifier), and to valdiate modifiers at atomic_check time.

If not present, then any modifier in the plane’s modifierlist is allowed with any of the plane’s formats.

Returns:

True if the given modifier is valid for that format on the plane.False otherwise.

enumdrm_plane_type¶: uapi plane type enumeration

Constants

DRM_PLANE_TYPE_OVERLAY: Overlay planes represent all non-primary, non-cursor planes. Somedrivers refer to these types of planes as “sprites” internally.
DRM_PLANE_TYPE_PRIMARY: Primary planes represent a “main” plane for a CRTC. Primary planesare the planes operated upon by CRTC modesetting and flippingoperations described in thedrm_crtc_funcs.page_flip anddrm_crtc_funcs.set_config hooks.
DRM_PLANE_TYPE_CURSOR: Cursor planes represent a “cursor” plane for a CRTC. Cursor planesare the planes operated upon by the DRM_IOCTL_MODE_CURSOR andDRM_IOCTL_MODE_CURSOR2 IOCTLs.

Description

For historical reasons not all planes are made the same. This enumeration isused to tell the different types of planes apart to implement the differentuapi semantics for them. For userspace which is universal plane aware andwhich is using that atomic IOCTL there’s no difference between these planes(beyong what the driver and hardware can support of course).

For compatibility with legacy userspace, only overlay planes are madeavailable to userspace by default. Userspace clients may set theDRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that theywish to receive a universal plane list containing all plane types. See alsodrm_for_each_legacy_plane().

WARNING: The values of this enum is UABI since they’re exposed in the “type”property.

structdrm_plane¶: central DRM plane control structure

Definition

struct drm_plane {  struct drm_device *dev;  struct list_head head;  char *name;  struct drm_modeset_lock mutex;  struct drm_mode_object base;  uint32_t possible_crtcs;  uint32_t *format_types;  unsigned int format_count;  bool format_default;  uint64_t *modifiers;  unsigned int modifier_count;  struct drm_crtc *crtc;  struct drm_framebuffer *fb;  struct drm_framebuffer *old_fb;  const struct drm_plane_funcs *funcs;  struct drm_object_properties properties;  enum drm_plane_type type;  unsigned index;  const struct drm_plane_helper_funcs *helper_private;  struct drm_plane_state *state;  struct drm_property *alpha_property;  struct drm_property *zpos_property;  struct drm_property *rotation_property;  struct drm_property *blend_mode_property;  struct drm_property *color_encoding_property;  struct drm_property *color_range_property;};

Members

dev

DRM device this plane belongs to

head

List of all planes ondev, linked fromdrm_mode_config.plane_list.Invariant over the lifetime ofdev and therefore does not needlocking.

name

human readable name, can be overwritten by the driver

mutex

Protects modeset plane state, together with thedrm_crtc.mutex ofCRTC this plane is linked to (when active, getting activated orgetting disabled).

For atomic drivers specifically this protectsstate.

base

base mode object

possible_crtcs

pipes this plane can be bound to constructed fromdrm_crtc_mask()

format_types

array of formats supported by this plane

format_count

Size of the array pointed at byformat_types.

format_default

driver hasn’t supplied supported formats for theplane. Used by the drm_plane_init compatibility wrapper only.

modifiers

array of modifiers supported by this plane

modifier_count

Size of the array pointed at bymodifier_count.

crtc

Currently bound CRTC, only meaningful for non-atomic drivers. Foratomic drivers this is forced to be NULL, atomic drivers shouldinstead checkdrm_plane_state.crtc.

fb

Currently bound framebuffer, only meaningful for non-atomic drivers.For atomic drivers this is forced to be NULL, atomic drivers shouldinstead checkdrm_plane_state.fb.

old_fb

Temporary tracking of the old fb while a modeset is ongoing. Onlyused by non-atomic drivers, forced to be NULL for atomic drivers.

funcs

plane control functions

properties

property tracking for this plane

type

Type of plane, seeenumdrm_plane_type for details.

index

Position inside the mode_config.list, can be used as an arrayindex. It is invariant over the lifetime of the plane.

helper_private

mid-layer private data

state

Current atomic state for this plane.

This is protected bymutex. Note that nonblocking atomic commitsaccess the current plane state without taking locks. Either by goingthrough thestructdrm_atomic_state pointers, seefor_each_oldnew_plane_in_state(),for_each_old_plane_in_state() andfor_each_new_plane_in_state(). Or through careful ordering of atomiccommit operations as implemented in the atomic helpers, seestructdrm_crtc_commit.

alpha_property

Optional alpha property for this plane. Seedrm_plane_create_alpha_property().

zpos_property

Optional zpos property for this plane. Seedrm_plane_create_zpos_property().

rotation_property

Optional rotation property for this plane. Seedrm_plane_create_rotation_property().

blend_mode_property

Optional “pixel blend mode” enum property for this plane.Blend mode property represents the alpha blending equation selection,describing how the pixels from the current plane are composited withthe background.

color_encoding_property

Optional “COLOR_ENCODING” enum property for specifyingcolor encoding for non RGB formats.Seedrm_plane_create_color_properties().

color_range_property

Optional “COLOR_RANGE” enum property for specifyingcolor range for non RGB formats.Seedrm_plane_create_color_properties().

Description

Planes represent the scanout hardware of a display block. They receive theirinput data from adrm_framebuffer and feed it to adrm_crtc. Planes controlthe color conversion, seePlane Composition Properties for more details,and are also involved in the color conversion of input pixels, seeColorManagement Properties for details on that.

unsigned intdrm_plane_index(const structdrm_plane * plane)¶: find the index of a registered plane

Parameters

conststructdrm_plane*plane: plane to find index for

Description

Given a registered plane, return the index of that plane within a DRMdevice’s list of planes.

u32drm_plane_mask(const structdrm_plane * plane)¶: find the mask of a registered plane

Parameters

conststructdrm_plane*plane: plane to find mask for

structdrm_plane *drm_plane_find(structdrm_device * dev, structdrm_file * file_priv, uint32_t id)¶: find adrm_plane

Parameters

structdrm_device*dev: DRM device
structdrm_file*file_priv: drm file to check for lease against.
uint32_tid: plane id

Description

Returns the plane withid, NULL if it doesn’t exist. Simple wrapper arounddrm_mode_object_find().

drm_for_each_plane_mask(plane,dev,plane_mask)¶: iterate over planes specified by bitmask

Parameters

plane: the loop cursor
dev: the DRM device
plane_mask: bitmask of plane indices

Description

Iterate over all planes specified by bitmask.

drm_for_each_legacy_plane(plane,dev)¶: iterate over all planes for legacy userspace

Parameters

plane: the loop cursor
dev: the DRM device

Description

Iterate over all legacy planes ofdev, excluding primary and cursor planes.This is useful for implementing userspace apis when userspace is notuniversal plane aware. See alsoenumdrm_plane_type.

drm_for_each_plane(plane,dev)¶: iterate over all planes

Parameters

plane: the loop cursor
dev: the DRM device

Description

Iterate over all planes ofdev, include primary and cursor planes.

unsigned intdrm_plane_get_damage_clips_count(const structdrm_plane_state * state)¶: Returns damage clips count.

Parameters

conststructdrm_plane_state*state: Plane state.

Description

Simple helper to get the number ofdrm_mode_rect clips set by user-spaceduring plane update.

Return

Number of clips in plane fb_damage_clips blob property.

structdrm_mode_rect *drm_plane_get_damage_clips(const structdrm_plane_state * state)¶: Returns damage clips.

Parameters

conststructdrm_plane_state*state: Plane state.

Description

Note that this function returns uapi typedrm_mode_rect. Drivers mightinstead be interested in internaldrm_rect which can be obtained by callingdrm_helper_get_plane_damage_clips().

Return

Damage clips in plane fb_damage_clips blob property.

intdrm_universal_plane_init(structdrm_device * dev, structdrm_plane * plane, uint32_t possible_crtcs, const structdrm_plane_funcs * funcs, const uint32_t * formats, unsigned int format_count, const uint64_t * format_modifiers, enumdrm_plane_type type, const char * name, ...)¶: Initialize a new universal plane object

Parameters

structdrm_device*dev: DRM device
structdrm_plane*plane: plane object to init
uint32_tpossible_crtcs: bitmask of possible CRTCs
conststructdrm_plane_funcs*funcs: callbacks for the new plane
constuint32_t*formats: array of supported formats (DRM_FORMAT_*)
unsignedintformat_count: number of elements informats
constuint64_t*format_modifiers: array of struct drm_format modifiers terminated byDRM_FORMAT_MOD_INVALID
enumdrm_plane_typetype: type of plane (overlay, primary, cursor)
constchar*name: printf style format string for the plane name, or NULL for default name
...: variable arguments

Description

Initializes a plane object of typetype.

Return

Zero on success, error code on failure.

intdrm_plane_init(structdrm_device * dev, structdrm_plane * plane, uint32_t possible_crtcs, const structdrm_plane_funcs * funcs, const uint32_t * formats, unsigned int format_count, bool is_primary)¶: Initialize a legacy plane

Parameters

structdrm_device*dev: DRM device
structdrm_plane*plane: plane object to init
uint32_tpossible_crtcs: bitmask of possible CRTCs
conststructdrm_plane_funcs*funcs: callbacks for the new plane
constuint32_t*formats: array of supported formats (DRM_FORMAT_*)
unsignedintformat_count: number of elements informats
boolis_primary: plane type (primary vs overlay)

Description

Legacy API to initialize a DRM plane.

New drivers should calldrm_universal_plane_init() instead.

Return

Zero on success, error code on failure.

voiddrm_plane_cleanup(structdrm_plane * plane)¶: Clean up the core plane usage

Parameters

structdrm_plane*plane: plane to cleanup

Description

This function cleans upplane and removes it from the DRM mode settingcore. Note that the function doesnot free the plane structure itself,this is the responsibility of the caller.

structdrm_plane *drm_plane_from_index(structdrm_device * dev, int idx)¶: find the registered plane at an index

Parameters

structdrm_device*dev: DRM device
intidx: index of registered plane to find for

Description

Given a plane index, return the registered plane from DRM device’slist of planes with matching index. This is the inverse ofdrm_plane_index().

voiddrm_plane_force_disable(structdrm_plane * plane)¶: Forcibly disable a plane

Parameters

structdrm_plane*plane: plane to disable

Description

Forces the plane to be disabled.

Used when the plane’s current framebuffer is destroyed,and when restoring fbdev mode.

Note that this function is not suitable for atomic drivers, since it doesn’twire through the lock acquisition context properly and hence can’t handleretries or driver private locks. You probably want to usedrm_atomic_helper_disable_plane() ordrm_atomic_helper_disable_planes_on_crtc() instead.

intdrm_mode_plane_set_obj_prop(structdrm_plane * plane, structdrm_property * property, uint64_t value)¶: set the value of a property

Parameters

structdrm_plane*plane: drm plane object to set property value for
structdrm_property*property: property to set
uint64_tvalue: value the property should be set to

Description

This functions sets a given property on a given plane object. This functioncalls the driver’s ->set_property callback and changes the software state ofthe property if the callback succeeds.

Return

Zero on success, error code on failure.

booldrm_any_plane_has_format(structdrm_device * dev, u32 format, u64 modifier)¶: Check whether any plane supports this format and modifier combination

Parameters

structdrm_device*dev: DRM device
u32format: pixel format (DRM_FORMAT_*)
u64modifier: data layout modifier

Return

Whether at least one plane supports the specified format and modifier combination.

Display Modes Function Reference¶

enumdrm_mode_status¶: hardware support status of a mode

Constants

MODE_OK: Mode OK
MODE_HSYNC: hsync out of range
MODE_VSYNC: vsync out of range
MODE_H_ILLEGAL: mode has illegal horizontal timings
MODE_V_ILLEGAL: mode has illegal vertical timings
MODE_BAD_WIDTH: requires an unsupported linepitch
MODE_NOMODE: no mode with a matching name
MODE_NO_INTERLACE: interlaced mode not supported
MODE_NO_DBLESCAN: doublescan mode not supported
MODE_NO_VSCAN: multiscan mode not supported
MODE_MEM: insufficient video memory
MODE_VIRTUAL_X: mode width too large for specified virtual size
MODE_VIRTUAL_Y: mode height too large for specified virtual size
MODE_MEM_VIRT: insufficient video memory given virtual size
MODE_NOCLOCK: no fixed clock available
MODE_CLOCK_HIGH: clock required is too high
MODE_CLOCK_LOW: clock required is too low
MODE_CLOCK_RANGE: clock/mode isn’t in a ClockRange
MODE_BAD_HVALUE: horizontal timing was out of range
MODE_BAD_VVALUE: vertical timing was out of range
MODE_BAD_VSCAN: VScan value out of range
MODE_HSYNC_NARROW: horizontal sync too narrow
MODE_HSYNC_WIDE: horizontal sync too wide
MODE_HBLANK_NARROW: horizontal blanking too narrow
MODE_HBLANK_WIDE: horizontal blanking too wide
MODE_VSYNC_NARROW: vertical sync too narrow
MODE_VSYNC_WIDE: vertical sync too wide
MODE_VBLANK_NARROW: vertical blanking too narrow
MODE_VBLANK_WIDE: vertical blanking too wide
MODE_PANEL: exceeds panel dimensions
MODE_INTERLACE_WIDTH: width too large for interlaced mode
MODE_ONE_WIDTH: only one width is supported
MODE_ONE_HEIGHT: only one height is supported
MODE_ONE_SIZE: only one resolution is supported
MODE_NO_REDUCED: monitor doesn’t accept reduced blanking
MODE_NO_STEREO: stereo modes not supported
MODE_NO_420: ycbcr 420 modes not supported
MODE_STALE: mode has become stale
MODE_BAD: unspecified reason
MODE_ERROR: error condition

Description

This enum is used to filter out modes not supported by the driver/hardwarecombination.

DRM_SIMPLE_MODE(hd,vd,hd_mm,vd_mm)¶: Simple display mode

Parameters

hd: Horizontal resolution, width
vd: Vertical resolution, height
hd_mm: Display width in millimeters
vd_mm: Display height in millimeters

Description

This macro initializes adrm_display_mode that only contains info aboutresolution and physical size.

structdrm_display_mode¶: DRM kernel-internal display mode structure

Definition

struct drm_display_mode {  int 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 flags;  int crtc_clock;  u16 crtc_hdisplay;  u16 crtc_hblank_start;  u16 crtc_hblank_end;  u16 crtc_hsync_start;  u16 crtc_hsync_end;  u16 crtc_htotal;  u16 crtc_hskew;  u16 crtc_vdisplay;  u16 crtc_vblank_start;  u16 crtc_vblank_end;  u16 crtc_vsync_start;  u16 crtc_vsync_end;  u16 crtc_vtotal;  u16 width_mm;  u16 height_mm;  u8 type;  int private_flags;  struct list_head head;  struct list_head export_head;  char name[DRM_DISPLAY_MODE_LEN];  enum drm_mode_status status;  enum hdmi_picture_aspect picture_aspect_ratio;};

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?!

flags

Sync and timing flags:

DRM_MODE_FLAG_PHSYNC: horizontal sync is active high.
DRM_MODE_FLAG_NHSYNC: horizontal sync is active low.
DRM_MODE_FLAG_PVSYNC: vertical sync is active high.
DRM_MODE_FLAG_NVSYNC: vertical sync is active low.
DRM_MODE_FLAG_INTERLACE: mode is interlaced.
DRM_MODE_FLAG_DBLSCAN: mode uses doublescan.
DRM_MODE_FLAG_CSYNC: mode uses composite sync.
DRM_MODE_FLAG_PCSYNC: composite sync is active high.
DRM_MODE_FLAG_NCSYNC: composite sync is active low.
DRM_MODE_FLAG_HSKEW: hskew provided (not used?).
DRM_MODE_FLAG_BCAST: <deprecated>
DRM_MODE_FLAG_PIXMUX: <deprecated>
DRM_MODE_FLAG_DBLCLK: double-clocked mode.
DRM_MODE_FLAG_CLKDIV2: half-clocked mode.

Additionally there’s flags to specify how 3D modes are packed:

DRM_MODE_FLAG_3D_NONE: normal, non-3D mode.
DRM_MODE_FLAG_3D_FRAME_PACKING: 2 full frames for left and right.
DRM_MODE_FLAG_3D_FIELD_ALTERNATIVE: interleaved like fields.
DRM_MODE_FLAG_3D_LINE_ALTERNATIVE: interleaved lines.
DRM_MODE_FLAG_3D_SIDE_BY_SIDE_FULL: side-by-side full frames.
DRM_MODE_FLAG_3D_L_DEPTH: ?
DRM_MODE_FLAG_3D_L_DEPTH_GFX_GFX_DEPTH: ?
DRM_MODE_FLAG_3D_TOP_AND_BOTTOM: frame split into top and bottomparts.
DRM_MODE_FLAG_3D_SIDE_BY_SIDE_HALF: frame split into left andright parts.

crtc_clock

Actual pixel or dot clock in the hardware. This differs from thelogicalclock when e.g. using interlacing, double-clocking, stereomodes or other fancy stuff that changes the timings and signalsactually sent over the wire.

This is again in kHz.

Note that with digital outputs like HDMI or DP there’s usually amassive confusion between the dot clock and the signal clock at thebit encoding level. Especially when a 8b/10b encoding is used and thedifference is exactly a factor of 10.

crtc_hdisplay

hardware mode horizontal display size

crtc_hblank_start

hardware mode horizontal blank start

crtc_hblank_end

hardware mode horizontal blank end

crtc_hsync_start

hardware mode horizontal sync start

crtc_hsync_end

hardware mode horizontal sync end

crtc_htotal

hardware mode horizontal total size

crtc_hskew

hardware mode horizontal skew?!

crtc_vdisplay

hardware mode vertical display size

crtc_vblank_start

hardware mode vertical blank start

crtc_vblank_end

hardware mode vertical blank end

crtc_vsync_start

hardware mode vertical sync start

crtc_vsync_end

hardware mode vertical sync end

crtc_vtotal

hardware mode vertical total size

width_mm

Addressable size of the output in mm, projectors should set this to0.

height_mm

Addressable size of the output in mm, projectors should set this to0.

type

A bitmask of flags, mostly about the source of a mode. Possible flagsare:

DRM_MODE_TYPE_PREFERRED: Preferred mode, usually the nativeresolution of an LCD panel. There should only be one preferredmode per connector at any given time.
DRM_MODE_TYPE_DRIVER: Mode created by the driver, which is all ofthem really. Drivers must set this bit for all modes they createand expose to userspace.
DRM_MODE_TYPE_USERDEF: Mode defined or selected via the kernelcommand line.

Plus a big list of flags which shouldn’t be used at all, but arestill around since these flags are also used in the userspace ABI.We no longer accept modes with these types though:

DRM_MODE_TYPE_BUILTIN: Meant for hard-coded modes, unused.Use DRM_MODE_TYPE_DRIVER instead.
DRM_MODE_TYPE_DEFAULT: Again a leftover, useDRM_MODE_TYPE_PREFERRED instead.
DRM_MODE_TYPE_CLOCK_C and DRM_MODE_TYPE_CRTC_C: Define leftoverswhich are stuck around for hysterical raisins only. No one has anidea what they were meant for. Don’t use.

private_flags

Driver private flags. private_flags can only be used for modeobjects passed to drivers in modeset operations. It shouldn’t be usedby atomic drivers since they can store any additional data bysubclassing state structures.

head

struct list_head for mode lists.

export_head

struct list_head for modes to be exposed to the userspace.This is to maintain a list of exposed modes while preparinguser-mode’s list in drm_mode_getconnector ioctl. The purpose of thislist_head only lies in the ioctl function, and is not expected to beused outside the function.Once used, the stale pointers are not reset, but left as it is, toavoid overhead of protecting it by mode_config.mutex.

name

Human-readable name of the mode, filled out withdrm_mode_set_name().

status

Status of the mode, used to filter out modes not supported by thehardware. See enumdrm_mode_status.

picture_aspect_ratio

Field for setting the HDMI picture aspect ratio of a mode.

Description

The horizontal and vertical timings are defined per the following diagram.

          Active                 Front           Sync           Back         Region                 Porch                          Porch<-----------------------><----------------><-------------><-------------->  //////////////////////| ////////////////////// |//////////////////////  |..................               ................                                           _______________<----- [hv]display -----><------------- [hv]sync_start ------------><--------------------- [hv]sync_end ---------------------><-------------------------------- [hv]total ----------------------------->*

This structure contains two copies of timings. First are the plain timings,which specify the logical mode, as it would be for a progressive 1:1 scanoutat the refresh rate userspace can observe through vblank timestamps. Thenthere’s the hardware timings, which are corrected for interlacing,double-clocking and similar things. They are provided as a convenience, andcan be appropriately computed usingdrm_mode_set_crtcinfo().

For printing you can useDRM_MODE_FMT andDRM_MODE_ARG().

DRM_MODE_FMT()¶: printf string forstructdrm_display_mode

Parameters

DRM_MODE_ARG(m)¶: printf arguments forstructdrm_display_mode

Parameters

m: display mode

booldrm_mode_is_stereo(const structdrm_display_mode * mode)¶: check for stereo mode flags

Parameters

conststructdrm_display_mode*mode: drm_display_mode to check

Return

True if the mode is one of the stereo modes (like side-by-side), false ifnot.

voiddrm_mode_debug_printmodeline(const structdrm_display_mode * mode)¶: print a mode to dmesg

Parameters

conststructdrm_display_mode*mode: mode to print

Description

Describemode using DRM_DEBUG.

structdrm_display_mode *drm_mode_create(structdrm_device * dev)¶: create a new display mode

Parameters

structdrm_device*dev: DRM device

Description

Create a new, cleared drm_display_mode with kzalloc, allocate an ID for itand return it.

Return

Pointer to new mode on success, NULL on error.

voiddrm_mode_destroy(structdrm_device * dev, structdrm_display_mode * mode)¶: remove a mode

Parameters

structdrm_device*dev: DRM device
structdrm_display_mode*mode: mode to remove

Description

Releasemode’s unique ID, then free itmode structure itself using kfree.

voiddrm_mode_probed_add(structdrm_connector * connector, structdrm_display_mode * mode)¶: add a mode to a connector’s probed_mode list

Parameters

structdrm_connector*connector: connector the new mode
structdrm_display_mode*mode: mode data

Description

Addmode toconnector’s probed_mode list for later use. This list shouldthen in a second step get filtered and all the modes actually supported bythe hardware moved to theconnector’s modes list.

structdrm_display_mode *drm_cvt_mode(structdrm_device * dev, int hdisplay, int vdisplay, int vrefresh, bool reduced, bool interlaced, bool margins)¶: create a modeline based on the CVT algorithm

Parameters

structdrm_device*dev: drm device
inthdisplay: hdisplay size
intvdisplay: vdisplay size
intvrefresh: vrefresh rate
boolreduced: whether to use reduced blanking
boolinterlaced: whether to compute an interlaced mode
boolmargins: whether to add margins (borders)

Description

This function is called to generate the modeline based on CVT algorithmaccording to the hdisplay, vdisplay, vrefresh.It is based from the VESA(TM) Coordinated Video Timing Generator byGraham Loveridge April 9, 2003 available athttp://www.elo.utfsm.cl/~elo212/docs/CVTd6r1.xls

And it is copied from xf86CVTmode in xserver/hw/xfree86/modes/xf86cvt.c.What I have done is to translate it by using integer calculation.

Return

The modeline based on the CVT algorithm stored in a drm_display_mode object.The display mode object is allocated withdrm_mode_create(). Returns NULLwhen no mode could be allocated.

structdrm_display_mode *drm_gtf_mode_complex(structdrm_device * dev, int hdisplay, int vdisplay, int vrefresh, bool interlaced, int margins, int GTF_M, int GTF_2C, int GTF_K, int GTF_2J)¶: create the modeline based on the full GTF algorithm

Parameters

structdrm_device*dev: drm device
inthdisplay: hdisplay size
intvdisplay: vdisplay size
intvrefresh: vrefresh rate.
boolinterlaced: whether to compute an interlaced mode
intmargins: desired margin (borders) size
intGTF_M: extended GTF formula parameters
intGTF_2C: extended GTF formula parameters
intGTF_K: extended GTF formula parameters
intGTF_2J: extended GTF formula parameters

Description

GTF feature blocks specify C and J in multiples of 0.5, so we pass themin here multiplied by two. For a C of 40, pass in 80.

Return

The modeline based on the full GTF algorithm stored in a drm_display_mode object.The display mode object is allocated withdrm_mode_create(). Returns NULLwhen no mode could be allocated.

structdrm_display_mode *drm_gtf_mode(structdrm_device * dev, int hdisplay, int vdisplay, int vrefresh, bool interlaced, int margins)¶: create the modeline based on the GTF algorithm

Parameters

structdrm_device*dev: drm device
inthdisplay: hdisplay size
intvdisplay: vdisplay size
intvrefresh: vrefresh rate.
boolinterlaced: whether to compute an interlaced mode
intmargins: desired margin (borders) size

Description

return the modeline based on GTF algorithm

This function is to create the modeline based on the GTF algorithm.Generalized Timing Formula is derived from:

GTF Spreadsheet by Andy Morrish (1/5/97)available athttps://www.vesa.org

And it is copied from the file of xserver/hw/xfree86/modes/xf86gtf.c.What I have done is to translate it by using integer calculation.I also refer to the function of fb_get_mode in the file ofdrivers/video/fbmon.c

Standard GTF parameters:

M = 600C = 40K = 128J = 20

Return

The modeline based on the GTF algorithm stored in a drm_display_mode object.The display mode object is allocated withdrm_mode_create(). Returns NULLwhen no mode could be allocated.

voiddrm_display_mode_from_videomode(const struct videomode * vm, structdrm_display_mode * dmode)¶: fill indmode usingvm,

Parameters

conststructvideomode*vm: videomode structure to use as source
structdrm_display_mode*dmode: drm_display_mode structure to use as destination

Description

Fills outdmode using the display mode specified invm.

voiddrm_display_mode_to_videomode(const structdrm_display_mode * dmode, struct videomode * vm)¶: fill invm usingdmode,

Parameters

conststructdrm_display_mode*dmode: drm_display_mode structure to use as source
structvideomode*vm: videomode structure to use as destination

Description

Fills outvm using the display mode specified indmode.

voiddrm_bus_flags_from_videomode(const struct videomode * vm, u32 * bus_flags)¶: extract information about pixelclk and DE polarity from videomode and store it in a separate variable

Parameters

conststructvideomode*vm: videomode structure to use
u32*bus_flags: information about pixelclk, sync and DE polarity will be storedhere

Description

Sets DRM_BUS_FLAG_DE_(LOW|HIGH), DRM_BUS_FLAG_PIXDATA_DRIVE_(POS|NEG)EDGEand DISPLAY_FLAGS_SYNC_(POS|NEG)EDGE inbus_flags according to DISPLAY_FLAGSfound invm

intof_get_drm_display_mode(struct device_node * np, structdrm_display_mode * dmode, u32 * bus_flags, int index)¶: get a drm_display_mode from devicetree

Parameters

structdevice_node*np: device_node with the timing specification
structdrm_display_mode*dmode: will be set to the return value
u32*bus_flags: information about pixelclk, sync and DE polarity
intindex: index into the list of display timings in devicetree

Description

This function is expensive and should only be used, if only one mode is to beread from DT. To get multiple modes start with of_get_display_timings andwork with that instead.

Return

0 on success, a negative errno code when no of videomode node was found.

voiddrm_mode_set_name(structdrm_display_mode * mode)¶: set the name on a mode

Parameters

structdrm_display_mode*mode: name will be set in this mode

Description

Set the name ofmode to a standard format which is <hdisplay>x<vdisplay>with an optional ‘i’ suffix for interlaced modes.

intdrm_mode_vrefresh(const structdrm_display_mode * mode)¶: get the vrefresh of a mode

Parameters

conststructdrm_display_mode*mode: mode

Return

modes’s vrefresh rate in Hz, rounded to the nearest integer. Calculates thevalue first if it is not yet set.

voiddrm_mode_get_hv_timing(const structdrm_display_mode * mode, int * hdisplay, int * vdisplay)¶: Fetches hdisplay/vdisplay for given mode

Parameters

conststructdrm_display_mode*mode: mode to query
int*hdisplay: hdisplay value to fill in
int*vdisplay: vdisplay value to fill in

Description

The vdisplay value will be doubled if the specified mode is a stereo mode ofthe appropriate layout.

voiddrm_mode_set_crtcinfo(structdrm_display_mode * p, int adjust_flags)¶: set CRTC modesetting timing parameters

Parameters

structdrm_display_mode*p: mode
intadjust_flags: a combination of adjustment flags

Description

Setup the CRTC modesetting timing parameters forp, adjusting if necessary.

The CRTC_INTERLACE_HALVE_V flag can be used to halve vertical timings ofinterlaced modes.
The CRTC_STEREO_DOUBLE flag can be used to compute the timings forbuffers containing two eyes (only adjust the timings when needed, eg. for“frame packing” or “side by side full”).
The CRTC_NO_DBLSCAN and CRTC_NO_VSCAN flags request that adjustmentnotbe performed for doublescan and vscan > 1 modes respectively.

voiddrm_mode_copy(structdrm_display_mode * dst, const structdrm_display_mode * src)¶: copy the mode

Parameters

structdrm_display_mode*dst: mode to overwrite
conststructdrm_display_mode*src: mode to copy

Description

Copy an existing mode into another mode, preserving the object id andlist head of the destination mode.

structdrm_display_mode *drm_mode_duplicate(structdrm_device * dev, const structdrm_display_mode * mode)¶: allocate and duplicate an existing mode

Parameters

structdrm_device*dev: drm_device to allocate the duplicated mode for
conststructdrm_display_mode*mode: mode to duplicate

Description

Just allocate a new mode, copy the existing mode into it, and returna pointer to it. Used to create new instances of established modes.

Return

Pointer to duplicated mode on success, NULL on error.

booldrm_mode_match(const structdrm_display_mode * mode1, const structdrm_display_mode * mode2, unsigned int match_flags)¶: test modes for (partial) equality

Parameters

conststructdrm_display_mode*mode1: first mode
conststructdrm_display_mode*mode2: second mode
unsignedintmatch_flags: which parts need to match (DRM_MODE_MATCH_*)

Description

Check to see ifmode1 andmode2 are equivalent.

Return

True if the modes are (partially) equal, false otherwise.

booldrm_mode_equal(const structdrm_display_mode * mode1, const structdrm_display_mode * mode2)¶: test modes for equality

Parameters

conststructdrm_display_mode*mode1: first mode
conststructdrm_display_mode*mode2: second mode

Description

Check to see ifmode1 andmode2 are equivalent.

Return

True if the modes are equal, false otherwise.

booldrm_mode_equal_no_clocks(const structdrm_display_mode * mode1, const structdrm_display_mode * mode2)¶: test modes for equality

Parameters

conststructdrm_display_mode*mode1: first mode
conststructdrm_display_mode*mode2: second mode

Description

Check to see ifmode1 andmode2 are equivalent, butdon’t check the pixel clocks.

Return

True if the modes are equal, false otherwise.

booldrm_mode_equal_no_clocks_no_stereo(const structdrm_display_mode * mode1, const structdrm_display_mode * mode2)¶: test modes for equality

Parameters

conststructdrm_display_mode*mode1: first mode
conststructdrm_display_mode*mode2: second mode

Description

Check to see ifmode1 andmode2 are equivalent, butdon’t check the pixel clocks nor the stereo layout.

Return

True if the modes are equal, false otherwise.

enumdrm_mode_statusdrm_mode_validate_driver(structdrm_device * dev, const structdrm_display_mode * mode)¶: make sure the mode is somewhat sane

Parameters

structdrm_device*dev: drm device
conststructdrm_display_mode*mode: mode to check

Description

First do basic validation on the mode, and then allow the driverto check for device/driver specific limitations via the optionaldrm_mode_config_helper_funcs.mode_valid hook.

Return

The mode status

enumdrm_mode_statusdrm_mode_validate_size(const structdrm_display_mode * mode, int maxX, int maxY)¶: make sure modes adhere to size constraints

Parameters

conststructdrm_display_mode*mode: mode to check
intmaxX: maximum width
intmaxY: maximum height

Description

This function is a helper which can be used to validate modes against sizelimitations of the DRM device/connector. If a mode is too big its statusmember is updated with the appropriate validation failure code. The listitself is not changed.

Return

The mode status

enumdrm_mode_statusdrm_mode_validate_ycbcr420(const structdrm_display_mode * mode, structdrm_connector * connector)¶: add ‘ycbcr420-only’ modes only when allowed

Parameters

conststructdrm_display_mode*mode: mode to check
structdrm_connector*connector: drm connector under action

Description

This function is a helper which can be used to filter out any YCBCR420only mode, when the source doesn’t support it.

Return

The mode status

voiddrm_mode_prune_invalid(structdrm_device * dev, struct list_head * mode_list, bool verbose)¶: remove invalid modes from mode list

Parameters

structdrm_device*dev: DRM device
structlist_head*mode_list: list of modes to check
boolverbose: be verbose about it

Description

This helper function can be used to prune a display mode list aftervalidation has been completed. All modes whose status is not MODE_OK will beremoved from the list, and ifverbose the status code and mode name is alsoprinted to dmesg.

voiddrm_mode_sort(struct list_head * mode_list)¶: sort mode list

Parameters

structlist_head*mode_list: list of drm_display_mode structures to sort

Description

Sortmode_list by favorability, moving good modes to the head of the list.

voiddrm_connector_list_update(structdrm_connector * connector)¶: update the mode list for the connector

Parameters

structdrm_connector*connector: the connector to update

Description

This moves the modes from theconnector probed_modes listto the actual mode list. It compares the probed mode against the currentlist and only adds different/new modes.

This is just a helper functions doesn’t validate any modes itself and alsodoesn’t prune any invalid modes. Callers need to do that themselves.

booldrm_mode_parse_command_line_for_connector(const char * mode_option, const structdrm_connector * connector, structdrm_cmdline_mode * mode)¶: parse command line modeline for connector

Parameters

constchar*mode_option: optional per connector mode option
conststructdrm_connector*connector: connector to parse modeline for
structdrm_cmdline_mode*mode: preallocated drm_cmdline_mode structure to fill out

Description

This parsesmode_option command line modeline for modes and options toconfigure the connector. Ifmode_option is NULL the default command linemodeline in fb_mode_option will be parsed instead.

This uses the same parameters as the fb modedb.c, except for an extraforce-enable, force-enable-digital and force-disable bit at the end:

<xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m][eDd]

Additionals options can be provided following the mode, using a comma toseparate each option. Valid options can be found inDocumentation/fb/modedb.rst.

The intermediate drm_cmdline_mode structure is required to store additionaloptions from the command line modline like the force-enable/disable flag.

Return

True if a valid modeline has been parsed, false otherwise.

structdrm_display_mode *drm_mode_create_from_cmdline_mode(structdrm_device * dev, structdrm_cmdline_mode * cmd)¶: convert a command line modeline into a DRM display mode

Parameters

structdrm_device*dev: DRM device to create the new mode for
structdrm_cmdline_mode*cmd: input command line modeline

Return

Pointer to converted mode on success, NULL on error.

booldrm_mode_is_420_only(const structdrm_display_info * display, const structdrm_display_mode * mode)¶: if a given videomode can be only supported in YCBCR420 output format

Parameters

conststructdrm_display_info*display: display under action
conststructdrm_display_mode*mode: video mode to be tested.

Return

true if the mode can be supported in YCBCR420 formatfalse if not.

booldrm_mode_is_420_also(const structdrm_display_info * display, const structdrm_display_mode * mode)¶: if a given videomode can be supported in YCBCR420 output format also (along with RGB/YCBCR444/422)

Parameters

conststructdrm_display_info*display: display under action.
conststructdrm_display_mode*mode: video mode to be tested.

Return

true if the mode can be support YCBCR420 formatfalse if not.

booldrm_mode_is_420(const structdrm_display_info * display, const structdrm_display_mode * mode)¶: if a given videomode can be supported in YCBCR420 output format

Parameters

conststructdrm_display_info*display: display under action.
conststructdrm_display_mode*mode: video mode to be tested.

Return

true if the mode can be supported in YCBCR420 formatfalse if not.

Connector Abstraction¶

In DRM connectors are the general abstraction for display sinks, and includealso fixed panels or anything else that can display pixels in some form. Asopposed to all other KMS objects representing hardware (like CRTC, encoder orplane abstractions) connectors can be hotplugged and unplugged at runtime.Hence they are reference-counted usingdrm_connector_get() anddrm_connector_put().

KMS driver must create, initialize, register and attach at astructdrm_connector for each such sink. The instance is created as other KMSobjects and initialized by setting the following fields. The connector isinitialized with a call todrm_connector_init() with a pointer to thestructdrm_connector_funcs and a connector type, and then exposed touserspace with a call todrm_connector_register().

Connectors must be attached to an encoder to be used. For devices that mapconnectors to encoders 1:1, the connector should be attached atinitialization time with a call todrm_connector_attach_encoder(). Thedriver must also set thedrm_connector.encoder field to point to theattached encoder.

For connectors which are not fixed (like built-in panels) the driver needs tosupport hotplug notifications. The simplest way to do that is by using theprobe helpers, seedrm_kms_helper_poll_init() for connectors which don’t havehardware support for hotplug interrupts. Connectors with hardware hotplugsupport can instead use e.g.drm_helper_hpd_irq_event().

Connector Functions Reference¶

enumdrm_connector_status¶: status for adrm_connector

Constants

connector_status_connected: The connector is definitely connected toa sink device, and can be enabled.
connector_status_disconnected: The connector isn’t connected to asink device which can be autodetect. For digital outputs like DP orHDMI (which can be realiable probed) this means there’s reallynothing there. It is driver-dependent whether a connector with thisstatus can be lit up or not.
connector_status_unknown: The connector’s status could not bereliably detected. This happens when probing would either causeflicker (like load-detection when the connector is in use), or when ahardware resource isn’t available (like when load-detection needs afree CRTC). It should be possible to light up the connector with oneof the listed fallback modes. For default configuration userspaceshould only try to light up connectors with unknown status whenthere’s not connector withconnector_status_connected.

Description

This enum is used to track the connector status. There are no separate#defines for the uapi!

enumdrm_connector_registration_state¶: userspace registration status for adrm_connector

Constants

DRM_CONNECTOR_INITIALIZING

The connector has just been created,but has yet to be exposed to userspace. There should be noadditional restrictions to how the state of this connector may bemodified.

DRM_CONNECTOR_REGISTERED

The connector has been fully initializedand registered with sysfs, as such it has been exposed touserspace. There should be no additional restrictions to how thestate of this connector may be modified.

DRM_CONNECTOR_UNREGISTERED

The connector has either been exposedto userspace and has since been unregistered and removed fromuserspace, or the connector was unregistered before it had a chanceto be exposed to userspace (e.g. still in theDRM_CONNECTOR_INITIALIZING state). When a connector isunregistered, there are additional restrictions to how its statemay be modified:

An unregistered connector may only have its DPMS changed fromOn->Off. Once DPMS is changed to Off, it may not be switched backto On.
Modesets are not allowed on unregistered connectors, unless theywould result in disabling its assigned CRTCs. This meansdisabling a CRTC on an unregistered connector is OK, but enablingone is not.
Removing a CRTC from an unregistered connector is OK, but newCRTCs may never be assigned to an unregistered connector.

Description

This enum is used to track the status of initializing a connector andregistering it with userspace, so that DRM can prevent bogus modesets onconnectors that no longer exist.

structdrm_scrambling¶

Definition

struct drm_scrambling {  bool supported;  bool low_rates;};

Members

supported: scrambling supported for rates > 340 Mhz.
low_rates: scrambling supported for rates <= 340 Mhz.

structdrm_hdmi_info¶: runtime information about the connected HDMI sink

Definition

struct drm_hdmi_info {  struct drm_scdc scdc;  unsigned long y420_vdb_modes[BITS_TO_LONGS(256)];  unsigned long y420_cmdb_modes[BITS_TO_LONGS(256)];  u64 y420_cmdb_map;  u8 y420_dc_modes;};

Members

scdc: sink’s scdc support and capabilities
y420_vdb_modes: bitmap of modes which can support ycbcr420output only (not normal RGB/YCBCR444/422 outputs). The max VICdefined by the CEA-861-G spec is 219, so the size is 256 bits to mapup to 256 VICs.
y420_cmdb_modes: bitmap of modes which can support ycbcr420output also, along with normal HDMI outputs. The max VIC defined bythe CEA-861-G spec is 219, so the size is 256 bits to map up to 256VICs.
y420_cmdb_map: bitmap of SVD index, to extraxt vcb modes
y420_dc_modes: bitmap of deep color support index

Description

Describes if a given display supports advanced HDMI 2.0 features.This information is available in CEA-861-F extension blocks (like HF-VSDB).

enumdrm_link_status¶: connector’s link_status property value

Constants

DRM_LINK_STATUS_GOOD: DP Link is Good as a result of successfullink training
DRM_LINK_STATUS_BAD: DP Link is BAD as a result of link trainingfailure

Description

This enum is used as the connector’s link status property value.It is set to the values defined in uapi.

enumdrm_panel_orientation¶: panel_orientation info fordrm_display_info

Constants

DRM_MODE_PANEL_ORIENTATION_UNKNOWN: The drm driver has not provided anypanel orientation information (normalfor non panels) in this case the “panelorientation” connector prop will not beattached.
DRM_MODE_PANEL_ORIENTATION_NORMAL: The top side of the panel matches thetop side of the device’s casing.
DRM_MODE_PANEL_ORIENTATION_BOTTOM_UP: The top side of the panel matches thebottom side of the device’s casing, iowthe panel is mounted upside-down.
DRM_MODE_PANEL_ORIENTATION_LEFT_UP: The left side of the panel matches thetop side of the device’s casing.
DRM_MODE_PANEL_ORIENTATION_RIGHT_UP: The right side of the panel matches thetop side of the device’s casing.

Description

This enum is used to track the (LCD) panel orientation. There are noseparate #defines for the uapi!

structdrm_monitor_range_info¶: Panel’s Monitor range in EDID fordrm_display_info

Definition

struct drm_monitor_range_info {  u8 min_vfreq;  u8 max_vfreq;};

Members

min_vfreq: This is the min supported refresh rate in Hz fromEDID’s detailed monitor range.
max_vfreq: This is the max supported refresh rate in Hz fromEDID’s detailed monitor range

Description

This struct is used to store a frequency range supported by panelas parsed from EDID’s detailed monitor range descriptor block.

enumdrm_bus_flags¶: bus_flags info fordrm_display_info

Constants

DRM_BUS_FLAG_DE_LOW: The Data Enable signal is active low
DRM_BUS_FLAG_DE_HIGH: The Data Enable signal is active high
DRM_BUS_FLAG_PIXDATA_DRIVE_POSEDGE: Data is driven on the rising edge of the pixel clock
DRM_BUS_FLAG_PIXDATA_DRIVE_NEGEDGE: Data is driven on the falling edge of the pixel clock
DRM_BUS_FLAG_PIXDATA_SAMPLE_POSEDGE: Data is sampled on the rising edge of the pixel clock
DRM_BUS_FLAG_PIXDATA_SAMPLE_NEGEDGE: Data is sampled on the falling edge of the pixel clock
DRM_BUS_FLAG_DATA_MSB_TO_LSB: Data is transmitted MSB to LSB on the bus
DRM_BUS_FLAG_DATA_LSB_TO_MSB: Data is transmitted LSB to MSB on the bus
DRM_BUS_FLAG_SYNC_DRIVE_POSEDGE: Sync signals are driven on the rising edge of the pixel clock
DRM_BUS_FLAG_SYNC_DRIVE_NEGEDGE: Sync signals are driven on the falling edge of the pixel clock
DRM_BUS_FLAG_SYNC_SAMPLE_POSEDGE: Sync signals are sampled on the rising edge of the pixel clock
DRM_BUS_FLAG_SYNC_SAMPLE_NEGEDGE: Sync signals are sampled on the falling edge of the pixel clock
DRM_BUS_FLAG_SHARP_SIGNALS: Set if the Sharp-specific signals (SPL, CLS, PS, REV) must be used

Description

This enum defines signal polarities and clock edge information for signals ona bus as bitmask flags.

The clock edge information is conveyed by two sets of symbols,DRM_BUS_FLAGS_*_DRIVE_* and DRM_BUS_FLAGS_*_SAMPLE_*. When this enum isused to describe a bus from the point of view of the transmitter, the*_DRIVE_* flags should be used. When used from the point of view of thereceiver, the *_SAMPLE_* flags should be used. The *_DRIVE_* and*_SAMPLE_* flags alias each other, with the *_SAMPLE_POSEDGE and*_SAMPLE_NEGEDGE flags being equal to *_DRIVE_NEGEDGE and *_DRIVE_POSEDGErespectively. This simplifies code as signals are usually sampled on theopposite edge of the driving edge. Transmitters and receivers may howeverneed to take other signal timings into account to convert between drivingand sample edges.

structdrm_display_info¶: runtime data about the connected sink

Definition

struct drm_display_info {  unsigned int width_mm;  unsigned int height_mm;  unsigned int bpc;  enum subpixel_order subpixel_order;#define DRM_COLOR_FORMAT_RGB444         (1<<0);#define DRM_COLOR_FORMAT_YCRCB444       (1<<1);#define DRM_COLOR_FORMAT_YCRCB422       (1<<2);#define DRM_COLOR_FORMAT_YCRCB420       (1<<3);  int panel_orientation;  u32 color_formats;  const u32 *bus_formats;  unsigned int num_bus_formats;  u32 bus_flags;  int max_tmds_clock;  bool dvi_dual;  bool is_hdmi;  bool has_hdmi_infoframe;  bool rgb_quant_range_selectable;  u8 edid_hdmi_dc_modes;  u8 cea_rev;  struct drm_hdmi_info hdmi;  bool non_desktop;  struct drm_monitor_range_info monitor_range;};

Members

width_mm

Physical width in mm.

height_mm

Physical height in mm.

bpc

Maximum bits per color channel. Used by HDMI and DP outputs.

subpixel_order

Subpixel order of LCD panels.

panel_orientation

Read only connector property for built-in panels,indicating the orientation of the panel vs the device’s casing.drm_connector_init() sets this to DRM_MODE_PANEL_ORIENTATION_UNKNOWN.When not UNKNOWN this gets used by the drm_fb_helpers to rotate thefb to compensate and gets exported as prop to userspace.

color_formats

HDMI Color formats, selects between RGB and YCrCbmodes. Used DRM_COLOR_FORMAT_ defines, which are _not_ the same onesas used to describe the pixel format in framebuffers, and also don’tmatch the formats inbus_formats which are shared with v4l.

bus_formats

Pixel data format on the wire, somewhat redundant withcolor_formats. Array of sizenum_bus_formats encoded usingMEDIA_BUS_FMT_ defines shared with v4l and media drivers.

num_bus_formats

Size ofbus_formats array.

bus_flags

Additional information (like pixel signal polarity) forthe pixel data on the bus, usingenumdrm_bus_flags valuesDRM_BUS_FLAGS_.

max_tmds_clock

Maximum TMDS clock rate supported by thesink in kHz. 0 means undefined.

dvi_dual

Dual-link DVI sink?

is_hdmi

True if the sink is an HDMI device.

This field shall be used instead of callingdrm_detect_hdmi_monitor() when possible.

has_hdmi_infoframe

Does the sink support the HDMI infoframe?

rgb_quant_range_selectable

Does the sink support selectingthe RGB quantization range?

edid_hdmi_dc_modes

Mask of supported hdmi deep color modes. Evenmore stuff redundant withbus_formats.

cea_rev

CEA revision of the HDMI sink.

hdmi

advance features of a HDMI sink.

non_desktop

Non desktop display (HMD).

monitor_range

Frequency range supported by monitor range descriptor

Description

Describes a given display (e.g. CRT or flat panel) and its limitations. Forfixed display sinks like built-in panels there’s not much difference betweenthis andstructdrm_connector. But for sinks with a real cable thisstructure is meant to describe all the things at the other end of the cable.

For sinks which provide an EDID this can be filled out by callingdrm_add_edid_modes().

structdrm_connector_tv_margins¶: TV connector related margins

Definition

struct drm_connector_tv_margins {  unsigned int bottom;  unsigned int left;  unsigned int right;  unsigned int top;};

Members

bottom: Bottom margin in pixels.
left: Left margin in pixels.
right: Right margin in pixels.
top: Top margin in pixels.

Description

Describes the margins in pixels to put around the image on TVconnectors to deal with overscan.

structdrm_tv_connector_state¶: TV connector related states

Definition

struct drm_tv_connector_state {  enum drm_mode_subconnector subconnector;  struct drm_connector_tv_margins margins;  unsigned int mode;  unsigned int brightness;  unsigned int contrast;  unsigned int flicker_reduction;  unsigned int overscan;  unsigned int saturation;  unsigned int hue;};

Members

subconnector: selected subconnector
margins: TV margins
mode: TV mode
brightness: brightness in percent
contrast: contrast in percent
flicker_reduction: flicker reduction in percent
overscan: overscan in percent
saturation: saturation in percent
hue: hue in percent

structdrm_connector_state¶: mutable connector state

Definition

struct drm_connector_state {  struct drm_connector *connector;  struct drm_crtc *crtc;  struct drm_encoder *best_encoder;  enum drm_link_status link_status;  struct drm_atomic_state *state;  struct drm_crtc_commit *commit;  struct drm_tv_connector_state tv;  bool self_refresh_aware;  enum hdmi_picture_aspect picture_aspect_ratio;  unsigned int content_type;  unsigned int hdcp_content_type;  unsigned int scaling_mode;  unsigned int content_protection;  u32 colorspace;  struct drm_writeback_job *writeback_job;  u8 max_requested_bpc;  u8 max_bpc;  struct drm_property_blob *hdr_output_metadata;};

Members

connector

backpointer to the connector

crtc

CRTC to connect connector to, NULL if disabled.

Do not change this directly, usedrm_atomic_set_crtc_for_connector()instead.

best_encoder

Used by the atomic helpers to select the encoder, through thedrm_connector_helper_funcs.atomic_best_encoder ordrm_connector_helper_funcs.best_encoder callbacks.

This is also used in the atomic helpers to map encoders to theircurrent and previous connectors, seedrm_atomic_get_old_connector_for_encoder() anddrm_atomic_get_new_connector_for_encoder().

NOTE: Atomic drivers must fill this out (either themselves or throughhelpers), for otherwise the GETCONNECTOR and GETENCODER IOCTLs willnot return correct data to userspace.

link_status

Connector link_status to keep track of whether link isGOOD or BAD to notify userspace if retraining is necessary.

state

backpointer to global drm_atomic_state

commit

Tracks the pending commit to prevent use-after-free conditions.

Is only set whencrtc is NULL.

tv

TV connector state

self_refresh_aware

This tracks whether a connector is aware of the self refresh state.It should be set to true for those connector implementations whichunderstand the self refresh state. This is needed since the crtcregisters the self refresh helpers and it doesn’t know if theconnectors downstream have implemented self refresh entry/exit.

Drivers should set this to true in atomic_check if they know how tohandle self_refresh requests.

picture_aspect_ratio

Connector property to control theHDMI infoframe aspect ratio setting.

TheDRM_MODE_PICTURE_ASPECT_* values much match thevalues forenumhdmi_picture_aspect

content_type

Connector property to control theHDMI infoframe content type setting.TheDRM_MODE_CONTENT_TYPE_* values muchmatch the values.

hdcp_content_type

Connector property to pass the type ofprotected content. This is most commonly used for HDCP.

scaling_mode

Connector property to control theupscaling, mostly used for built-in panels.

content_protection

Connector property to request contentprotection. This is most commonly used for HDCP.

colorspace

State variable for Connector property to requestcolorspace change on Sink. This is most commonly used to switchto wider color gamuts like BT2020.

writeback_job

Writeback job for writeback connectors

Holds the framebuffer and out-fence for a writeback connector. Asthe writeback completion may be asynchronous to the normal commitcycle, the writeback job lifetime is managed separately from thenormal atomic state by this object.

max_requested_bpc

Connector property to limit the maximum bitdepth of the pixels.

max_bpc

Connector max_bpc based on the requested max_bpc propertyand the connector bpc limitations obtained from edid.

hdr_output_metadata

DRM blob property for HDR output metadata

structdrm_connector_funcs¶: control connectors on a given device

Definition

struct drm_connector_funcs {  int (*dpms)(struct drm_connector *connector, int mode);  void (*reset)(struct drm_connector *connector);  enum drm_connector_status (*detect)(struct drm_connector *connector, bool force);  void (*force)(struct drm_connector *connector);  int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, uint32_t max_height);  int (*set_property)(struct drm_connector *connector, struct drm_property *property, uint64_t val);  int (*late_register)(struct drm_connector *connector);  void (*early_unregister)(struct drm_connector *connector);  void (*destroy)(struct drm_connector *connector);  struct drm_connector_state *(*atomic_duplicate_state)(struct drm_connector *connector);  void (*atomic_destroy_state)(struct drm_connector *connector, struct drm_connector_state *state);  int (*atomic_set_property)(struct drm_connector *connector,struct drm_connector_state *state,struct drm_property *property, uint64_t val);  int (*atomic_get_property)(struct drm_connector *connector,const struct drm_connector_state *state,struct drm_property *property, uint64_t *val);  void (*atomic_print_state)(struct drm_printer *p, const struct drm_connector_state *state);};

Members

dpms

Legacy entry point to set the per-connector DPMS state. Legacy DPMSis exposed as a standard property on the connector, but diverted tothis callback in the drm core. Note that atomic drivers don’timplement the 4 level DPMS support on the connector any more, butinstead only have an on/off “ACTIVE” property on the CRTC object.

This hook is not used by atomic drivers, remapping of the legacy DPMSproperty is entirely handled in the DRM core.

RETURNS:

0 on success or a negative error code on failure.

reset

Reset connector hardware and software state to off. This function isn’tcalled by the core directly, only throughdrm_mode_config_reset().It’s not a helper hook only for historical reasons.

Atomic drivers can usedrm_atomic_helper_connector_reset() to resetatomic state using this hook.

detect

Check to see if anything is attached to the connector. The parameterforce is set to false whilst polling, true when checking theconnector due to a user request. force can be used by the driver toavoid expensive, destructive operations during automated probing.

This callback is optional, if not implemented the connector will beconsidered as always being attached.

FIXME:

Note that this hook is only called by the probe helper. It’s not inthe helper library vtable purely for historical reasons. The only DRMcore entry point to probe connector state isfill_modes.

Note that the helper library will already holddrm_mode_config.connection_mutex. Drivers which need to grab additionallocks to avoid races with concurrent modeset changes need to usedrm_connector_helper_funcs.detect_ctx instead.

RETURNS:

drm_connector_status indicating the connector’s status.

force

This function is called to update internal encoder state when theconnector is forced to a certain state by userspace, either throughthe sysfs interfaces or on the kernel cmdline. In that case thedetect callback isn’t called.

FIXME:

Note that this hook is only called by the probe helper. It’s not inthe helper library vtable purely for historical reasons. The only DRMcore entry point to probe connector state isfill_modes.

fill_modes

Entry point for output detection and basic mode validation. Thedriver should reprobe the output if needed (e.g. when hotplughandling is unreliable), add all detected modes todrm_connector.modesand filter out any the device can’t support in any configuration. Italso needs to filter out any modes wider or higher than theparameters max_width and max_height indicate.

The drivers must also prune any modes no longer valid fromdrm_connector.modes. Furthermore it must updatedrm_connector.status anddrm_connector.edid. If no EDID has beenreceived for this output connector->edid must be NULL.

Drivers using the probe helpers should usedrm_helper_probe_single_connector_modes() to implement thisfunction.

RETURNS:

The number of modes detected and filled intodrm_connector.modes.

set_property

This is the legacy entry point to update a property attached to theconnector.

This callback is optional if the driver does not support any legacydriver-private properties. For atomic drivers it is not used becauseproperty handling is done entirely in the DRM core.

RETURNS:

0 on success or a negative error code on failure.

late_register

This optional hook can be used to register additional userspaceinterfaces attached to the connector, light backlight control, i2c,DP aux or similar interfaces. It is called late in the driver loadsequence fromdrm_connector_register() when registering all thecore drm connector interfaces. Everything added from this callbackshould be unregistered in the early_unregister callback.

This is called while holdingdrm_connector.mutex.

Returns:

0 on success, or a negative error code on failure.

early_unregister

This optional hook should be used to unregister the additionaluserspace interfaces attached to the connector fromlate_register(). It is called fromdrm_connector_unregister(),early in the driver unload sequence to disable userspace accessbefore data structures are torndown.

This is called while holdingdrm_connector.mutex.

destroy

Clean up connector resources. This is called at driver unload timethroughdrm_mode_config_cleanup(). It can also be called at runtimewhen a connector is being hot-unplugged for drivers that supportconnector hotplugging (e.g. DisplayPort MST).

atomic_duplicate_state

Duplicate the current atomic state for this connector and return it.The core and helpers guarantee that any atomic state duplicated withthis hook and still owned by the caller (i.e. not transferred to thedriver by callingdrm_mode_config_funcs.atomic_commit) will becleaned up by calling theatomic_destroy_state hook in thisstructure.

This callback is mandatory for atomic drivers.

Atomic drivers which don’t subclassstructdrm_connector_state should usedrm_atomic_helper_connector_duplicate_state(). Drivers that subclass thestate structure to extend it with driver-private state should use__drm_atomic_helper_connector_duplicate_state() to make sure shared state isduplicated in a consistent fashion across drivers.

It is an error to call this hook beforedrm_connector.state has beeninitialized correctly.

NOTE:

If the duplicate state references refcounted resources this hook mustacquire a reference for each of them. The driver must release thesereferences again inatomic_destroy_state.

RETURNS:

Duplicated atomic state or NULL when the allocation failed.

atomic_destroy_state

Destroy a state duplicated withatomic_duplicate_state and releaseor unreference all resources it references

This callback is mandatory for atomic drivers.

atomic_set_property

Do not call this function directly, usedrm_atomic_connector_set_property() instead.

This callback is optional if the driver does not support anydriver-private atomic properties.

NOTE:

RETURNS:

0 if the property has been found, -EINVAL if the property isn’timplemented by the driver (which shouldn’t ever happen, the core onlyasks for properties attached to this connector). No other validationis allowed by the driver. The core already checks that the propertyvalue is within the range (integer, valid enum value, …) the driverset when registering the property.

atomic_get_property

Reads out the decoded driver-private property. This is used toimplement the GETCONNECTOR IOCTL.

Do not call this function directly, usedrm_atomic_connector_get_property() instead.

This callback is optional if the driver does not support anydriver-private atomic properties.

RETURNS:

0 on success, -EINVAL if the property isn’t implemented by thedriver (which shouldn’t ever happen, the core only asks forproperties attached to this connector).

atomic_print_state

If driver subclassesstructdrm_connector_state, it should implementthis optional hook for printing additional driver specific state.

Do not call this directly, use drm_atomic_connector_print_state()instead.

Description

Each CRTC may have one or more connectors attached to it. The functionsbelow allow the core DRM code to control connectors, enumerate available modes,etc.

structdrm_cmdline_mode¶: DRM Mode passed through the kernel command-line

Definition

struct drm_cmdline_mode {  char name[DRM_DISPLAY_MODE_LEN];  bool specified;  bool refresh_specified;  bool bpp_specified;  int xres;  int yres;  int bpp;  int refresh;  bool rb;  bool interlace;  bool cvt;  bool margins;  enum drm_connector_force force;  unsigned int rotation_reflection;  enum drm_panel_orientation panel_orientation;  struct drm_connector_tv_margins tv_margins;};

Members

name: Name of the mode.
specified: Has a mode been read from the command-line?
refresh_specified: Did the mode have a preferred refresh rate?
bpp_specified: Did the mode have a preferred BPP?
xres: Active resolution on the X axis, in pixels.
yres: Active resolution on the Y axis, in pixels.
bpp: Bits per pixels for the mode.
refresh: Refresh rate, in Hertz.
rb: Do we need to use reduced blanking?
interlace: The mode is interlaced.
cvt: The timings will be calculated using the VESA CoordinatedVideo Timings instead of looking up the mode from a table.
margins: Add margins to the mode calculation (1.8% of xres roundeddown to 8 pixels and 1.8% of yres).
force: Ignore the hotplug state of the connector, and force itsstate to one of the DRM_FORCE_* values.
rotation_reflection: Initial rotation and reflection of the mode setup from thecommand line. See DRM_MODE_ROTATE_* andDRM_MODE_REFLECT_*. The only rotations supported areDRM_MODE_ROTATE_0 and DRM_MODE_ROTATE_180.
panel_orientation: drm-connector “panel orientation” property override value,DRM_MODE_PANEL_ORIENTATION_UNKNOWN if not set.
tv_margins: TV margins to apply to the mode.

Description

Each connector can have an initial mode with additional optionspassed through the kernel command line. This structure allows toexpress those parameters and will be filled by the command-lineparser.

structdrm_connector¶: central DRM connector control structure

Definition

struct drm_connector {  struct drm_device *dev;  struct device *kdev;  struct device_attribute *attr;  struct list_head head;  struct drm_mode_object base;  char *name;  struct mutex mutex;  unsigned index;  int connector_type;  int connector_type_id;  bool interlace_allowed;  bool doublescan_allowed;  bool stereo_allowed;  bool ycbcr_420_allowed;  enum drm_connector_registration_state registration_state;  struct list_head modes;  enum drm_connector_status status;  struct list_head probed_modes;  struct drm_display_info display_info;  const struct drm_connector_funcs *funcs;  struct drm_property_blob *edid_blob_ptr;  struct drm_object_properties properties;  struct drm_property *scaling_mode_property;  struct drm_property *vrr_capable_property;  struct drm_property *colorspace_property;  struct drm_property_blob *path_blob_ptr;  struct drm_property *max_bpc_property;#define DRM_CONNECTOR_POLL_HPD (1 << 0);#define DRM_CONNECTOR_POLL_CONNECT (1 << 1);#define DRM_CONNECTOR_POLL_DISCONNECT (1 << 2);  uint8_t polled;  int dpms;  const struct drm_connector_helper_funcs *helper_private;  struct drm_cmdline_mode cmdline_mode;  enum drm_connector_force force;  bool override_edid;  u64 epoch_counter;  u32 possible_encoders;  struct drm_encoder *encoder;#define MAX_ELD_BYTES   128;  uint8_t eld[MAX_ELD_BYTES];  bool latency_present[2];  int video_latency[2];  int audio_latency[2];  struct i2c_adapter *ddc;  int null_edid_counter;  unsigned bad_edid_counter;  bool edid_corrupt;  u8 real_edid_checksum;  struct dentry *debugfs_entry;  struct drm_connector_state *state;  struct drm_property_blob *tile_blob_ptr;  bool has_tile;  struct drm_tile_group *tile_group;  bool tile_is_single_monitor;  uint8_t num_h_tile, num_v_tile;  uint8_t tile_h_loc, tile_v_loc;  uint16_t tile_h_size, tile_v_size;  struct llist_node free_node;  struct hdr_sink_metadata hdr_sink_metadata;};

Members

dev

parent DRM device

kdev

kernel device for sysfs attributes

attr

sysfs attributes

head

List of all connectors on adev, linked fromdrm_mode_config.connector_list. Protected bydrm_mode_config.connector_list_lock, but please only usedrm_connector_list_iter to walk this list.

base

base KMS object

name

human readable name, can be overwritten by the driver

mutex

Lock for general connector state, but currently only protectsregistered. Most of the connector state is still protected bydrm_mode_config.mutex.

index

Compacted connector index, which matches the position insidethe mode_config.list for drivers not supporting hot-add/removing. Canbe used as an array index. It is invariant over the lifetime of theconnector.

connector_type

one of the DRM_MODE_CONNECTOR_<foo> types from drm_mode.h

connector_type_id

index into connector type enum

interlace_allowed

Can this connector handle interlaced modes? Only used bydrm_helper_probe_single_connector_modes() for mode filtering.

doublescan_allowed

Can this connector handle doublescan? Only used bydrm_helper_probe_single_connector_modes() for mode filtering.

stereo_allowed

Can this connector handle stereo modes? Only used bydrm_helper_probe_single_connector_modes() for mode filtering.

ycbcr_420_allowed

This bool indicates if this connector iscapable of handling YCBCR 420 output. While parsing the EDIDblocks it’s very helpful to know if the source is capable ofhandling YCBCR 420 outputs.

registration_state

Is this connector initializing, exposed(registered) with userspace, or unregistered?

Protected bymutex.

modes

Modes available on this connector (from fill_modes() + user).Protected bydrm_mode_config.mutex.

status

One of the drm_connector_status enums (connected, not, or unknown).Protected bydrm_mode_config.mutex.

probed_modes

These are modes added by probing with DDC or the BIOS, beforefiltering is applied. Used by the probe helpers. Protected bydrm_mode_config.mutex.

display_info

Display information is filled from EDID informationwhen a display is detected. For non hot-pluggable displays such asflat panels in embedded systems, the driver should initialize thedrm_display_info.width_mm anddrm_display_info.height_mm fieldswith the physical size of the display.

Protected bydrm_mode_config.mutex.

funcs

connector control functions

edid_blob_ptr

DRM property containing EDID if present. Protected bydrm_mode_config.mutex. This should be updated only by callingdrm_connector_update_edid_property().

properties

property tracking for this connector

scaling_mode_property

Optional atomic property to control theupscaling. Seedrm_connector_attach_content_protection_property().

vrr_capable_property

Optional property to help userspacequery hardware support for variable refresh rate on a connector.connector. Drivers can add the property to a connector bycallingdrm_connector_attach_vrr_capable_property().

This should be updated only by callingdrm_connector_set_vrr_capable_property().

colorspace_property

Connector property to set the suitablecolorspace supported by the sink.

path_blob_ptr

DRM blob property data for the DP MST path property. This should onlybe updated by callingdrm_connector_set_path_property().

max_bpc_property

Default connector property for the max bpc to bedriven out of the connector.

polled

Connector polling mode, a combination of

DRM_CONNECTOR_POLL_HPD: The connector generates hotplug events and doesn’t need to beperiodically polled. The CONNECT and DISCONNECT flags must notbe set together with the HPD flag.
DRM_CONNECTOR_POLL_CONNECT: Periodically poll the connector for connection.
DRM_CONNECTOR_POLL_DISCONNECT: Periodically poll the connector for disconnection, withoutcausing flickering even when the connector is in use. DACs shouldrarely do this without a lot of testing.

Set to 0 for connectors that don’t support connection statusdiscovery.

dpms

Current dpms state. For legacy drivers thedrm_connector_funcs.dpms callback must update this. For atomicdrivers, this is handled by the core atomic code, and drivers mustonly takedrm_crtc_state.active into account.

helper_private

mid-layer private data

cmdline_mode

mode line parsed from the kernel cmdline for this connector

force

a DRM_FORCE_<foo> state for forced mode sets

override_edid

has the EDID been overwritten through debugfs for testing?

epoch_counter

used to detect any other changes in connector, besides status

possible_encoders

Bit mask of encoders that can drive thisconnector,drm_encoder_index() determines the index into the bitfieldand the bits are set withdrm_connector_attach_encoder().

encoder

Currently bound encoder driving this connector, if any.Only really meaningful for non-atomic drivers. Atomic drivers shouldinstead look atdrm_connector_state.best_encoder, and in case theyneed the CRTC driving this output,drm_connector_state.crtc.

eld

EDID-like data, if present

latency_present

AV delay info from ELD, if found

video_latency

Video latency info from ELD, if found.[0]: progressive, [1]: interlaced

audio_latency

audio latency info from ELD, if found[0]: progressive, [1]: interlaced

ddc

associated ddc adapter.A connector usually has its associated ddc adapter. If a driver usesthis field, then an appropriate symbolic link is created in connectorsysfs directory to make it easy for the user to tell which i2cadapter is for a particular display.

The field should be set by callingdrm_connector_init_with_ddc().

null_edid_counter

track sinks that give us all zeros for the EDID.Needed to workaround some HW bugs where we get all 0s

bad_edid_counter

track sinks that give us an EDID with invalid checksum

edid_corrupt

Indicates whether the last read EDID was corrupt. Usedin Displayport compliance testing - Displayport Link CTS Core 1.2rev1.1 4.2.2.6

real_edid_checksum

real edid checksum for corrupted edid block.Required in Displayport 1.4 compliance testingrev1.1 4.2.2.6

debugfs_entry

debugfs directory for this connector

state

Current atomic state for this connector.

This is protected bydrm_mode_config.connection_mutex. Note thatnonblocking atomic commits access the current connector state withouttaking locks. Either by going through thestructdrm_atomic_statepointers, seefor_each_oldnew_connector_in_state(),for_each_old_connector_in_state() andfor_each_new_connector_in_state(). Or through careful ordering ofatomic commit operations as implemented in the atomic helpers, seestructdrm_crtc_commit.

tile_blob_ptr

DRM blob property data for the tile property (used mostly by DP MST).This is meant for screens which are driven through separate displaypipelines represented bydrm_crtc, which might not be running withgenlocked clocks. For tiled panels which are genlocked, likedual-link LVDS or dual-link DSI, the driver should try to not exposethe tiling and virtualize bothdrm_crtc anddrm_plane if needed.

This should only be updated by callingdrm_connector_set_tile_property().

has_tile

is this connector connected to a tiled monitor

tile_group

tile group for the connected monitor

tile_is_single_monitor

whether the tile is one monitor housing

num_h_tile

number of horizontal tiles in the tile group

num_v_tile

number of vertical tiles in the tile group

tile_h_loc

horizontal location of this tile

tile_v_loc

vertical location of this tile

tile_h_size

horizontal size of this tile.

tile_v_size

vertical size of this tile.

free_node

List used only bydrm_connector_list_iter to be able to clean up aconnector from any context, in conjunction withdrm_mode_config.connector_free_work.

hdr_sink_metadata

HDR Metadata Information read from sink

Description

Each connector may be connected to one or more CRTCs, or may be clonable byanother connector if they can share a CRTC. Each connector also has a specificposition in the broader display (referred to as a ‘screen’ though it couldspan multiple monitors).

structdrm_connector *drm_connector_lookup(structdrm_device * dev, structdrm_file * file_priv, uint32_t id)¶: lookup connector object

Parameters

structdrm_device*dev: DRM device
structdrm_file*file_priv: drm file to check for lease against.
uint32_tid: connector object id

Description

This function looks up the connector object specified by idadd takes a reference to it.

voiddrm_connector_get(structdrm_connector * connector)¶: acquire a connector reference

Parameters

structdrm_connector*connector: DRM connector

Description

This function increments the connector’s refcount.

voiddrm_connector_put(structdrm_connector * connector)¶: release a connector reference

Parameters

structdrm_connector*connector: DRM connector

Description

This function decrements the connector’s reference count and frees theobject if the reference count drops to zero.

booldrm_connector_is_unregistered(structdrm_connector * connector)¶: has the connector been unregistered from userspace?

Parameters

structdrm_connector*connector: DRM connector

Description

Checks whether or notconnector has been unregistered from userspace.

Return

True if the connector was unregistered, false if the connector isregistered or has not yet been registered with userspace.

structdrm_tile_group¶: Tile group metadata

Definition

struct drm_tile_group {  struct kref refcount;  struct drm_device *dev;  int id;  u8 group_data[8];};

Members

refcount: reference count
dev: DRM device
id: tile group id exposed to userspace
group_data: Sink-private data identifying this group

Description

group_data corresponds to displayid vend/prod/serial for external screenswith an EDID.

structdrm_connector_list_iter¶: connector_list iterator

Definition

struct drm_connector_list_iter {};

Members

Description

This iterator tracks state needed to be able to walk the connector_listwithin struct drm_mode_config. Only use together withdrm_connector_list_iter_begin(),drm_connector_list_iter_end() anddrm_connector_list_iter_next() respectively the convenience macrodrm_for_each_connector_iter().

drm_for_each_connector_iter(connector,iter)¶: connector_list iterator macro

Parameters

connector: structdrm_connector pointer used as cursor
iter: structdrm_connector_list_iter

Description

Note thatconnector is only valid within the list body, if you want to useconnector after callingdrm_connector_list_iter_end() then you need to grabyour own reference first usingdrm_connector_get().

drm_connector_for_each_possible_encoder(connector,encoder)¶: iterate connector’s possible encoders

Parameters

connector: structdrm_connector pointer
encoder: structdrm_encoder pointer used as cursor

const char *drm_get_connector_type_name(unsigned int type)¶: return a string for connector type

Parameters

unsignedinttype: The connector type (DRM_MODE_CONNECTOR_*)

Return

the name of the connector type, or NULL if the type is not valid.

intdrm_connector_init(structdrm_device * dev, structdrm_connector * connector, const structdrm_connector_funcs * funcs, int connector_type)¶: Init a preallocated connector

Parameters

structdrm_device*dev: DRM device
structdrm_connector*connector: the connector to init
conststructdrm_connector_funcs*funcs: callbacks for this connector
intconnector_type: user visible type of the connector

Description

Initialises a preallocated connector. Connectors should besubclassed as part of driver connector objects.

Return

Zero on success, error code on failure.

intdrm_connector_init_with_ddc(structdrm_device * dev, structdrm_connector * connector, const structdrm_connector_funcs * funcs, int connector_type, struct i2c_adapter * ddc)¶: Init a preallocated connector

Parameters

structdrm_device*dev: DRM device
structdrm_connector*connector: the connector to init
conststructdrm_connector_funcs*funcs: callbacks for this connector
intconnector_type: user visible type of the connector
structi2c_adapter*ddc: pointer to the associated ddc adapter

Description

Initialises a preallocated connector. Connectors should besubclassed as part of driver connector objects.

Ensures that the ddc field of the connector is correctly set.

Return

Zero on success, error code on failure.

voiddrm_connector_attach_edid_property(structdrm_connector * connector)¶: attach edid property.

Parameters

structdrm_connector*connector: the connector

Description

Some connector types like DRM_MODE_CONNECTOR_VIRTUAL do not get aedid property attached by default. This function can be used toexplicitly enable the edid property in these cases.

intdrm_connector_attach_encoder(structdrm_connector * connector, structdrm_encoder * encoder)¶: attach a connector to an encoder

Parameters

structdrm_connector*connector: connector to attach
structdrm_encoder*encoder: encoder to attachconnector to

Description

This function links up a connector to an encoder. Note that the routingrestrictions between encoders and crtcs are exposed to userspace through thepossible_clones and possible_crtcs bitmasks.

Return

Zero on success, negative errno on failure.

booldrm_connector_has_possible_encoder(structdrm_connector * connector, structdrm_encoder * encoder)¶: check if the connector and encoder are associated with each other

Parameters

structdrm_connector*connector: the connector
structdrm_encoder*encoder: the encoder

Return

True ifencoder is one of the possible encoders forconnector.

voiddrm_connector_cleanup(structdrm_connector * connector)¶: cleans up an initialised connector

Parameters

structdrm_connector*connector: connector to cleanup

Description

Cleans up the connector but doesn’t free the object.

intdrm_connector_register(structdrm_connector * connector)¶: register a connector

Parameters

structdrm_connector*connector: the connector to register

Description

Register userspace interfaces for a connector. Only call this for connectorswhich can be hotplugged afterdrm_dev_register() has been called already,e.g. DP MST connectors. All other connectors will be registered automaticallywhen callingdrm_dev_register().

Return

Zero on success, error code on failure.

voiddrm_connector_unregister(structdrm_connector * connector)¶: unregister a connector

Parameters

structdrm_connector*connector: the connector to unregister

Description

Unregister userspace interfaces for a connector. Only call this forconnectors which have registered explicitly by callingdrm_dev_register(),since connectors are unregistered automatically whendrm_dev_unregister() iscalled.

const char *drm_get_connector_status_name(enumdrm_connector_status status)¶: return a string for connector status

Parameters

enumdrm_connector_statusstatus: connector status to compute name of

Description

In contrast to the other drm_get_*_name functions this one here returns aconst pointer and hence is threadsafe.

voiddrm_connector_list_iter_begin(structdrm_device * dev, structdrm_connector_list_iter * iter)¶: initialize a connector_list iterator

Parameters

structdrm_device*dev: DRM device
structdrm_connector_list_iter*iter: connector_list iterator

Description

Setsiter up to walk thedrm_mode_config.connector_list ofdev.itermust always be cleaned up again by callingdrm_connector_list_iter_end().Iteration itself happens usingdrm_connector_list_iter_next() ordrm_for_each_connector_iter().

structdrm_connector *drm_connector_list_iter_next(structdrm_connector_list_iter * iter)¶: return next connector

Parameters

structdrm_connector_list_iter*iter: connector_list iterator

Description

Returns the next connector foriter, or NULL when the list walk hascompleted.

voiddrm_connector_list_iter_end(structdrm_connector_list_iter * iter)¶: tear down a connector_list iterator

Parameters

structdrm_connector_list_iter*iter: connector_list iterator

Description

Tears downiter and releases any resources (likedrm_connector references)acquired while walking the list. This must always be called, both when theiteration completes fully or when it was aborted without walking the entirelist.

const char *drm_get_subpixel_order_name(enum subpixel_order order)¶: return a string for a given subpixel enum

Parameters

enumsubpixel_orderorder: enum of subpixel_order

Description

Note you could abuse this and return something out of bounds, but thatwould be a caller error. No unscrubbed user data should make it here.

intdrm_display_info_set_bus_formats(structdrm_display_info * info, const u32 * formats, unsigned int num_formats)¶: set the supported bus formats

Parameters

structdrm_display_info*info: display info to store bus formats in
constu32*formats: array containing the supported bus formats
unsignedintnum_formats: the number of entries in the fmts array

Description

Store the supported bus formats in display info structure.See MEDIA_BUS_FMT_* definitions in include/uapi/linux/media-bus-format.h fora full list of available formats.

intdrm_mode_create_dvi_i_properties(structdrm_device * dev)¶: create DVI-I specific connector properties

Parameters

structdrm_device*dev: DRM device

Description

Called by a driver the first time a DVI-I connector is made.

intdrm_connector_attach_content_type_property(structdrm_connector * connector)¶: attach content-type property

Parameters

structdrm_connector*connector: connector to attach content type property on.

Description

Called by a driver the first time a HDMI connector is made.

voiddrm_hdmi_avi_infoframe_content_type(struct hdmi_avi_infoframe * frame, const structdrm_connector_state * conn_state)¶: fill the HDMI AVI infoframe content type information, based on correspondent DRM property.

Parameters

structhdmi_avi_infoframe*frame: HDMI AVI infoframe
conststructdrm_connector_state*conn_state: DRM display connector state

voiddrm_connector_attach_tv_margin_properties(structdrm_connector * connector)¶: attach TV connector margin properties

Parameters

structdrm_connector*connector: DRM connector

Description

Called by a driver when it needs to attach TV margin props to a connector.Typically used on SDTV and HDMI connectors.

intdrm_mode_create_tv_margin_properties(structdrm_device * dev)¶: create TV connector margin properties

Parameters

structdrm_device*dev: DRM device

Description

Called by a driver’s HDMI connector initialization routine, this functioncreates the TV margin properties for a given device. No need to call thisfunction for an SDTV connector, it’s already called fromdrm_mode_create_tv_properties().

intdrm_mode_create_tv_properties(structdrm_device * dev, unsigned int num_modes, const char *const modes)¶: create TV specific connector properties

Parameters

structdrm_device*dev: DRM device
unsignedintnum_modes: number of different TV formats (modes) supported
constchar*constmodes: array of pointers to strings containing name of each format

Description

Called by a driver’s TV initialization routine, this function createsthe TV specific connector properties for a given device. Caller isresponsible for allocating a list of format names and passing them tothis routine.

intdrm_mode_create_scaling_mode_property(structdrm_device * dev)¶: create scaling mode property

Parameters

structdrm_device*dev: DRM device

Description

Called by a driver the first time it’s needed, must be attached to desiredconnectors.

Atomic drivers should usedrm_connector_attach_scaling_mode_property()instead to correctly assigndrm_connector_state.picture_aspect_ratioin the atomic state.

intdrm_connector_attach_vrr_capable_property(structdrm_connector * connector)¶: creates the vrr_capable property

Parameters

structdrm_connector*connector: connector to create the vrr_capable property on.

Description

This is used by atomic drivers to add support for queryingvariable refresh rate capability for a connector.

Return

Zero on success, negative errno on failure.

intdrm_connector_attach_scaling_mode_property(structdrm_connector * connector, u32 scaling_mode_mask)¶: attach atomic scaling mode property

Parameters

structdrm_connector*connector: connector to attach scaling mode property on.
u32scaling_mode_mask: or’ed mask of BIT(DRM_MODE_SCALE_*).

Description

This is used to add support for scaling mode to atomic drivers.The scaling mode will be set todrm_connector_state.picture_aspect_ratioand can be used fromdrm_connector_helper_funcs->atomic_check for validation.

This is the atomic version ofdrm_mode_create_scaling_mode_property().

Return

Zero on success, negative errno on failure.

intdrm_mode_create_aspect_ratio_property(structdrm_device * dev)¶: create aspect ratio property

Parameters

structdrm_device*dev: DRM device

Description

Called by a driver the first time it’s needed, must be attached to desiredconnectors.

Return

Zero on success, negative errno on failure.

intdrm_mode_create_hdmi_colorspace_property(structdrm_connector * connector)¶: create hdmi colorspace property

Parameters

structdrm_connector*connector: connector to create the Colorspace property on.

Description

Called by a driver the first time it’s needed, must be attached to desiredHDMI connectors.

Return

Zero on success, negative errno on failure.

intdrm_mode_create_dp_colorspace_property(structdrm_connector * connector)¶: create dp colorspace property

Parameters

structdrm_connector*connector: connector to create the Colorspace property on.

Description

Called by a driver the first time it’s needed, must be attached to desiredDP connectors.

Return

Zero on success, negative errno on failure.

intdrm_mode_create_content_type_property(structdrm_device * dev)¶: create content type property

Parameters

structdrm_device*dev: DRM device

Description

Called by a driver the first time it’s needed, must be attached to desiredconnectors.

Return

Zero on success, negative errno on failure.

intdrm_mode_create_suggested_offset_properties(structdrm_device * dev)¶: create suggests offset properties

Parameters

structdrm_device*dev: DRM device

Description

Create the suggested x/y offset property for connectors.

intdrm_connector_set_path_property(structdrm_connector * connector, const char * path)¶: set tile property on connector

Parameters

structdrm_connector*connector: connector to set property on.
constchar*path: path to use for property; must not be NULL.

Description

This creates a property to expose to userspace to specify aconnector path. This is mainly used for DisplayPort MST whereconnectors have a topology and we want to allow userspace to givethem more meaningful names.

Return

Zero on success, negative errno on failure.

intdrm_connector_set_tile_property(structdrm_connector * connector)¶: set tile property on connector

Parameters

structdrm_connector*connector: connector to set property on.

Description

This looks up the tile information for a connector, and creates aproperty for userspace to parse if it exists. The property is ofthe form of 8 integers using ‘:’ as a separator.This is used for dual port tiled displays with DisplayPort SSTor DisplayPort MST connectors.

Return

Zero on success, errno on failure.

intdrm_connector_update_edid_property(structdrm_connector * connector, const struct edid * edid)¶: update the edid property of a connector

Parameters

structdrm_connector*connector: drm connector
conststructedid*edid: new value of the edid property

Description

This function creates a new blob modeset object and assigns its id to theconnector’s edid property.Since we also parse tile information from EDID’s displayID block, we alsoset the connector’s tile property here. Seedrm_connector_set_tile_property()for more details.

Return

Zero on success, negative errno on failure.

voiddrm_connector_set_link_status_property(structdrm_connector * connector, uint64_t link_status)¶: Set link status property of a connector

Parameters

structdrm_connector*connector: drm connector
uint64_tlink_status: new value of link status property (0: Good, 1: Bad)

Description

In usual working scenario, this link status property will always be set to“GOOD”. If something fails during or after a mode set, the kernel drivermay set this link status property to “BAD”. The caller then needs to send ahotplug uevent for userspace to re-check the valid modes throughGET_CONNECTOR_IOCTL and retry modeset.

The reason for adding this property is to handle link training failures, butit is not limited to DP or link training. For example, if we implementasynchronous setcrtc, this property can be used to report any failures in that.

Note

Drivers cannot rely on userspace to support this property andissue a modeset. As such, they may choose to handle issues (likere-training a link) without userspace’s intervention.

intdrm_connector_attach_max_bpc_property(structdrm_connector * connector, int min, int max)¶: attach “max bpc” property

Parameters

structdrm_connector*connector: connector to attach max bpc property on.
intmin: The minimum bit depth supported by the connector.
intmax: The maximum bit depth supported by the connector.

Description

This is used to add support for limiting the bit depth on a connector.

Return

Zero on success, negative errno on failure.

voiddrm_connector_set_vrr_capable_property(structdrm_connector * connector, bool capable)¶: sets the variable refresh rate capable property for a connector

Parameters

structdrm_connector*connector: drm connector
boolcapable: True if the connector is variable refresh rate capable

Description

Should be used by atomic drivers to update the indicated support forvariable refresh rate over a connector.

intdrm_connector_set_panel_orientation(structdrm_connector * connector, enumdrm_panel_orientation panel_orientation)¶: sets the connector’s panel_orientation

Parameters

structdrm_connector*connector: connector for which to set the panel-orientation property.
enumdrm_panel_orientationpanel_orientation: drm_panel_orientation value to set

Description

This function sets the connector’s panel_orientation and attachesa “panel orientation” property to the connector.

Calling this function on a connector where the panel_orientation hasalready been set is a no-op (e.g. the orientation has been overridden witha kernel commandline option).

It is allowed to call this function with a panel_orientation ofDRM_MODE_PANEL_ORIENTATION_UNKNOWN, in which case it is a no-op.

Return

Zero on success, negative errno on failure.

intdrm_connector_set_panel_orientation_with_quirk(structdrm_connector * connector, enumdrm_panel_orientation panel_orientation, int width, int height)¶: set the connector’s panel_orientation after checking for quirks

Parameters

structdrm_connector*connector: connector for which to init the panel-orientation property.
enumdrm_panel_orientationpanel_orientation: drm_panel_orientation value to set
intwidth: width in pixels of the panel, used for panel quirk detection
intheight: height in pixels of the panel, used for panel quirk detection

Description

Likedrm_connector_set_panel_orientation(), but with a check for platformspecific (e.g. DMI based) quirks overriding the passed in panel_orientation.

Return

Zero on success, negative errno on failure.

voiddrm_mode_put_tile_group(structdrm_device * dev, structdrm_tile_group * tg)¶: drop a reference to a tile group.

Parameters

structdrm_device*dev: DRM device
structdrm_tile_group*tg: tile group to drop reference to.

Description

drop reference to tile group and free if 0.

structdrm_tile_group *drm_mode_get_tile_group(structdrm_device * dev, const char topology)¶: get a reference to an existing tile group

Parameters

structdrm_device*dev: DRM device
constchartopology: 8-bytes unique per monitor.

Description

Use the unique bytes to get a reference to an existing tile group.

Return

tile group or NULL if not found.

structdrm_tile_group *drm_mode_create_tile_group(structdrm_device * dev, const char topology)¶: create a tile group from a displayid description

Parameters

structdrm_device*dev: DRM device
constchartopology: 8-bytes unique per monitor.

Description

Create a tile group for the unique monitor, and get a uniqueidentifier for the tile group.

Return

new tile group or NULL.

Writeback Connectors¶

structdrm_writeback_connector¶: DRM writeback connector

Definition

struct drm_writeback_connector {  struct drm_connector base;  struct drm_encoder encoder;  struct drm_property_blob *pixel_formats_blob_ptr;  spinlock_t job_lock;  struct list_head job_queue;  unsigned int fence_context;  spinlock_t fence_lock;  unsigned long fence_seqno;  char timeline_name[32];};

Members

base

base drm_connector object

encoder

Internal encoder used by the connector to fulfillthe DRM framework requirements. The users of thedrm_writeback_connector control the behaviour of theencoderby passing theenc_funcs parameter todrm_writeback_connector_init()function.

pixel_formats_blob_ptr

DRM blob property data for the pixel formats list on writebackconnectorsSee alsodrm_writeback_connector_init()

job_lock

Protects job_queue

job_queue

Holds a list of a connector’s writeback jobs; the last item is themost recent. The first item may be either waiting for the hardwareto begin writing, or currently being written.

fence_context

timeline context used for fence operations.

fence_lock

spinlock to protect the fences in the fence_context.

fence_seqno

Seqno variable used as monotonic counter for the fencescreated on the connector’s timeline.

timeline_name

The name of the connector’s fence timeline.

structdrm_writeback_job¶: DRM writeback job

Definition

struct drm_writeback_job {  struct drm_writeback_connector *connector;  bool prepared;  struct work_struct cleanup_work;  struct list_head list_entry;  struct drm_framebuffer *fb;  struct dma_fence *out_fence;  void *priv;};

Members

connector: Back-pointer to the writeback connector associated with the job
prepared: Set when the job has been prepared with drm_writeback_prepare_job()
cleanup_work: Used to allow drm_writeback_signal_completion to defer dropping theframebuffer reference to a workqueue
list_entry: List item for the writeback connector’sjob_queue
fb: Framebuffer to be written to by the writeback connector. Do not setdirectly, use drm_writeback_set_fb()
out_fence: Fence which will signal once the writeback has completed
priv: Driver-private data

Writeback connectors are used to expose hardware which can write the outputfrom a CRTC to a memory buffer. They are used and act similarly to othertypes of connectors, with some important differences:

Writeback connectors don’t provide a way to output visually to the user.
Writeback connectors are visible to userspace only when the client setsDRM_CLIENT_CAP_WRITEBACK_CONNECTORS.
Writeback connectors don’t have EDID.

A framebuffer may only be attached to a writeback connector when theconnector is attached to a CRTC. The WRITEBACK_FB_ID property which sets theframebuffer applies only to a single commit (see below). A framebuffer maynot be attached while the CRTC is off.

Unlike with planes, when a writeback framebuffer is removed by userspace DRMmakes no attempt to remove it from active use by the connector. This isbecause no method is provided to abort a writeback operation, and in anycase making a new commit whilst a writeback is ongoing is undefined (seeWRITEBACK_OUT_FENCE_PTR below). As soon as the current writeback is finished,the framebuffer will automatically no longer be in active use. As it willalso have already been removed from the framebuffer list, there will be noway for any userspace application to retrieve a reference to it in theintervening period.

Writeback connectors have some additional properties, which userspacecan use to query and control them:

“WRITEBACK_FB_ID”:
Write-only object property storing a DRM_MODE_OBJECT_FB: it stores theframebuffer to be written by the writeback connector. This property issimilar to the FB_ID property on planes, but will always read as zeroand is not preserved across commits.Userspace must set this property to an output buffer every time itwishes the buffer to get filled.
“WRITEBACK_PIXEL_FORMATS”:
Immutable blob property to store the supported pixel formats table. Thedata is an array of u32 DRM_FORMAT_* fourcc values.Userspace can use this blob to find out what pixel formats are supportedby the connector’s writeback engine.
“WRITEBACK_OUT_FENCE_PTR”:
Userspace can use this property to provide a pointer for the kernel tofill with a sync_file file descriptor, which will signal once thewriteback is finished. The value should be the address of a 32-bitsigned integer, cast to a u64.Userspace should wait for this fence to signal before making anothercommit affecting any of the same CRTCs, Planes or Connectors.Failure to do so will result in undefined behaviour.For this reason it is strongly recommended that all userspaceapplications making use of writeback connectorsalways retrieve anout-fence for the commit and use it appropriately.From userspace, this property will always read as zero.

intdrm_writeback_connector_init(structdrm_device * dev, structdrm_writeback_connector * wb_connector, const structdrm_connector_funcs * con_funcs, const structdrm_encoder_helper_funcs * enc_helper_funcs, const u32 * formats, int n_formats)¶: Initialize a writeback connector and its properties

Parameters

structdrm_device*dev: DRM device
structdrm_writeback_connector*wb_connector: Writeback connector to initialize
conststructdrm_connector_funcs*con_funcs: Connector funcs vtable
conststructdrm_encoder_helper_funcs*enc_helper_funcs: Encoder helper funcs vtable to be used by the internal encoder
constu32*formats: Array of supported pixel formats for the writeback engine
intn_formats: Length of the formats array

Description

This function creates the writeback-connector-specific properties if theyhave not been already created, initializes the connector astype DRM_MODE_CONNECTOR_WRITEBACK, and correctly initializes the propertyvalues. It will also create an internal encoder associated with thedrm_writeback_connector and set it to use theenc_helper_funcs vtable forthe encoder helper.

Drivers should always use this function instead ofdrm_connector_init() toset up writeback connectors.

Return

0 on success, or a negative error code

voiddrm_writeback_queue_job(structdrm_writeback_connector * wb_connector, structdrm_connector_state * conn_state)¶: Queue a writeback job for later signalling

Parameters

structdrm_writeback_connector*wb_connector: The writeback connector to queue a job on
structdrm_connector_state*conn_state: The connector state containing the job to queue

Description

This function adds the job contained inconn_state to the job_queue for awriteback connector. It takes ownership of the writeback job and sets theconn_state->writeback_job to NULL, and so no access to the job may beperformed by the caller after this function returns.

Drivers must ensure that for a given writeback connector, jobs are queued inexactly the same order as they will be completed by the hardware (andsignaled via drm_writeback_signal_completion).

For every call todrm_writeback_queue_job() there must be exactly one call todrm_writeback_signal_completion()

voiddrm_writeback_signal_completion(structdrm_writeback_connector * wb_connector, int status)¶: Signal the completion of a writeback job

Parameters

structdrm_writeback_connector*wb_connector: The writeback connector whose job is complete
intstatus: Status code to set in the writeback out_fence (0 for success)

Description

Drivers should call this to signal the completion of a previously queuedwriteback job. It should be called as soon as possible after the hardwarehas finished writing, and may be called from interrupt context.It is the driver’s responsibility to ensure that for a given connector, thehardware completes writeback jobs in the same order as they are queued.

Unless the driver is holding its own reference to the framebuffer, it mustnot be accessed after calling this function.

Encoder Abstraction¶

Encoders represent the connecting element between the CRTC (as the overallpixel pipeline, represented bystructdrm_crtc) and the connectors (as thegeneric sink entity, represented bystructdrm_connector). An encoder takespixel data from a CRTC and converts it to a format suitable for any attachedconnector. Encoders are objects exposed to userspace, originally to allowuserspace to infer cloning and connector/CRTC restrictions. Unfortunatelyalmost all drivers get this wrong, making the uabi pretty much useless. Ontop of that the exposed restrictions are too simple for today’s hardware, andthe recommended way to infer restrictions is by using theDRM_MODE_ATOMIC_TEST_ONLY flag for the atomic IOCTL.

Otherwise encoders aren’t used in the uapi at all (any modeset request fromuserspace directly connects a connector with a CRTC), drivers are thereforefree to use them however they wish. Modeset helper libraries make strong useof encoders to facilitate code sharing. But for more complex settings it isusually better to move shared code into a separatedrm_bridge. Compared toencoders, bridges also have the benefit of being purely an internalabstraction since they are not exposed to userspace at all.

Encoders are initialized withdrm_encoder_init() and cleaned up usingdrm_encoder_cleanup().

Encoder Functions Reference¶

structdrm_encoder_funcs¶: encoder controls

Definition

struct drm_encoder_funcs {  void (*reset)(struct drm_encoder *encoder);  void (*destroy)(struct drm_encoder *encoder);  int (*late_register)(struct drm_encoder *encoder);  void (*early_unregister)(struct drm_encoder *encoder);};

Members

reset

Reset encoder hardware and software state to off. This function isn’tcalled by the core directly, only throughdrm_mode_config_reset().It’s not a helper hook only for historical reasons.

destroy

Clean up encoder resources. This is only called at driver unload timethroughdrm_mode_config_cleanup() since an encoder cannot behotplugged in DRM.

late_register

This optional hook can be used to register additional userspaceinterfaces attached to the encoder like debugfs interfaces.It is called late in the driver load sequence fromdrm_dev_register().Everything added from this callback should be unregistered inthe early_unregister callback.

Returns:

0 on success, or a negative error code on failure.

early_unregister

This optional hook should be used to unregister the additionaluserspace interfaces attached to the encoder fromlate_register. It is called fromdrm_dev_unregister(),early in the driver unload sequence to disable userspace accessbefore data structures are torndown.

Description

Encoders sit between CRTCs and connectors.

structdrm_encoder¶: central DRM encoder structure

Definition

struct drm_encoder {  struct drm_device *dev;  struct list_head head;  struct drm_mode_object base;  char *name;  int encoder_type;  unsigned index;  uint32_t possible_crtcs;  uint32_t possible_clones;  struct drm_crtc *crtc;  struct list_head bridge_chain;  const struct drm_encoder_funcs *funcs;  const struct drm_encoder_helper_funcs *helper_private;};

Members

dev

parent DRM device

head

list management

base

base KMS object

name

human readable name, can be overwritten by the driver

encoder_type

One of the DRM_MODE_ENCODER_<foo> types in drm_mode.h. The followingencoder types are defined thus far:

DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A.
DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort.
DRM_MODE_ENCODER_LVDS for display panels, or in general any panelwith a proprietary parallel connector.
DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video,Component, SCART).
DRM_MODE_ENCODER_VIRTUAL for virtual machine displays
DRM_MODE_ENCODER_DSI for panels connected using the DSI serial bus.
DRM_MODE_ENCODER_DPI for panels connected using the DPI parallelbus.
DRM_MODE_ENCODER_DPMST for special fake encoders used to allowmutliple DP MST streams to share one physical encoder.

index

Position inside the mode_config.list, can be used as an arrayindex. It is invariant over the lifetime of the encoder.

possible_crtcs

Bitmask of potential CRTC bindings, usingdrm_crtc_index() as the index into the bitfield. The driver must setthe bits for alldrm_crtc objects this encoder can be connected tobefore callingdrm_dev_register().

You will get a WARN if you get this wrong in the driver.

Note that since CRTC objects can’t be hotplugged the assigned indicesare stable and hence known before registering all objects.

possible_clones

Bitmask of potential sibling encoders for cloning,usingdrm_encoder_index() as the index into the bitfield. The drivermust set the bits for alldrm_encoder objects which can clone adrm_crtc together with this encoder before callingdrm_dev_register(). Drivers should set the bit representing theencoder itself, too. Cloning bits should be set such that when twoencoders can be used in a cloned configuration, they both should haveeach another bits set.

As an exception to the above rule if the driver doesn’t implementany cloning it can leavepossible_clones set to 0. The core willautomagically fix this up by setting the bit for the encoder itself.

You will get a WARN if you get this wrong in the driver.

Note that since encoder objects can’t be hotplugged the assigned indicesare stable and hence known before registering all objects.

crtc

Currently bound CRTC, only really meaningful for non-atomicdrivers. Atomic drivers should instead checkdrm_connector_state.crtc.

bridge_chain

Bridges attached to this encoder. Drivers shall notaccess this field directly.

funcs

control functions

helper_private

mid-layer private data

Description

CRTCs drive pixels to encoders, which convert them into signalsappropriate for a given connector or set of connectors.

unsigned intdrm_encoder_index(const structdrm_encoder * encoder)¶: find the index of a registered encoder

Parameters

conststructdrm_encoder*encoder: encoder to find index for

Description

Given a registered encoder, return the index of that encoder within a DRMdevice’s list of encoders.

u32drm_encoder_mask(const structdrm_encoder * encoder)¶: find the mask of a registered encoder

Parameters

conststructdrm_encoder*encoder: encoder to find mask for

Description

Given a registered encoder, return the mask bit of that encoder for anencoder’s possible_clones field.

booldrm_encoder_crtc_ok(structdrm_encoder * encoder, structdrm_crtc * crtc)¶: can a given crtc drive a given encoder?

Parameters

structdrm_encoder*encoder: encoder to test
structdrm_crtc*crtc: crtc to test

Description

Returns false ifencoder can’t be driven bycrtc, true otherwise.

structdrm_encoder *drm_encoder_find(structdrm_device * dev, structdrm_file * file_priv, uint32_t id)¶: find adrm_encoder

Parameters

structdrm_device*dev: DRM device
structdrm_file*file_priv: drm file to check for lease against.
uint32_tid: encoder id

Description

Returns the encoder withid, NULL if it doesn’t exist. Simple wrapper arounddrm_mode_object_find().

drm_for_each_encoder_mask(encoder,dev,encoder_mask)¶: iterate over encoders specified by bitmask

Parameters

encoder: the loop cursor
dev: the DRM device
encoder_mask: bitmask of encoder indices

Description

Iterate over all encoders specified by bitmask.

drm_for_each_encoder(encoder,dev)¶: iterate over all encoders

Parameters

encoder: the loop cursor
dev: the DRM device

Description

Iterate over all encoders ofdev.

intdrm_encoder_init(structdrm_device * dev, structdrm_encoder * encoder, const structdrm_encoder_funcs * funcs, int encoder_type, const char * name, ...)¶: Init a preallocated encoder

Parameters

structdrm_device*dev: drm device
structdrm_encoder*encoder: the encoder to init
conststructdrm_encoder_funcs*funcs: callbacks for this encoder
intencoder_type: user visible type of the encoder
constchar*name: printf style format string for the encoder name, or NULL for default name
...: variable arguments

Description

Initialises a preallocated encoder. Encoder should be subclassed as part ofdriver encoder objects. At driver unload timedrm_encoder_cleanup() should becalled from the driver’sdrm_encoder_funcs.destroy hook.

Return

Zero on success, error code on failure.

voiddrm_encoder_cleanup(structdrm_encoder * encoder)¶: cleans up an initialised encoder

Parameters

structdrm_encoder*encoder: encoder to cleanup

Description

Cleans up the encoder but doesn’t free the object.

KMS Locking¶

As KMS moves toward more fine grained locking, and atomic ioctl whereuserspace can indirectly control locking order, it becomes necessaryto useww_mutex and acquire-contexts to avoid deadlocks. But becausethe locking is more distributed around the driver code, we want a bitof extra utility/tracking out of our acquire-ctx. This is providedbystructdrm_modeset_lock andstructdrm_modeset_acquire_ctx.

For basic principles ofww_mutex, see: Documentation/locking/ww-mutex-design.rst

The basic usage pattern is to:

drm_modeset_acquire_init(ctx, DRM_MODESET_ACQUIRE_INTERRUPTIBLE)retry:foreach (lock in random_ordered_set_of_locks) {    ret = drm_modeset_lock(lock, ctx)    if (ret == -EDEADLK) {        ret = drm_modeset_backoff(ctx);        if (!ret)            goto retry;    }    if (ret)        goto out;}... do stuff ...out:drm_modeset_drop_locks(ctx);drm_modeset_acquire_fini(ctx);

For convenience this control flow is implemented inDRM_MODESET_LOCK_ALL_BEGIN() andDRM_MODESET_LOCK_ALL_END() for the casewhere all modeset locks need to be taken throughdrm_modeset_lock_all_ctx().

If all that is needed is a single modeset lock, then thestructdrm_modeset_acquire_ctx is not needed and the locking can be simplifiedby passing a NULL instead of ctx in thedrm_modeset_lock() call orcallingdrm_modeset_lock_single_interruptible(). To unlock afterwardscalldrm_modeset_unlock().

On top of these per-object locks usingww_mutex there’s also an overalldrm_mode_config.mutex, for protecting everything else. Mostly this meansprobe state of connectors, and preventing hotplug add/removal of connectors.

Finally there’s a bunch of dedicated locks to protect drm core internallists and lookup data structures.

structdrm_modeset_acquire_ctx¶: locking context (see ww_acquire_ctx)

Definition

struct drm_modeset_acquire_ctx {  struct ww_acquire_ctx ww_ctx;  struct drm_modeset_lock *contended;  struct list_head locked;  bool trylock_only;  bool interruptible;};

Members

ww_ctx: base acquire ctx
contended: used internally for -EDEADLK handling
locked: list of held locks
trylock_only: trylock mode used in atomic contexts/panic notifiers
interruptible: whether interruptible locking should be used.

Description

Each thread competing for a set of locks must use one acquirectx. And if any lock fxn returns -EDEADLK, it must backoff andretry.

structdrm_modeset_lock¶: used for locking modeset resources.

Definition

struct drm_modeset_lock {  struct ww_mutex mutex;  struct list_head head;};

Members

mutex: resource locking
head: used to hold its place ondrm_atomi_state.locked list whenpart of an atomic update

Description

Used for locking CRTCs and other modeset resources.

voiddrm_modeset_lock_fini(structdrm_modeset_lock * lock)¶: cleanup lock

Parameters

structdrm_modeset_lock*lock: lock to cleanup

booldrm_modeset_is_locked(structdrm_modeset_lock * lock)¶: equivalent tomutex_is_locked()

Parameters

structdrm_modeset_lock*lock: lock to check

voiddrm_modeset_lock_assert_held(structdrm_modeset_lock * lock)¶: equivalent to lockdep_assert_held()

Parameters

structdrm_modeset_lock*lock: lock to check

DRM_MODESET_LOCK_ALL_BEGIN(dev,ctx,flags,ret)¶: Helper to acquire modeset locks

Parameters

dev: drm device
ctx: local modeset acquire context, will be dereferenced
flags: DRM_MODESET_ACQUIRE_* flags to pass todrm_modeset_acquire_init()
ret: local ret/err/etc variable to track error status

Description

Use these macros to simplify grabbing all modeset locks using a localcontext. This has the advantage of reducing boilerplate, but also properlychecking return values where appropriate.

Any code run between BEGIN and END will be holding the modeset locks.

This must be paired withDRM_MODESET_LOCK_ALL_END(). We will jump back andforth between the labels on deadlock and error conditions.

Drivers can acquire additional modeset locks. If any lock acquisitionfails, the control flow needs to jump toDRM_MODESET_LOCK_ALL_END() withtheret parameter containing the return value ofdrm_modeset_lock().

Return

The only possible value of ret immediately afterDRM_MODESET_LOCK_ALL_BEGIN()is 0, so no error checking is necessary

DRM_MODESET_LOCK_ALL_END(dev,ctx,ret)¶: Helper to release and cleanup modeset locks

Parameters

dev: drm device
ctx: local modeset acquire context, will be dereferenced
ret: local ret/err/etc variable to track error status

Description

The other side ofDRM_MODESET_LOCK_ALL_BEGIN(). It will bounce back to BEGINif ret is -EDEADLK.

It’s important that you use the same ret variable for begin and end sodeadlock conditions are properly handled.

Return

ret will be untouched unless it is -EDEADLK on entry. That means that if yousuccessfully acquire the locks, ret will be whatever your code sets it to. Ifthere is a deadlock or other failure with acquire or backoff, ret will be setto that failure. In both of these cases the code between BEGIN/END will notbe run, so the failure will reflect the inability to grab the locks.

voiddrm_modeset_lock_all(structdrm_device * dev)¶: take all modeset locks

Parameters

structdrm_device*dev: DRM device

Description

This function takes all modeset locks, suitable where a more fine-grainedscheme isn’t (yet) implemented. Locks must be dropped by calling thedrm_modeset_unlock_all() function.

This function is deprecated. It allocates a lock acquisition context andstores it indrm_device.mode_config. This facilitate conversion ofexisting code because it removes the need to manually deal with theacquisition context, but it is also brittle because the context is globaland care must be taken not to nest calls. New code should use thedrm_modeset_lock_all_ctx() function and pass in the context explicitly.

voiddrm_modeset_unlock_all(structdrm_device * dev)¶: drop all modeset locks

Parameters

structdrm_device*dev: DRM device

Description

This function drops all modeset locks taken by a previous call to thedrm_modeset_lock_all() function.

This function is deprecated. It uses the lock acquisition context storedindrm_device.mode_config. This facilitates conversion of existingcode because it removes the need to manually deal with the acquisitioncontext, but it is also brittle because the context is global and care mustbe taken not to nest calls. New code should pass the acquisition contextdirectly to thedrm_modeset_drop_locks() function.

voiddrm_warn_on_modeset_not_all_locked(structdrm_device * dev)¶: check that all modeset locks are locked

Parameters

structdrm_device*dev: device

Description

Useful as a debug assert.

voiddrm_modeset_acquire_init(structdrm_modeset_acquire_ctx * ctx, uint32_t flags)¶: initialize acquire context

Parameters

structdrm_modeset_acquire_ctx*ctx: the acquire context
uint32_tflags: 0 orDRM_MODESET_ACQUIRE_INTERRUPTIBLE

Description

When passingDRM_MODESET_ACQUIRE_INTERRUPTIBLE toflags,all calls todrm_modeset_lock() will perform an interruptiblewait.

voiddrm_modeset_acquire_fini(structdrm_modeset_acquire_ctx * ctx)¶: cleanup acquire context

Parameters

structdrm_modeset_acquire_ctx*ctx: the acquire context

voiddrm_modeset_drop_locks(structdrm_modeset_acquire_ctx * ctx)¶: drop all locks

Parameters

structdrm_modeset_acquire_ctx*ctx: the acquire context

Description

Drop all locks currently held against this acquire context.

intdrm_modeset_backoff(structdrm_modeset_acquire_ctx * ctx)¶: deadlock avoidance backoff

Parameters

structdrm_modeset_acquire_ctx*ctx: the acquire context

Description

If deadlock is detected (ie.drm_modeset_lock() returns -EDEADLK),you must call this function to drop all currently held locks andblock until the contended lock becomes available.

This function returns 0 on success, or -ERESTARTSYS if this contextis initialized withDRM_MODESET_ACQUIRE_INTERRUPTIBLE and thewait has been interrupted.

voiddrm_modeset_lock_init(structdrm_modeset_lock * lock)¶: initialize lock

Parameters

structdrm_modeset_lock*lock: lock to init

intdrm_modeset_lock(structdrm_modeset_lock * lock, structdrm_modeset_acquire_ctx * ctx): take modeset lock

Parameters

structdrm_modeset_lock*lock: lock to take
structdrm_modeset_acquire_ctx*ctx: acquire ctx

Description

Ifctx is not NULL, then its ww acquire context is used and thelock will be tracked by the context and can be released by callingdrm_modeset_drop_locks(). If -EDEADLK is returned, this means adeadlock scenario has been detected and it is an error to attemptto take any more locks without first callingdrm_modeset_backoff().

If thectx is not NULL and initialized withDRM_MODESET_ACQUIRE_INTERRUPTIBLE, this function will fail with-ERESTARTSYS when interrupted.

Ifctx is NULL then the function call behaves like a normal,uninterruptible non-nestingmutex_lock() call.

intdrm_modeset_lock_single_interruptible(structdrm_modeset_lock * lock)¶: take a single modeset lock

Parameters

structdrm_modeset_lock*lock: lock to take

Description

This function behaves asdrm_modeset_lock() with a NULL context,but performs interruptible waits.

This function returns 0 on success, or -ERESTARTSYS when interrupted.

voiddrm_modeset_unlock(structdrm_modeset_lock * lock)¶: drop modeset lock

Parameters

structdrm_modeset_lock*lock: lock to release

intdrm_modeset_lock_all_ctx(structdrm_device * dev, structdrm_modeset_acquire_ctx * ctx)¶: take all modeset locks

Parameters

structdrm_device*dev: DRM device
structdrm_modeset_acquire_ctx*ctx: lock acquisition context

Description

This function takes all modeset locks, suitable where a more fine-grainedscheme isn’t (yet) implemented.

Unlikedrm_modeset_lock_all(), it doesn’t take thedrm_mode_config.mutexsince that lock isn’t required for modeset state changes. Callers whichneed to grab that lock too need to do so outside of the acquire contextctx.

Locks acquired with this function should be released by calling thedrm_modeset_drop_locks() function onctx.

Return

0 on success or a negative error-code on failure.

KMS Properties¶

Property Types and Blob Property Support¶

Properties as represented bydrm_property are used to extend the modesetinterface exposed to userspace. For the atomic modeset IOCTL properties areeven the only way to transport metadata about the desired new modesetconfiguration from userspace to the kernel. Properties have a well-definedvalue range, which is enforced by the drm core. See the documentation of theflags member ofstructdrm_property for an overview of the differentproperty types and ranges.

Properties don’t store the current value directly, but need to beinstatiated by attaching them to adrm_mode_object withdrm_object_attach_property().

Property values are only 64bit. To support bigger piles of data (like gammatables, color correction matrices or large structures) a property can insteadpoint at adrm_property_blob with that additional data.

Properties are defined by their symbolic name, userspace must keep aper-object mapping from those names to the property ID used in the atomicIOCTL and in the get/set property IOCTL.

structdrm_property_enum¶: symbolic values for enumerations

Definition

struct drm_property_enum {  uint64_t value;  struct list_head head;  char name[DRM_PROP_NAME_LEN];};

Members

value: numeric property value for this enum entry
head: list of enum values, linked todrm_property.enum_list
name: symbolic name for the enum

Description

For enumeration and bitmask properties this structure stores the symbolicdecoding for each value. This is used for example for the rotation property.

structdrm_property¶: modeset object property

Definition

struct drm_property {  struct list_head head;  struct drm_mode_object base;  uint32_t flags;  char name[DRM_PROP_NAME_LEN];  uint32_t num_values;  uint64_t *values;  struct drm_device *dev;  struct list_head enum_list;};

Members

head

per-device list of properties, for cleanup.

base

base KMS object

flags

Property flags and type. A property needs to be one of the followingtypes:

DRM_MODE_PROP_RANGE

Range properties report their minimum and maximum admissible unsigned values.The KMS core verifies that values set by application fit in thatrange. The range is unsigned. Range properties are created usingdrm_property_create_range().

DRM_MODE_PROP_SIGNED_RANGE

Range properties report their minimum and maximum admissible unsigned values.The KMS core verifies that values set by application fit in thatrange. The range is signed. Range properties are created usingdrm_property_create_signed_range().

DRM_MODE_PROP_ENUM

Enumerated properties take a numerical value that ranges from 0 tothe number of enumerated values defined by the property minus one,and associate a free-formed string name to each value. Applicationscan retrieve the list of defined value-name pairs and use thenumerical value to get and set property instance values. Enumproperties are created usingdrm_property_create_enum().

DRM_MODE_PROP_BITMASK

Bitmask properties are enumeration properties that additionallyrestrict all enumerated values to the 0..63 range. Bitmask propertyinstance values combine one or more of the enumerated bits definedby the property. Bitmask properties are created usingdrm_property_create_bitmask().

DRM_MODE_PROB_OBJECT

Object properties are used to link modeset objects. This is usedextensively in the atomic support to create the display pipeline,by linkingdrm_framebuffer todrm_plane,drm_plane todrm_crtc anddrm_connector todrm_crtc. An object property canonly link to a specific type ofdrm_mode_object, this limit isenforced by the core. Object properties are created usingdrm_property_create_object().

Object properties work like blob properties, but in a moregeneral fashion. They are limited to atomic drivers and must havethe DRM_MODE_PROP_ATOMIC flag set.

DRM_MODE_PROP_BLOB

Blob properties store a binary blob without any format restriction.The binary blobs are created as KMS standalone objects, and blobproperty instance values store the ID of their associated blobobject. Blob properties are created by callingdrm_property_create() with DRM_MODE_PROP_BLOB as the type.

Actual blob objects to contain blob data are created usingdrm_property_create_blob(), or through the corresponding IOCTL.

Besides the built-in limit to only accept blob objects blobproperties work exactly like object properties. The only reasonsblob properties exist is backwards compatibility with existinguserspace.

In addition a property can have any combination of the below flags:

DRM_MODE_PROP_ATOMIC: Set for properties which encode atomic modeset state. Suchproperties are not exposed to legacy userspace.
DRM_MODE_PROP_IMMUTABLE: Set for properties whose values cannot be changed byuserspace. The kernel is allowed to update the value of theseproperties. This is generally used to expose probe state touserspace, e.g. the EDID, or the connector path property on DPMST sinks. Kernel can update the value of an immutable propertyby callingdrm_object_property_set_value().

name

symbolic name of the properties

num_values

size of thevalues array.

values

Array with limits and values for the property. Theinterpretation of these limits is dependent upon the type perflags.

dev

DRM device

enum_list

List ofdrm_prop_enum_list structures with the symbolic names forenum and bitmask values.

Description

This structure represent a modeset object property. It combines both the nameof the property with the set of permissible values. This means that when adriver wants to use a property with the same name on different objects, butwith different value ranges, then it must create property for each one. Anexample would be rotation ofdrm_plane, when e.g. the primary plane cannotbe rotated. But if both the name and the value range match, then the sameproperty structure can be instantiated multiple times for the same object.Userspace must be able to cope with this and cannot assume that the samesymbolic property will have the same modeset object ID on all modesetobjects.

Properties are created by one of the special functions, as explained indetail in theflags structure member.

To actually expose a property it must be attached to each object usingdrm_object_attach_property(). Currently properties can only be attached todrm_connector,drm_crtc anddrm_plane.

Properties are also used as the generic metadatatransport for the atomicIOCTL. Everything that was set directly in structures in the legacy modesetIOCTLs (like the plane source or destination windows, or e.g. the links tothe CRTC) is exposed as a property with the DRM_MODE_PROP_ATOMIC flag set.

structdrm_property_blob¶: Blob data fordrm_property

Definition

struct drm_property_blob {  struct drm_mode_object base;  struct drm_device *dev;  struct list_head head_global;  struct list_head head_file;  size_t length;  void *data;};

Members

base: base KMS object
dev: DRM device
head_global: entry on the global blob list indrm_mode_config.property_blob_list.
head_file: entry on the per-file blob list indrm_file.blobs list.
length: size of the blob in bytes, invariant over the lifetime of the object
data: actual data, embedded at the end of this structure

Description

Blobs are used to store bigger values than what fits directly into the 64bits available for adrm_property.

Blobs are reference counted usingdrm_property_blob_get() anddrm_property_blob_put(). They are created usingdrm_property_create_blob().

booldrm_property_type_is(structdrm_property * property, uint32_t type)¶: check the type of a property

Parameters

structdrm_property*property: property to check
uint32_ttype: property type to compare with

Description

This is a helper function becauase the uapi encoding of property types isa bit special for historical reasons.

structdrm_property *drm_property_find(structdrm_device * dev, structdrm_file * file_priv, uint32_t id)¶: find property object

Parameters

structdrm_device*dev: DRM device
structdrm_file*file_priv: drm file to check for lease against.
uint32_tid: property object id

Description

This function looks up the property object specified by id and returns it.

structdrm_property *drm_property_create(structdrm_device * dev, u32 flags, const char * name, int num_values)¶: create a new property type

Parameters

structdrm_device*dev: drm device
u32flags: flags specifying the property type
constchar*name: name of the property
intnum_values: number of pre-defined values

Description

This creates a new generic drm property which can then be attached to a drmobject withdrm_object_attach_property(). The returned property object mustbe freed withdrm_property_destroy(), which is done automatically whencallingdrm_mode_config_cleanup().

Return

A pointer to the newly created property on success, NULL on failure.

structdrm_property *drm_property_create_enum(structdrm_device * dev, u32 flags, const char * name, const struct drm_prop_enum_list * props, int num_values)¶: create a new enumeration property type

Parameters

structdrm_device*dev: drm device
u32flags: flags specifying the property type
constchar*name: name of the property
conststructdrm_prop_enum_list*props: enumeration lists with property values
intnum_values: number of pre-defined values

Description

Userspace is only allowed to set one of the predefined values for enumerationproperties.

Return

A pointer to the newly created property on success, NULL on failure.

structdrm_property *drm_property_create_bitmask(structdrm_device * dev, u32 flags, const char * name, const struct drm_prop_enum_list * props, int num_props, uint64_t supported_bits)¶: create a new bitmask property type

Parameters

structdrm_device*dev: drm device
u32flags: flags specifying the property type
constchar*name: name of the property
conststructdrm_prop_enum_list*props: enumeration lists with property bitflags
intnum_props: size of theprops array
uint64_tsupported_bits: bitmask of all supported enumeration values

Description

This creates a new bitmask drm property which can then be attached to a drmobject withdrm_object_attach_property(). The returned property object mustbe freed withdrm_property_destroy(), which is done automatically whencallingdrm_mode_config_cleanup().

Compared to plain enumeration properties userspace is allowed to set anyor’ed together combination of the predefined property bitflag values

Return

A pointer to the newly created property on success, NULL on failure.

structdrm_property *drm_property_create_range(structdrm_device * dev, u32 flags, const char * name, uint64_t min, uint64_t max)¶: create a new unsigned ranged property type

Parameters

structdrm_device*dev: drm device
u32flags: flags specifying the property type
constchar*name: name of the property
uint64_tmin: minimum value of the property
uint64_tmax: maximum value of the property

Description

Userspace is allowed to set any unsigned integer value in the (min, max)range inclusive.

Return

A pointer to the newly created property on success, NULL on failure.

structdrm_property *drm_property_create_signed_range(structdrm_device * dev, u32 flags, const char * name, int64_t min, int64_t max)¶: create a new signed ranged property type

Parameters

structdrm_device*dev: drm device
u32flags: flags specifying the property type
constchar*name: name of the property
int64_tmin: minimum value of the property
int64_tmax: maximum value of the property

Description

Userspace is allowed to set any signed integer value in the (min, max)range inclusive.

Return

A pointer to the newly created property on success, NULL on failure.

structdrm_property *drm_property_create_object(structdrm_device * dev, u32 flags, const char * name, uint32_t type)¶: create a new object property type

Parameters

structdrm_device*dev: drm device
u32flags: flags specifying the property type
constchar*name: name of the property
uint32_ttype: object type from DRM_MODE_OBJECT_* defines

Description

Userspace is only allowed to set this to any property value of the giventype. Only useful for atomic properties, which is enforced.

Return

A pointer to the newly created property on success, NULL on failure.

structdrm_property *drm_property_create_bool(structdrm_device * dev, u32 flags, const char * name)¶: create a new boolean property type

Parameters

structdrm_device*dev: drm device
u32flags: flags specifying the property type
constchar*name: name of the property

Description

This is implemented as a ranged property with only {0, 1} as valid values.

Return

A pointer to the newly created property on success, NULL on failure.

intdrm_property_add_enum(structdrm_property * property, uint64_t value, const char * name)¶: add a possible value to an enumeration property

Parameters

structdrm_property*property: enumeration property to change
uint64_tvalue: value of the new enumeration
constchar*name: symbolic name of the new enumeration

Description

This functions adds enumerations to a property.

It’s use is deprecated, drivers should use one of the more specific helpersto directly create the property with all enumerations already attached.

Return

Zero on success, error code on failure.

voiddrm_property_destroy(structdrm_device * dev, structdrm_property * property)¶: destroy a drm property

Parameters

structdrm_device*dev: drm device
structdrm_property*property: property to destry

Description

This function frees a property including any attached resources likeenumeration values.

structdrm_property_blob *drm_property_create_blob(structdrm_device * dev, size_t length, const void * data)¶: Create new blob property

Parameters

structdrm_device*dev: DRM device to create property for
size_tlength: Length to allocate for blob data
constvoid*data: If specified, copies data into blob

Description

Creates a new blob property for a specified DRM device, optionallycopying data. Note that blob properties are meant to be invariant, hence thedata must be filled out before the blob is used as the value of any property.

Return

New blob property with a single reference on success, or an ERR_PTRvalue on failure.

voiddrm_property_blob_put(structdrm_property_blob * blob)¶: release a blob property reference

Parameters

structdrm_property_blob*blob: DRM blob property

Description

Releases a reference to a blob property. May free the object.

structdrm_property_blob *drm_property_blob_get(structdrm_property_blob * blob)¶: acquire blob property reference

Parameters

structdrm_property_blob*blob: DRM blob property

Description

Acquires a reference to an existing blob property. Returnsblob, whichallows this to be used as a shorthand in assignments.

structdrm_property_blob *drm_property_lookup_blob(structdrm_device * dev, uint32_t id)¶: look up a blob property and take a reference

Parameters

structdrm_device*dev: drm device
uint32_tid: id of the blob property

Description

If successful, this takes an additional reference to the blob property.callers need to make sure to eventually unreference the returned propertyagain, usingdrm_property_blob_put().

Return

NULL on failure, pointer to the blob on success.

intdrm_property_replace_global_blob(structdrm_device * dev, structdrm_property_blob ** replace, size_t length, const void * data, structdrm_mode_object * obj_holds_id, structdrm_property * prop_holds_id)¶: replace existing blob property

Parameters

structdrm_device*dev: drm device
structdrm_property_blob**replace: location of blob property pointer to be replaced
size_tlength: length of data for new blob, or 0 for no data
constvoid*data: content for new blob, or NULL for no data
structdrm_mode_object*obj_holds_id: optional object for property holding blob ID
structdrm_property*prop_holds_id: optional property holding blob IDreturn 0 on success or error on failure

Description

This function will replace a global property in the blob list, optionallyupdating a property which holds the ID of that property.

If length is 0 or data is NULL, no new blob will be created, and the holdingproperty, if specified, will be set to 0.

Access to the replace pointer is assumed to be protected by the caller, e.g.by holding the relevant modesetting object lock for its parent.

For example, a drm_connector has a ‘PATH’ property, which contains the IDof a blob property with the value of the MST path information. Calling thisfunction with replace pointing to the connector’s path_blob_ptr, length anddata set for the new path information, obj_holds_id set to the connector’sbase object, and prop_holds_id set to the path property name, will performa completely atomic update. The access to path_blob_ptr is protected by thecaller holding a lock on the connector.

booldrm_property_replace_blob(structdrm_property_blob ** blob, structdrm_property_blob * new_blob)¶: replace a blob property

Parameters

structdrm_property_blob**blob: a pointer to the member blob to be replaced
structdrm_property_blob*new_blob: the new blob to replace with

Return

true if the blob was in fact replaced.

Standard Connector Properties¶

DRM connectors have a few standardized properties:

EDID:

Blob property which contains the current EDID read from the sink. Thisis useful to parse sink identification information like vendor, modeland serial. Drivers should update this property by callingdrm_connector_update_edid_property(), usually after having parsedthe EDID usingdrm_add_edid_modes(). Userspace cannot change thisproperty.

DPMS:

Legacy property for setting the power state of the connector. For atomicdrivers this is only provided for backwards compatibility with existingdrivers, it remaps to controlling the “ACTIVE” property on the CRTC theconnector is linked to. Drivers should never set this property directly,it is handled by the DRM core by calling thedrm_connector_funcs.dpmscallback. For atomic drivers the remapping to the “ACTIVE” property isimplemented in the DRM core.

Note that this property cannot be set through the MODE_ATOMIC ioctl,userspace must use “ACTIVE” on the CRTC instead.

WARNING:

For userspace also running on legacy drivers the “DPMS” semantics are alot more complicated. First, userspace cannot rely on the “DPMS” valuereturned by the GETCONNECTOR actually reflecting reality, because manydrivers fail to update it. For atomic drivers this is taken care of indrm_atomic_helper_update_legacy_modeset_state().

The second issue is that the DPMS state is only well-defined when theconnector is connected to a CRTC. In atomic the DRM core enforces that“ACTIVE” is off in such a case, no such checks exists for “DPMS”.

Finally, when enabling an output using the legacy SETCONFIG ioctl then“DPMS” is forced to ON. But see above, that might not be reflected inthe software value on legacy drivers.

Summarizing: Only set “DPMS” when the connector is known to be enabled,assume that a successful SETCONFIG call also sets “DPMS” to on, andnever read back the value of “DPMS” because it can be incorrect.

PATH:

Connector path property to identify how this sink is physicallyconnected. Used by DP MST. This should be set by callingdrm_connector_set_path_property(), in the case of DP MST with thepath property the MST manager created. Userspace cannot change thisproperty.

TILE:

Connector tile group property to indicate how a set of DRM connectorcompose together into one logical screen. This is used by both high-resexternal screens (often only using a single cable, but exposing multipleDP MST sinks), or high-res integrated panels (like dual-link DSI) whichare not gen-locked. Note that for tiled panels which are genlocked, likedual-link LVDS or dual-link DSI, the driver should try to not expose thetiling and virtualise bothdrm_crtc anddrm_plane if needed. Driversshould update this value usingdrm_connector_set_tile_property().Userspace cannot change this property.

link-status:

Connector link-status property to indicate the status of link. Thedefault value of link-status is “GOOD”. If something fails during orafter modeset, the kernel driver may set this to “BAD” and issue ahotplug uevent. Drivers should update this value usingdrm_connector_set_link_status_property().

When user-space receives the hotplug uevent and detects a “BAD”link-status, the sink doesn’t receive pixels anymore (e.g. the screenbecomes completely black). The list of available modes may havechanged. User-space is expected to pick a new mode if the current onehas disappeared and perform a new modeset with link-status set to“GOOD” to re-enable the connector.

If multiple connectors share the same CRTC and one of them gets a “BAD”link-status, the other are unaffected (ie. the sinks still continue toreceive pixels).

When user-space performs an atomic commit on a connector with a “BAD”link-status without resetting the property to “GOOD”, the sink maystill not receive pixels. When user-space performs an atomic commitwhich resets the link-status property to “GOOD” without theALLOW_MODESET flag set, it might fail because a modeset is required.

User-space can only change link-status to “GOOD”, changing it to “BAD”is a no-op.

For backwards compatibility with non-atomic userspace the kerneltries to automatically set the link-status back to “GOOD” in theSETCRTC IOCTL. This might fail if the mode is no longer valid, similarto how it might fail if a different screen has been connected in theinterim.

non_desktop:

Indicates the output should be ignored for purposes of displaying astandard desktop environment or console. This is most likely becausethe output device is not rectilinear.

Content Protection:

This property is used by userspace to request the kernel protect futurecontent communicated over the link. When requested, kernel will applythe appropriate means of protection (most often HDCP), and use theproperty to tell userspace the protection is active.

Drivers can set this up by callingdrm_connector_attach_content_protection_property() on initialization.

The value of this property can be one of the following:

DRM_MODE_CONTENT_PROTECTION_UNDESIRED = 0: The link is not protected, content is transmitted in the clear.
DRM_MODE_CONTENT_PROTECTION_DESIRED = 1: Userspace has requested content protection, but the link is notcurrently protected. When in this state, kernel should enableContent Protection as soon as possible.
DRM_MODE_CONTENT_PROTECTION_ENABLED = 2: Userspace has requested content protection, and the link isprotected. Only the driver can set the property to this value.If userspace attempts to set to ENABLED, kernel will return-EINVAL.

A few guidelines:

DESIRED state should be preserved until userspace de-asserts it bysetting the property to UNDESIRED. This means ENABLED should onlytransition to UNDESIRED when the user explicitly requests it.
If the state is DESIRED, kernel should attempt to re-authenticate thelink whenever possible. This includes across disable/enable, dpms,hotplug, downstream device changes, link status failures, etc..
Kernel sends uevent with the connector id and property id throughdrm_hdcp_update_content_protection, upon below kernel triggeredscenarios:
- DESIRED -> ENABLED (authentication success)
- ENABLED -> DESIRED (termination of authentication)
Please note no uevents for userspace triggered property state changes,which can’t fail such as
- DESIRED/ENABLED -> UNDESIRED
- UNDESIRED -> DESIRED
Userspace is responsible for polling the property or listen to ueventsto determine when the value transitions from ENABLED to DESIRED.This signifies the link is no longer protected and userspace shouldtake appropriate action (whatever that might be).

HDCP Content Type:

This Enum property is used by the userspace to declare the content typeof the display stream, to kernel. Here display stream stands for anydisplay content that userspace intended to display through HDCPencryption.

Content Type of a stream is decided by the owner of the stream, as“HDCP Type0” or “HDCP Type1”.

The value of the property can be one of the below:

“HDCP Type0”: DRM_MODE_HDCP_CONTENT_TYPE0 = 0
“HDCP Type1”: DRM_MODE_HDCP_CONTENT_TYPE1 = 1

When kernel starts the HDCP authentication (see “Content Protection”for details), it uses the content type in “HDCP Content Type”for performing the HDCP authentication with the display sink.

Please note in HDCP spec versions, a link can be authenticated withHDCP 2.2 for Content Type 0/Content Type 1. Where as a link can beauthenticated with HDCP1.4 only for Content Type 0(though it is implicitin nature. As there is no reference for Content Type in HDCP1.4).

HDCP2.2 authentication protocol itself takes the “Content Type” as aparameter, which is a input for the DP HDCP2.2 encryption algo.

In case of Type 0 content protection request, kernel driver can chooseeither of HDCP spec versions 1.4 and 2.2. When HDCP2.2 is used for“HDCP Type 0”, a HDCP 2.2 capable repeater in the downstream can sendthat content to a HDCP 1.4 authenticated HDCP sink (Type0 link).But if the content is classified as “HDCP Type 1”, above mentionedHDCP 2.2 repeater wont send the content to the HDCP sink as it can’tauthenticate the HDCP1.4 capable sink for “HDCP Type 1”.

Please note userspace can be ignorant of the HDCP versions used by thekernel driver to achieve the “HDCP Content Type”.

At current scenario, classifying a content as Type 1 ensures that thecontent will be displayed only through the HDCP2.2 encrypted link.

Note that the HDCP Content Type property is introduced at HDCP 2.2, anddefaults to type 0. It is only exposed by drivers supporting HDCP 2.2(hence supporting Type 0 and Type 1). Based on how next versions ofHDCP specs are defined content Type could be used for higher versionstoo.

If content type is changed when “Content Protection” is not UNDESIRED,then kernel will disable the HDCP and re-enable with new type in thesame atomic commit. And when “Content Protection” is ENABLED, it meansthat link is HDCP authenticated and encrypted, for the transmission ofthe Type of stream mentioned at “HDCP Content Type”.

HDR_OUTPUT_METADATA:

Connector property to enable userspace to send HDR Metadata todriver. This metadata is based on the composition and blendingpolicies decided by user, taking into account the hardware andsink capabilities. The driver gets this metadata and creates aDynamic Range and Mastering Infoframe (DRM) in case of HDMI,SDP packet (Non-audio INFOFRAME SDP v1.3) for DP. This is thensent to sink. This notifies the sink of the upcoming frame’s ColorEncoding and Luminance parameters.

Userspace first need to detect the HDR capabilities of sink byreading and parsing the EDID. Details of HDR metadata for HDMIare added in CTA 861.G spec. For DP , its defined in VESA DPStandard v1.4. It needs to then get the metadata informationof the video/game/app content which are encoded in HDR (basicallyusing HDR transfer functions). With this information it needs todecide on a blending policy and compose the relevantlayers/overlays into a common format. Once this blending is done,userspace will be aware of the metadata of the composed frame tobe send to sink. It then uses this property to communicate thismetadata to driver which then make a Infoframe packet and sendsto sink based on the type of encoder connected.

Userspace will be responsible to do Tone mapping operation in case:

Some layers are HDR and others are SDR
HDR layers luminance is not same as sink

It will even need to do colorspace conversion and get all layersto one common colorspace for blending. It can use either GL, Mediaor display engine to get this done based on the capabilities of theassociated hardware.

Driver expects metadata to be put instructhdr_output_metadatastructure from userspace. This is received as blob and stored indrm_connector_state.hdr_output_metadata. It parses EDID and saves thesink metadata instructhdr_sink_metadata, asdrm_connector.hdr_sink_metadata. Driver usesdrm_hdmi_infoframe_set_hdr_metadata() helper to set the HDR metadata,hdmi_drm_infoframe_pack() to pack the infoframe as per spec, in case ofHDMI encoder.

max bpc:

This range property is used by userspace to limit the bit depth. Whenused the driver would limit the bpc in accordance with the valid rangesupported by the hardware and sink. Drivers to use the functiondrm_connector_attach_max_bpc_property() to create and attach theproperty to the connector during initialization.

Connectors also have one standardized atomic property:

CRTC_ID:: Mode object ID of thedrm_crtc this connector should be connected to.

Connectors for LCD panels may also have one standardized property:

panel orientation:

On some devices the LCD panel is mounted in the casing in such a waythat the up/top side of the panel does not match with the top side ofthe device. Userspace can use this property to check for this.Note that input coordinates from touchscreens (input devices withINPUT_PROP_DIRECT) will still map 1:1 to the actual LCD panelcoordinates, so if userspace rotates the picture to adjust forthe orientation it must also apply the same transformation to thetouchscreen input coordinates. This property is initialized by callingdrm_connector_set_panel_orientation() ordrm_connector_set_panel_orientation_with_quirk()

scaling mode:

This property defines how a non-native mode is upscaled to the nativemode of an LCD panel:

None:: No upscaling happens, scaling is left to the panel. Not alldrivers expose this mode.
Full:: The output is upscaled to the full resolution of the panel,ignoring the aspect ratio.
Center:: No upscaling happens, the output is centered within the nativeresolution the panel.
Full aspect:: The output is upscaled to maximize either the width or heightwhile retaining the aspect ratio.

This property should be set up by callingdrm_connector_attach_scaling_mode_property(). Note that driverscan also expose this property to external outputs, in which case theymust support “None”, which should be the default (since external screenshave a built-in scaler).

Colorspace:

This property helps select a suitable colorspace based on the sinkcapability. Modern sink devices support wider gamut like BT2020.This helps switch to BT2020 mode if the BT2020 encoded video streamis being played by the user, same for any other colorspace. Therebygiving a good visual experience to users.

The expectation from userspace is that it should parse the EDIDand get supported colorspaces. Use this property and switch to theone supported. Sink supported colorspaces should be retrieved byuserspace from EDID and driver will not explicitly expose them.

Basically the expectation from userspace is:

Set up CRTC DEGAMMA/CTM/GAMMA to convert to some sinkcolorspace
Set this new property to let the sink know what itconverted the CRTC output to.
This property is just to inform sink what colorspacesource is trying to drive.

Because between HDMI and DP have different colorspaces,drm_mode_create_hdmi_colorspace_property() is used for HDMI connector anddrm_mode_create_dp_colorspace_property() is used for DP connector.

HDMI Specific Connector Properties¶

content type (HDMI specific):

Indicates content type setting to be used in HDMI infoframes to indicatecontent type for the external device, so that it adjusts its displaysettings accordingly.

The value of this property can be one of the following:

No Data:: Content type is unknown
Graphics:: Content type is graphics
Photo:: Content type is photo
Cinema:: Content type is cinema
Game:: Content type is game

Drivers can set up this property by callingdrm_connector_attach_content_type_property(). Decoding toinfoframe values is done throughdrm_hdmi_avi_infoframe_content_type().

Standard CRTC Properties¶

DRM CRTCs have a few standardized properties:

ACTIVE:

Atomic property for setting the power state of the CRTC. When set to 1the CRTC will actively display content. When set to 0 the CRTC will bepowered off. There is no expectation that user-space will reset CRTCresources like the mode and planes when setting ACTIVE to 0.

User-space can rely on an ACTIVE change to 1 to never fail an atomictest as long as no other property has changed. If a change to ACTIVEfails an atomic test, this is a driver bug. For this reason settingACTIVE to 0 must not release internal resources (like reserved memorybandwidth or clock generators).

Note that the legacy DPMS property on connectors is internally routedto control this property for atomic drivers.

MODE_ID:

Atomic property for setting the CRTC display timings. The value is theID of a blob containing the DRM mode info. To disable the CRTC,user-space must set this property to 0.

Setting MODE_ID to 0 will release reserved resources for the CRTC.

Plane Composition Properties¶

The basic plane composition model supported by standard plane properties onlyhas a source rectangle (in logical pixels within thedrm_framebuffer), withsub-pixel accuracy, which is scaled up to a pixel-aligned destinationrectangle in the visible area of adrm_crtc. The visible area of a CRTC isdefined by the horizontal and vertical visible pixels (stored inhdisplayandvdisplay) of the requested mode (stored indrm_crtc_state.mode). Thesetwo rectangles are both stored in thedrm_plane_state.

For the atomic ioctl the following standard (atomic) properties on the plane objectencode the basic plane composition model:

SRC_X:: X coordinate offset for the source rectangle within thedrm_framebuffer, in 16.16 fixed point. Must be positive.
SRC_Y:: Y coordinate offset for the source rectangle within thedrm_framebuffer, in 16.16 fixed point. Must be positive.
SRC_W:: Width for the source rectangle within thedrm_framebuffer, in 16.16fixed point. SRC_X plus SRC_W must be within the width of the sourceframebuffer. Must be positive.
SRC_H:: Height for the source rectangle within thedrm_framebuffer, in 16.16fixed point. SRC_Y plus SRC_H must be within the height of the sourceframebuffer. Must be positive.
CRTC_X:: X coordinate offset for the destination rectangle. Can be negative.
CRTC_Y:: Y coordinate offset for the destination rectangle. Can be negative.
CRTC_W:: Width for the destination rectangle. CRTC_X plus CRTC_W can extend pastthe currently visible horizontal area of thedrm_crtc.
CRTC_H:: Height for the destination rectangle. CRTC_Y plus CRTC_H can extend pastthe currently visible vertical area of thedrm_crtc.
FB_ID:: Mode object ID of thedrm_framebuffer this plane should scan out.
CRTC_ID:: Mode object ID of thedrm_crtc this plane should be connected to.

Note that the source rectangle must fully lie within the bounds of thedrm_framebuffer. The destination rectangle can lie outside of the visiblearea of the current mode of the CRTC. It must be apprpriately clipped by thedriver, which can be done by calling drm_plane_helper_check_update(). Driversare also allowed to round the subpixel sampling positions appropriately, butonly to the next full pixel. No pixel outside of the source rectangle mayever be sampled, which is important when applying more sophisticatedfiltering than just a bilinear one when scaling. The filtering mode whenscaling is unspecified.

On top of this basic transformation additional properties can be exposed bythe driver:

alpha:

Alpha is setup withdrm_plane_create_alpha_property(). It controls theplane-wide opacity, from transparent (0) to opaque (0xffff). It can becombined with pixel alpha.The pixel values in the framebuffers are expected to not bepre-multiplied by the global alpha associated to the plane.

rotation:

Rotation is set up withdrm_plane_create_rotation_property(). It adds arotation and reflection step between the source and destination rectangles.Without this property the rectangle is only scaled, but not rotated orreflected.

Possbile values:

“rotate-<degrees>”:: Signals that a drm plane is rotated <degrees> degrees in counterclockwise direction.
“reflect-<axis>”:: Signals that the contents of a drm plane is reflected along the<axis> axis, in the same way as mirroring.

reflect-x:

|o |    | o||  | -> |  || v|    |v |

reflect-y:

|o |    | ^||  | -> |  || v|    |o |

zpos:

Z position is set up withdrm_plane_create_zpos_immutable_property() anddrm_plane_create_zpos_property(). It controls the visibility of overlappingplanes. Without this property the primary plane is always below the cursorplane, and ordering between all other planes is undefined. The positiveZ axis points towards the user, i.e. planes with lower Z position valuesare underneath planes with higher Z position values. Two planes with thesame Z position value have undefined ordering. Note that the Z positionvalue can also be immutable, to inform userspace about the hard-codedstacking of planes, seedrm_plane_create_zpos_immutable_property(). Ifany plane has a zpos property (either mutable or immutable), then allplanes shall have a zpos property.

pixel blend mode:

Pixel blend mode is set up withdrm_plane_create_blend_mode_property().It adds a blend mode for alpha blending equation selection, describinghow the pixels from the current plane are composited with thebackground.

Three alpha blending equations are defined:
“None”:
Blend formula that ignores the pixel alpha:
out.rgb = plane_alpha * fg.rgb +        (1 - plane_alpha) * bg.rgb
“Pre-multiplied”:
Blend formula that assumes the pixel color valueshave been already pre-multiplied with the alphachannel values:
out.rgb = plane_alpha * fg.rgb +        (1 - (plane_alpha * fg.alpha)) * bg.rgb
“Coverage”:
Blend formula that assumes the pixel color values have notbeen pre-multiplied and will do so when blending them to thebackground color values:
out.rgb = plane_alpha * fg.alpha * fg.rgb +        (1 - (plane_alpha * fg.alpha)) * bg.rgb
Using the following symbols:
“fg.rgb”:
Each of the RGB component values from the plane’s pixel
“fg.alpha”:
Alpha component value from the plane’s pixel. If the plane’spixel format has no alpha component, then this is assumed to be1.0. In these cases, this property has no effect, as all threeequations become equivalent.
“bg.rgb”:
Each of the RGB component values from the background
“plane_alpha”:
Plane alpha value set by the plane “alpha” property. If theplane does not expose the “alpha” property, then this isassumed to be 1.0

IN_FORMATS:

Blob property which contains the set of buffer format and modifierpairs supported by this plane. The blob is a drm_format_modifier_blobstruct. Without this property the plane doesn’t support buffers withmodifiers. Userspace cannot change this property.

Note that all the property extensions described here apply either to theplane or the CRTC (e.g. for the background color, which currently is notexposed and assumed to be black).

intdrm_plane_create_alpha_property(structdrm_plane * plane)¶: create a new alpha property

Parameters

structdrm_plane*plane: drm plane

Description

This function creates a generic, mutable, alpha property and enables supportfor it in the DRM core. It is attached toplane.

The alpha property will be allowed to be within the bounds of 0(transparent) to 0xffff (opaque).

Return

0 on success, negative error code on failure.

intdrm_plane_create_rotation_property(structdrm_plane * plane, unsigned int rotation, unsigned int supported_rotations)¶: create a new rotation property

Parameters

structdrm_plane*plane: drm plane
unsignedintrotation: initial value of the rotation property
unsignedintsupported_rotations: bitmask of supported rotations and reflections

Description

This creates a new property with the selected support for transformations.

Since a rotation by 180° degress is the same as reflecting both along the xand the y axis the rotation property is somewhat redundant. Drivers can usedrm_rotation_simplify() to normalize values of this property.

The property exposed to userspace is a bitmask property (seedrm_property_create_bitmask()) called “rotation” and has the followingbitmask enumaration values:

DRM_MODE_ROTATE_0:: “rotate-0”
DRM_MODE_ROTATE_90:: “rotate-90”
DRM_MODE_ROTATE_180:: “rotate-180”
DRM_MODE_ROTATE_270:: “rotate-270”
DRM_MODE_REFLECT_X:: “reflect-x”
DRM_MODE_REFLECT_Y:: “reflect-y”

Rotation is the specified amount in degrees in counter clockwise direction,the X and Y axis are within the source rectangle, i.e. the X/Y axis beforerotation. After reflection, the rotation is applied to the image sampled fromthe source rectangle, before scaling it to fit the destination rectangle.

unsigned intdrm_rotation_simplify(unsigned int rotation, unsigned int supported_rotations)¶: Try to simplify the rotation

Parameters

unsignedintrotation: Rotation to be simplified
unsignedintsupported_rotations: Supported rotations

Description

Attempt to simplify the rotation to a form that is supported.Eg. if the hardware supports everything except DRM_MODE_REFLECT_Xone could call this function like this:

drm_rotation_simplify(rotation, DRM_MODE_ROTATE_0 |: DRM_MODE_ROTATE_90 | DRM_MODE_ROTATE_180 |DRM_MODE_ROTATE_270 | DRM_MODE_REFLECT_Y);

to eliminate the DRM_MODE_ROTATE_X flag. Depending on what kind oftransforms the hardware supports, this function may notbe able to produce a supported transform, so the caller shouldcheck the result afterwards.

intdrm_plane_create_zpos_property(structdrm_plane * plane, unsigned int zpos, unsigned int min, unsigned int max)¶: create mutable zpos property

Parameters

structdrm_plane*plane: drm plane
unsignedintzpos: initial value of zpos property
unsignedintmin: minimal possible value of zpos property
unsignedintmax: maximal possible value of zpos property

Description

This function initializes generic mutable zpos property and enables supportfor it in drm core. Drivers can then attach this property to planes to enablesupport for configurable planes arrangement during blending operation.Drivers that attach a mutable zpos property to any plane should call thedrm_atomic_normalize_zpos() helper during their implementation ofdrm_mode_config_funcs.atomic_check(), which will update the normalized zposvalues and store them indrm_plane_state.normalized_zpos. Usually minshould be set to 0 and max to maximal number of planes for given crtc - 1.

If zpos of some planes cannot be changed (like fixed background orcursor/topmost planes), drivers shall adjust the min/max values and assignthose planes immutable zpos properties with lower or higher values (for moreinformation, seedrm_plane_create_zpos_immutable_property() function). In suchcase drivers shall also assign proper initial zpos values for all planes inits plane_reset() callback, so the planes will be always sorted properly.

FB_DAMAGE_CLIPS¶

FB_DAMAGE_CLIPS is an optional plane property which provides a means tospecify a list of damage rectangles on a plane in framebuffer coordinates ofthe framebuffer attached to the plane. In current context damage is the areaof plane framebuffer that has changed since last plane update (also calledpage-flip), irrespective of whether currently attached framebuffer is same asframebuffer attached during last plane update or not.

FB_DAMAGE_CLIPS is a hint to kernel which could be helpful for some driversto optimize internally especially for virtual devices where each framebufferchange needs to be transmitted over network, usb, etc.

Since FB_DAMAGE_CLIPS is a hint so it is an optional property. User-space canignore damage clips property and in that case driver will do a full planeupdate. In case damage clips are provided then it is guaranteed that the areainside damage clips will be updated to plane. For efficiency driver can dofull update or can update more than specified in damage clips. Since driveris free to read more, user-space must always render the entire visibleframebuffer. Otherwise there can be corruptions. Also, if a user-spaceprovides damage clips which doesn’t encompass the actual damage toframebuffer (since last plane update) can result in incorrect rendering.

FB_DAMAGE_CLIPS is a blob property with the layout of blob data is simply anarray ofdrm_mode_rect. Unlike planedrm_plane_state.src coordinates,damage clips are not in 16.16 fixed point. Similar to plane src inframebuffer, damage clips cannot be negative. In damage clip, x1/y1 areinclusive and x2/y2 are exclusive. While kernel does not error for overlappeddamage clips, it is strongly discouraged.

Drivers that are interested in damage interface for plane should enableFB_DAMAGE_CLIPS property by callingdrm_plane_enable_fb_damage_clips().Drivers implementing damage can usedrm_atomic_helper_damage_iter_init() anddrm_atomic_helper_damage_iter_next() helper iterator function to get damagerectangles clipped todrm_plane_state.src.

voiddrm_plane_enable_fb_damage_clips(structdrm_plane * plane)¶: Enables plane fb damage clips property.

Parameters

structdrm_plane*plane: Plane on which to enable damage clips property.

Description

This function lets driver to enable the damage clips property on a plane.

voiddrm_atomic_helper_check_plane_damage(structdrm_atomic_state * state, structdrm_plane_state * plane_state)¶: Verify plane damage on atomic_check.

Parameters

structdrm_atomic_state*state: The driver state object.
structdrm_plane_state*plane_state: Plane state for which to verify damage.

Description

This helper function makes sure that damage from plane state is discardedfor full modeset. If there are more reasons a driver would want to do a fullplane update rather than processing individual damage regions, then thosecases should be taken care of here.

Note thatdrm_plane_state.fb_damage_clips == NULL in plane state means thatfull plane update should happen. It also ensure helper iterator will returndrm_plane_state.src as damage.

intdrm_atomic_helper_dirtyfb(structdrm_framebuffer * fb, structdrm_file * file_priv, unsigned int flags, unsigned int color, struct drm_clip_rect * clips, unsigned int num_clips)¶: Helper for dirtyfb.

Parameters

structdrm_framebuffer*fb: DRM framebuffer.
structdrm_file*file_priv: Drm file for the ioctl call.
unsignedintflags: Dirty fb annotate flags.
unsignedintcolor: Color for annotate fill.
structdrm_clip_rect*clips: Dirty region.
unsignedintnum_clips: Count of clip in clips.

Description

A helper to implementdrm_framebuffer_funcs.dirty using damage interfaceduring plane update. If num_clips is 0 then this helper will do a full planeupdate. This is the same behaviour expected by DIRTFB IOCTL.

Note that this helper is blocking implementation. This is what currentdrivers and userspace expect in their DIRTYFB IOCTL implementation, as a wayto rate-limit userspace and make sure its rendering doesn’t get ahead ofuploading new data too much.

Return

Zero on success, negative errno on failure.

voiddrm_atomic_helper_damage_iter_init(structdrm_atomic_helper_damage_iter * iter, const structdrm_plane_state * old_state, const structdrm_plane_state * state)¶: Initialize the damage iterator.

Parameters

structdrm_atomic_helper_damage_iter*iter: The iterator to initialize.
conststructdrm_plane_state*old_state: Old plane state for validation.
conststructdrm_plane_state*state: Plane state from which to iterate the damage clips.

Description

Initialize an iterator, which clips plane damagedrm_plane_state.fb_damage_clips to planedrm_plane_state.src. This iteratorreturns full plane src in case damage is not present because eitheruser-space didn’t sent or driver discarded it (it want to do full planeupdate). Currently this iterator returns full plane src in case plane srcchanged but that can be changed in future to return damage.

For the case when plane is not visible or plane update should not happen thefirst call to iter_next will return false. Note that this helper use clippeddrm_plane_state.src, so driver calling this helper should have calleddrm_atomic_helper_check_plane_state() earlier.

booldrm_atomic_helper_damage_iter_next(structdrm_atomic_helper_damage_iter * iter, structdrm_rect * rect)¶: Advance the damage iterator.

Parameters

structdrm_atomic_helper_damage_iter*iter: The iterator to advance.
structdrm_rect*rect: Return a rectangle in fb coordinate clipped to plane src.

Description

Since plane src is in 16.16 fixed point and damage clips are whole number,this iterator round off clips that intersect with plane src. Round down forx1/y1 and round up for x2/y2 for the intersected coordinate. Similar roundingoff for full plane src, in case it’s returned as damage. This iterator willskip damage clips outside of plane src.

If the first call to iterator next returns false then it means no need toupdate the plane.

Return

True if the output is valid, false if reached the end.

booldrm_atomic_helper_damage_merged(const structdrm_plane_state * old_state, structdrm_plane_state * state, structdrm_rect * rect)¶: Merged plane damage

Parameters

conststructdrm_plane_state*old_state: Old plane state for validation.
structdrm_plane_state*state: Plane state from which to iterate the damage clips.
structdrm_rect*rect: Returns the merged damage rectangle

Description

This function merges any valid plane damage clips into one rectangle andreturns it inrect.

For details see:drm_atomic_helper_damage_iter_init() anddrm_atomic_helper_damage_iter_next().

Return

True if there is valid plane damage otherwise false.

drm_atomic_for_each_plane_damage(iter,rect)¶: Iterator macro for plane damage.

Parameters

iter: The iterator to advance.
rect: Return a rectangle in fb coordinate clipped to plane src.

Description

Note that if the first call to iterator macro return false then no need to doplane update. Iterator will return full plane src when damage is not passedby user-space.

structdrm_atomic_helper_damage_iter¶: Closure structure for damage iterator.

Definition

struct drm_atomic_helper_damage_iter {};

Members

Description

This structure tracks state needed to walk the list of plane damage clips.

structdrm_rect *drm_helper_get_plane_damage_clips(const structdrm_plane_state * state)¶: Returns damage clips indrm_rect.

Parameters

conststructdrm_plane_state*state: Plane state.

Description

Returns plane damage rectangles in internaldrm_rect. Currentlydrm_rectcan be obtained by simply typecastingdrm_mode_rect. This is because bothare signed 32 and duringdrm_atomic_check_only() it is verified that damageclips are inside fb.

Return

Clips in plane fb_damage_clips blob property.

Color Management Properties¶

Color management or color space adjustments is supported through a set of 5properties on thedrm_crtc object. They are set up by callingdrm_crtc_enable_color_mgmt().

“DEGAMMA_LUT”:

Blob property to set the degamma lookup table (LUT) mapping pixel datafrom the framebuffer before it is given to the transformation matrix.The data is interpreted as an array ofstructdrm_color_lut elements.Hardware might choose not to use the full precision of the LUT elementsnor use all the elements of the LUT (for example the hardware mightchoose to interpolate between LUT[0] and LUT[4]).

Setting this to NULL (blob property value set to 0) means alinear/pass-thru gamma table should be used. This is generally thedriver boot-up state too. Drivers can access this blob throughdrm_crtc_state.degamma_lut.

“DEGAMMA_LUT_SIZE”:

Unsinged range property to give the size of the lookup table to be seton the DEGAMMA_LUT property (the size depends on the underlyinghardware). If drivers support multiple LUT sizes then they shouldpublish the largest size, and sub-sample smaller sized LUTs (e.g. forsplit-gamma modes) appropriately.

“CTM”:

Blob property to set the current transformation matrix (CTM) apply topixel data after the lookup through the degamma LUT and before thelookup through the gamma LUT. The data is interpreted as a structdrm_color_ctm.

Setting this to NULL (blob property value set to 0) means aunit/pass-thru matrix should be used. This is generally the driverboot-up state too. Drivers can access the blob for the color conversionmatrix throughdrm_crtc_state.ctm.

“GAMMA_LUT”:

Blob property to set the gamma lookup table (LUT) mapping pixel dataafter the transformation matrix to data sent to the connector. Thedata is interpreted as an array ofstructdrm_color_lut elements.Hardware might choose not to use the full precision of the LUT elementsnor use all the elements of the LUT (for example the hardware mightchoose to interpolate between LUT[0] and LUT[4]).

“GAMMA_LUT_SIZE”:

Unsigned range property to give the size of the lookup table to be seton the GAMMA_LUT property (the size depends on the underlying hardware).If drivers support multiple LUT sizes then they should publish thelargest size, and sub-sample smaller sized LUTs (e.g. for split-gammamodes) appropriately.

There is also support for a legacy gamma table, which is set up by callingdrm_mode_crtc_set_gamma_size(). Drivers which support both should usedrm_atomic_helper_legacy_gamma_set() to alias the legacy gamma ramp with the“GAMMA_LUT” property above.

Support for different non RGB color encodings is controlled throughdrm_plane specific COLOR_ENCODING and COLOR_RANGE properties. Theyare set up by callingdrm_plane_create_color_properties().

“COLOR_ENCODING”: Optional plane enum property to support different non RGBcolor encodings. The driver can provide a subset of standardenum values supported by the DRM plane.
“COLOR_RANGE”: Optional plane enum property to support different non RGBcolor parameter ranges. The driver can provide a subset ofstandard enum values supported by the DRM plane.

u64drm_color_ctm_s31_32_to_qm_n(u64 user_input, u32 m, u32 n)¶

Parameters

u64user_input: input value
u32m: number of integer bits, only support m <= 32, include the sign-bit
u32n: number of fractional bits, only support n <= 32

Description

Convert and clamp S31.32 sign-magnitude to Qm.n (signed 2’s complement).The sign-bit BIT(m+n-1) and above are 0 for positive value and 1 for negativethe range of value is [-2^(m-1), 2^(m-1) - 2^-n]

For exampleA Q3.12 format number:- required bit: 3 + 12 = 15bits- range: [-2^2, 2^2 - 2^−15]

NOTE

the m can be zero if all bit_precision are used to present fractional: bits like Q0.32

voiddrm_crtc_enable_color_mgmt(structdrm_crtc * crtc, uint degamma_lut_size, bool has_ctm, uint gamma_lut_size)¶: enable color management properties

Parameters

structdrm_crtc*crtc: DRM CRTC
uintdegamma_lut_size: the size of the degamma lut (before CSC)
boolhas_ctm: whether to attach ctm_property for CSC matrix
uintgamma_lut_size: the size of the gamma lut (after CSC)

Description

This function lets the driver enable the color correctionproperties on a CRTC. This includes 3 degamma, csc and gammaproperties that userspace can set and 2 size properties to informthe userspace of the lut sizes. Each of the properties areoptional. The gamma and degamma properties are only attached iftheir size is not 0 and ctm_property is only attached if has_ctm istrue.

Drivers should usedrm_atomic_helper_legacy_gamma_set() to implement thelegacydrm_crtc_funcs.gamma_set callback.

intdrm_mode_crtc_set_gamma_size(structdrm_crtc * crtc, int gamma_size)¶: set the gamma table size

Parameters

structdrm_crtc*crtc: CRTC to set the gamma table size for
intgamma_size: size of the gamma table

Description

Drivers which support gamma tables should set this to the supported gammatable size when initializing the CRTC. Currently the drm core only supports afixed gamma table size.

Return

Zero on success, negative errno on failure.

intdrm_plane_create_color_properties(structdrm_plane * plane, u32 supported_encodings, u32 supported_ranges, enum drm_color_encoding default_encoding, enum drm_color_range default_range)¶: color encoding related plane properties

Parameters

structdrm_plane*plane: plane object
u32supported_encodings: bitfield indicating supported color encodings
u32supported_ranges: bitfileld indicating supported color ranges
enumdrm_color_encodingdefault_encoding: default color encoding
enumdrm_color_rangedefault_range: default color range

Description

Create and attach plane specific COLOR_ENCODING and COLOR_RANGEproperties toplane. The supported encodings and ranges shouldbe provided in supported_encodings and supported_ranges bitmasks.Each bit set in the bitmask indicates that its number as enumvalue is supported.

intdrm_color_lut_check(const structdrm_property_blob * lut, u32 tests)¶: check validity of lookup table

Parameters

conststructdrm_property_blob*lut: property blob containing LUT to check
u32tests: bitmask of tests to run

Description

Helper to check whether a userspace-provided lookup table is valid andsatisfies hardware requirements. Drivers pass a bitmask indicating which ofthe tests indrm_color_lut_tests should be performed.

Returns 0 on success, -EINVAL on failure.

u32drm_color_lut_extract(u32 user_input, int bit_precision)¶: clamp and round LUT entries

Parameters

u32user_input: input value
intbit_precision: number of bits the hw LUT supports

Description

Extract a degamma/gamma LUT value provided by user (in the form ofdrm_color_lut entries) and round it to the precision supported by thehardware.

intdrm_color_lut_size(const structdrm_property_blob * blob)¶: calculate the number of entries in the LUT

Parameters

conststructdrm_property_blob*blob: blob containing the LUT

Return

The number of entries in the color LUT stored inblob.

enumdrm_color_lut_tests¶: hw-specific LUT tests to perform

Constants

DRM_COLOR_LUT_EQUAL_CHANNELS: Checks whether the entries of a LUT all have equal values for thered, green, and blue channels. Intended for hardware that onlyaccepts a single value per LUT entry and assumes that value appliesto all three color components.
DRM_COLOR_LUT_NON_DECREASING: Checks whether the entries of a LUT are always flat or increasing(never decreasing).

Description

Thedrm_color_lut_check() function takes a bitmask of the values here todetermine which tests to apply to a userspace-provided LUT.

Tile Group Property¶

Tile groups are used to represent tiled monitors with a unique integeridentifier. Tiled monitors using DisplayID v1.3 have a unique 8-byte handle,we store this in a tile group, so we have a common identifier for all tilesin a monitor group. The property is called “TILE”. Drivers can manage tilegroups usingdrm_mode_create_tile_group(),drm_mode_put_tile_group() anddrm_mode_get_tile_group(). But this is only needed for internal panels wherethe tile group information is exposed through a non-standard way.

Explicit Fencing Properties¶

Explicit fencing allows userspace to control the buffer synchronizationbetween devices. A Fence or a group of fences are transfered to/fromuserspace using Sync File fds and there are two DRM properties for that.IN_FENCE_FD on each DRM Plane to send fences to the kernel andOUT_FENCE_PTR on each DRM CRTC to receive fences from the kernel.

As a contrast, with implicit fencing the kernel keeps track of anyongoing rendering, and automatically ensures that the atomic update waitsfor any pending rendering to complete. For shared buffers represented withastructdma_buf this is tracked instructdma_resv.Implicit syncing is how Linux traditionally worked (e.g. DRI2/3 on X.org),whereas explicit fencing is what Android wants.

“IN_FENCE_FD”:

Use this property to pass a fence that DRM should wait on beforeproceeding with the Atomic Commit request and show the framebuffer forthe plane on the screen. The fence can be either a normal fence or amerged one, the sync_file framework will handle both cases and use afence_array if a merged fence is received. Passing -1 here means nofences to wait on.

If the Atomic Commit request has the DRM_MODE_ATOMIC_TEST_ONLY flagit will only check if the Sync File is a valid one.

On the driver side the fence is stored on thefence parameter ofstructdrm_plane_state. Drivers which also support implicit fencingshould set the implicit fence usingdrm_atomic_set_fence_for_plane(),to make sure there’s consistent behaviour between drivers in precedenceof implicit vs. explicit fencing.

“OUT_FENCE_PTR”:

Use this property to pass a file descriptor pointer to DRM. Once theAtomic Commit request call returns OUT_FENCE_PTR will be filled withthe file descriptor number of a Sync File. This Sync File contains theCRTC fence that will be signaled when all framebuffers present on theAtomic Commit * request for that given CRTC are scanned out on thescreen.

The Atomic Commit request fails if a invalid pointer is passed. If theAtomic Commit request fails for any other reason the out fence fdreturned will be -1. On a Atomic Commit with theDRM_MODE_ATOMIC_TEST_ONLY flag the out fence will also be set to -1.

Note that out-fences don’t have a special interface to drivers and areinternally represented by astructdrm_pending_vblank_event in structdrm_crtc_state, which is also used by the nonblocking atomic commithelpers and for the DRM event handling for existing userspace.

Variable Refresh Properties¶

Variable refresh rate capable displays can dynamically adjust theirrefresh rate by extending the duration of their vertical front porchuntil page flip or timeout occurs. This can reduce or remove stutteringand latency in scenarios where the page flip does not align with thevblank interval.

An example scenario would be an application flipping at a constant rateof 48Hz on a 60Hz display. The page flip will frequently miss the vblankinterval and the same contents will be displayed twice. This can beobserved as stuttering for content with motion.

If variable refresh rate was active on a display that supported avariable refresh range from 35Hz to 60Hz no stuttering would be observablefor the example scenario. The minimum supported variable refresh rate of35Hz is below the page flip frequency and the vertical front porch canbe extended until the page flip occurs. The vblank interval will bedirectly aligned to the page flip rate.

Not all userspace content is suitable for use with variable refresh rate.Large and frequent changes in vertical front porch duration may worsenperceived stuttering for input sensitive applications.

Panel brightness will also vary with vertical front porch duration. Somepanels may have noticeable differences in brightness between the minimumvertical front porch duration and the maximum vertical front porch duration.Large and frequent changes in vertical front porch duration may produceobservable flickering for such panels.

Userspace control for variable refresh rate is supported via propertieson thedrm_connector anddrm_crtc objects.

“vrr_capable”:

Optionaldrm_connector boolean property that drivers should attachwithdrm_connector_attach_vrr_capable_property() on connectors thatcould support variable refresh rates. Drivers should update theproperty value by callingdrm_connector_set_vrr_capable_property().

Absence of the property should indicate absence of support.

“VRR_ENABLED”:

Defaultdrm_crtc boolean property that notifies the driver that thecontent on the CRTC is suitable for variable refresh rate presentation.The driver will take this property as a hint to enable variablerefresh rate support if the receiver supports it, ie. if the“vrr_capable” property is true on thedrm_connector object. Thevertical front porch duration will be extended until page-flip ortimeout when enabled.

The minimum vertical front porch duration is defined as the verticalfront porch duration for the current mode.

The maximum vertical front porch duration is greater than or equal tothe minimum vertical front porch duration. The duration is derivedfrom the minimum supported variable refresh rate for the connector.

The driver may place further restrictions within these minimumand maximum bounds.

Existing KMS Properties¶

The following table gives description of drm properties exposed by variousmodules/drivers. Because this table is very unwieldy, do not add any newproperties here. Instead document them in a section above.

Owner Module/Drivers	Group	Property Name	Type	Property Values	Object attached	Description/Restrictions
	DVI-I	“subconnector”	ENUM	{ “Unknown”, “DVI-D”, “DVI-A” }	Connector	TBD
		“select subconnector”	ENUM	{ “Automatic”, “DVI-D”, “DVI-A” }	Connector	TBD
	TV	“subconnector”	ENUM	{ “Unknown”, “Composite”, “SVIDEO”, “Component”, “SCART” }	Connector	TBD
		“select subconnector”	ENUM	{ “Automatic”, “Composite”, “SVIDEO”, “Component”, “SCART” }	Connector	TBD
		“mode”	ENUM	{ “NTSC_M”, “NTSC_J”, “NTSC_443”, “PAL_B” } etc.	Connector	TBD
		“left margin”	RANGE	Min=0, Max=100	Connector	TBD
		“right margin”	RANGE	Min=0, Max=100	Connector	TBD
		“top margin”	RANGE	Min=0, Max=100	Connector	TBD
		“bottom margin”	RANGE	Min=0, Max=100	Connector	TBD
		“brightness”	RANGE	Min=0, Max=100	Connector	TBD
		“contrast”	RANGE	Min=0, Max=100	Connector	TBD
		“flicker reduction”	RANGE	Min=0, Max=100	Connector	TBD
		“overscan”	RANGE	Min=0, Max=100	Connector	TBD
		“saturation”	RANGE	Min=0, Max=100	Connector	TBD
		“hue”	RANGE	Min=0, Max=100	Connector	TBD
	Virtual GPU	“suggested X”	RANGE	Min=0, Max=0xffffffff	Connector	property to suggest an X offset for a connector
		“suggested Y”	RANGE	Min=0, Max=0xffffffff	Connector	property to suggest an Y offset for a connector
	Optional	“aspect ratio”	ENUM	{ “None”, “4:3”, “16:9” }	Connector	TDB
i915	Generic	“Broadcast RGB”	ENUM	{ “Automatic”, “Full”, “Limited 16:235” }	Connector	When this property is set to Limited 16:235 and CTM is set, the hardware will be programmed with the result of the multiplication of CTM by the limited range matrix to ensure the pixels normaly in the range 0..1.0 are remapped to the range 16/255..235/255.
		“audio”	ENUM	{ “force-dvi”, “off”, “auto”, “on” }	Connector	TBD
	SDVO-TV	“mode”	ENUM	{ “NTSC_M”, “NTSC_J”, “NTSC_443”, “PAL_B” } etc.	Connector	TBD
		“left_margin”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“right_margin”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“top_margin”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“bottom_margin”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“hpos”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“vpos”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“contrast”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“saturation”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“hue”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“sharpness”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“flicker_filter”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“flicker_filter_adaptive”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“flicker_filter_2d”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“tv_chroma_filter”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“tv_luma_filter”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“dot_crawl”	RANGE	Min=0, Max=1	Connector	TBD
	SDVO-TV/LVDS	“brightness”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
CDV gma-500	Generic	“Broadcast RGB”	ENUM	{ “Full”, “Limited 16:235” }	Connector	TBD
		“Broadcast RGB”	ENUM	{ “off”, “auto”, “on” }	Connector	TBD
Poulsbo	Generic	“backlight”	RANGE	Min=0, Max=100	Connector	TBD
	SDVO-TV	“mode”	ENUM	{ “NTSC_M”, “NTSC_J”, “NTSC_443”, “PAL_B” } etc.	Connector	TBD
		“left_margin”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“right_margin”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“top_margin”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“bottom_margin”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“hpos”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“vpos”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“contrast”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“saturation”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“hue”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“sharpness”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“flicker_filter”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“flicker_filter_adaptive”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“flicker_filter_2d”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“tv_chroma_filter”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“tv_luma_filter”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
		“dot_crawl”	RANGE	Min=0, Max=1	Connector	TBD
	SDVO-TV/LVDS	“brightness”	RANGE	Min=0, Max= SDVO dependent	Connector	TBD
armada	CRTC	“CSC_YUV”	ENUM	{ “Auto” , “CCIR601”, “CCIR709” }	CRTC	TBD
		“CSC_RGB”	ENUM	{ “Auto”, “Computer system”, “Studio” }	CRTC	TBD
	Overlay	“colorkey”	RANGE	Min=0, Max=0xffffff	Plane	TBD
		“colorkey_min”	RANGE	Min=0, Max=0xffffff	Plane	TBD
		“colorkey_max”	RANGE	Min=0, Max=0xffffff	Plane	TBD
		“colorkey_val”	RANGE	Min=0, Max=0xffffff	Plane	TBD
		“colorkey_alpha”	RANGE	Min=0, Max=0xffffff	Plane	TBD
		“colorkey_mode”	ENUM	{ “disabled”, “Y component”, “U component” , “V component”, “RGB”, “R component”, “G component”, “B component” }	Plane	TBD
		“brightness”	RANGE	Min=0, Max=256 + 255	Plane	TBD
		“contrast”	RANGE	Min=0, Max=0x7fff	Plane	TBD
		“saturation”	RANGE	Min=0, Max=0x7fff	Plane	TBD
exynos	CRTC	“mode”	ENUM	{ “normal”, “blank” }	CRTC	TBD
i2c/ch7006_drv	Generic	“scale”	RANGE	Min=0, Max=2	Connector	TBD
	TV	“mode”	ENUM	{ “PAL”, “PAL-M”,”PAL-N”}, ”PAL-Nc” , “PAL-60”, “NTSC-M”, “NTSC-J” }	Connector	TBD
nouveau	NV10 Overlay	“colorkey”	RANGE	Min=0, Max=0x01ffffff	Plane	TBD
		“contrast”	RANGE	Min=0, Max=8192-1	Plane	TBD
		“brightness”	RANGE	Min=0, Max=1024	Plane	TBD
		“hue”	RANGE	Min=0, Max=359	Plane	TBD
		“saturation”	RANGE	Min=0, Max=8192-1	Plane	TBD
		“iturbt_709”	RANGE	Min=0, Max=1	Plane	TBD
	Nv04 Overlay	“colorkey”	RANGE	Min=0, Max=0x01ffffff	Plane	TBD
		“brightness”	RANGE	Min=0, Max=1024	Plane	TBD
	Display	“dithering mode”	ENUM	{ “auto”, “off”, “on” }	Connector	TBD
		“dithering depth”	ENUM	{ “auto”, “off”, “on”, “static 2x2”, “dynamic 2x2”, “temporal” }	Connector	TBD
		“underscan”	ENUM	{ “auto”, “6 bpc”, “8 bpc” }	Connector	TBD
		“underscan hborder”	RANGE	Min=0, Max=128	Connector	TBD
		“underscan vborder”	RANGE	Min=0, Max=128	Connector	TBD
		“vibrant hue”	RANGE	Min=0, Max=180	Connector	TBD
		“color vibrance”	RANGE	Min=0, Max=200	Connector	TBD
omap	Generic	“zorder”	RANGE	Min=0, Max=3	CRTC, Plane	TBD
qxl	Generic	“hotplug_mode_update”	RANGE	Min=0, Max=1	Connector	TBD
radeon	DVI-I	“coherent”	RANGE	Min=0, Max=1	Connector	TBD
	DAC enable load detect	“load detection”	RANGE	Min=0, Max=1	Connector	TBD
	TV Standard	“tv standard”	ENUM	{ “ntsc”, “pal”, “pal-m”, “pal-60”, “ntsc-j” , “scart-pal”, “pal-cn”, “secam” }	Connector	TBD
	legacy TMDS PLL detect	“tmds_pll”	ENUM	{ “driver”, “bios” }		TBD
	Underscan	“underscan”	ENUM	{ “off”, “on”, “auto” }	Connector	TBD
		“underscan hborder”	RANGE	Min=0, Max=128	Connector	TBD
		“underscan vborder”	RANGE	Min=0, Max=128	Connector	TBD
	Audio	“audio”	ENUM	{ “off”, “on”, “auto” }	Connector	TBD
	FMT Dithering	“dither”	ENUM	{ “off”, “on” }	Connector	TBD
		“colorkey”	RANGE	Min=0, Max=0x01ffffff	Plane	TBD

Vertical Blanking¶

From the computer’s perspective, every time the monitor displaysa new frame the scanout engine has “scanned out” the display imagefrom top to bottom, one row of pixels at a time. The current rowof pixels is referred to as the current scanline.

In addition to the display’s visible area, there’s usually a couple ofextra scanlines which aren’t actually displayed on the screen.These extra scanlines don’t contain image data and are occasionally usedfor features like audio and infoframes. The region made up of thesescanlines is referred to as the vertical blanking region, or vblank forshort.

For historical reference, the vertical blanking period was designed togive the electron gun (on CRTs) enough time to move back to the top ofthe screen to start scanning out the next frame. Similar for horizontalblanking periods. They were designed to give the electron gun enoughtime to move back to the other side of the screen to start scanning thenext scanline.

physical →   ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽top of      |                                        |display     |                                        |            |               New frame                |            |                                        |            |↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓|            |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| ← Scanline,            |↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓|   updates the            |                                        |   frame as it            |                                        |   travels down            |                                        |   ("sacn out")            |               Old frame                |            |                                        |            |                                        |            |                                        |            |                                        |   physical            |                                        |   bottom ofvertical    |⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽| ← displayblanking    ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆region   →  ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆            ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆start of →   ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽new frame

“Physical top of display” is the reference point for the high-precision/corrected timestamp.

On a lot of display hardware, programming needs to take effect during thevertical blanking period so that settings like gamma, the image bufferbuffer to be scanned out, etc. can safely be changed without showingany visual artifacts on the screen. In some unforgiving hardware, some ofthis programming has to both start and end in the same vblank. To helpwith the timing of the hardware programming, an interrupt is usuallyavailable to notify the driver when it can start the updating of registers.The interrupt is in this context named the vblank interrupt.

The vblank interrupt may be fired at different points depending on thehardware. Some hardware implementations will fire the interrupt when thenew frame start, other implementations will fire the interrupt at differentpoints in time.

Vertical blanking plays a major role in graphics rendering. To achievetear-free display, users must synchronize page flips and/or rendering tovertical blanking. The DRM API offers ioctls to perform page flipssynchronized to vertical blanking and wait for vertical blanking.

The DRM core handles most of the vertical blanking management logic, whichinvolves filtering out spurious interrupts, keeping race-free blankingcounters, coping with counter wrap-around and resets and keeping use counts.It relies on the driver to generate vertical blanking interrupts andoptionally provide a hardware vertical blanking counter.

Drivers must initialize the vertical blanking handling core with a call todrm_vblank_init(). Minimally, a driver needs to implementdrm_crtc_funcs.enable_vblank anddrm_crtc_funcs.disable_vblank plus calldrm_crtc_handle_vblank() in its vblank interrupt handler for working vblanksupport.

Vertical blanking interrupts can be enabled by the DRM core or by driversthemselves (for instance to handle page flipping operations). The DRM coremaintains a vertical blanking use count to ensure that the interrupts are notdisabled while a user still needs them. To increment the use count, driverscalldrm_crtc_vblank_get() and release the vblank reference again withdrm_crtc_vblank_put(). In between these two calls vblank interrupts areguaranteed to be enabled.

On many hardware disabling the vblank interrupt cannot be done in a race-freemanner, seedrm_driver.vblank_disable_immediate anddrm_driver.max_vblank_count. In that case the vblank core only disables thevblanks after a timer has expired, which can be configured through thevblankoffdelay module parameter.

Drivers for hardware without support for vertical-blanking interruptsmust not calldrm_vblank_init(). For such drivers, atomic helpers willautomatically generate fake vblank events as part of the display update.This functionality also can be controlled by the driver by enabling anddisabling struct drm_crtc_state.no_vblank.

Vertical Blanking and Interrupt Handling Functions Reference¶

structdrm_pending_vblank_event¶: pending vblank event tracking

Definition

struct drm_pending_vblank_event {  struct drm_pending_event base;  unsigned int pipe;  u64 sequence;  union {    struct drm_event base;    struct drm_event_vblank vbl;    struct drm_event_crtc_sequence seq;  } event;};

Members

base: Base structure for tracking pending DRM events.
pipe: drm_crtc_index() of thedrm_crtc this event is for.
sequence: frame event should be triggered at
event: Actual event which will be sent to userspace.
event.base: DRM event base class.
event.vbl: Event payload for vblank events, requested througheither the MODE_PAGE_FLIP or MODE_ATOMIC IOCTL. Alsogenerated by the legacy WAIT_VBLANK IOCTL, but new userspaceshould use MODE_QUEUE_SEQUENCE andevent.seq instead.
event.seq: Event payload for the MODE_QUEUEU_SEQUENCE IOCTL.

structdrm_vblank_crtc¶: vblank tracking for a CRTC

Definition

struct drm_vblank_crtc {  struct drm_device *dev;  wait_queue_head_t queue;  struct timer_list disable_timer;  seqlock_t seqlock;  atomic64_t count;  ktime_t time;  atomic_t refcount;  u32 last;  u32 max_vblank_count;  unsigned int inmodeset;  unsigned int pipe;  int framedur_ns;  int linedur_ns;  struct drm_display_mode hwmode;  bool enabled;  struct kthread_worker *worker;  struct list_head pending_work;  wait_queue_head_t work_wait_queue;};

Members

dev

Pointer to thedrm_device.

queue

Wait queue for vblank waiters.

disable_timer

Disable timer for the delayed vblank disablinghysteresis logic. Vblank disabling is controlled through thedrm_vblank_offdelay module option and the setting of thedrm_device.max_vblank_count value.

seqlock

Protect vblank count and time.

count

Current software vblank counter.

Note that for a given vblank counter valuedrm_crtc_handle_vblank()anddrm_crtc_vblank_count() ordrm_crtc_vblank_count_and_time()provide a barrier: Any writes done before callingdrm_crtc_handle_vblank() will be visible to callers of the laterfunctions, iff the vblank count is the same or a later one.

IMPORTANT: This guarantee requires barriers, therefor never accessthis field directly. Usedrm_crtc_vblank_count() instead.

time

Vblank timestamp corresponding tocount.

refcount

Number of users/waiters of the vblank interrupt. Only whenthis refcount reaches 0 can the hardware interrupt be disabled usingdisable_timer.

last

Protected bydrm_device.vbl_lock, used for wraparound handling.

max_vblank_count

Maximum value of the vblank registers for this crtc. This value +1will result in a wrap-around of the vblank register. It is usedby the vblank core to handle wrap-arounds.

If set to zero the vblank core will try to guess the elapsed vblanksbetween times when the vblank interrupt is disabled throughhigh-precision timestamps. That approach is suffering from smallraces and imprecision over longer time periods, hence exposing ahardware vblank counter is always recommended.

This is the runtime configurable per-crtc maximum set throughdrm_crtc_set_max_vblank_count(). If this is used the drivermust leave the device widedrm_device.max_vblank_count at zero.

If non-zero,drm_crtc_funcs.get_vblank_counter must be set.

inmodeset

Tracks whether the vblank is disabled due to a modeset.For legacy driver bit 2 additionally tracks whether an additionaltemporary vblank reference has been acquired to paper over thehardware counter resetting/jumping. KMS drivers should instead justcalldrm_crtc_vblank_off() anddrm_crtc_vblank_on(), which explicitlysave and restore the vblank count.

pipe

drm_crtc_index() of thedrm_crtc corresponding to thisstructure.

framedur_ns

Frame/Field duration in ns, used bydrm_crtc_vblank_helper_get_vblank_timestamp() and computed bydrm_calc_timestamping_constants().

linedur_ns

Line duration in ns, used bydrm_crtc_vblank_helper_get_vblank_timestamp() and computed bydrm_calc_timestamping_constants().

hwmode

Cache of the current hardware display mode. Only valid whenenabledis set. This is used by helpers likedrm_crtc_vblank_helper_get_vblank_timestamp(). We can’t just accessthe hardware mode by e.g. looking atdrm_crtc_state.adjusted_mode,because that one is really hard to get from interrupt context.

enabled

Tracks the enabling state of the correspondingdrm_crtc toavoid double-disabling and hence corrupting saved state. Needed bydrivers not using atomic KMS, since those might go through their CRTCdisabling functions multiple times.

worker

Thekthread_worker used for executing vblank works.

pending_work

A list of scheduleddrm_vblank_work items that arewaiting for a future vblank.

work_wait_queue

The wait queue used for signaling that adrm_vblank_work item has either finished executing, or wascancelled.

Description

This structure tracks the vblank state for one CRTC.

Note that for historical reasons - the vblank handling code is still sharedwith legacy/non-kms drivers - this is a free-standing structure not directlyconnected tostructdrm_crtc. But all public interface functions are takingastructdrm_crtc to hide this implementation detail.

u64drm_crtc_accurate_vblank_count(structdrm_crtc * crtc)¶: retrieve the master vblank counter

Parameters

structdrm_crtc*crtc: which counter to retrieve

Description

This function is similar todrm_crtc_vblank_count() but this functioninterpolates to handle a race with vblank interrupts using the high precisiontimestamping support.

This is mostly useful for hardware that can obtain the scanout position, butdoesn’t have a hardware frame counter.

intdrm_vblank_init(structdrm_device * dev, unsigned int num_crtcs)¶: initialize vblank support

Parameters

structdrm_device*dev: DRM device
unsignedintnum_crtcs: number of CRTCs supported bydev

Description

This function initializes vblank support fornum_crtcs display pipelines.Cleanup is handled automatically through a cleanup function added withdrmm_add_action_or_reset().

Return

Zero on success or a negative error code on failure.

booldrm_dev_has_vblank(const structdrm_device * dev)¶: test if vblanking has been initialized for a device

Parameters

conststructdrm_device*dev: the device

Description

Drivers may call this function to test if vblank support isinitialized for a device. For most hardware this means that vblankingcan also be enabled.

Atomic helpers use this function to initializedrm_crtc_state.no_vblank. See alsodrm_atomic_helper_check_modeset().

Return

True if vblanking has been initialized for the given device, falseotherwise.

wait_queue_head_t *drm_crtc_vblank_waitqueue(structdrm_crtc * crtc)¶: get vblank waitqueue for the CRTC

Parameters

structdrm_crtc*crtc: which CRTC’s vblank waitqueue to retrieve

Description

This function returns a pointer to the vblank waitqueue for the CRTC.Drivers can use this to implement vblank waits usingwait_event() and relatedfunctions.

voiddrm_calc_timestamping_constants(structdrm_crtc * crtc, const structdrm_display_mode * mode)¶: calculate vblank timestamp constants

Parameters

structdrm_crtc*crtc: drm_crtc whose timestamp constants should be updated.
conststructdrm_display_mode*mode: display mode containing the scanout timings

Description

Calculate and store various constants which are later needed by vblank andswap-completion timestamping, e.g, bydrm_crtc_vblank_helper_get_vblank_timestamp(). They are derived fromCRTC’s true scanout timing, so they take things like panel scaling orother adjustments into account.

booldrm_crtc_vblank_helper_get_vblank_timestamp_internal(structdrm_crtc * crtc, int * max_error, ktime_t * vblank_time, bool in_vblank_irq, drm_vblank_get_scanout_position_func get_scanout_position)¶: precise vblank timestamp helper

Parameters

structdrm_crtc*crtc: CRTC whose vblank timestamp to retrieve
int*max_error: Desired maximum allowable error in timestamps (nanosecs)On return contains true maximum error of timestamp
ktime_t*vblank_time: Pointer to time which should receive the timestamp
boolin_vblank_irq: True when called fromdrm_crtc_handle_vblank(). Some driversneed to apply some workarounds for gpu-specific vblank irq quirksif flag is set.
drm_vblank_get_scanout_position_funcget_scanout_position: Callback function to retrieve the scanout position. Seestruct drm_crtc_helper_funcs.get_scanout_position.

Description

Implements calculation of exact vblank timestamps from given drm_display_modetimings and current video scanout position of a CRTC.

The current implementation only handles standard video modes. For double scanand interlaced modes the driver is supposed to adjust the hardware mode(taken fromdrm_crtc_state.adjusted mode for atomic modeset drivers) tomatch the scanout position reported.

Note that atomic drivers must calldrm_calc_timestamping_constants() beforeenabling a CRTC. The atomic helpers already take care of that indrm_atomic_helper_update_legacy_modeset_state().

Returns true on success, and false on failure, i.e. when no accuratetimestamp could be acquired.

Return

booldrm_crtc_vblank_helper_get_vblank_timestamp(structdrm_crtc * crtc, int * max_error, ktime_t * vblank_time, bool in_vblank_irq)¶: precise vblank timestamp helper

Parameters

structdrm_crtc*crtc: CRTC whose vblank timestamp to retrieve
int*max_error: Desired maximum allowable error in timestamps (nanosecs)On return contains true maximum error of timestamp
ktime_t*vblank_time: Pointer to time which should receive the timestamp
boolin_vblank_irq: True when called fromdrm_crtc_handle_vblank(). Some driversneed to apply some workarounds for gpu-specific vblank irq quirksif flag is set.

Description

Implements calculation of exact vblank timestamps from given drm_display_modetimings and current video scanout position of a CRTC. This can be directlyused as thedrm_crtc_funcs.get_vblank_timestamp implementation of a kmsdriver ifdrm_crtc_helper_funcs.get_scanout_position is implemented.

Note that atomic drivers must calldrm_calc_timestamping_constants() beforeenabling a CRTC. The atomic helpers already take care of that indrm_atomic_helper_update_legacy_modeset_state().

Returns true on success, and false on failure, i.e. when no accuratetimestamp could be acquired.

Return

u64drm_crtc_vblank_count(structdrm_crtc * crtc)¶: retrieve “cooked” vblank counter value

Parameters

structdrm_crtc*crtc: which counter to retrieve

Description

Fetches the “cooked” vblank count value that represents the number ofvblank events since the system was booted, including lost events due tomodesetting activity. Note that this timer isn’t correct against a racingvblank interrupt (since it only reports the software vblank counter), seedrm_crtc_accurate_vblank_count() for such use-cases.

Vertical Blank Work¶

Many DRM drivers need to program hardware in a time-sensitive manner, manytimes with a deadline of starting and finishing within a certain region ofthe scanout. Most of the time the safest way to accomplish this is tosimply do said time-sensitive programming in the driver’s IRQ handler,which allows drivers to avoid being preempted during these criticalregions. Or even better, the hardware may even handle applying suchtime-critical programming independently of the CPU.

While there’s a decent amount of hardware that’s designed so that the CPUdoesn’t need to be concerned with extremely time-sensitive programming,there’s a few situations where it can’t be helped. Some unforgivinghardware may require that certain time-sensitive programming be handledcompletely by the CPU, and said programming may even take too long tohandle in an IRQ handler. Another such situation would be where the driverneeds to perform a task that needs to complete within a specific scanoutperiod, but might possibly block and thus cannot be handled in an IRQcontext. Both of these situations can’t be solved perfectly in Linux sincewe’re not a realtime kernel, and thus the scheduler may cause us to missour deadline if it decides to preempt us. But for some drivers, it’s goodenough if we can lower our chance of being preempted to an absoluteminimum.

This is wheredrm_vblank_work comes in.drm_vblank_work provides a simplegeneric delayed work implementation which delays work execution until aparticular vblank has passed, and then executes the work at realtimepriority. This provides the best possible chance at performingtime-sensitive hardware programming on time, even when the system is underheavy load.drm_vblank_work also supports rescheduling, so that selfre-arming work items can be easily implemented.

Vertical Blank Work Functions Reference¶

structdrm_vblank_work¶: A delayed work item which delays until a target vblank passes, and then executes at realtime priority outside of IRQ context.

Definition

struct drm_vblank_work {  struct kthread_work base;  struct drm_vblank_crtc *vblank;  u64 count;  int cancelling;  struct list_head node;};

Members

base: The basekthread_work item which will be executed bydrm_vblank_crtc.worker. Drivers should not interact with thisdirectly, and instead rely ondrm_vblank_work_init() to initializethis.
vblank: A pointer todrm_vblank_crtc this work item belongs to.
count: The target vblank this work will execute on. Drivers shouldnot modify this value directly, and instead usedrm_vblank_work_schedule()
cancelling: The number ofdrm_vblank_work_cancel_sync() calls thatare currently running. A work item cannot be rescheduled until allcalls have finished.
node: The position of this work item indrm_vblank_crtc.pending_work.

Description

to_drm_vblank_work(_work)¶: Retrieve the respectivedrm_vblank_work item from akthread_work

Parameters

_work: Thekthread_work embedded inside adrm_vblank_work

intdrm_vblank_work_schedule(structdrm_vblank_work * work, u64 count, bool nextonmiss)¶: schedule a vblank work

Parameters

structdrm_vblank_work*work: vblank work to schedule
u64count: target vblank count
boolnextonmiss: defer until the next vblank if target vblank was missed

Description

Schedulework for execution once the crtc vblank count reachescount.

If the crtc vblank count has already reachedcount andnextonmiss isfalse the work starts to execute immediately.

If the crtc vblank count has already reachedcount andnextonmiss istrue the work is deferred until the next vblank (as ifcount has beenspecified as crtc vblank count + 1).

Ifwork is already scheduled, this function will reschedule said workusing the newcount. This can be used for self-rearming work items.

Return

1 ifwork was successfully (re)scheduled,0 if it was either alreadyscheduled or cancelled, or a negative error code on failure.

booldrm_vblank_work_cancel_sync(structdrm_vblank_work * work)¶: cancel a vblank work and wait for it to finish executing

Parameters

structdrm_vblank_work*work: vblank work to cancel

Description

Cancel an already scheduled vblank work and wait for itsexecution to finish.

On return,work is guaranteed to no longer be scheduled or running, evenif it’s self-arming.

Return

True if the work was cancelled before it started to execute,falseotherwise.

voiddrm_vblank_work_flush(structdrm_vblank_work * work)¶: wait for a scheduled vblank work to finish executing

Parameters

structdrm_vblank_work*work: vblank work to flush

Description

Wait untilwork has finished executing once.

voiddrm_vblank_work_init(structdrm_vblank_work * work, structdrm_crtc * crtc, void (*func)(struct kthread_work *work))¶: initialize a vblank work item

Parameters

structdrm_vblank_work*work: vblank work item
structdrm_crtc*crtc: CRTC whose vblank will trigger the work execution
void(*)(structkthread_work*work)func: work function to be executed

Description

Initialize a vblank work item for a specific crtc.

Movatterモバイル変換

Kernel Mode Setting (KMS)¶

Overview¶

KMS Core Structures and Functions¶

Modeset Base Object Abstraction¶

Atomic Mode Setting¶

Handling Driver Private State¶

Atomic Mode Setting Function Reference¶

Atomic Mode Setting IOCTL and UAPI Functions¶

CRTC Abstraction¶

CRTC Functions Reference¶

Frame Buffer Abstraction¶

Frame Buffer Functions Reference¶

DRM Format Handling¶

Format Modifiers¶

Format Functions Reference¶

Dumb Buffer Objects¶

Plane Abstraction¶

Plane Functions Reference¶

Display Modes Function Reference¶

Connector Abstraction¶

Connector Functions Reference¶

Writeback Connectors¶

Encoder Abstraction¶

Encoder Functions Reference¶

KMS Locking¶

KMS Properties¶

Property Types and Blob Property Support¶

Standard Connector Properties¶

HDMI Specific Connector Properties¶

Standard CRTC Properties¶

Plane Composition Properties¶

FB_DAMAGE_CLIPS¶

Color Management Properties¶

Tile Group Property¶

Explicit Fencing Properties¶

Variable Refresh Properties¶

Existing KMS Properties¶

Vertical Blanking¶

Vertical Blanking and Interrupt Handling Functions Reference¶

Vertical Blank Work¶

Vertical Blank Work Functions Reference¶