Modeset Helper Reference for Common Vtables¶

The DRM mode setting helper functions are common code for drivers to use ifthey wish. Drivers are not forced to use this code in theirimplementations but it would be useful if the code they do use at leastprovides a consistent interface and operation to userspace. Therefore it ishighly recommended to use the provided helpers as much as possible.

Because there is only one pointer per modeset object to hold a vfunc tablefor helper libraries they are by necessity shared among the differenthelpers.

To make this clear all the helper vtables are pulled together in this location here.

structdrm_crtc_helper_funcs¶

helper operations for CRTCs

Definition

struct drm_crtc_helper_funcs {  void (*dpms)(struct drm_crtc *crtc, int mode);  void (*prepare)(struct drm_crtc *crtc);  void (*commit)(struct drm_crtc *crtc);  enum drm_mode_status (*mode_valid)(struct drm_crtc *crtc, const struct drm_display_mode *mode);  bool (*mode_fixup)(struct drm_crtc *crtc,const struct drm_display_mode *mode, struct drm_display_mode *adjusted_mode);  int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode, int x, int y, struct drm_framebuffer *old_fb);  void (*mode_set_nofb)(struct drm_crtc *crtc);  int (*mode_set_base)(struct drm_crtc *crtc, int x, int y, struct drm_framebuffer *old_fb);  int (*mode_set_base_atomic)(struct drm_crtc *crtc,struct drm_framebuffer *fb, int x, int y, enum mode_set_atomic);  void (*disable)(struct drm_crtc *crtc);  int (*atomic_check)(struct drm_crtc *crtc, struct drm_crtc_state *state);  void (*atomic_begin)(struct drm_crtc *crtc, struct drm_crtc_state *old_crtc_state);  void (*atomic_flush)(struct drm_crtc *crtc, struct drm_crtc_state *old_crtc_state);  void (*atomic_enable)(struct drm_crtc *crtc, struct drm_crtc_state *old_crtc_state);  void (*atomic_disable)(struct drm_crtc *crtc, struct drm_crtc_state *old_crtc_state);  bool (*get_scanout_position)(struct drm_crtc *crtc,bool in_vblank_irq, int *vpos, int *hpos,ktime_t *stime, ktime_t *etime, const struct drm_display_mode *mode);};

Members

dpms

Callback to control power levels on the CRTC. If the mode passed inis unsupported, the provider must use the next lowest power level.This is used by the legacy CRTC helpers to implement DPMSfunctionality indrm_helper_connector_dpms().

This callback is also used to disable a CRTC by calling it withDRM_MODE_DPMS_OFF if thedisable hook isn’t used.

This callback is used by the legacy CRTC helpers. Atomic helpersalso support using this hook for enabling and disabling a CRTC tofacilitate transitions to atomic, but it is deprecated. Insteadatomic_enable andatomic_disable should be used.

prepare

This callback should prepare the CRTC for a subsequent modeset, whichin practice means the driver should disable the CRTC if it isrunning. Most drivers ended up implementing this by calling theirdpms hook with DRM_MODE_DPMS_OFF.

This callback is used by the legacy CRTC helpers. Atomic helpersalso support using this hook for disabling a CRTC to facilitatetransitions to atomic, but it is deprecated. Insteadatomic_disableshould be used.

commit

This callback should commit the new mode on the CRTC after a modeset,which in practice means the driver should enable the CRTC. Mostdrivers ended up implementing this by calling theirdpms hook withDRM_MODE_DPMS_ON.

This callback is used by the legacy CRTC helpers. Atomic helpersalso support using this hook for enabling a CRTC to facilitatetransitions to atomic, but it is deprecated. Insteadatomic_enableshould be used.

mode_valid

This callback is used to check if a specific mode is valid in thiscrtc. This should be implemented if the crtc has some sort ofrestriction in the modes it can display. For example, a given crtcmay be responsible to set a clock value. If the clock can notproduce all the values for the available modes then this callbackcan be used to restrict the number of modes to only the ones thatcan be displayed.

This hook is used by the probe helpers to filter the mode list indrm_helper_probe_single_connector_modes(), and it is used by theatomic helpers to validate modes supplied by userspace indrm_atomic_helper_check_modeset().

This function is optional.

NOTE:

Since this function is both called from the check phase of an atomiccommit, and the mode validation in the probe paths it is not allowedto look at anything else but the passed-in mode, and validate itagainst configuration-invariant hardward constraints. Any furtherlimits which depend upon the configuration can only be checked inmode_fixup oratomic_check.

RETURNS:

drm_mode_status Enum

mode_fixup

This callback is used to validate a mode. The parameter mode is thedisplay mode that userspace requested, adjusted_mode is the mode theencoders need to be fed with. Note that this is the inverse semanticsof the meaning for thedrm_encoder anddrm_bridge_funcs.mode_fixupvfunc. If the CRTC cannot support the requested conversion from modeto adjusted_mode it should reject the modeset. See alsodrm_crtc_state.adjusted_mode for more details.

This function is used by both legacy CRTC helpers and atomic helpers.With atomic helpers it is optional.

NOTE:

This function is called in the check phase of atomic modesets, whichcan be aborted for any reason (including on userspace’s request tojust check whether a configuration would be possible). Atomic driversMUST NOT touch any persistent state (hardware or software) or datastructures except the passed in adjusted_mode parameter.

This is in contrast to the legacy CRTC helpers where this wasallowed.

Atomic drivers which need to inspect and adjust more state shouldinstead use theatomic_check callback, but note that they’re notperfectly equivalent:mode_valid is called fromdrm_atomic_helper_check_modeset(), butatomic_check is called fromdrm_atomic_helper_check_planes(), because originally it was meant forplane update checks only.

Also beware that userspace can request its own custom modes, neithercore nor helpers filter modes to the list of probe modes reported bythe GETCONNECTOR IOCTL and stored indrm_connector.modes. To ensurethat modes are filtered consistently put any CRTC constraints andlimits checks intomode_valid.

RETURNS:

True if an acceptable configuration is possible, false if the modesetoperation should be rejected.

mode_set

This callback is used by the legacy CRTC helpers to set a new mode,position and framebuffer. Since it ties the primary plane to everymode change it is incompatible with universal plane support. Andsince it can’t update other planes it’s incompatible with atomicmodeset support.

This callback is only used by CRTC helpers and deprecated.

RETURNS:

0 on success or a negative error code on failure.

mode_set_nofb

This callback is used to update the display mode of a CRTC withoutchanging anything of the primary plane configuration. This fits therequirement of atomic and hence is used by the atomic helpers. It isalso used by the transitional plane helpers to implement amode_set hook in drm_helper_crtc_mode_set().

Note that the display pipe is completely off when this function iscalled. Atomic drivers which need hardware to be running before theyprogram the new display mode (e.g. because they implement runtime PM)should not use this hook. This is because the helper library callsthis hook only once per mode change and not every time the displaypipeline is suspended using either DPMS or the new “ACTIVE” property.Which means register values set in this callback might get reset whenthe CRTC is suspended, but not restored. Such drivers should insteadmove all their CRTC setup into theatomic_enable callback.

This callback is optional.

mode_set_base

This callback is used by the legacy CRTC helpers to set a newframebuffer and scanout position. It is optional and used as anoptimized fast-path instead of a full mode set operation with all theresulting flickering. If it is not presentdrm_crtc_helper_set_config() will fall back to a full modeset, usingthemode_set callback. Since it can’t update other planes it’sincompatible with atomic modeset support.

This callback is only used by the CRTC helpers and deprecated.

RETURNS:

0 on success or a negative error code on failure.

mode_set_base_atomic

This callback is used by the fbdev helpers to set a new framebufferand scanout without sleeping, i.e. from an atomic calling context. Itis only used to implement kgdb support.

This callback is optional and only needed for kgdb support in the fbdevhelpers.

RETURNS:

0 on success or a negative error code on failure.

disable

This callback should be used to disable the CRTC. With the atomicdrivers it is called after all encoders connected to this CRTC havebeen shut off already using their owndrm_encoder_helper_funcs.disable hook. If that sequence is toosimple drivers can just add their own hooks and call it from thisCRTC callback here by looping over all encoders connected to it usingfor_each_encoder_on_crtc().

This hook is used both by legacy CRTC helpers and atomic helpers.Atomic drivers don’t need to implement it if there’s no need todisable anything at the CRTC level. To ensure that runtime PMhandling (using either DPMS or the new “ACTIVE” property) worksdisable must be the inverse ofatomic_enable for atomic drivers.Atomic drivers should consider to useatomic_disable instead ofthis one.

NOTE:

With legacy CRTC helpers there’s a big semantic difference betweendisable and other hooks (likeprepare ordpms) used to shut down aCRTC:disable is only called when also logically disabling thedisplay pipeline and needs to release any resources acquired inmode_set (like shared PLLs, or again release pinned framebuffers).

Thereforedisable must be the inverse ofmode_set pluscommit fordrivers still using legacy CRTC helpers, which is different from therules under atomic.

atomic_check

Drivers should check plane-update related CRTC constraints in thishook. They can also check mode related limitations but need to beaware of the calling order, since this hook is used bydrm_atomic_helper_check_planes() whereas the preparations needed tocheck output routing and the display mode is done indrm_atomic_helper_check_modeset(). Therefore drivers that want tocheck output routing and display mode constraints in this callbackmust ensure thatdrm_atomic_helper_check_modeset() has been calledbeforehand. This is calling order used by the default helperimplementation indrm_atomic_helper_check().

When usingdrm_atomic_helper_check_planes() this hook is calledafter thedrm_plane_helper_funcs.atomic_check hook for planes, whichallows drivers to assign shared resources requested by planes in thiscallback here. For more complicated dependencies the driver can callthe provided check helpers multiple times until the computed statehas a final configuration and everything has been checked.

This function is also allowed to inspect any other object’s state andcan add more state objects to the atomic commit if needed. Care mustbe taken though to ensure that state check and compute functions forthese added states are all called, and derived state in other objectsall updated. Again the recommendation is to just call check helpersuntil a maximal configuration is reached.

This callback is used by the atomic modeset helpers and by thetransitional plane helpers, but it is optional.

NOTE:

This function is called in the check phase of an atomic update. Thedriver is not allowed to change anything outside of the free-standingstate objects passed-in or assembled in the overalldrm_atomic_stateupdate tracking structure.

Also beware that userspace can request its own custom modes, neithercore nor helpers filter modes to the list of probe modes reported bythe GETCONNECTOR IOCTL and stored indrm_connector.modes. To ensurethat modes are filtered consistently put any CRTC constraints andlimits checks intomode_valid.

RETURNS:

0 on success, -EINVAL if the state or the transition can’t besupported, -ENOMEM on memory allocation failure and -EDEADLK if anattempt to obtain another state object ran into adrm_modeset_lockdeadlock.

atomic_begin

Drivers should prepare for an atomic update of multiple planes ona CRTC in this hook. Depending upon hardware this might be vblankevasion, blocking updates by setting bits or doing preparatory workfor e.g. manual update display.

This hook is called before any plane commit functions are called.

Note that the power state of the display pipe when this function iscalled depends upon the exact helpers and calling sequence the driverhas picked. Seedrm_atomic_helper_commit_planes() for a discussion ofthe tradeoffs and variants of plane commit helpers.

This callback is used by the atomic modeset helpers and by thetransitional plane helpers, but it is optional.

atomic_flush

Drivers should finalize an atomic update of multiple planes ona CRTC in this hook. Depending upon hardware this might includechecking that vblank evasion was successful, unblocking updates bysetting bits or setting the GO bit to flush out all updates.

Simple hardware or hardware with special requirements can commit andflush out all updates for all planes from this hook and forgo all theother commit hooks for plane updates.

This hook is called after any plane commit functions are called.

Note that the power state of the display pipe when this function iscalled depends upon the exact helpers and calling sequence the driverhas picked. Seedrm_atomic_helper_commit_planes() for a discussion ofthe tradeoffs and variants of plane commit helpers.

This callback is used by the atomic modeset helpers and by thetransitional plane helpers, but it is optional.

atomic_enable

This callback should be used to enable the CRTC. With the atomicdrivers it is called before all encoders connected to this CRTC areenabled through the encoder’s owndrm_encoder_helper_funcs.enablehook. If that sequence is too simple drivers can just add their ownhooks and call it from this CRTC callback here by looping over allencoders connected to it using for_each_encoder_on_crtc().

This hook is used only by atomic helpers, for symmetry withatomic_disable. Atomic drivers don’t need to implement it if there’sno need to enable anything at the CRTC level. To ensure that runtimePM handling (using either DPMS or the new “ACTIVE” property) worksatomic_enable must be the inverse ofatomic_disable for atomicdrivers.

Drivers can use theold_crtc_state input parameter if the operationsneeded to enable the CRTC don’t depend solely on the new state butalso on the transition between the old state and the new state.

This function is optional.

atomic_disable

This callback should be used to disable the CRTC. With the atomicdrivers it is called after all encoders connected to this CRTC havebeen shut off already using their owndrm_encoder_helper_funcs.disable hook. If that sequence is toosimple drivers can just add their own hooks and call it from thisCRTC callback here by looping over all encoders connected to it usingfor_each_encoder_on_crtc().

This hook is used only by atomic helpers. Atomic drivers don’tneed to implement it if there’s no need to disable anything at theCRTC level.

Comparing todisable, this one provides the additional inputparameterold_crtc_state which could be used to access the oldstate. Atomic drivers should consider to use this one insteadofdisable.

This function is optional.

get_scanout_position

Called by vblank timestamping code.

Returns the current display scanout position from a CRTC and anoptional accuratektime_get() timestamp of when the position wasmeasured. Note that this is a helper callback which is only usedif a driver usesdrm_crtc_vblank_helper_get_vblank_timestamp()for thedrm_crtc_funcs.get_vblank_timestamp callback.

Parameters:

crtc:

The CRTC.

in_vblank_irq:

True when called fromdrm_crtc_handle_vblank(). Some driversneed to apply some workarounds for gpu-specific vblank irqquirks if the flag is set.

vpos:

Target location for current vertical scanout position.

hpos:

Target location for current horizontal scanout position.

stime:

Target location for timestamp taken immediately beforescanout position query. Can be NULL to skip timestamp.

etime:

Target location for timestamp taken immediately afterscanout position query. Can be NULL to skip timestamp.

mode:

Current display timings.

Returns vpos as a positive number while in active scanout area.Returns vpos as a negative number inside vblank, counting the numberof scanlines to go until end of vblank, e.g., -1 means “one scanlineuntil start of active scanout / end of vblank.”

Returns:

True on success, false if a reliable scanout position counter couldnot be read out.

Description

These hooks are used by the legacy CRTC helpers, the transitional planehelpers and the new atomic modesetting helpers.

voiddrm_crtc_helper_add(structdrm_crtc * crtc, const structdrm_crtc_helper_funcs * funcs)¶

sets the helper vtable for a crtc

Parameters

structdrm_crtc*crtc

DRM CRTC

conststructdrm_crtc_helper_funcs*funcs

helper vtable to set forcrtc

structdrm_encoder_helper_funcs¶

helper operations for encoders

Definition

struct drm_encoder_helper_funcs {  void (*dpms)(struct drm_encoder *encoder, int mode);  enum drm_mode_status (*mode_valid)(struct drm_encoder *crtc, const struct drm_display_mode *mode);  bool (*mode_fixup)(struct drm_encoder *encoder,const struct drm_display_mode *mode, struct drm_display_mode *adjusted_mode);  void (*prepare)(struct drm_encoder *encoder);  void (*commit)(struct drm_encoder *encoder);  void (*mode_set)(struct drm_encoder *encoder,struct drm_display_mode *mode, struct drm_display_mode *adjusted_mode);  void (*atomic_mode_set)(struct drm_encoder *encoder,struct drm_crtc_state *crtc_state, struct drm_connector_state *conn_state);  enum drm_connector_status (*detect)(struct drm_encoder *encoder, struct drm_connector *connector);  void (*atomic_disable)(struct drm_encoder *encoder, struct drm_atomic_state *state);  void (*atomic_enable)(struct drm_encoder *encoder, struct drm_atomic_state *state);  void (*disable)(struct drm_encoder *encoder);  void (*enable)(struct drm_encoder *encoder);  int (*atomic_check)(struct drm_encoder *encoder,struct drm_crtc_state *crtc_state, struct drm_connector_state *conn_state);};

Members

dpms

Callback to control power levels on the encoder. If the mode passed inis unsupported, the provider must use the next lowest power level.This is used by the legacy encoder helpers to implement DPMSfunctionality indrm_helper_connector_dpms().

This callback is also used to disable an encoder by calling it withDRM_MODE_DPMS_OFF if thedisable hook isn’t used.

This callback is used by the legacy CRTC helpers. Atomic helpersalso support using this hook for enabling and disabling an encoder tofacilitate transitions to atomic, but it is deprecated. Insteadenable anddisable should be used.

mode_valid

This callback is used to check if a specific mode is valid in thisencoder. This should be implemented if the encoder has some sortof restriction in the modes it can display. For example, a givenencoder may be responsible to set a clock value. If the clock cannot produce all the values for the available modes then this callbackcan be used to restrict the number of modes to only the ones thatcan be displayed.

This hook is used by the probe helpers to filter the mode list indrm_helper_probe_single_connector_modes(), and it is used by theatomic helpers to validate modes supplied by userspace indrm_atomic_helper_check_modeset().

This function is optional.

NOTE:

Since this function is both called from the check phase of an atomiccommit, and the mode validation in the probe paths it is not allowedto look at anything else but the passed-in mode, and validate itagainst configuration-invariant hardward constraints. Any furtherlimits which depend upon the configuration can only be checked inmode_fixup oratomic_check.

RETURNS:

drm_mode_status Enum

mode_fixup

This callback is used to validate and adjust a mode. The parametermode is the display mode that should be fed to the next element inthe display chain, either the finaldrm_connector or adrm_bridge.The parameter adjusted_mode is the input mode the encoder requires. Itcan be modified by this callback and does not need to match mode. Seealsodrm_crtc_state.adjusted_mode for more details.

This function is used by both legacy CRTC helpers and atomic helpers.This hook is optional.

NOTE:

This function is called in the check phase of atomic modesets, whichcan be aborted for any reason (including on userspace’s request tojust check whether a configuration would be possible). Atomic driversMUST NOT touch any persistent state (hardware or software) or datastructures except the passed in adjusted_mode parameter.

This is in contrast to the legacy CRTC helpers where this wasallowed.

Atomic drivers which need to inspect and adjust more state shouldinstead use theatomic_check callback. Ifatomic_check is used,this hook isn’t called sinceatomic_check allows a strict supersetof the functionality ofmode_fixup.

Also beware that userspace can request its own custom modes, neithercore nor helpers filter modes to the list of probe modes reported bythe GETCONNECTOR IOCTL and stored indrm_connector.modes. To ensurethat modes are filtered consistently put any encoder constraints andlimits checks intomode_valid.

RETURNS:

True if an acceptable configuration is possible, false if the modesetoperation should be rejected.

prepare

This callback should prepare the encoder for a subsequent modeset,which in practice means the driver should disable the encoder if itis running. Most drivers ended up implementing this by calling theirdpms hook with DRM_MODE_DPMS_OFF.

This callback is used by the legacy CRTC helpers. Atomic helpersalso support using this hook for disabling an encoder to facilitatetransitions to atomic, but it is deprecated. Insteaddisable shouldbe used.

commit

This callback should commit the new mode on the encoder after a modeset,which in practice means the driver should enable the encoder. Mostdrivers ended up implementing this by calling theirdpms hook withDRM_MODE_DPMS_ON.

This callback is used by the legacy CRTC helpers. Atomic helpersalso support using this hook for enabling an encoder to facilitatetransitions to atomic, but it is deprecated. Insteadenable shouldbe used.

mode_set

This callback is used to update the display mode of an encoder.

Note that the display pipe is completely off when this function iscalled. Drivers which need hardware to be running before they programthe new display mode (because they implement runtime PM) should notuse this hook, because the helper library calls it only once and notevery time the display pipeline is suspend using either DPMS or thenew “ACTIVE” property. Such drivers should instead move all theirencoder setup into theenable callback.

This callback is used both by the legacy CRTC helpers and the atomicmodeset helpers. It is optional in the atomic helpers.

NOTE:

If the driver uses the atomic modeset helpers and needs to inspectthe connector state or connector display info during mode setting,atomic_mode_set can be used instead.

atomic_mode_set

This callback is used to update the display mode of an encoder.

Note that the display pipe is completely off when this function iscalled. Drivers which need hardware to be running before they programthe new display mode (because they implement runtime PM) should notuse this hook, because the helper library calls it only once and notevery time the display pipeline is suspended using either DPMS or thenew “ACTIVE” property. Such drivers should instead move all theirencoder setup into theenable callback.

This callback is used by the atomic modeset helpers in place of themode_set callback, if set by the driver. It is optional and shouldbe used instead ofmode_set if the driver needs to inspect theconnector state or display info, since there is no direct way togo from the encoder to the current connector.

detect

This callback can be used by drivers who want to do detection on theencoder object instead of in connector functions.

It is not used by any helper and therefore has purely driver-specificsemantics. New drivers shouldn’t use this and instead just implementtheir own private callbacks.

FIXME:

This should just be converted into a pile of driver vfuncs.Currently radeon, amdgpu and nouveau are using it.

atomic_disable

This callback should be used to disable the encoder. With the atomicdrivers it is called before this encoder’s CRTC has been shut offusing their owndrm_crtc_helper_funcs.atomic_disable hook. If thatsequence is too simple drivers can just add their own driver privateencoder hooks and call them from CRTC’s callback by looping over allencoders connected to it using for_each_encoder_on_crtc().

This callback is a variant ofdisable that provides the atomic stateto the driver. Ifatomic_disable is implemented,disable is notcalled by the helpers.

This hook is only used by atomic helpers. Atomic drivers don’t needto implement it if there’s no need to disable anything at the encoderlevel. To ensure that runtime PM handling (using either DPMS or thenew “ACTIVE” property) worksatomic_disable must be the inverse ofatomic_enable.

atomic_enable

This callback should be used to enable the encoder. It is calledafter this encoder’s CRTC has been enabled using their owndrm_crtc_helper_funcs.atomic_enable hook. If that sequence istoo simple drivers can just add their own driver private encoderhooks and call them from CRTC’s callback by looping over all encodersconnected to it using for_each_encoder_on_crtc().

This callback is a variant ofenable that provides the atomic stateto the driver. Ifatomic_enable is implemented,enable is notcalled by the helpers.

This hook is only used by atomic helpers, it is the opposite ofatomic_disable. Atomic drivers don’t need to implement it if there’sno need to enable anything at the encoder level. To ensure thatruntime PM handling worksatomic_enable must be the inverse ofatomic_disable.

disable

This callback should be used to disable the encoder. With the atomicdrivers it is called before this encoder’s CRTC has been shut offusing their owndrm_crtc_helper_funcs.disable hook. If thatsequence is too simple drivers can just add their own driver privateencoder hooks and call them from CRTC’s callback by looping over allencoders connected to it using for_each_encoder_on_crtc().

This hook is used both by legacy CRTC helpers and atomic helpers.Atomic drivers don’t need to implement it if there’s no need todisable anything at the encoder level. To ensure that runtime PMhandling (using either DPMS or the new “ACTIVE” property) worksdisable must be the inverse ofenable for atomic drivers.

For atomic drivers also consideratomic_disable and save yourselffrom having to read the NOTE below!

NOTE:

With legacy CRTC helpers there’s a big semantic difference betweendisable and other hooks (likeprepare ordpms) used to shut down aencoder:disable is only called when also logically disabling thedisplay pipeline and needs to release any resources acquired inmode_set (like shared PLLs, or again release pinned framebuffers).

Thereforedisable must be the inverse ofmode_set pluscommit fordrivers still using legacy CRTC helpers, which is different from therules under atomic.

enable

This callback should be used to enable the encoder. With the atomicdrivers it is called after this encoder’s CRTC has been enabled usingtheir owndrm_crtc_helper_funcs.enable hook. If that sequence istoo simple drivers can just add their own driver private encoderhooks and call them from CRTC’s callback by looping over all encodersconnected to it using for_each_encoder_on_crtc().

This hook is only used by atomic helpers, it is the opposite ofdisable. Atomic drivers don’t need to implement it if there’s noneed to enable anything at the encoder level. To ensure thatruntime PM handling (using either DPMS or the new “ACTIVE” property)worksenable must be the inverse ofdisable for atomic drivers.

atomic_check

This callback is used to validate encoder state for atomic drivers.Since the encoder is the object connecting the CRTC and connector itgets passed both states, to be able to validate interactions andupdate the CRTC to match what the encoder needs for the requestedconnector.

Since this provides a strict superset of the functionality ofmode_fixup (the requested and adjusted modes are both availablethrough the passed instructdrm_crtc_state)mode_fixup is notcalled whenatomic_check is implemented.

This function is used by the atomic helpers, but it is optional.

NOTE:

This function is called in the check phase of an atomic update. Thedriver is not allowed to change anything outside of the free-standingstate objects passed-in or assembled in the overalldrm_atomic_stateupdate tracking structure.

Also beware that userspace can request its own custom modes, neithercore nor helpers filter modes to the list of probe modes reported bythe GETCONNECTOR IOCTL and stored indrm_connector.modes. To ensurethat modes are filtered consistently put any encoder constraints andlimits checks intomode_valid.

RETURNS:

0 on success, -EINVAL if the state or the transition can’t besupported, -ENOMEM on memory allocation failure and -EDEADLK if anattempt to obtain another state object ran into adrm_modeset_lockdeadlock.

Description

These hooks are used by the legacy CRTC helpers, the transitional planehelpers and the new atomic modesetting helpers.

voiddrm_encoder_helper_add(structdrm_encoder * encoder, const structdrm_encoder_helper_funcs * funcs)¶

sets the helper vtable for an encoder

Parameters

structdrm_encoder*encoder

DRM encoder

conststructdrm_encoder_helper_funcs*funcs

helper vtable to set forencoder

structdrm_connector_helper_funcs¶

helper operations for connectors

Definition

struct drm_connector_helper_funcs {  int (*get_modes)(struct drm_connector *connector);  int (*detect_ctx)(struct drm_connector *connector,struct drm_modeset_acquire_ctx *ctx, bool force);  enum drm_mode_status (*mode_valid)(struct drm_connector *connector, struct drm_display_mode *mode);  int (*mode_valid_ctx)(struct drm_connector *connector,struct drm_display_mode *mode,struct drm_modeset_acquire_ctx *ctx, enum drm_mode_status *status);  struct drm_encoder *(*best_encoder)(struct drm_connector *connector);  struct drm_encoder *(*atomic_best_encoder)(struct drm_connector *connector, struct drm_connector_state *connector_state);  int (*atomic_check)(struct drm_connector *connector, struct drm_atomic_state *state);  void (*atomic_commit)(struct drm_connector *connector, struct drm_connector_state *state);  int (*prepare_writeback_job)(struct drm_writeback_connector *connector, struct drm_writeback_job *job);  void (*cleanup_writeback_job)(struct drm_writeback_connector *connector, struct drm_writeback_job *job);};

Members

get_modes

This function should fill in all modes currently valid for the sinkinto thedrm_connector.probed_modes list. It should also update theEDID property by callingdrm_connector_update_edid_property().

The usual way to implement this is to cache the EDID retrieved in theprobe callback somewhere in the driver-private connector structure.In this function drivers then parse the modes in the EDID and addthem by callingdrm_add_edid_modes(). But connectors that driver afixed panel can also manually add specific modes usingdrm_mode_probed_add(). Drivers which manually add modes should alsomake sure that thedrm_connector.display_info,drm_connector.width_mm anddrm_connector.height_mm fields arefilled in.

Virtual drivers that just want some standard VESA mode with a givenresolution can calldrm_add_modes_noedid(), and mark the preferredone usingdrm_set_preferred_mode().

This function is only called after thedetect hook has indicatedthat a sink is connected and when the EDID isn’t overridden throughsysfs or the kernel commandline.

This callback is used by the probe helpers in e.g.drm_helper_probe_single_connector_modes().

To avoid races with concurrent connector state updates, the helperlibraries always call this with thedrm_mode_config.connection_mutexheld. Because of this it’s safe to inspectdrm_connector->state.

RETURNS:

The number of modes added by callingdrm_mode_probed_add().

detect_ctx

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.

This is the atomic version ofdrm_connector_funcs.detect.

To avoid races against concurrent connector state updates, thehelper libraries always call this with ctx set to a valid context,anddrm_mode_config.connection_mutex will always be locked withthe ctx parameter set to this ctx. This allows taking additionallocks as required.

RETURNS:

drm_connector_status indicating the connector’s status,or the error code returned bydrm_modeset_lock(), -EDEADLK.

mode_valid

Callback to validate a mode for a connector, irrespective of thespecific display configuration.

This callback is used by the probe helpers to filter the mode list(which is usually derived from the EDID data block from the sink).See e.g.drm_helper_probe_single_connector_modes().

This function is optional.

NOTE:

This only filters the mode list supplied to userspace in theGETCONNECTOR IOCTL. Compared todrm_encoder_helper_funcs.mode_valid,drm_crtc_helper_funcs.mode_valid anddrm_bridge_funcs.mode_valid,which are also called by the atomic helpers fromdrm_atomic_helper_check_modeset(). This allows userspace to force andignore sink constraint (like the pixel clock limits in the screen’sEDID), which is useful for e.g. testing, or working around a brokenEDID. Any source hardware constraint (which always need to beenforced) therefore should be checked in one of the above callbacks,and not this one here.

To avoid races with concurrent connector state updates, the helperlibraries always call this with thedrm_mode_config.connection_mutexheld. Because of this it’s safe to inspectdrm_connector->state.

RETURNS:

Eitherdrm_mode_status.MODE_OK or one of the failure reasons inenumdrm_mode_status.

mode_valid_ctx

Callback to validate a mode for a connector, irrespective of thespecific display configuration.

This callback is used by the probe helpers to filter the mode list(which is usually derived from the EDID data block from the sink).See e.g.drm_helper_probe_single_connector_modes().

This function is optional, and is the atomic version ofdrm_connector_helper_funcs.mode_valid.

To allow for accessing the atomic state of modesetting objects, thehelper libraries always call this with ctx set to a valid context,anddrm_mode_config.connection_mutex will always be locked withthe ctx parameter set toctx. This allows for taking additionallocks as required.

Even though additional locks may be acquired, this callback isstill expected not to take any constraints into account which wouldbe influenced by the currently set display state - such constraintsshould be handled in the driver’s atomic check. For example, if aconnector shares display bandwidth with other connectors then itwould be ok to validate the minimum bandwidth requirement of a modeagainst the maximum possible bandwidth of the connector. But itwouldn’t be ok to take the current bandwidth usage of otherconnectors into account, as this would change depending on thedisplay state.

Returns:0 ifdrm_connector_helper_funcs.mode_valid_ctx succeeded and wrotetheenumdrm_mode_status value tostatus, or a negative errorcode otherwise.

best_encoder

This function should select the best encoder for the given connector.

This function is used by both the atomic helpers (in thedrm_atomic_helper_check_modeset() function) and in the legacy CRTChelpers.

NOTE:

In atomic drivers this function is called in the check phase of anatomic update. The driver is not allowed to change or inspectanything outside of arguments passed-in. Atomic drivers which need toinspect dynamic configuration state should instead useatomic_best_encoder.

You can leave this function to NULL if the connector is onlyattached to a single encoder. In this case, the core will calldrm_connector_get_single_encoder() for you.

RETURNS:

Encoder that should be used for the given connector and connectorstate, or NULL if no suitable encoder exists. Note that the helperswill ensure that encoders aren’t used twice, drivers should not checkfor this.

atomic_best_encoder

This is the atomic version ofbest_encoder for atomic drivers whichneed to select the best encoder depending upon the desiredconfiguration and can’t select it statically.

This function is used bydrm_atomic_helper_check_modeset().If it is not implemented, the core will fallback tobest_encoder(or drm_connector_get_single_encoder() ifbest_encoder is NULL).

NOTE:

This function is called in the check phase of an atomic update. Thedriver is not allowed to change anything outside of the free-standingstate objects passed-in or assembled in the overalldrm_atomic_stateupdate tracking structure.

RETURNS:

Encoder that should be used for the given connector and connectorstate, or NULL if no suitable encoder exists. Note that the helperswill ensure that encoders aren’t used twice, drivers should not checkfor this.

atomic_check

This hook is used to validate connector state. This function iscalled fromdrm_atomic_helper_check_modeset, and is called whena connector property is set, or a modeset on the crtc is forced.

Becausedrm_atomic_helper_check_modeset may be called multiple times,this function should handle being called multiple times as well.

This function is also allowed to inspect any other object’s state andcan add more state objects to the atomic commit if needed. Care mustbe taken though to ensure that state check and compute functions forthese added states are all called, and derived state in other objectsall updated. Again the recommendation is to just call check helpersuntil a maximal configuration is reached.

NOTE:

This function is called in the check phase of an atomic update. Thedriver is not allowed to change anything outside of the free-standingstate objects passed-in or assembled in the overalldrm_atomic_stateupdate tracking structure.

RETURNS:

0 on success, -EINVAL if the state or the transition can’t besupported, -ENOMEM on memory allocation failure and -EDEADLK if anattempt to obtain another state object ran into adrm_modeset_lockdeadlock.

atomic_commit

This hook is to be used by drivers implementing writeback connectorsthat need a point when to commit the writeback job to the hardware.The writeback_job to commit is available indrm_connector_state.writeback_job.

This hook is optional.

This callback is used by the atomic modeset helpers.

prepare_writeback_job

As writeback jobs contain a framebuffer, drivers may need toprepare and clean them up the same way they can prepare andclean up framebuffers for planes. This optional connector operationis used to support the preparation of writeback jobs. The jobprepare operation is called fromdrm_atomic_helper_prepare_planes()for structdrm_writeback_connector connectors only.

This operation is optional.

This callback is used by the atomic modeset helpers.

cleanup_writeback_job

This optional connector operation is used to support thecleanup of writeback jobs. The job cleanup operation is calledfrom the existing drm_writeback_cleanup_job() function, invokedboth when destroying the job as part of an aborted commit, or whenthe job completes.

This operation is optional.

This callback is used by the atomic modeset helpers.

Description

These functions are used by the atomic and legacy modeset helpers and by theprobe helpers.

voiddrm_connector_helper_add(structdrm_connector * connector, const structdrm_connector_helper_funcs * funcs)¶

sets the helper vtable for a connector

Parameters

structdrm_connector*connector

DRM connector

conststructdrm_connector_helper_funcs*funcs

helper vtable to set forconnector

structdrm_plane_helper_funcs¶

helper operations for planes

Definition

struct drm_plane_helper_funcs {  int (*prepare_fb)(struct drm_plane *plane, struct drm_plane_state *new_state);  void (*cleanup_fb)(struct drm_plane *plane, struct drm_plane_state *old_state);  int (*atomic_check)(struct drm_plane *plane, struct drm_plane_state *state);  void (*atomic_update)(struct drm_plane *plane, struct drm_plane_state *old_state);  void (*atomic_disable)(struct drm_plane *plane, struct drm_plane_state *old_state);  int (*atomic_async_check)(struct drm_plane *plane, struct drm_plane_state *state);  void (*atomic_async_update)(struct drm_plane *plane, struct drm_plane_state *new_state);};

Members

prepare_fb

This hook is to prepare a framebuffer for scanout by e.g. pinningits backing storage or relocating it into a contiguous block ofVRAM. Other possible preparatory work includes flushing caches.

This function must not block for outstanding rendering, since it iscalled in the context of the atomic IOCTL even for async commits tobe able to return any errors to userspace. Instead the recommendedway is to fill out thedrm_plane_state.fence of the passed-indrm_plane_state. If the driver doesn’t support native fences thenequivalent functionality should be implemented through privatemembers in the plane structure.

Drivers which always have their buffers pinned should usedrm_gem_fb_prepare_fb() for this hook.

The helpers will callcleanup_fb with matching arguments for everysuccessful call to this hook.

This callback is used by the atomic modeset helpers and by thetransitional plane helpers, but it is optional.

RETURNS:

0 on success or one of the following negative error codes allowed bythedrm_mode_config_funcs.atomic_commit vfunc. When using helpersthis callback is the only one which can fail an atomic commit,everything else must complete successfully.

cleanup_fb

This hook is called to clean up any resources allocated for the givenframebuffer and plane configuration inprepare_fb.

This callback is used by the atomic modeset helpers and by thetransitional plane helpers, but it is optional.

atomic_check

Drivers should check plane specific constraints in this hook.

When usingdrm_atomic_helper_check_planes() plane’satomic_checkhooks are called before the ones for CRTCs, which allows drivers torequest shared resources that the CRTC controls here. For morecomplicated dependencies the driver can call the provided check helpersmultiple times until the computed state has a final configuration andeverything has been checked.

This function is also allowed to inspect any other object’s state andcan add more state objects to the atomic commit if needed. Care mustbe taken though to ensure that state check and compute functions forthese added states are all called, and derived state in other objectsall updated. Again the recommendation is to just call check helpersuntil a maximal configuration is reached.

This callback is used by the atomic modeset helpers and by thetransitional plane helpers, but it is optional.

NOTE:

This function is called in the check phase of an atomic update. Thedriver is not allowed to change anything outside of the free-standingstate objects passed-in or assembled in the overalldrm_atomic_stateupdate tracking structure.

RETURNS:

0 on success, -EINVAL if the state or the transition can’t besupported, -ENOMEM on memory allocation failure and -EDEADLK if anattempt to obtain another state object ran into adrm_modeset_lockdeadlock.

atomic_update

Drivers should use this function to update the plane state. Thishook is called in-between thedrm_crtc_helper_funcs.atomic_begin anddrm_crtc_helper_funcs.atomic_flush callbacks.

Note that the power state of the display pipe when this function iscalled depends upon the exact helpers and calling sequence the driverhas picked. Seedrm_atomic_helper_commit_planes() for a discussion ofthe tradeoffs and variants of plane commit helpers.

This callback is used by the atomic modeset helpers and by thetransitional plane helpers, but it is optional.

atomic_disable

Drivers should use this function to unconditionally disable a plane.This hook is called in-between thedrm_crtc_helper_funcs.atomic_begin anddrm_crtc_helper_funcs.atomic_flush callbacks. It is an alternative toatomic_update, which will be called for disabling planes, too, iftheatomic_disable hook isn’t implemented.

This hook is also useful to disable planes in preparation of a modeset,by callingdrm_atomic_helper_disable_planes_on_crtc() from thedrm_crtc_helper_funcs.disable hook.

Note that the power state of the display pipe when this function iscalled depends upon the exact helpers and calling sequence the driverhas picked. Seedrm_atomic_helper_commit_planes() for a discussion ofthe tradeoffs and variants of plane commit helpers.

This callback is used by the atomic modeset helpers and by thetransitional plane helpers, but it is optional.

atomic_async_check

Drivers should set this function pointer to check if the plane statecan be updated in a async fashion. Here async means “not vblanksynchronized”.

This hook is called by drm_atomic_async_check() to establish if agiven update can be committed asynchronously, that is, if it canjump ahead of the state currently queued for update.

RETURNS:

Return 0 on success and any error returned indicates that the updatecan not be applied in asynchronous manner.

atomic_async_update

Drivers should set this function pointer to perform asynchronousupdates of planes, that is, jump ahead of the currently queuedstate and update the plane. Here async means “not vblanksynchronized”.

This hook is called bydrm_atomic_helper_async_commit().

An async update will happen on legacy cursor updates. An asyncupdate won’t happen if there is an outstanding commit modifyingthe same plane.

Note that unlikedrm_plane_helper_funcs.atomic_update this hooktakes the newdrm_plane_state as parameter. When doing async_updatedrivers shouldn’t replace thedrm_plane_state but update thecurrent one with the new plane configurations in the newplane_state.

Drivers should also swap the framebuffers between current planestate (drm_plane.state) and new_state.This is required since cleanup for async commits is performed onthe new state, rather than old state like for traditional commits.Since we want to give up the reference on the current (old) fbinstead of our brand new one, swap them in the driver during theasync commit.

FIXME:

• It only works for single plane updates
• Async Pageflips are not supported yet
• Some hw might still scan out the old buffer until the nextvblank, however we let go of the fb references as soon aswe run this hook. For now drivers must implement their own workersfor deferring if needed, until a common solution is created.

Description

These functions are used by the atomic helpers and by the transitional planehelpers.

voiddrm_plane_helper_add(structdrm_plane * plane, const structdrm_plane_helper_funcs * funcs)¶

sets the helper vtable for a plane

Parameters

structdrm_plane*plane

DRM plane

conststructdrm_plane_helper_funcs*funcs

helper vtable to set forplane

structdrm_mode_config_helper_funcs¶

global modeset helper operations

Definition

struct drm_mode_config_helper_funcs {  void (*atomic_commit_tail)(struct drm_atomic_state *state);};

Members

atomic_commit_tail

This hook is used by the default atomic_commit() hook implemented indrm_atomic_helper_commit() together with the nonblocking commithelpers (seedrm_atomic_helper_setup_commit() for a starting point)to implement blocking and nonblocking commits easily. It is not usedby the atomic helpers

This function is called when the new atomic state has already beenswapped into the various state pointers. The passed in statetherefore contains copies of the old/previous state. This hook shouldcommit the new state into hardware. Note that the helpers havealready waited for preceeding atomic commits and fences, but driverscan add more waiting calls at the start of their implementation, e.g.to wait for driver-internal request for implicit syncing, beforestarting to commit the update to the hardware.

After the atomic update is committed to the hardware this hook needsto calldrm_atomic_helper_commit_hw_done(). Then wait for the upateto be executed by the hardware, for example usingdrm_atomic_helper_wait_for_vblanks() ordrm_atomic_helper_wait_for_flip_done(), and then clean up the oldframebuffers usingdrm_atomic_helper_cleanup_planes().

When disabling a CRTC this hook _must_ stall for the commit tocomplete. Vblank waits don’t work on disabled CRTC, hence the corecan’t take care of this. And it also can’t rely on the vblank event,since that can be signalled already when the screen shows black,which can happen much earlier than the last hardware access needed toshut off the display pipeline completely.

This hook is optional, the default implementation isdrm_atomic_helper_commit_tail().

Description

These helper functions are used by the atomic helpers.

Atomic Modeset Helper Functions Reference¶

Simple KMS Helper Reference¶

This helper library provides helpers for drivers for simple displayhardware.

drm_simple_display_pipe_init() initializes a simple display pipelinewhich has only one full-screen scanout buffer feeding one output. Thepipeline is represented bystructdrm_simple_display_pipe and bindstogetherdrm_plane,drm_crtc anddrm_encoder structures into one fixedentity. Some flexibility for code reuse is provided through a separatelyallocateddrm_connector object and supporting optionaldrm_bridgeencoder drivers.

Many drivers require only a very simple encoder that fulfills the minimumrequirements of the display pipeline and does not add additionalfunctionality. The functiondrm_simple_encoder_init() provides animplementation of such an encoder.

structdrm_simple_display_pipe_funcs¶

helper operations for a simple display pipeline

Definition

struct drm_simple_display_pipe_funcs {  enum drm_mode_status (*mode_valid)(struct drm_simple_display_pipe *pipe, const struct drm_display_mode *mode);  void (*enable)(struct drm_simple_display_pipe *pipe,struct drm_crtc_state *crtc_state, struct drm_plane_state *plane_state);  void (*disable)(struct drm_simple_display_pipe *pipe);  int (*check)(struct drm_simple_display_pipe *pipe,struct drm_plane_state *plane_state, struct drm_crtc_state *crtc_state);  void (*update)(struct drm_simple_display_pipe *pipe, struct drm_plane_state *old_plane_state);  int (*prepare_fb)(struct drm_simple_display_pipe *pipe, struct drm_plane_state *plane_state);  void (*cleanup_fb)(struct drm_simple_display_pipe *pipe, struct drm_plane_state *plane_state);  int (*enable_vblank)(struct drm_simple_display_pipe *pipe);  void (*disable_vblank)(struct drm_simple_display_pipe *pipe);};

Members

mode_valid

This callback is used to check if a specific mode is valid in thecrtc used in this simple display pipe. This should be implementedif the display pipe has some sort of restriction in the modesit can display. For example, a given display pipe may be responsibleto set a clock value. If the clock can not produce all the valuesfor the available modes then this callback can be used to restrictthe number of modes to only the ones that can be displayed. Anotherreason can be bandwidth mitigation: the memory port on the displaycontroller can have bandwidth limitations not allowing pixel datato be fetched at any rate.

This hook is used by the probe helpers to filter the mode list indrm_helper_probe_single_connector_modes(), and it is used by theatomic helpers to validate modes supplied by userspace indrm_atomic_helper_check_modeset().

This function is optional.

NOTE:

Since this function is both called from the check phase of an atomiccommit, and the mode validation in the probe paths it is not allowedto look at anything else but the passed-in mode, and validate itagainst configuration-invariant hardware constraints.

RETURNS:

drm_mode_status Enum

enable

This function should be used to enable the pipeline.It is called when the underlying crtc is enabled.This hook is optional.

disable

This function should be used to disable the pipeline.It is called when the underlying crtc is disabled.This hook is optional.

check

This function is called in the check phase of an atomic update,specifically when the underlying plane is checked.The simple display pipeline helpers already check that the plane isnot scaled, fills the entire visible area and is always enabledwhen the crtc is also enabled.This hook is optional.

RETURNS:

0 on success, -EINVAL if the state or the transition can’t besupported, -ENOMEM on memory allocation failure and -EDEADLK if anattempt to obtain another state object ran into adrm_modeset_lockdeadlock.

update

This function is called when the underlying plane state is updated.This hook is optional.

This is the function drivers should submit thedrm_pending_vblank_event from. Using eitherdrm_crtc_arm_vblank_event(), when the driver supports vblankinterrupt handling, ordrm_crtc_send_vblank_event() for morecomplex case. In case the hardware lacks vblank support entirely,drivers can setstructdrm_crtc_state.no_vblank instructdrm_simple_display_pipe_funcs.check and let DRM’satomic helper fake a vblank event.

prepare_fb

Optional, called bydrm_plane_helper_funcs.prepare_fb. Please readthe documentation for thedrm_plane_helper_funcs.prepare_fb hook formore details.

Drivers which always have their buffers pinned should usedrm_gem_fb_simple_display_pipe_prepare_fb() for this hook.

cleanup_fb

Optional, called bydrm_plane_helper_funcs.cleanup_fb. Please readthe documentation for thedrm_plane_helper_funcs.cleanup_fb hook formore details.

enable_vblank

Optional, called bydrm_crtc_funcs.enable_vblank. Please readthe documentation for thedrm_crtc_funcs.enable_vblank hook formore details.

disable_vblank

Optional, called bydrm_crtc_funcs.disable_vblank. Please readthe documentation for thedrm_crtc_funcs.disable_vblank hook formore details.

structdrm_simple_display_pipe¶

simple display pipeline

Definition

struct drm_simple_display_pipe {  struct drm_crtc crtc;  struct drm_plane plane;  struct drm_encoder encoder;  struct drm_connector *connector;  const struct drm_simple_display_pipe_funcs *funcs;};

Members

crtc

CRTC control structure

plane

Plane control structure

encoder

Encoder control structure

connector

Connector control structure

funcs

Pipeline control functions (optional)

Description

Simple display pipeline with plane, crtc and encoder collapsed into oneentity. It should be initialized by callingdrm_simple_display_pipe_init().

intdrm_simple_encoder_init(structdrm_device * dev, structdrm_encoder * encoder, int encoder_type)¶

Initialize a preallocated encoder with basic functionality.

Parameters

structdrm_device*dev

drm device

structdrm_encoder*encoder

the encoder to initialize

intencoder_type

user visible type of the encoder

Description

Initialises a preallocated encoder that has no further functionality.Settings for possible CRTC and clones are left to their initial values.The encoder will be cleaned up automatically as part of the mode-settingcleanup.

The caller ofdrm_simple_encoder_init() is responsible for freeingthe encoder’s memory after the encoder has been cleaned up. At themoment this only works reliably if the encoder data structure isstored in the device structure. Free the encoder’s memory as part ofthe device release function.

FIXME: Later improvements to DRM’s resource management may allow for

an automatedkfree() of the encoder’s memory.

Return

Zero on success, error code on failure.

intdrm_simple_display_pipe_attach_bridge(structdrm_simple_display_pipe * pipe, structdrm_bridge * bridge)¶

Attach a bridge to the display pipe

Parameters

structdrm_simple_display_pipe*pipe

simple display pipe object

structdrm_bridge*bridge

bridge to attach

Description

Makes it possible to still use the drm_simple_display_pipe helpers whena DRM bridge has to be used.

Note that you probably want to initialize the pipe by passing a NULLconnector todrm_simple_display_pipe_init().

Return

Zero on success, negative error code on failure.

intdrm_simple_display_pipe_init(structdrm_device * dev, structdrm_simple_display_pipe * pipe, const structdrm_simple_display_pipe_funcs * funcs, const uint32_t * formats, unsigned int format_count, const uint64_t * format_modifiers, structdrm_connector * connector)¶

Initialize a simple display pipeline

Parameters

structdrm_device*dev

DRM device

structdrm_simple_display_pipe*pipe

simple display pipe object to initialize

conststructdrm_simple_display_pipe_funcs*funcs

callbacks for the display pipe (optional)

constuint32_t*formats

array of supported formats (DRM_FORMAT_*)

unsignedintformat_count

number of elements informats

constuint64_t*format_modifiers

array of formats modifiers

structdrm_connector*connector

connector to attach and register (optional)

Description

Sets up a display pipeline which consist of a really simpleplane-crtc-encoder pipe.

If a connector is supplied, the pipe will be coupled with the providedconnector. You may supply a NULL connector when using drm bridges, thathandle connectors themselves (seedrm_simple_display_pipe_attach_bridge()).

Teardown of a simple display pipe is all handled automatically by the drmcore through callingdrm_mode_config_cleanup(). Drivers afterwards need torelease the memory for the structure themselves.

Return

Zero on success, negative error code on failure.

fbdev Helper Functions Reference¶

The fb helper functions are useful to provide an fbdev on top of a drm kernelmode setting driver. They can be used mostly independently from the crtchelper functions used by many drivers to implement the kernel mode settinginterfaces.

Drivers that support a dumb buffer with a virtual address and mmap support,should try out the generic fbdev emulation usingdrm_fbdev_generic_setup().It will automatically set up deferred I/O if the driver requires a shadowbuffer.

At runtime drivers should restore the fbdev console by usingdrm_fb_helper_lastclose() as theirdrm_driver.lastclose callback.They should also notify the fb helper code from updates to the outputconfiguration by usingdrm_fb_helper_output_poll_changed() as theirdrm_mode_config_funcs.output_poll_changed callback.

For suspend/resume consider usingdrm_mode_config_helper_suspend() anddrm_mode_config_helper_resume() which takes care of fbdev as well.

All other functions exported by the fb helper library can be used toimplement the fbdev driver interface by the driver.

It is possible, though perhaps somewhat tricky, to implement race-freehotplug detection using the fbdev helpers. Thedrm_fb_helper_prepare()helper must be called first to initialize the minimum required to makehotplug detection work. Drivers also need to make sure to properly set upthedrm_mode_config.funcs member. After callingdrm_kms_helper_poll_init()it is safe to enable interrupts and start processing hotplug events. At thesame time, drivers should initialize all modeset objects such as CRTCs,encoders and connectors. To finish up the fbdev helper initialization, thedrm_fb_helper_init() function is called. To probe for all attached displaysand set up an initial configuration using the detected hardware, driversshould calldrm_fb_helper_initial_config().

Ifdrm_framebuffer_funcs.dirty is set, thedrm_fb_helper_{cfb,sys}_{write,fillrect,copyarea,imageblit} functions willaccumulate changes and scheduledrm_fb_helper.dirty_work to run rightaway. This worker then calls the dirty() function ensuring that it willalways run in process context since the fb_*() function could be running inatomic context. Ifdrm_fb_helper_deferred_io() is used as the deferred_iocallback it will also schedule dirty_work with the damage collected from themmap page writes.

Deferred I/O is not compatible with SHMEM. Such drivers should request anfbdev shadow buffer and calldrm_fbdev_generic_setup() instead.

structdrm_fb_helper_surface_size¶

describes fbdev size and scanout surface size

Definition

struct drm_fb_helper_surface_size {  u32 fb_width;  u32 fb_height;  u32 surface_width;  u32 surface_height;  u32 surface_bpp;  u32 surface_depth;};

Members

fb_width

fbdev width

fb_height

fbdev height

surface_width

scanout buffer width

surface_height

scanout buffer height

surface_bpp

scanout buffer bpp

surface_depth

scanout buffer depth

Description

Note that the scanout surface width/height may be larger than the fbdevwidth/height. In case of multiple displays, the scanout surface is sizedaccording to the largest width/height (so it is large enough for all CRTCsto scanout). But the fbdev width/height is sized to the minimum width/height of all the displays. This ensures that fbcon fits on the smallestof the attached displays. fb_width/fb_height is used bydrm_fb_helper_fill_info() to fill out thefb_info.var structure.

structdrm_fb_helper_funcs¶

driver callbacks for the fbdev emulation library

Definition

struct drm_fb_helper_funcs {  int (*fb_probe)(struct drm_fb_helper *helper, struct drm_fb_helper_surface_size *sizes);};

Members

fb_probe

Driver callback to allocate and initialize the fbdev info structure.Furthermore it also needs to allocate the DRM framebuffer used toback the fbdev.

This callback is mandatory.

RETURNS:

The driver should return 0 on success and a negative error code onfailure.

Description

Driver callbacks used by the fbdev emulation helper library.

structdrm_fb_helper¶

main structure to emulate fbdev on top of KMS

Definition

struct drm_fb_helper {  struct drm_client_dev client;  struct drm_client_buffer *buffer;  struct drm_framebuffer *fb;  struct drm_device *dev;  const struct drm_fb_helper_funcs *funcs;  struct fb_info *fbdev;  u32 pseudo_palette[17];  struct drm_clip_rect dirty_clip;  spinlock_t dirty_lock;  struct work_struct dirty_work;  struct work_struct resume_work;  struct mutex lock;  struct list_head kernel_fb_list;  bool delayed_hotplug;  bool deferred_setup;  int preferred_bpp;};

Members

client

DRM client used by the generic fbdev emulation.

buffer

Framebuffer used by the generic fbdev emulation.

fb

Scanout framebuffer object

dev

DRM device

funcs

driver callbacks for fb helper

fbdev

emulated fbdev device info struct

pseudo_palette

fake palette of 16 colors

dirty_clip

clip rectangle used with deferred_io to accumulate damage tothe screen buffer

dirty_lock

spinlock protectingdirty_clip

dirty_work

worker used to flush the framebuffer

resume_work

worker used during resume if the console lock is already taken

lock

Top-level FBDEV helper lock. This protects all internal datastructures and lists, such asconnector_info andcrtc_info.

FIXME: fbdev emulation locking is a mess and long term we want toprotect all helper internal state with this lock as well as reducecore KMS locking as much as possible.

kernel_fb_list

Entry on the global kernel_fb_helper_list, used for kgdb entry/exit.

delayed_hotplug

A hotplug was received while fbdev wasn’t in control of the DRMdevice, i.e. another KMS master was active. The output configurationneeds to be reprobe when fbdev is in control again.

deferred_setup

If no outputs are connected (disconnected or unknown) the FB helpercode will defer setup until at least one of the outputs shows up.This field keeps track of the status so that setup can be retriedat every hotplug event until it succeeds eventually.

Protected bylock.

preferred_bpp

Temporary storage for the driver’s preferred BPP setting passed toFB helper initialization. This needs to be tracked so that deferredFB helper setup can pass this on.

See also:deferred_setup

Description

This is the main structure used by the fbdev helpers. Drivers supportingfbdev emulation should embedded this into their overall driver structure.Drivers must also fill out astructdrm_fb_helper_funcs with a fewoperations.

DRM_FB_HELPER_DEFAULT_OPS()¶

helper define for drm drivers

Parameters

Description

Helper define to register default implementations of drm_fb_helperfunctions. To be used in struct fb_ops of drm drivers.

intdrm_fb_helper_remove_conflicting_framebuffers(struct apertures_struct * a, const char * name, bool primary)¶

remove firmware-configured framebuffers

Parameters

structapertures_struct*a

memory range, users of which are to be removed

constchar*name

requesting driver name

boolprimary

also kick vga16fb if present

Description

This function removes framebuffer devices (initialized by firmware/bootloader)which use memory range described bya. Ifa is NULL all such devices areremoved.

intdrm_fb_helper_remove_conflicting_pci_framebuffers(struct pci_dev * pdev, const char * name)¶

remove firmware-configured framebuffers for PCI devices

Parameters

structpci_dev*pdev

PCI device

constchar*name

requesting driver name

Description

This function removes framebuffer devices (eg. initialized by firmware)using memory range configured for any ofpdev’s memory bars.

The function assumes that PCI device with shadowed ROM drives a primarydisplay and so kicks out vga16fb.

intdrm_fb_helper_debug_enter(struct fb_info * info)¶

implementation forfb_ops.fb_debug_enter

Parameters

structfb_info*info

fbdev registered by the helper

intdrm_fb_helper_debug_leave(struct fb_info * info)¶

implementation forfb_ops.fb_debug_leave

Parameters

structfb_info*info

fbdev registered by the helper

intdrm_fb_helper_restore_fbdev_mode_unlocked(structdrm_fb_helper * fb_helper)¶

restore fbdev configuration

Parameters

structdrm_fb_helper*fb_helper

driver-allocated fbdev helper, can be NULL

Description

This should be called from driver’s drmdrm_driver.lastclose callbackwhen implementing an fbcon on top of kms using this helper. This ensures thatthe user isn’t greeted with a black screen when e.g. X dies.

Return

Zero if everything went ok, negative error code otherwise.

intdrm_fb_helper_blank(int blank, struct fb_info * info)¶

implementation forfb_ops.fb_blank

Parameters

intblank

desired blanking state

structfb_info*info

fbdev registered by the helper

voiddrm_fb_helper_prepare(structdrm_device * dev, structdrm_fb_helper * helper, const structdrm_fb_helper_funcs * funcs)¶

setup a drm_fb_helper structure

Parameters

structdrm_device*dev

DRM device

structdrm_fb_helper*helper

driver-allocated fbdev helper structure to set up

conststructdrm_fb_helper_funcs*funcs

pointer to structure of functions associate with this helper

Description

Sets up the bare minimum to make the framebuffer helper usable. This isuseful to implement race-free initialization of the polling helpers.

intdrm_fb_helper_init(structdrm_device * dev, structdrm_fb_helper * fb_helper)¶

initialize astructdrm_fb_helper

Parameters

structdrm_device*dev

drm device

structdrm_fb_helper*fb_helper

driver-allocated fbdev helper structure to initialize

Description

This allocates the structures for the fbdev helper with the given limits.Note that this won’t yet touch the hardware (through the driver interfaces)nor register the fbdev. This is only done indrm_fb_helper_initial_config()to allow driver writes more control over the exact init sequence.

Drivers must calldrm_fb_helper_prepare() before calling this function.

Return

Zero if everything went ok, nonzero otherwise.

struct fb_info *drm_fb_helper_alloc_fbi(structdrm_fb_helper * fb_helper)¶

allocate fb_info and some of its members

Parameters

structdrm_fb_helper*fb_helper

driver-allocated fbdev helper

Description

A helper to alloc fb_info and the members cmap and apertures. Calledby the driver within the fb_probe fb_helper callback function. Drivers do notneed to release the allocated fb_info structure themselves, this isautomatically done when callingdrm_fb_helper_fini().

Return

fb_info pointer if things went okay, pointer containing error codeotherwise

voiddrm_fb_helper_unregister_fbi(structdrm_fb_helper * fb_helper)¶

unregister fb_info framebuffer device

Parameters

structdrm_fb_helper*fb_helper

driver-allocated fbdev helper, can be NULL

Description

A wrapper around unregister_framebuffer, to release the fb_infoframebuffer device. This must be called before releasing all resources forfb_helper by callingdrm_fb_helper_fini().

voiddrm_fb_helper_fini(structdrm_fb_helper * fb_helper)¶

finialize astructdrm_fb_helper

Parameters

structdrm_fb_helper*fb_helper

driver-allocated fbdev helper, can be NULL

Description

This cleans up all remaining resources associated withfb_helper.

voiddrm_fb_helper_deferred_io(struct fb_info * info, struct list_head * pagelist)¶

fbdev deferred_io callback function

Parameters

structfb_info*info

fb_info struct pointer

structlist_head*pagelist

list of dirty mmap framebuffer pages

Description

This function is used as thefb_deferred_io.deferred_iocallback function for flushing the fbdev mmap writes.

ssize_tdrm_fb_helper_sys_read(struct fb_info * info, char __user * buf, size_t count, loff_t * ppos)¶

wrapper around fb_sys_read

Parameters

structfb_info*info

fb_info struct pointer

char__user*buf

userspace buffer to read from framebuffer memory

size_tcount

number of bytes to read from framebuffer memory

loff_t*ppos

read offset within framebuffer memory

Description

A wrapper around fb_sys_read implemented by fbdev core

ssize_tdrm_fb_helper_sys_write(struct fb_info * info, const char __user * buf, size_t count, loff_t * ppos)¶

wrapper around fb_sys_write

Parameters

structfb_info*info

fb_info struct pointer

constchar__user*buf

userspace buffer to write to framebuffer memory

size_tcount

number of bytes to write to framebuffer memory

loff_t*ppos

write offset within framebuffer memory

Description

A wrapper around fb_sys_write implemented by fbdev core

voiddrm_fb_helper_sys_fillrect(struct fb_info * info, const struct fb_fillrect * rect)¶

wrapper around sys_fillrect

Parameters

structfb_info*info

fbdev registered by the helper

conststructfb_fillrect*rect

info about rectangle to fill

Description

A wrapper around sys_fillrect implemented by fbdev core

voiddrm_fb_helper_sys_copyarea(struct fb_info * info, const struct fb_copyarea * area)¶

wrapper around sys_copyarea

Parameters

structfb_info*info

fbdev registered by the helper

conststructfb_copyarea*area

info about area to copy

Description

A wrapper around sys_copyarea implemented by fbdev core

voiddrm_fb_helper_sys_imageblit(struct fb_info * info, const struct fb_image * image)¶

wrapper around sys_imageblit

Parameters

structfb_info*info

fbdev registered by the helper

conststructfb_image*image

info about image to blit

Description

A wrapper around sys_imageblit implemented by fbdev core

voiddrm_fb_helper_cfb_fillrect(struct fb_info * info, const struct fb_fillrect * rect)¶

wrapper around cfb_fillrect

Parameters

structfb_info*info

fbdev registered by the helper

conststructfb_fillrect*rect

info about rectangle to fill

Description

A wrapper around cfb_fillrect implemented by fbdev core

voiddrm_fb_helper_cfb_copyarea(struct fb_info * info, const struct fb_copyarea * area)¶

wrapper around cfb_copyarea

Parameters

structfb_info*info

fbdev registered by the helper

conststructfb_copyarea*area

info about area to copy

Description

A wrapper around cfb_copyarea implemented by fbdev core

voiddrm_fb_helper_cfb_imageblit(struct fb_info * info, const struct fb_image * image)¶

wrapper around cfb_imageblit

Parameters

structfb_info*info

fbdev registered by the helper

conststructfb_image*image

info about image to blit

Description

A wrapper around cfb_imageblit implemented by fbdev core

voiddrm_fb_helper_set_suspend(structdrm_fb_helper * fb_helper, bool suspend)¶

wrapper around fb_set_suspend

Parameters

structdrm_fb_helper*fb_helper

driver-allocated fbdev helper, can be NULL

boolsuspend

whether to suspend or resume

Description

A wrapper around fb_set_suspend implemented by fbdev core.Usedrm_fb_helper_set_suspend_unlocked() if you don’t need to takethe lock yourself

voiddrm_fb_helper_set_suspend_unlocked(structdrm_fb_helper * fb_helper, bool suspend)¶

wrapper around fb_set_suspend that also takes the console lock

Parameters

structdrm_fb_helper*fb_helper

driver-allocated fbdev helper, can be NULL

boolsuspend

whether to suspend or resume

Description

A wrapper aroundfb_set_suspend() that takes the console lock. If the lockisn’t available on resume, a worker is tasked with waiting for the lockto become available. The console lock can be pretty contented on resumedue to all the printk activity.

This function can be called multiple times with the same state sincefb_info.state is checked to see if fbdev is running or not before locking.

Usedrm_fb_helper_set_suspend() if you need to take the lock yourself.

intdrm_fb_helper_setcmap(struct fb_cmap * cmap, struct fb_info * info)¶

implementation forfb_ops.fb_setcmap

Parameters

structfb_cmap*cmap

cmap to set

structfb_info*info

fbdev registered by the helper

intdrm_fb_helper_ioctl(struct fb_info * info, unsigned int cmd, unsigned long arg)¶

legacy ioctl implementation

Parameters

structfb_info*info

fbdev registered by the helper

unsignedintcmd

ioctl command

unsignedlongarg

ioctl argument

Description

A helper to implement the standard fbdev ioctl. OnlyFBIO_WAITFORVSYNC is implemented for now.

intdrm_fb_helper_check_var(struct fb_var_screeninfo * var, struct fb_info * info)¶

implementation forfb_ops.fb_check_var

Parameters

structfb_var_screeninfo*var

screeninfo to check

structfb_info*info

fbdev registered by the helper

intdrm_fb_helper_set_par(struct fb_info * info)¶

implementation forfb_ops.fb_set_par

Parameters

structfb_info*info

fbdev registered by the helper

Description

This will let fbcon do the mode init and is called at initialization time bythe fbdev core when registering the driver, and later on through the hotplugcallback.

intdrm_fb_helper_pan_display(struct fb_var_screeninfo * var, struct fb_info * info)¶

implementation forfb_ops.fb_pan_display

Parameters

structfb_var_screeninfo*var

updated screen information

structfb_info*info

fbdev registered by the helper

voiddrm_fb_helper_fill_info(struct fb_info * info, structdrm_fb_helper * fb_helper, structdrm_fb_helper_surface_size * sizes)¶

initializes fbdev information

Parameters

structfb_info*info

fbdev instance to set up

structdrm_fb_helper*fb_helper

fb helper instance to use as template

structdrm_fb_helper_surface_size*sizes

describes fbdev size and scanout surface size

Description

Sets up the variable and fixed fbdev metainformation from the given fb helperinstance and the drm framebuffer allocated indrm_fb_helper.fb.

Drivers should call this (or their equivalent setup code) from theirdrm_fb_helper_funcs.fb_probe callback after having allocated the fbdevbacking storage framebuffer.

intdrm_fb_helper_initial_config(structdrm_fb_helper * fb_helper, int bpp_sel)¶

setup a sane initial connector configuration

Parameters

structdrm_fb_helper*fb_helper

fb_helper device struct

intbpp_sel

bpp value to use for the framebuffer configuration

Description

Scans the CRTCs and connectors and tries to put together an initial setup.At the moment, this is a cloned configuration across all heads witha new framebuffer object as the backing store.

Note that this also registers the fbdev and so allows userspace to call intothe driver through the fbdev interfaces.

This function will call down into thedrm_fb_helper_funcs.fb_probe callbackto let the driver allocate and initialize the fbdev info structure and thedrm framebuffer used to back the fbdev.drm_fb_helper_fill_info() is providedas a helper to setup simple default values for the fbdev info structure.

HANG DEBUGGING:

When you have fbcon support built-in or already loaded, this function will doa full modeset to setup the fbdev console. Due to locking misdesign in theVT/fbdev subsystem that entire modeset sequence has to be done while holdingconsole_lock. Until console_unlock is called no dmesg lines will be sent outto consoles, not even serial console. This means when your driver crashes,you will see absolutely nothing else but a system stuck in this function,with no further output. Any kind ofprintk() you place within your own driveror in the drm core modeset code will also never show up.

Standard debug practice is to run the fbcon setup without taking theconsole_lock as a hack, to be able to see backtraces and crashes on theserial line. This can be done by setting the fb.lockless_register_fb=1 kernelcmdline option.

The other option is to just disable fbdev emulation since very likely thefirst modeset from userspace will crash in the same way, and is even easierto debug. This can be done by setting the drm_kms_helper.fbdev_emulation=0kernel cmdline option.

Return

Zero if everything went ok, nonzero otherwise.

intdrm_fb_helper_hotplug_event(structdrm_fb_helper * fb_helper)¶

respond to a hotplug notification by probing all the outputs attached to the fb

Parameters

structdrm_fb_helper*fb_helper

driver-allocated fbdev helper, can be NULL

Description

Scan the connectors attached to the fb_helper and try to put together asetup after notification of a change in output configuration.

Called at runtime, takes the mode config locks to be able to check/change themodeset configuration. Must be run from process context (which usually meanseither the output polling work or a work item launched from the driver’shotplug interrupt).

Note that drivers may call this even before callingdrm_fb_helper_initial_config but only after drm_fb_helper_init. This allowsfor a race-free fbcon setup and will make sure that the fbdev emulation willnot miss any hotplug events.

Return

0 on success and a non-zero error code otherwise.

voiddrm_fb_helper_lastclose(structdrm_device * dev)¶

DRM driver lastclose helper for fbdev emulation

Parameters

structdrm_device*dev

DRM device

Description

This function can be used as thedrm_driver->lastclose callback for driversthat only need to calldrm_fb_helper_restore_fbdev_mode_unlocked().

voiddrm_fb_helper_output_poll_changed(structdrm_device * dev)¶

DRM mode config .output_poll_changed helper for fbdev emulation

Parameters

structdrm_device*dev

DRM device

Description

This function can be used as thedrm_mode_config_funcs.output_poll_changed callback for drivers that onlyneed to calldrm_fb_helper_hotplug_event().

voiddrm_fbdev_generic_setup(structdrm_device * dev, unsigned int preferred_bpp)¶

Setup generic fbdev emulation

Parameters

structdrm_device*dev

DRM device

unsignedintpreferred_bpp

Preferred bits per pixel for the device.dev->mode_config.preferred_depth is used if this is zero.

Description

This function sets up generic fbdev emulation for drivers that supportsdumb buffers with a virtual address and that can be mmap’ed.drm_fbdev_generic_setup() shall be called after the DRM driver registeredthe new DRM device withdrm_dev_register().

Restore, hotplug events and teardown are all taken care of. Drivers that dosuspend/resume need to calldrm_fb_helper_set_suspend_unlocked() themselves.Simple drivers might usedrm_mode_config_helper_suspend().

Drivers that set the dirty callback on their framebuffer will get a shadowfbdev buffer that is blitted onto the real buffer. This is done in order tomake deferred I/O work with all kinds of buffers. A shadow buffer can berequested explicitly by setting struct drm_mode_config.prefer_shadow orstruct drm_mode_config.prefer_shadow_fbdev to true beforehand. This isrequired to use generic fbdev emulation with SHMEM helpers.

This function is safe to call even when there are no connectors present.Setup will be retried on the next hotplug event.

The fbdev is destroyed bydrm_dev_unregister().

format Helper Functions Reference¶

voiddrm_fb_memcpy(void * dst, void * vaddr, structdrm_framebuffer * fb, structdrm_rect * clip)¶

Copy clip buffer

Parameters

void*dst

Destination buffer

void*vaddr

Source buffer

structdrm_framebuffer*fb

DRM framebuffer

structdrm_rect*clip

Clip rectangle area to copy

Description

This function does not apply clipping on dst, i.e. the destinationis a small buffer containing the clip rect only.

voiddrm_fb_memcpy_dstclip(void __iomem * dst, void * vaddr, structdrm_framebuffer * fb, structdrm_rect * clip)¶

Copy clip buffer

Parameters

void__iomem*dst

Destination buffer (iomem)

void*vaddr

Source buffer

structdrm_framebuffer*fb

DRM framebuffer

structdrm_rect*clip

Clip rectangle area to copy

Description

This function applies clipping on dst, i.e. the destination is afull (iomem) framebuffer but only the clip rect content is copied over.

voiddrm_fb_swab(void * dst, void * src, structdrm_framebuffer * fb, structdrm_rect * clip, bool cached)¶

Swap bytes into clip buffer

Parameters

void*dst

Destination buffer

void*src

Source buffer

structdrm_framebuffer*fb

DRM framebuffer

structdrm_rect*clip

Clip rectangle area to copy

boolcached

Source buffer is mapped cached (eg. not write-combined)

Description

Ifcached is false a temporary buffer is used to cache one pixel line at atime to speed up slow uncached reads.

This function does not apply clipping on dst, i.e. the destinationis a small buffer containing the clip rect only.

voiddrm_fb_xrgb8888_to_rgb565(void * dst, void * vaddr, structdrm_framebuffer * fb, structdrm_rect * clip, bool swab)¶

Convert XRGB8888 to RGB565 clip buffer

Parameters

void*dst

RGB565 destination buffer

void*vaddr

XRGB8888 source buffer

structdrm_framebuffer*fb

DRM framebuffer

structdrm_rect*clip

Clip rectangle area to copy

boolswab

Swap bytes

Description

Drivers can use this function for RGB565 devices that don’t nativelysupport XRGB8888.

This function does not apply clipping on dst, i.e. the destinationis a small buffer containing the clip rect only.

voiddrm_fb_xrgb8888_to_rgb565_dstclip(void __iomem * dst, unsigned int dst_pitch, void * vaddr, structdrm_framebuffer * fb, structdrm_rect * clip, bool swab)¶

Convert XRGB8888 to RGB565 clip buffer

Parameters

void__iomem*dst

RGB565 destination buffer (iomem)

unsignedintdst_pitch

destination buffer pitch

void*vaddr

XRGB8888 source buffer

structdrm_framebuffer*fb

DRM framebuffer

structdrm_rect*clip

Clip rectangle area to copy

boolswab

Swap bytes

Description

Drivers can use this function for RGB565 devices that don’t nativelysupport XRGB8888.

This function applies clipping on dst, i.e. the destination is afull (iomem) framebuffer but only the clip rect content is copied over.

voiddrm_fb_xrgb8888_to_rgb888_dstclip(void __iomem * dst, unsigned int dst_pitch, void * vaddr, structdrm_framebuffer * fb, structdrm_rect * clip)¶

Convert XRGB8888 to RGB888 clip buffer

Parameters

void__iomem*dst

RGB565 destination buffer (iomem)

unsignedintdst_pitch

destination buffer pitch

void*vaddr

XRGB8888 source buffer

structdrm_framebuffer*fb

DRM framebuffer

structdrm_rect*clip

Clip rectangle area to copy

Description

Drivers can use this function for RGB888 devices that don’t nativelysupport XRGB8888.

This function applies clipping on dst, i.e. the destination is afull (iomem) framebuffer but only the clip rect content is copied over.

voiddrm_fb_xrgb8888_to_gray8(u8 * dst, void * vaddr, structdrm_framebuffer * fb, structdrm_rect * clip)¶

Convert XRGB8888 to grayscale

Parameters

u8*dst

8-bit grayscale destination buffer

void*vaddr

XRGB8888 source buffer

structdrm_framebuffer*fb

DRM framebuffer

structdrm_rect*clip

Clip rectangle area to copy

Description

Drm doesn’t have native monochrome or grayscale support.Such drivers can announce the commonly supported XR24 format to userspaceand use this function to convert to the native format.

Monochrome drivers will use the most significant bit,where 1 means foreground color and 0 background color.

ITU BT.601 is used for the RGB -> luma (brightness) conversion.

Framebuffer CMA Helper Functions Reference¶

Provides helper functions for creating a cma (contiguous memory allocator)backed framebuffer.

drm_gem_fb_create() is used in thedrm_mode_config_funcs.fb_createcallback function to create a cma backed framebuffer.

structdrm_gem_cma_object *drm_fb_cma_get_gem_obj(structdrm_framebuffer * fb, unsigned int plane)¶

Get CMA GEM object for framebuffer

Parameters

structdrm_framebuffer*fb

The framebuffer

unsignedintplane

Which plane

Description

Return the CMA GEM object for given framebuffer.

This function will usually be called from the CRTC callback functions.

dma_addr_tdrm_fb_cma_get_gem_addr(structdrm_framebuffer * fb, structdrm_plane_state * state, unsigned int plane)¶

Get physical address for framebuffer, for pixel formats where values are grouped in blocks this will get you the beginning of the block

Parameters

structdrm_framebuffer*fb

The framebuffer

structdrm_plane_state*state

Which state of drm plane

unsignedintplane

Which planeReturn the CMA GEM address for given framebuffer.

Description

This function will usually be called from the PLANE callback functions.

Framebuffer GEM Helper Reference¶

This library provides helpers for drivers that don’t subclassdrm_framebuffer and usedrm_gem_object for their backing storage.

Drivers without additional needs to validate framebuffers can simply usedrm_gem_fb_create() and everything is wired up automatically. Other driverscan use all parts independently.

structdrm_gem_object *drm_gem_fb_get_obj(structdrm_framebuffer * fb, unsigned int plane)¶

Get GEM object backing the framebuffer

Parameters

structdrm_framebuffer*fb

Framebuffer

unsignedintplane

Plane index

Description

No additional reference is taken beyond the one that thedrm_frambufferalready holds.

Return

Pointer todrm_gem_object for the given framebuffer and plane index or NULLif it does not exist.

voiddrm_gem_fb_destroy(structdrm_framebuffer * fb)¶

Free GEM backed framebuffer

Parameters

structdrm_framebuffer*fb

Framebuffer

Description

Frees a GEM backed framebuffer with its backing buffer(s) and the structureitself. Drivers can use this as theirdrm_framebuffer_funcs->destroycallback.

intdrm_gem_fb_create_handle(structdrm_framebuffer * fb, structdrm_file * file, unsigned int * handle)¶

Create handle for GEM backed framebuffer

Parameters

structdrm_framebuffer*fb

Framebuffer

structdrm_file*file

DRM file to register the handle for

unsignedint*handle

Pointer to return the created handle

Description

This function creates a handle for the GEM object backing the framebuffer.Drivers can use this as theirdrm_framebuffer_funcs->create_handlecallback. The GETFB IOCTL calls into this callback.

Return

0 on success or a negative error code on failure.

intdrm_gem_fb_init_with_funcs(structdrm_device * dev, structdrm_framebuffer * fb, structdrm_file * file, const struct drm_mode_fb_cmd2 * mode_cmd, const structdrm_framebuffer_funcs * funcs)¶

Helper function for implementingdrm_mode_config_funcs.fb_create callback in cases when the driver allocates a subclass of struct drm_framebuffer

Parameters

structdrm_device*dev

DRM device

structdrm_framebuffer*fb

framebuffer object

structdrm_file*file

DRM file that holds the GEM handle(s) backing the framebuffer

conststructdrm_mode_fb_cmd2*mode_cmd

Metadata from the userspace framebuffer creation request

conststructdrm_framebuffer_funcs*funcs

vtable to be used for the new framebuffer object

Description

This function can be used to setdrm_framebuffer_funcs for drivers that needcustom framebuffer callbacks. Usedrm_gem_fb_create() if you don’t need tochangedrm_framebuffer_funcs. The function does buffer size validation.The buffer size validation is for a general case, though, so users shouldpay attention to the checks being appropriate for them or, at least,non-conflicting.

Return

Zero or a negative error code.

structdrm_framebuffer *drm_gem_fb_create_with_funcs(structdrm_device * dev, structdrm_file * file, const struct drm_mode_fb_cmd2 * mode_cmd, const structdrm_framebuffer_funcs * funcs)¶

Helper function for thedrm_mode_config_funcs.fb_create callback

Parameters

structdrm_device*dev

DRM device

structdrm_file*file

DRM file that holds the GEM handle(s) backing the framebuffer

conststructdrm_mode_fb_cmd2*mode_cmd

Metadata from the userspace framebuffer creation request

conststructdrm_framebuffer_funcs*funcs

vtable to be used for the new framebuffer object

Description

This function can be used to setdrm_framebuffer_funcs for drivers that needcustom framebuffer callbacks. Usedrm_gem_fb_create() if you don’t need tochangedrm_framebuffer_funcs. The function does buffer size validation.

Return

Pointer to adrm_framebuffer on success or an error pointer on failure.

structdrm_framebuffer *drm_gem_fb_create(structdrm_device * dev, structdrm_file * file, const struct drm_mode_fb_cmd2 * mode_cmd)¶

Helper function for thedrm_mode_config_funcs.fb_create callback

Parameters

structdrm_device*dev

DRM device

structdrm_file*file

DRM file that holds the GEM handle(s) backing the framebuffer

conststructdrm_mode_fb_cmd2*mode_cmd

Metadata from the userspace framebuffer creation request

Description

This function creates a new framebuffer object described bydrm_mode_fb_cmd2. This description includes handles for the buffer(s)backing the framebuffer.

If your hardware has special alignment or pitch requirements these should bechecked before calling this function. The function does buffer sizevalidation. Usedrm_gem_fb_create_with_dirty() if you need framebufferflushing.

Drivers can use this as theirdrm_mode_config_funcs.fb_create callback.The ADDFB2 IOCTL calls into this callback.

Return

Pointer to adrm_framebuffer on success or an error pointer on failure.

structdrm_framebuffer *drm_gem_fb_create_with_dirty(structdrm_device * dev, structdrm_file * file, const struct drm_mode_fb_cmd2 * mode_cmd)¶

Helper function for thedrm_mode_config_funcs.fb_create callback

Parameters

structdrm_device*dev

DRM device

structdrm_file*file

DRM file that holds the GEM handle(s) backing the framebuffer

conststructdrm_mode_fb_cmd2*mode_cmd

Metadata from the userspace framebuffer creation request

Description

This function creates a new framebuffer object described bydrm_mode_fb_cmd2. This description includes handles for the buffer(s)backing the framebuffer.drm_atomic_helper_dirtyfb() is used for the dirtycallback giving framebuffer flushing through the atomic machinery. Usedrm_gem_fb_create() if you don’t need the dirty callback.The function does buffer size validation.

Drivers should also calldrm_plane_enable_fb_damage_clips() on all planesto enable userspace to use damage clips also with the ATOMIC IOCTL.

Drivers can use this as theirdrm_mode_config_funcs.fb_create callback.The ADDFB2 IOCTL calls into this callback.

Return

Pointer to adrm_framebuffer on success or an error pointer on failure.

intdrm_gem_fb_afbc_init(structdrm_device * dev, const struct drm_mode_fb_cmd2 * mode_cmd, structdrm_afbc_framebuffer * afbc_fb)¶

Helper function for drivers using afbc to fill and validate all the afbc-specific struct drm_afbc_framebuffer members

Parameters

structdrm_device*dev

DRM device

conststructdrm_mode_fb_cmd2*mode_cmd

Metadata from the userspace framebuffer creation request

structdrm_afbc_framebuffer*afbc_fb

afbc framebuffer

Description

This function can be used by drivers which support afbc to completethe preparation of struct drm_afbc_framebuffer. It must be called afterallocating the said struct and callingdrm_gem_fb_init_with_funcs().It is caller’s responsibility to put afbc_fb->base.obj objects in casethe call is unsuccessful.

Return

Zero on success or a negative error value on failure.

intdrm_gem_fb_prepare_fb(structdrm_plane * plane, structdrm_plane_state * state)¶

Prepare a GEM backed framebuffer

Parameters

structdrm_plane*plane

Plane

structdrm_plane_state*state

Plane state the fence will be attached to

Description

This function extracts the exclusive fence fromdrm_gem_object.resv andattaches it to plane state for the atomic helper to wait on. This isnecessary to correctly implement implicit synchronization for any buffersshared as a structdma_buf. This function can be used as thedrm_plane_helper_funcs.prepare_fb callback.

There is no need fordrm_plane_helper_funcs.cleanup_fb hook for simplegem based framebuffer drivers which have their buffers always pinned inmemory.

Seedrm_atomic_set_fence_for_plane() for a discussion of implicit andexplicit fencing in atomic modeset updates.

intdrm_gem_fb_simple_display_pipe_prepare_fb(structdrm_simple_display_pipe * pipe, structdrm_plane_state * plane_state)¶

prepare_fb helper fordrm_simple_display_pipe

Parameters

structdrm_simple_display_pipe*pipe

Simple display pipe

structdrm_plane_state*plane_state

Plane state

Description

This function usesdrm_gem_fb_prepare_fb() to extract the exclusive fencefromdrm_gem_object.resv and attaches it to plane state for the atomichelper to wait on. This is necessary to correctly implement implicitsynchronization for any buffers shared as a structdma_buf. Drivers can usethis as theirdrm_simple_display_pipe_funcs.prepare_fb callback.

Seedrm_atomic_set_fence_for_plane() for a discussion of implicit andexplicit fencing in atomic modeset updates.

Bridges¶

[ CRTC ---> ] Encoder ---> Bridge A ---> Bridge B

struct drm_bridge_funcs {  int (*attach)(struct drm_bridge *bridge, enum drm_bridge_attach_flags flags);  void (*detach)(struct drm_bridge *bridge);  enum drm_mode_status (*mode_valid)(struct drm_bridge *bridge,const struct drm_display_info *info, const struct drm_display_mode *mode);  bool (*mode_fixup)(struct drm_bridge *bridge,const struct drm_display_mode *mode, struct drm_display_mode *adjusted_mode);  void (*disable)(struct drm_bridge *bridge);  void (*post_disable)(struct drm_bridge *bridge);  void (*mode_set)(struct drm_bridge *bridge,const struct drm_display_mode *mode, const struct drm_display_mode *adjusted_mode);  void (*pre_enable)(struct drm_bridge *bridge);  void (*enable)(struct drm_bridge *bridge);  void (*atomic_pre_enable)(struct drm_bridge *bridge, struct drm_bridge_state *old_bridge_state);  void (*atomic_enable)(struct drm_bridge *bridge, struct drm_bridge_state *old_bridge_state);  void (*atomic_disable)(struct drm_bridge *bridge, struct drm_bridge_state *old_bridge_state);  void (*atomic_post_disable)(struct drm_bridge *bridge, struct drm_bridge_state *old_bridge_state);  struct drm_bridge_state *(*atomic_duplicate_state)(struct drm_bridge *bridge);  void (*atomic_destroy_state)(struct drm_bridge *bridge, struct drm_bridge_state *state);  u32 *(*atomic_get_output_bus_fmts)(struct drm_bridge *bridge,struct drm_bridge_state *bridge_state,struct drm_crtc_state *crtc_state,struct drm_connector_state *conn_state, unsigned int *num_output_fmts);  u32 *(*atomic_get_input_bus_fmts)(struct drm_bridge *bridge,struct drm_bridge_state *bridge_state,struct drm_crtc_state *crtc_state,struct drm_connector_state *conn_state,u32 output_fmt, unsigned int *num_input_fmts);  int (*atomic_check)(struct drm_bridge *bridge,struct drm_bridge_state *bridge_state,struct drm_crtc_state *crtc_state, struct drm_connector_state *conn_state);  struct drm_bridge_state *(*atomic_reset)(struct drm_bridge *bridge);  enum drm_connector_status (*detect)(struct drm_bridge *bridge);  int (*get_modes)(struct drm_bridge *bridge, struct drm_connector *connector);  struct edid *(*get_edid)(struct drm_bridge *bridge, struct drm_connector *connector);  void (*hpd_notify)(struct drm_bridge *bridge, enum drm_connector_status status);  void (*hpd_enable)(struct drm_bridge *bridge);  void (*hpd_disable)(struct drm_bridge *bridge);};

struct drm_bridge_timings {  u32 input_bus_flags;  u32 setup_time_ps;  u32 hold_time_ps;  bool dual_link;};

struct drm_bridge {  struct drm_private_obj base;  struct drm_device *dev;  struct drm_encoder *encoder;  struct list_head chain_node;#ifdef CONFIG_OF;  struct device_node *of_node;#endif;  struct list_head list;  const struct drm_bridge_timings *timings;  const struct drm_bridge_funcs *funcs;  void *driver_private;  enum drm_bridge_ops ops;  int type;  bool interlace_allowed;  struct i2c_adapter *ddc;  struct mutex hpd_mutex;  void (*hpd_cb)(void *data, enum drm_connector_status status);  void *hpd_data;};