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);    void (*disable)(struct drm_crtc *crtc);    int (*atomic_check)(struct drm_crtc *crtc, struct drm_atomic_state *state);    void (*atomic_begin)(struct drm_crtc *crtc, struct drm_atomic_state *state);    void (*atomic_flush)(struct drm_crtc *crtc, struct drm_atomic_state *state);    void (*atomic_enable)(struct drm_crtc *crtc, struct drm_atomic_state *state);    void (*atomic_disable)(struct drm_crtc *crtc, struct drm_atomic_state *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);    bool (*handle_vblank_timeout)(struct drm_crtc *crtc);};

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 hardware 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.

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.

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, but it isoptional.

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 object passed-in.

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, but it isoptional.

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, but it isoptional.

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 usingfor_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.

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.

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.

handle_vblank_timeout

Handles timeouts of the vblank timer.

Called by CRTC’s the vblank timer on each timeout. Semantics isequivalient todrm_crtc_handle_vblank(). Implementations shouldinvokedrm_crtc_handle_vblank() as part of processing the timeout.

This callback is optional. If unset, the vblank timer invokesdrm_crtc_handle_vblank() directly.

Parameters

structdrm_crtc*crtc

DRM CRTC

conststructdrm_crtc_helper_funcs*funcs

helper vtable to set forcrtc

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 hardware 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 usingfor_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 usingfor_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 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 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 usingfor_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.

Parameters

structdrm_encoder*encoder

DRM encoder

conststructdrm_encoder_helper_funcs*funcs

helper vtable to set forencoder

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, const struct drm_display_mode *mode);    int (*mode_valid_ctx)(struct drm_connector *connector, const 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_atomic_state *state);    int (*atomic_check)(struct drm_connector *connector, struct drm_atomic_state *state);    void (*atomic_commit)(struct drm_connector *connector, struct drm_atomic_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);    void (*enable_hpd)(struct drm_connector *connector);    void (*disable_hpd)(struct drm_connector *connector);};

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 drive 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.

Note that the caller function will automatically add standard VESADMT modes up to 1024x768 if the .get_modes() helper operation returnsno mode and if the connector status is connector_status_connected orconnector_status_unknown. There is no need to calldrm_add_modes_noedid() manually in that case.

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(). Return 0on failures (no modes) instead of negative error codes.

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(ordrm_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 thedrm_atomic_state update tracking structure passed in.

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 in the new connector state,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 existingdrm_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.

enable_hpd

Enable hot-plug detection for the connector.

This operation is optional.

This callback is used by thedrm_kms_helper_poll_enable() helpers.

This operation does not need to perform any hpd state tracking asthe DRM core handles that maintenance and ensures the calls to enableand disable hpd are balanced.

disable_hpd

Disable hot-plug detection for the connector.

This operation is optional.

This callback is used by thedrm_kms_helper_poll_disable() helpers.

This operation does not need to perform any hpd state tracking asthe DRM core handles that maintenance and ensures the calls to enableand disable hpd are balanced.

Parameters

structdrm_connector*connector

DRM connector

conststructdrm_connector_helper_funcs*funcs

helper vtable to set forconnector

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 (*begin_fb_access)(struct drm_plane *plane, struct drm_plane_state *new_plane_state);    void (*end_fb_access)(struct drm_plane *plane, struct drm_plane_state *new_plane_state);    int (*atomic_check)(struct drm_plane *plane, struct drm_atomic_state *state);    void (*atomic_update)(struct drm_plane *plane, struct drm_atomic_state *state);    void (*atomic_enable)(struct drm_plane *plane, struct drm_atomic_state *state);    void (*atomic_disable)(struct drm_plane *plane, struct drm_atomic_state *state);    int (*atomic_async_check)(struct drm_plane *plane, struct drm_atomic_state *state, bool flip);    void (*atomic_async_update)(struct drm_plane *plane, struct drm_atomic_state *state);    int (*get_scanout_buffer)(struct drm_plane *plane, struct drm_scanout_buffer *sb);    void (*panic_flush)(struct drm_plane *plane);};

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.

For GEM drivers who neither have aprepare_fb norcleanup_fb hooksetdrm_gem_plane_helper_prepare_fb() is called automatically toimplement this. Other drivers which need additional plane processingcan calldrm_gem_plane_helper_prepare_fb() from theirprepare_fbhook.

The resources acquired inprepare_fb persist after the end ofthe atomic commit. Resources that can be release at the commit’s endshould be acquired inbegin_fb_access and released inend_fb_access.For example, a GEM buffer’s pin operation belongs intoprepare_fb tokeep the buffer pinned after the commit. But a vmap operation forshadow-plane helpers belongs intobegin_fb_access, so that atomichelpers remove the mapping at the end of the commit.

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

This callback is used by the atomic modeset helpers, but it isoptional. Seebegin_fb_access for preparing per-commit resources.

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, but it isoptional.

begin_fb_access

This hook prepares the plane for access during an atomic commit.In contrast toprepare_fb, resources acquired inbegin_fb_access,are released at the end of the atomic commit inend_fb_access.

For example, with shadow-plane helpers, the GEM buffer’s vmapoperation belongs intobegin_fb_access, so that the buffer’smemory will be unmapped at the end of the commit inend_fb_access.But a GEM buffer’s pin operation belongs intoprepare_fbto keep the buffer pinned after the commit.

The callback is used by the atomic modeset helpers, but it is optional.Seeend_fb_cleanup for undoing the effects ofbegin_fb_access andprepare_fb for acquiring resources until the next pageflip.

Returns:0 on success, or a negative errno code otherwise.

end_fb_access

This hook cleans up resources allocated bybegin_fb_access. It it calledat the end of a commit for the new plane state.

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, but it isoptional.

NOTE:

This function is called in the check phase of an atomic update. Thedriver is not allowed to change anything outside of thedrm_atomic_state update 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, but it is optional.

atomic_enable

Drivers should use this function to unconditionally enable a plane.This hook is called in-between thedrm_crtc_helper_funcs.atomic_beginand drm_crtc_helper_funcs.atomic_flush callbacks. It is called afteratomic_update, which will be called for all enabled planes. Driversthat useatomic_enable should set up a plane inatomic_update andafterwards enable the plane inatomic_enable. If a plane needs to beenabled before installing the scanout buffer, drivers can still doso inatomic_update.

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, but it isoptional. If implemented,atomic_enable should be the inverse ofatomic_disable. Drivers that don’t want to use either can stillimplement the complete plane update inatomic_update.

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, but it isoptional. It’s intended to reverse the effects ofatomic_enable.

atomic_async_check

Drivers should set this function pointer to check if the plane’satomic state can be updated in a async fashion. Here async means“not vblank synchronized”.

This hook is called bydrm_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.

This function is also used bydrm_atomic_set_property() to determineif the plane can be flipped in async. The flip flag is used todistinguish if the function is used for just the plane state or for aflip.

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.

When doing async_update drivers shouldn’t replace thedrm_plane_state but update the current one with the new planeconfigurations in the new plane_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.

get_scanout_buffer

Get the current scanout buffer, to display a message with drm_panic.The driver should do the minimum changes to provide a buffer,that can be used to display the panic screen. Currently only linearbuffers are supported. Non-linear buffer support is on the TODO list.The devicedev.mode_config.panic_lock is taken before calling thisfunction, so you can safely access theplane.stateIt is called from a panic callback, and must follow its restrictions.Please look the documentation atdrm_panic_trylock() for an in-depthdiscussions of what’s safe and what is not allowed.It’s a best effort mode, so it’s expected that in some complex casesthe panic screen won’t be displayed.The returneddrm_scanout_buffer.map must be valid if no error code isreturned.

Return:0 on success, negative errno on failure.

panic_flush

It is used by drm_panic, and is called after the panic screen isdrawn to the scanout buffer. In this function, the drivercan send additional commands to the hardware, to make the scanoutbuffer visible.It is only called ifget_scanout_buffer() returned successfully, andthedev.mode_config.panic_lock is held during the entire sequence.It is called from a panic callback, and must follow its restrictions.Please look the documentation atdrm_panic_trylock() for an in-depthdiscussions of what’s safe and what is not allowed.

Parameters

structdrm_plane*plane

DRM plane

conststructdrm_plane_helper_funcs*funcs

helper vtable to set forplane

Definition:

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

Members

atomic_commit_tail

This hook is used by the defaultatomic_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 preceding 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 updateto 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().

atomic_commit_setup

This hook is used by the defaultatomic_commit() hook implemented indrm_atomic_helper_commit() together with the nonblocking helpers (seedrm_atomic_helper_setup_commit()) to extend the DRM commit setup. Itis not used by the atomic helpers.

This function is called at the end ofdrm_atomic_helper_setup_commit(), so once the commit has beenproperly setup across the generic DRM object states. It allowsdrivers to do some additional commit tracking that isn’t related to aCRTC, plane or connector, tracked in adrm_private_obj structure.

Note that the documentation ofdrm_private_obj has more details onhow one should implement this.

This hook is optional.