Mode Setting Helper Functions

The DRM subsystem aims for a strong separation between core code and helper libraries. Core code takes care of general setup and teardown and decoding userspace requests to kernel internal objects. Everything else is handled by a large set of helper libraries, which can be combined freely to pick and choose for each driver what fits, and avoid shared code where special behaviour is needed.

This distinction between core code and helpers is especially strong in the modesetting code, where there's a shared userspace ABI for all drivers. This is in contrast to the render side, where pretty much everything (with very few exceptions) can be considered optional helper code.

There are a few areas these helpers can grouped into:

• Helpers to implement modesetting. The important ones here are the atomic helpers. Old drivers still often use the legacy CRTC helpers. They both share the same set of common helper vtables. For really simple drivers (anything that would have been a great fit in the deprecated fbdev subsystem) there's also the simple display pipe helpers.

• There's a big pile of helpers for handling outputs. First the generic bridge helpers for handling encoder and transcoder IP blocks. Second the panel helpers for handling panel-related information and logic. Plus then a big set of helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally there's also generic helpers for handling output probing, and for dealing with EDIDs.

• The last group of helpers concerns itself with the frontend side of a display pipeline: Planes, handling rectangles for visibility checking and scissoring, flip queues and assorted bits.

Modeset Helper Reference for Common Vtables

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

Because there is only one pointer per modeset object to hold a vfunc table for helper libraries they are by necessity shared among the different helpers.

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

struct drm_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);
};

Members

dpms

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

This callback is also used to disable a CRTC by calling it with DRM_MODE_DPMS_OFF if the disable hook isn't used.

This callback is used by the legacy CRTC helpers. Atomic helpers also support using this hook for enabling and disabling a CRTC to facilitate transitions to atomic, but it is deprecated. Instead atomic_enable and atomic_disable should be used.

prepare

This callback should prepare the CRTC for a subsequent modeset, which in practice means the driver should disable the CRTC if it is running. Most drivers ended up implementing this by calling their dpms hook with DRM_MODE_DPMS_OFF.

This callback is used by the legacy CRTC helpers. Atomic helpers also support using this hook for disabling a CRTC to facilitate transitions to atomic, but it is deprecated. Instead atomic_disable should 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. Most drivers ended up implementing this by calling their dpms hook with DRM_MODE_DPMS_ON.

This callback is used by the legacy CRTC helpers. Atomic helpers also support using this hook for enabling a CRTC to facilitate transitions to atomic, but it is deprecated. Instead atomic_enable should be used.

mode_valid

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

This hook is used by the probe helpers to filter the mode list in drm_helper_probe_single_connector_modes(), and it is used by the atomic helpers to validate modes supplied by userspace in drm_atomic_helper_check_modeset().

This function is optional.

NOTE:

Since this function is both called from the check phase of an atomic commit, and the mode validation in the probe paths it is not allowed to look at anything else but the passed-in mode, and validate it against configuration-invariant hardward constraints. Any further limits which depend upon the configuration can only be checked in mode_fixup or atomic_check.

RETURNS:

drm_mode_status Enum

mode_fixup

This callback is used to validate a mode. The parameter mode is the display mode that userspace requested, adjusted_mode is the mode the encoders need to be fed with. Note that this is the inverse semantics of the meaning for the drm_encoder and drm_bridge_funcs.mode_fixup vfunc. If the CRTC cannot support the requested conversion from mode to adjusted_mode it should reject the modeset. See also drm_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, which can be aborted for any reason (including on userspace's request to just check whether a configuration would be possible). Atomic drivers MUST NOT touch any persistent state (hardware or software) or data structures except the passed in adjusted_mode parameter.

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

Atomic drivers which need to inspect and adjust more state should instead use the atomic_check callback, but note that they're not perfectly equivalent: mode_valid is called from drm_atomic_helper_check_modeset(), but atomic_check is called from drm_atomic_helper_check_planes(), because originally it was meant for plane update checks only.

Also beware that userspace can request its own custom modes, neither core nor helpers filter modes to the list of probe modes reported by the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure that modes are filtered consistently put any CRTC constraints and limits checks into mode_valid.

RETURNS:

True if an acceptable configuration is possible, false if the modeset operation 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 every mode change it is incompatible with universal plane support. And since it can't update other planes it's incompatible with atomic modeset 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 without changing anything of the primary plane configuration. This fits the requirement of atomic and hence is used by the atomic helpers. It is also used by the transitional plane helpers to implement a mode_set hook in drm_helper_crtc_mode_set().

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

This callback is optional.

mode_set_base

This callback is used by the legacy CRTC helpers to set a new framebuffer and scanout position. It is optional and used as an optimized fast-path instead of a full mode set operation with all the resulting flickering. If it is not present drm_crtc_helper_set_config() will fall back to a full modeset, using the mode_set callback. Since it can't update other planes it's incompatible 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 framebuffer and scanout without sleeping, i.e. from an atomic calling context. It is only used to implement kgdb support.

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

RETURNS:

0 on success or a negative error code on failure.

disable

This callback should be used to disable the CRTC. With the atomic drivers it is called after all encoders connected to this CRTC have been shut off already using their own drm_encoder_helper_funcs.disable hook. If that sequence is too simple drivers can just add their own hooks and call it from this CRTC callback here by looping over all encoders 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 to disable anything at the CRTC level. To ensure that runtime PM handling (using either DPMS or the new "ACTIVE" property) works disable must be the inverse of atomic_enable for atomic drivers. Atomic drivers should consider to use atomic_disable instead of this one.

NOTE:

With legacy CRTC helpers there's a big semantic difference between disable and other hooks (like prepare or dpms) used to shut down a CRTC: disable is only called when also logically disabling the display pipeline and needs to release any resources acquired in mode_set (like shared PLLs, or again release pinned framebuffers).

Therefore disable must be the inverse of mode_set plus commit for drivers still using legacy CRTC helpers, which is different from the rules under atomic.

atomic_check

Drivers should check plane-update related CRTC constraints in this hook. They can also check mode related limitations but need to be aware of the calling order, since this hook is used by drm_atomic_helper_check_planes() whereas the preparations needed to check output routing and the display mode is done in drm_atomic_helper_check_modeset(). Therefore drivers that want to check output routing and display mode constraints in this callback must ensure that drm_atomic_helper_check_modeset() has been called beforehand. This is calling order used by the default helper implementation in drm_atomic_helper_check().

When using drm_atomic_helper_check_planes() this hook is called after the drm_plane_helper_funcs.atomic_check hook for planes, which allows drivers to assign shared resources requested by planes in this callback here. For more complicated dependencies the driver can call the provided check helpers multiple times until the computed state has a final configuration and everything has been checked.

This function is also allowed to inspect any other object's state and can add more state objects to the atomic commit if needed. Care must be taken though to ensure that state check and compute functions for these added states are all called, and derived state in other objects all updated. Again the recommendation is to just call check helpers until a maximal configuration is reached.

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

NOTE:

This function is called in the check phase of an atomic update. The driver is not allowed to change anything outside of the free-standing state objects passed-in or assembled in the overall drm_atomic_state update tracking structure.

Also beware that userspace can request its own custom modes, neither core nor helpers filter modes to the list of probe modes reported by the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure that modes are filtered consistently put any CRTC constraints and limits checks into mode_valid.

RETURNS:

0 on success, -EINVAL if the state or the transition can't be supported, -ENOMEM on memory allocation failure and -EDEADLK if an attempt to obtain another state object ran into a drm_modeset_lock deadlock.

atomic_begin

Drivers should prepare for an atomic update of multiple planes on a CRTC in this hook. Depending upon hardware this might be vblank evasion, blocking updates by setting bits or doing preparatory work for 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 is called depends upon the exact helpers and calling sequence the driver has picked. See drm_atomic_helper_commit_planes() for a discussion of the tradeoffs and variants of plane commit helpers.

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

atomic_flush

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

Simple hardware or hardware with special requirements can commit and flush out all updates for all planes from this hook and forgo all the other 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 is called depends upon the exact helpers and calling sequence the driver has picked. See drm_atomic_helper_commit_planes() for a discussion of the tradeoffs and variants of plane commit helpers.

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

atomic_enable

This callback should be used to enable the CRTC. With the atomic drivers it is called before all encoders connected to this CRTC are enabled through the encoder's own drm_encoder_helper_funcs.enable hook. If that sequence is too simple drivers can just add their own hooks and call it from this CRTC callback here by looping over all encoders connected to it using for_each_encoder_on_crtc().

This hook is used only by atomic helpers, for symmetry with atomic_disable. Atomic drivers don't need to implement it if there's no need to enable anything at the CRTC level. To ensure that runtime PM handling (using either DPMS or the new "ACTIVE" property) works atomic_enable must be the inverse of atomic_disable for atomic drivers.

Drivers can use the old_crtc_state input parameter if the operations needed to enable the CRTC don't depend solely on the new state but also 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 atomic drivers it is called after all encoders connected to this CRTC have been shut off already using their own drm_encoder_helper_funcs.disable hook. If that sequence is too simple drivers can just add their own hooks and call it from this CRTC callback here by looping over all encoders connected to it using for_each_encoder_on_crtc().

This hook is used only by atomic helpers. Atomic drivers don't need to implement it if there's no need to disable anything at the CRTC level.

Comparing to disable, this one provides the additional input parameter old_crtc_state which could be used to access the old state. Atomic drivers should consider to use this one instead of disable.

This function is optional.

Description

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

void drm_crtc_helper_add(struct drm_crtc * crtc, const struct drm_crtc_helper_funcs * funcs)

sets the helper vtable for a crtc

Parameters

struct drm_crtc * crtc

DRM CRTC

const struct drm_crtc_helper_funcs * funcs

helper vtable to set for crtc

struct drm_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);
  struct drm_crtc *(*get_crtc)(struct drm_encoder *encoder);
  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 in is unsupported, the provider must use the next lowest power level. This is used by the legacy encoder helpers to implement DPMS functionality in drm_helper_connector_dpms().

This callback is also used to disable an encoder by calling it with DRM_MODE_DPMS_OFF if the disable hook isn't used.

This callback is used by the legacy CRTC helpers. Atomic helpers also support using this hook for enabling and disabling an encoder to facilitate transitions to atomic, but it is deprecated. Instead enable and disable should be used.

mode_valid

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

This hook is used by the probe helpers to filter the mode list in drm_helper_probe_single_connector_modes(), and it is used by the atomic helpers to validate modes supplied by userspace in drm_atomic_helper_check_modeset().

This function is optional.

NOTE:

Since this function is both called from the check phase of an atomic commit, and the mode validation in the probe paths it is not allowed to look at anything else but the passed-in mode, and validate it against configuration-invariant hardward constraints. Any further limits which depend upon the configuration can only be checked in mode_fixup or atomic_check.

RETURNS:

drm_mode_status Enum

mode_fixup

This callback is used to validate and adjust a mode. The parameter mode is the display mode that should be fed to the next element in the display chain, either the final drm_connector or a drm_bridge. The parameter adjusted_mode is the input mode the encoder requires. It can be modified by this callback and does not need to match mode. See also drm_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, which can be aborted for any reason (including on userspace's request to just check whether a configuration would be possible). Atomic drivers MUST NOT touch any persistent state (hardware or software) or data structures except the passed in adjusted_mode parameter.

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

Atomic drivers which need to inspect and adjust more state should instead use the atomic_check callback. If atomic_check is used, this hook isn't called since atomic_check allows a strict superset of the functionality of mode_fixup.

Also beware that userspace can request its own custom modes, neither core nor helpers filter modes to the list of probe modes reported by the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure that modes are filtered consistently put any encoder constraints and limits checks into mode_valid.

RETURNS:

True if an acceptable configuration is possible, false if the modeset operation 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 it is running. Most drivers ended up implementing this by calling their dpms hook with DRM_MODE_DPMS_OFF.

This callback is used by the legacy CRTC helpers. Atomic helpers also support using this hook for disabling an encoder to facilitate transitions to atomic, but it is deprecated. Instead disable should be 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. Most drivers ended up implementing this by calling their dpms hook with DRM_MODE_DPMS_ON.

This callback is used by the legacy CRTC helpers. Atomic helpers also support using this hook for enabling an encoder to facilitate transitions to atomic, but it is deprecated. Instead enable should be 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 is called. Drivers which need hardware to be running before they program the new display mode (because they implement runtime PM) should not use this hook, because the helper library calls it only once and not every time the display pipeline is suspend using either DPMS or the new "ACTIVE" property. Such drivers should instead move all their encoder setup into the enable callback.

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

NOTE:

If the driver uses the atomic modeset helpers and needs to inspect the 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 is called. Drivers which need hardware to be running before they program the new display mode (because they implement runtime PM) should not use this hook, because the helper library calls it only once and not every time the display pipeline is suspended using either DPMS or the new "ACTIVE" property. Such drivers should instead move all their encoder setup into the enable callback.

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

get_crtc

This callback is used by the legacy CRTC helpers to work around deficiencies in its own book-keeping.

Do not use, use atomic helpers instead, which get the book keeping right.

FIXME:

Currently only nouveau is using this, and as soon as nouveau is atomic we can ditch this hook.

detect

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

It is not used by any helper and therefore has purely driver-specific semantics. New drivers shouldn't use this and instead just implement their 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 atomic drivers it is called before this encoder's CRTC has been shut off using their own drm_crtc_helper_funcs.atomic_disable hook. If that sequence is too simple drivers can just add their own driver private encoder hooks and call them from CRTC's callback by looping over all encoders connected to it using for_each_encoder_on_crtc().

This callback is a variant of disable that provides the atomic state to the driver. If atomic_disable is implemented, disable is not called by the helpers.

This hook is only used by atomic helpers. Atomic drivers don't need to implement it if there's no need to disable anything at the encoder level. To ensure that runtime PM handling (using either DPMS or the new "ACTIVE" property) works atomic_disable must be the inverse of atomic_enable.

atomic_enable

This callback should be used to enable the encoder. It is called after this encoder's CRTC has been enabled using their own drm_crtc_helper_funcs.atomic_enable hook. If that sequence is too simple drivers can just add their own driver private encoder hooks and call them from CRTC's callback by looping over all encoders connected to it using for_each_encoder_on_crtc().

This callback is a variant of enable that provides the atomic state to the driver. If atomic_enable is implemented, enable is not called by the helpers.

This hook is only used by atomic helpers, it is the opposite of atomic_disable. Atomic drivers don't need to implement it if there's no need to enable anything at the encoder level. To ensure that runtime PM handling works atomic_enable must be the inverse of atomic_disable.

disable

This callback should be used to disable the encoder. With the atomic drivers it is called before this encoder's CRTC has been shut off using their own drm_crtc_helper_funcs.disable hook. If that sequence is too simple drivers can just add their own driver private encoder hooks and call them from CRTC's callback by looping over all encoders 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 to disable anything at the encoder level. To ensure that runtime PM handling (using either DPMS or the new "ACTIVE" property) works disable must be the inverse of enable for atomic drivers.

For atomic drivers also consider atomic_disable and save yourself from having to read the NOTE below!

NOTE:

With legacy CRTC helpers there's a big semantic difference between disable and other hooks (like prepare or dpms) used to shut down a encoder: disable is only called when also logically disabling the display pipeline and needs to release any resources acquired in mode_set (like shared PLLs, or again release pinned framebuffers).

Therefore disable must be the inverse of mode_set plus commit for drivers still using legacy CRTC helpers, which is different from the rules under atomic.

enable

This callback should be used to enable the encoder. With the atomic drivers it is called after this encoder's CRTC has been enabled using their own drm_crtc_helper_funcs.enable hook. If that sequence is too simple drivers can just add their own driver private encoder hooks and call them from CRTC's callback by looping over all encoders connected to it using for_each_encoder_on_crtc().

This hook is only used by atomic helpers, it is the opposite of disable. Atomic drivers don't need to implement it if there's no need to enable anything at the encoder level. To ensure that runtime PM handling (using either DPMS or the new "ACTIVE" property) works enable must be the inverse of disable 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 it gets passed both states, to be able to validate interactions and update the CRTC to match what the encoder needs for the requested connector.

Since this provides a strict superset of the functionality of mode_fixup (the requested and adjusted modes are both available through the passed in struct drm_crtc_state) mode_fixup is not called when atomic_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. The driver is not allowed to change anything outside of the free-standing state objects passed-in or assembled in the overall drm_atomic_state update tracking structure.

Also beware that userspace can request its own custom modes, neither core nor helpers filter modes to the list of probe modes reported by the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure that modes are filtered consistently put any encoder constraints and limits checks into mode_valid.

RETURNS:

0 on success, -EINVAL if the state or the transition can't be supported, -ENOMEM on memory allocation failure and -EDEADLK if an attempt to obtain another state object ran into a drm_modeset_lock deadlock.

Description

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

void drm_encoder_helper_add(struct drm_encoder * encoder, const struct drm_encoder_helper_funcs * funcs)

sets the helper vtable for an encoder

Parameters

struct drm_encoder * encoder

DRM encoder

const struct drm_encoder_helper_funcs * funcs

helper vtable to set for encoder

struct drm_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);
  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 sink into the drm_connector.probed_modes list. It should also update the EDID property by calling drm_connector_update_edid_property().

The usual way to implement this is to cache the EDID retrieved in the probe callback somewhere in the driver-private connector structure. In this function drivers then parse the modes in the EDID and add them by calling drm_add_edid_modes(). But connectors that driver a fixed panel can also manually add specific modes using drm_mode_probed_add(). Drivers which manually add modes should also make sure that the drm_connector.display_info, drm_connector.width_mm and drm_connector.height_mm fields are filled in.

Virtual drivers that just want some standard VESA mode with a given resolution can call drm_add_modes_noedid(), and mark the preferred one using drm_set_preferred_mode().

This function is only called after the detect hook has indicated that a sink is connected and when the EDID isn't overridden through sysfs 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 helper libraries always call this with the drm_mode_config.connection_mutex held. Because of this it's safe to inspect drm_connector->state.

RETURNS:

The number of modes added by calling drm_mode_probed_add().

detect_ctx

Check to see if anything is attached to the connector. The parameter force is set to false whilst polling, true when checking the connector due to a user request. force can be used by the driver to avoid expensive, destructive operations during automated probing.

This callback is optional, if not implemented the connector will be considered as always being attached.

This is the atomic version of drm_connector_funcs.detect.

To avoid races against concurrent connector state updates, the helper libraries always call this with ctx set to a valid context, and drm_mode_config.connection_mutex will always be locked with the ctx parameter set to this ctx. This allows taking additional locks as required.

RETURNS:

drm_connector_status indicating the connector's status, or the error code returned by drm_modeset_lock(), -EDEADLK.

mode_valid

Callback to validate a mode for a connector, irrespective of the specific 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 the GETCONNECTOR IOCTL. Compared to drm_encoder_helper_funcs.mode_valid, drm_crtc_helper_funcs.mode_valid and drm_bridge_funcs.mode_valid, which are also called by the atomic helpers from drm_atomic_helper_check_modeset(). This allows userspace to force and ignore sink constraint (like the pixel clock limits in the screen's EDID), which is useful for e.g. testing, or working around a broken EDID. Any source hardware constraint (which always need to be enforced) therefore should be checked in one of the above callbacks, and not this one here.

To avoid races with concurrent connector state updates, the helper libraries always call this with the drm_mode_config.connection_mutex held. Because of this it's safe to inspect drm_connector->state.

RETURNS:

Either drm_mode_status.MODE_OK or one of the failure reasons in enum drm_mode_status.

best_encoder

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

This function is used by both the atomic helpers (in the drm_atomic_helper_check_modeset() function) and in the legacy CRTC helpers.

NOTE:

In atomic drivers this function is called in the check phase of an atomic update. The driver is not allowed to change or inspect anything outside of arguments passed-in. Atomic drivers which need to inspect dynamic configuration state should instead use atomic_best_encoder.

You can leave this function to NULL if the connector is only attached to a single encoder and you are using the atomic helpers. In this case, the core will call drm_atomic_helper_best_encoder() for you.

RETURNS:

Encoder that should be used for the given connector and connector state, or NULL if no suitable encoder exists. Note that the helpers will ensure that encoders aren't used twice, drivers should not check for this.

atomic_best_encoder

This is the atomic version of best_encoder for atomic drivers which need to select the best encoder depending upon the desired configuration and can't select it statically.

This function is used by drm_atomic_helper_check_modeset(). If it is not implemented, the core will fallback to best_encoder (or drm_atomic_helper_best_encoder() if best_encoder is NULL).

NOTE:

This function is called in the check phase of an atomic update. The driver is not allowed to change anything outside of the free-standing state objects passed-in or assembled in the overall drm_atomic_state update tracking structure.

RETURNS:

Encoder that should be used for the given connector and connector state, or NULL if no suitable encoder exists. Note that the helpers will ensure that encoders aren't used twice, drivers should not check for this.

atomic_check

This hook is used to validate connector state. This function is called from drm_atomic_helper_check_modeset, and is called when a connector property is set, or a modeset on the crtc is forced.

Because drm_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 and can add more state objects to the atomic commit if needed. Care must be taken though to ensure that state check and compute functions for these added states are all called, and derived state in other objects all updated. Again the recommendation is to just call check helpers until a maximal configuration is reached.

NOTE:

This function is called in the check phase of an atomic update. The driver is not allowed to change anything outside of the free-standing state objects passed-in or assembled in the overall drm_atomic_state update tracking structure.

RETURNS:

0 on success, -EINVAL if the state or the transition can't be supported, -ENOMEM on memory allocation failure and -EDEADLK if an attempt to obtain another state object ran into a drm_modeset_lock deadlock.

atomic_commit

This hook is to be used by drivers implementing writeback connectors that need a point when to commit the writeback job to the hardware. The writeback_job to commit is available in drm_connector_state.writeback_job.

This hook 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 the probe helpers.

void drm_connector_helper_add(struct drm_connector * connector, const struct drm_connector_helper_funcs * funcs)

sets the helper vtable for a connector

Parameters

struct drm_connector * connector

DRM connector

const struct drm_connector_helper_funcs * funcs

helper vtable to set for connector

struct drm_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. pinning its backing storage or relocating it into a contiguous block of VRAM. Other possible preparatory work includes flushing caches.

This function must not block for outstanding rendering, since it is called in the context of the atomic IOCTL even for async commits to be able to return any errors to userspace. Instead the recommended way is to fill out the drm_plane_state.fence of the passed-in drm_plane_state. If the driver doesn't support native fences then equivalent functionality should be implemented through private members in the plane structure.

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

The helpers will call cleanup_fb with matching arguments for every successful call to this hook.

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

RETURNS:

0 on success or one of the following negative error codes allowed by the drm_mode_config_funcs.atomic_commit vfunc. When using helpers this 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 given framebuffer and plane configuration in prepare_fb.

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

atomic_check

Drivers should check plane specific constraints in this hook.

When using drm_atomic_helper_check_planes() plane's atomic_check hooks are called before the ones for CRTCs, which allows drivers to request shared resources that the CRTC controls here. For more complicated dependencies the driver can call the provided check helpers multiple times until the computed state has a final configuration and everything has been checked.

This function is also allowed to inspect any other object's state and can add more state objects to the atomic commit if needed. Care must be taken though to ensure that state check and compute functions for these added states are all called, and derived state in other objects all updated. Again the recommendation is to just call check helpers until a maximal configuration is reached.

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

NOTE:

This function is called in the check phase of an atomic update. The driver is not allowed to change anything outside of the free-standing state objects passed-in or assembled in the overall drm_atomic_state update tracking structure.

RETURNS:

0 on success, -EINVAL if the state or the transition can't be supported, -ENOMEM on memory allocation failure and -EDEADLK if an attempt to obtain another state object ran into a drm_modeset_lock deadlock.

atomic_update

Drivers should use this function to update the plane state. This hook is called in-between the drm_crtc_helper_funcs.atomic_begin and drm_crtc_helper_funcs.atomic_flush callbacks.

Note that the power state of the display pipe when this function is called depends upon the exact helpers and calling sequence the driver has picked. See drm_atomic_helper_commit_planes() for a discussion of the tradeoffs and variants of plane commit helpers.

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

atomic_disable

Drivers should use this function to unconditionally disable a plane. This hook is called in-between the drm_crtc_helper_funcs.atomic_begin and drm_crtc_helper_funcs.atomic_flush callbacks. It is an alternative to atomic_update, which will be called for disabling planes, too, if the atomic_disable hook isn't implemented.

This hook is also useful to disable planes in preparation of a modeset, by calling drm_atomic_helper_disable_planes_on_crtc() from the drm_crtc_helper_funcs.disable hook.

Note that the power state of the display pipe when this function is called depends upon the exact helpers and calling sequence the driver has picked. See drm_atomic_helper_commit_planes() for a discussion of the tradeoffs and variants of plane commit helpers.

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

atomic_async_check

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

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

RETURNS:

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

atomic_async_update

Drivers should set this function pointer to perform asynchronous updates of planes, that is, jump ahead of the currently queued state and update the plane. Here async means "not vblank synchronized".

This hook is called by drm_atomic_helper_async_commit().

An async update will happen on legacy cursor updates. An async update won't happen if there is an outstanding commit modifying the same plane.

Note that unlike drm_plane_helper_funcs.atomic_update this hook takes the new drm_plane_state as parameter. When doing async_update drivers shouldn't replace the drm_plane_state but update the current one with the new plane configurations in the new plane_state.

Drivers should also swap the framebuffers between current plane state (drm_plane.state) and new_state. This is required since cleanup for async commits is performed on the new state, rather than old state like for traditional commits. Since we want to give up the reference on the current (old) fb instead of our brand new one, swap them in the driver during the async 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 next vblank, however we let go of the fb references as soon as we run this hook. For now drivers must implement their own workers for deferring if needed, until a common solution is created.

Description

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

void drm_plane_helper_add(struct drm_plane * plane, const struct drm_plane_helper_funcs * funcs)

sets the helper vtable for a plane

Parameters

struct drm_plane * plane

DRM plane

const struct drm_plane_helper_funcs * funcs

helper vtable to set for plane

struct drm_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 in drm_atomic_helper_commit() together with the nonblocking commit helpers (see drm_atomic_helper_setup_commit() for a starting point) to implement blocking and nonblocking commits easily. It is not used by the atomic helpers

This function is called when the new atomic state has already been swapped into the various state pointers. The passed in state therefore contains copies of the old/previous state. This hook should commit the new state into hardware. Note that the helpers have already waited for preceeding atomic commits and fences, but drivers can add more waiting calls at the start of their implementation, e.g. to wait for driver-internal request for implicit syncing, before starting to commit the update to the hardware.

After the atomic update is committed to the hardware this hook needs to call drm_atomic_helper_commit_hw_done(). Then wait for the upate to be executed by the hardware, for example using drm_atomic_helper_wait_for_vblanks() or drm_atomic_helper_wait_for_flip_done(), and then clean up the old framebuffers using drm_atomic_helper_cleanup_planes().

When disabling a CRTC this hook _must_ stall for the commit to complete. Vblank waits don't work on disabled CRTC, hence the core can'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 to shut off the display pipeline completely.

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

Description

These helper functions are used by the atomic helpers.

Atomic Modeset Helper Functions Reference

Overview

This helper library provides implementations of check and commit functions on top of the CRTC modeset helper callbacks and the plane helper callbacks. It also provides convenience implementations for the atomic state handling callbacks for drivers which don't need to subclass the drm core structures to add their own additional internal state.

This library also provides default implementations for the check callback in drm_atomic_helper_check() and for the commit callback with drm_atomic_helper_commit(). But the individual stages and callbacks are exposed to allow drivers to mix and match and e.g. use the plane helpers only together with a driver private modeset implementation.

This library also provides implementations for all the legacy driver interfaces on top of the atomic interface. See drm_atomic_helper_set_config(), drm_atomic_helper_disable_plane(), drm_atomic_helper_disable_plane() and the various functions to implement set_property callbacks. New drivers must not implement these functions themselves but must use the provided helpers.

The atomic helper uses the same function table structures as all other modesetting helpers. See the documentation for struct drm_crtc_helper_funcs, struct drm_encoder_helper_funcs and struct drm_connector_helper_funcs. It also shares the struct drm_plane_helper_funcs function table with the plane helpers.

Implementing Asynchronous Atomic Commit

Nonblocking atomic commits have to be implemented in the following sequence:

1. Run drm_atomic_helper_prepare_planes() first. This is the only function which commit needs to call which can fail, so we want to run it first and synchronously.

2. Synchronize with any outstanding nonblocking commit worker threads which might be affected the new state update. This can be done by either cancelling or flushing the work items, depending upon whether the driver can deal with cancelled updates. Note that it is important to ensure that the framebuffer cleanup is still done when cancelling.

Asynchronous workers need to have sufficient parallelism to be able to run different atomic commits on different CRTCs in parallel. The simplest way to achieve this is by running them on the system_unbound_wq work queue. Note that drivers are not required to split up atomic commits and run an individual commit in parallel - userspace is supposed to do that if it cares. But it might be beneficial to do that for modesets, since those necessarily must be done as one global operation, and enabling or disabling a CRTC can take a long time. But even that is not required.

3. The software state is updated synchronously with drm_atomic_helper_swap_state(). Doing this under the protection of all modeset locks means concurrent callers never see inconsistent state. And doing this while it's guaranteed that no relevant nonblocking worker runs means that nonblocking workers do not need grab any locks. Actually they must not grab locks, for otherwise the work flushing will deadlock.

4. Schedule a work item to do all subsequent steps, using the split-out commit helpers: a) pre-plane commit b) plane commit c) post-plane commit and then cleaning up the framebuffers after the old framebuffer is no longer being displayed.

The above scheme is implemented in the atomic helper libraries in drm_atomic_helper_commit() using a bunch of helper functions. See drm_atomic_helper_setup_commit() for a starting point.

Helper Functions Reference

drm_atomic_crtc_for_each_plane(plane, crtc)

iterate over planes currently attached to CRTC

Parameters

plane

the loop cursor

crtc

the crtc whose planes are iterated

Description

This iterates over the current state, useful (for example) when applying atomic state after it has been checked and swapped. To iterate over the planes which will be attached (more useful in code called from drm_mode_config_funcs.atomic_check) see drm_atomic_crtc_state_for_each_plane().

drm_atomic_crtc_state_for_each_plane(plane, crtc_state)

iterate over attached planes in new state

Parameters

plane

the loop cursor

crtc_state

the incoming crtc-state

Description

Similar to drm_crtc_for_each_plane(), but iterates the planes that will be attached if the specified state is applied. Useful during for example in code called from drm_mode_config_funcs.atomic_check operations, to validate the incoming state.

drm_atomic_crtc_state_for_each_plane_state(plane, plane_state, crtc_state)

iterate over attached planes in new state

Parameters

plane

the loop cursor

plane_state

loop cursor for the plane's state, must be const

crtc_state

the incoming crtc-state

Description

Similar to drm_crtc_for_each_plane(), but iterates the planes that will be attached if the specified state is applied. Useful during for example in code called from drm_mode_config_funcs.atomic_check operations, to validate the incoming state.

Compared to just drm_atomic_crtc_state_for_each_plane() this also fills in a const plane_state. This is useful when a driver just wants to peek at other active planes on this crtc, but does not need to change it.

bool drm_atomic_plane_disabling(struct drm_plane_state * old_plane_state, struct drm_plane_state * new_plane_state)

check whether a plane is being disabled

Parameters

struct drm_plane_state * old_plane_state

old atomic plane state

struct drm_plane_state * new_plane_state

new atomic plane state

Description

Checks the atomic state of a plane to determine whether it's being disabled or not. This also WARNs if it detects an invalid state (both CRTC and FB need to either both be NULL or both be non-NULL).

Return

True if the plane is being disabled, false otherwise.

int drm_atomic_helper_check_modeset(struct drm_device * dev, struct drm_atomic_state * state)

validate state object for modeset changes

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * state

the driver state object

Description

Check the state object to see if the requested state is physically possible. This does all the crtc and connector related computations for an atomic update and adds any additional connectors needed for full modesets. It calls the various per-object callbacks in the follow order:

1. drm_connector_helper_funcs.atomic_best_encoder for determining the new encoder.

2. drm_connector_helper_funcs.atomic_check to validate the connector state.

3. If it's determined a modeset is needed then all connectors on the affected crtc crtc are added and drm_connector_helper_funcs.atomic_check is run on them.

4. drm_encoder_helper_funcs.mode_valid, drm_bridge_funcs.mode_valid and drm_crtc_helper_funcs.mode_valid are called on the affected components.

5. drm_bridge_funcs.mode_fixup is called on all encoder bridges.

6. drm_encoder_helper_funcs.atomic_check is called to validate any encoder state. This function is only called when the encoder will be part of a configured crtc, it must not be used for implementing connector property validation. If this function is NULL, drm_atomic_encoder_helper_funcs.mode_fixup is called instead.

7. drm_crtc_helper_funcs.mode_fixup is called last, to fix up the mode with crtc constraints.

drm_crtc_state.mode_changed is set when the input mode is changed. drm_crtc_state.connectors_changed is set when a connector is added or removed from the crtc. drm_crtc_state.active_changed is set when drm_crtc_state.active changes, which is used for DPMS. See also: drm_atomic_crtc_needs_modeset()

IMPORTANT:

Drivers which set drm_crtc_state.mode_changed (e.g. in their drm_plane_helper_funcs.atomic_check hooks if a plane update can't be done without a full modeset) _must_ call this function afterwards after that change. It is permitted to call this function multiple times for the same update, e.g. when the drm_crtc_helper_funcs.atomic_check functions depend upon the adjusted dotclock for fifo space allocation and watermark computation.

Return

Zero for success or -errno

int drm_atomic_helper_check_plane_state(struct drm_plane_state * plane_state, const struct drm_crtc_state * crtc_state, int min_scale, int max_scale, bool can_position, bool can_update_disabled)

Check plane state for validity

Parameters

struct drm_plane_state * plane_state

plane state to check

const struct drm_crtc_state * crtc_state

crtc state to check

int min_scale

minimum src:dest scaling factor in 16.16 fixed point

int max_scale

maximum src:dest scaling factor in 16.16 fixed point

bool can_position

is it legal to position the plane such that it doesn't cover the entire crtc? This will generally only be false for primary planes.

bool can_update_disabled

can the plane be updated while the crtc is disabled?

Description

Checks that a desired plane update is valid, and updates various bits of derived state (clipped coordinates etc.). Drivers that provide their own plane handling rather than helper-provided implementations may still wish to call this function to avoid duplication of error checking code.

Return

Zero if update appears valid, error code on failure

int drm_atomic_helper_check_planes(struct drm_device * dev, struct drm_atomic_state * state)

validate state object for planes changes

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * state

the driver state object

Description

Check the state object to see if the requested state is physically possible. This does all the plane update related checks using by calling into the drm_crtc_helper_funcs.atomic_check and drm_plane_helper_funcs.atomic_check hooks provided by the driver.

It also sets drm_crtc_state.planes_changed to indicate that a crtc has updated planes.

Return

Zero for success or -errno

int drm_atomic_helper_check(struct drm_device * dev, struct drm_atomic_state * state)

validate state object

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * state

the driver state object

Description

Check the state object to see if the requested state is physically possible. Only crtcs and planes have check callbacks, so for any additional (global) checking that a driver needs it can simply wrap that around this function. Drivers without such needs can directly use this as their drm_mode_config_funcs.atomic_check callback.

This just wraps the two parts of the state checking for planes and modeset state in the default order: First it calls drm_atomic_helper_check_modeset() and then drm_atomic_helper_check_planes(). The assumption is that the drm_plane_helper_funcs.atomic_check and drm_crtc_helper_funcs.atomic_check functions depend upon an updated adjusted_mode.clock to e.g. properly compute watermarks.

Note that zpos normalization will add all enable planes to the state which might not desired for some drivers. For example enable/disable of a cursor plane which have fixed zpos value would trigger all other enabled planes to be forced to the state change.

Return

Zero for success or -errno

void drm_atomic_helper_update_legacy_modeset_state(struct drm_device * dev, struct drm_atomic_state * old_state)

update legacy modeset state

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

This function updates all the various legacy modeset state pointers in connectors, encoders and crtcs. It also updates the timestamping constants used for precise vblank timestamps by calling drm_calc_timestamping_constants().

Drivers can use this for building their own atomic commit if they don't have a pure helper-based modeset implementation.

Since these updates are not synchronized with lockings, only code paths called from drm_mode_config_helper_funcs.atomic_commit_tail can look at the legacy state filled out by this helper. Defacto this means this helper and the legacy state pointers are only really useful for transitioning an existing driver to the atomic world.

void drm_atomic_helper_commit_modeset_disables(struct drm_device * dev, struct drm_atomic_state * old_state)

modeset commit to disable outputs

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

This function shuts down all the outputs that need to be shut down and prepares them (if required) with the new mode.

For compatibility with legacy crtc helpers this should be called before drm_atomic_helper_commit_planes(), which is what the default commit function does. But drivers with different needs can group the modeset commits together and do the plane commits at the end. This is useful for drivers doing runtime PM since planes updates then only happen when the CRTC is actually enabled.

void drm_atomic_helper_commit_modeset_enables(struct drm_device * dev, struct drm_atomic_state * old_state)

modeset commit to enable outputs

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

This function enables all the outputs with the new configuration which had to be turned off for the update.

For compatibility with legacy crtc helpers this should be called after drm_atomic_helper_commit_planes(), which is what the default commit function does. But drivers with different needs can group the modeset commits together and do the plane commits at the end. This is useful for drivers doing runtime PM since planes updates then only happen when the CRTC is actually enabled.

int drm_atomic_helper_wait_for_fences(struct drm_device * dev, struct drm_atomic_state * state, bool pre_swap)

wait for fences stashed in plane state

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * state

atomic state object with old state structures

bool pre_swap

If true, do an interruptible wait, and state is the new state. Otherwise state is the old state.

Description

For implicit sync, driver should fish the exclusive fence out from the incoming fb's and stash it in the drm_plane_state. This is called after drm_atomic_helper_swap_state() so it uses the current plane state (and just uses the atomic state to find the changed planes)

Note that pre_swap is needed since the point where we block for fences moves around depending upon whether an atomic commit is blocking or non-blocking. For non-blocking commit all waiting needs to happen after drm_atomic_helper_swap_state() is called, but for blocking commits we want to wait before we do anything that can't be easily rolled back. That is before we call drm_atomic_helper_swap_state().

Returns zero if success or < 0 if dma_fence_wait() fails.

void drm_atomic_helper_wait_for_vblanks(struct drm_device * dev, struct drm_atomic_state * old_state)

wait for vblank on crtcs

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

Helper to, after atomic commit, wait for vblanks on all effected crtcs (ie. before cleaning up old framebuffers using drm_atomic_helper_cleanup_planes()). It will only wait on CRTCs where the framebuffers have actually changed to optimize for the legacy cursor and plane update use-case.

Drivers using the nonblocking commit tracking support initialized by calling drm_atomic_helper_setup_commit() should look at drm_atomic_helper_wait_for_flip_done() as an alternative.

void drm_atomic_helper_wait_for_flip_done(struct drm_device * dev, struct drm_atomic_state * old_state)

wait for all page flips to be done

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

Helper to, after atomic commit, wait for page flips on all effected crtcs (ie. before cleaning up old framebuffers using drm_atomic_helper_cleanup_planes()). Compared to drm_atomic_helper_wait_for_vblanks() this waits for the completion of on all CRTCs, assuming that cursors-only updates are signalling their completion immediately (or using a different path).

This requires that drivers use the nonblocking commit tracking support initialized using drm_atomic_helper_setup_commit().

void drm_atomic_helper_commit_tail(struct drm_atomic_state * old_state)

commit atomic update to hardware

Parameters

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

This is the default implementation for the drm_mode_config_helper_funcs.atomic_commit_tail hook, for drivers that do not support runtime_pm or do not need the CRTC to be enabled to perform a commit. Otherwise, see drm_atomic_helper_commit_tail_rpm().

Note that the default ordering of how the various stages are called is to match the legacy modeset helper library closest.

void drm_atomic_helper_commit_tail_rpm(struct drm_atomic_state * old_state)

commit atomic update to hardware

Parameters

struct drm_atomic_state * old_state

new modeset state to be committed

Description

This is an alternative implementation for the drm_mode_config_helper_funcs.atomic_commit_tail hook, for drivers that support runtime_pm or need the CRTC to be enabled to perform a commit. Otherwise, one should use the default implementation drm_atomic_helper_commit_tail().

int drm_atomic_helper_async_check(struct drm_device * dev, struct drm_atomic_state * state)

check if state can be commited asynchronously

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * state

the driver state object

Description

This helper will check if it is possible to commit the state asynchronously. Async commits are not supposed to swap the states like normal sync commits but just do in-place changes on the current state.

It will return 0 if the commit can happen in an asynchronous fashion or error if not. Note that error just mean it can't be commited asynchronously, if it fails the commit should be treated like a normal synchronous commit.

void drm_atomic_helper_async_commit(struct drm_device * dev, struct drm_atomic_state * state)

commit state asynchronously

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * state

the driver state object

Description

This function commits a state asynchronously, i.e., not vblank synchronized. It should be used on a state only when drm_atomic_async_check() succeeds. Async commits are not supposed to swap the states like normal sync commits, but just do in-place changes on the current state.

TODO: Implement full swap instead of doing in-place changes.

int drm_atomic_helper_commit(struct drm_device * dev, struct drm_atomic_state * state, bool nonblock)

commit validated state object

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * state

the driver state object

bool nonblock

whether nonblocking behavior is requested.

Description

This function commits a with drm_atomic_helper_check() pre-validated state object. This can still fail when e.g. the framebuffer reservation fails. This function implements nonblocking commits, using drm_atomic_helper_setup_commit() and related functions.

Committing the actual hardware state is done through the drm_mode_config_helper_funcs.atomic_commit_tail callback, or its default implementation drm_atomic_helper_commit_tail().

Return

Zero for success or -errno.

int drm_atomic_helper_setup_commit(struct drm_atomic_state * state, bool nonblock)

setup possibly nonblocking commit

Parameters

struct drm_atomic_state * state

new modeset state to be committed

bool nonblock

whether nonblocking behavior is requested.

Description

This function prepares state to be used by the atomic helper's support for nonblocking commits. Drivers using the nonblocking commit infrastructure should always call this function from their drm_mode_config_funcs.atomic_commit hook.

To be able to use this support drivers need to use a few more helper functions. drm_atomic_helper_wait_for_dependencies() must be called before actually committing the hardware state, and for nonblocking commits this call must be placed in the async worker. See also drm_atomic_helper_swap_state() and its stall parameter, for when a driver's commit hooks look at the drm_crtc.state, drm_plane.state or drm_connector.state pointer directly.

Completion of the hardware commit step must be signalled using drm_atomic_helper_commit_hw_done(). After this step the driver is not allowed to read or change any permanent software or hardware modeset state. The only exception is state protected by other means than drm_modeset_lock locks. Only the free standing state with pointers to the old state structures can be inspected, e.g. to clean up old buffers using drm_atomic_helper_cleanup_planes().

At the very end, before cleaning up state drivers must call drm_atomic_helper_commit_cleanup_done().

This is all implemented by in drm_atomic_helper_commit(), giving drivers a complete and easy-to-use default implementation of the atomic_commit() hook.

The tracking of asynchronously executed and still pending commits is done using the core structure drm_crtc_commit.

By default there's no need to clean up resources allocated by this function explicitly: drm_atomic_state_default_clear() will take care of that automatically.

Return

0 on success. -EBUSY when userspace schedules nonblocking commits too fast, -ENOMEM on allocation failures and -EINTR when a signal is pending.

void drm_atomic_helper_wait_for_dependencies(struct drm_atomic_state * old_state)

wait for required preceeding commits

Parameters

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

This function waits for all preceeding commits that touch the same CRTC as old_state to both be committed to the hardware (as signalled by drm_atomic_helper_commit_hw_done) and executed by the hardware (as signalled by calling drm_crtc_send_vblank_event() on the drm_crtc_state.event).

This is part of the atomic helper support for nonblocking commits, see drm_atomic_helper_setup_commit() for an overview.

void drm_atomic_helper_fake_vblank(struct drm_atomic_state * old_state)

fake VBLANK events if needed

Parameters

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

This function walks all CRTCs and fake VBLANK events on those with drm_crtc_state.no_vblank set to true and drm_crtc_state.event != NULL. The primary use of this function is writeback connectors working in oneshot mode and faking VBLANK events. In this case they only fake the VBLANK event when a job is queued, and any change to the pipeline that does not touch the connector is leading to timeouts when calling drm_atomic_helper_wait_for_vblanks() or drm_atomic_helper_wait_for_flip_done().

This is part of the atomic helper support for nonblocking commits, see drm_atomic_helper_setup_commit() for an overview.

void drm_atomic_helper_commit_hw_done(struct drm_atomic_state * old_state)

setup possible nonblocking commit

Parameters

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

This function is used to signal completion of the hardware commit step. After this step the driver is not allowed to read or change any permanent software or hardware modeset state. The only exception is state protected by other means than drm_modeset_lock locks.

Drivers should try to postpone any expensive or delayed cleanup work after this function is called.

This is part of the atomic helper support for nonblocking commits, see drm_atomic_helper_setup_commit() for an overview.

void drm_atomic_helper_commit_cleanup_done(struct drm_atomic_state * old_state)

signal completion of commit

Parameters

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

This signals completion of the atomic update old_state, including any cleanup work. If used, it must be called right before calling drm_atomic_state_put().

This is part of the atomic helper support for nonblocking commits, see drm_atomic_helper_setup_commit() for an overview.

int drm_atomic_helper_prepare_planes(struct drm_device * dev, struct drm_atomic_state * state)

prepare plane resources before commit

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * state

atomic state object with new state structures

Description

This function prepares plane state, specifically framebuffers, for the new configuration, by calling drm_plane_helper_funcs.prepare_fb. If any failure is encountered this function will call drm_plane_helper_funcs.cleanup_fb on any already successfully prepared framebuffer.

Return

0 on success, negative error code on failure.

void drm_atomic_helper_commit_planes(struct drm_device * dev, struct drm_atomic_state * old_state, uint32_t flags)

commit plane state

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * old_state

atomic state object with old state structures

uint32_t flags

flags for committing plane state

Description

This function commits the new plane state using the plane and atomic helper functions for planes and crtcs. It assumes that the atomic state has already been pushed into the relevant object state pointers, since this step can no longer fail.

It still requires the global state object old_state to know which planes and crtcs need to be updated though.

Note that this function does all plane updates across all CRTCs in one step. If the hardware can't support this approach look at drm_atomic_helper_commit_planes_on_crtc() instead.

Plane parameters can be updated by applications while the associated CRTC is disabled. The DRM/KMS core will store the parameters in the plane state, which will be available to the driver when the CRTC is turned on. As a result most drivers don't need to be immediately notified of plane updates for a disabled CRTC.

Unless otherwise needed, drivers are advised to set the ACTIVE_ONLY flag in flags in order not to receive plane update notifications related to a disabled CRTC. This avoids the need to manually ignore plane updates in driver code when the driver and/or hardware can't or just don't need to deal with updates on disabled CRTCs, for example when supporting runtime PM.

Drivers may set the NO_DISABLE_AFTER_MODESET flag in flags if the relevant display controllers require to disable a CRTC's planes when the CRTC is disabled. This function would skip the drm_plane_helper_funcs.atomic_disable call for a plane if the CRTC of the old plane state needs a modesetting operation. Of course, the drivers need to disable the planes in their CRTC disable callbacks since no one else would do that.

The drm_atomic_helper_commit() default implementation doesn't set the ACTIVE_ONLY flag to most closely match the behaviour of the legacy helpers. This should not be copied blindly by drivers.

void drm_atomic_helper_commit_planes_on_crtc(struct drm_crtc_state * old_crtc_state)

commit plane state for a crtc

Parameters

struct drm_crtc_state * old_crtc_state

atomic state object with the old crtc state

Description

This function commits the new plane state using the plane and atomic helper functions for planes on the specific crtc. It assumes that the atomic state has already been pushed into the relevant object state pointers, since this step can no longer fail.

This function is useful when plane updates should be done crtc-by-crtc instead of one global step like drm_atomic_helper_commit_planes() does.

This function can only be savely used when planes are not allowed to move between different CRTCs because this function doesn't handle inter-CRTC depencies. Callers need to ensure that either no such depencies exist, resolve them through ordering of commit calls or through some other means.

void drm_atomic_helper_disable_planes_on_crtc(struct drm_crtc_state * old_crtc_state, bool atomic)

helper to disable CRTC's planes

Parameters

struct drm_crtc_state * old_crtc_state

atomic state object with the old CRTC state

bool atomic

if set, synchronize with CRTC's atomic_begin/flush hooks

Description

Disables all planes associated with the given CRTC. This can be used for instance in the CRTC helper atomic_disable callback to disable all planes.

If the atomic-parameter is set the function calls the CRTC's atomic_begin hook before and atomic_flush hook after disabling the planes.

It is a bug to call this function without having implemented the drm_plane_helper_funcs.atomic_disable plane hook.

void drm_atomic_helper_cleanup_planes(struct drm_device * dev, struct drm_atomic_state * old_state)

cleanup plane resources after commit

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * old_state

atomic state object with old state structures

Description

This function cleans up plane state, specifically framebuffers, from the old configuration. Hence the old configuration must be perserved in old_state to be able to call this function.

This function must also be called on the new state when the atomic update fails at any point after calling drm_atomic_helper_prepare_planes().

int drm_atomic_helper_swap_state(struct drm_atomic_state * state, bool stall)

store atomic state into current sw state

Parameters

struct drm_atomic_state * state

atomic state

bool stall

stall for preceeding commits

Description

This function stores the atomic state into the current state pointers in all driver objects. It should be called after all failing steps have been done and succeeded, but before the actual hardware state is committed.

For cleanup and error recovery the current state for all changed objects will be swapped into state.

With that sequence it fits perfectly into the plane prepare/cleanup sequence:

1. Call drm_atomic_helper_prepare_planes() with the staged atomic state.

2. Do any other steps that might fail.

3. Put the staged state into the current state pointers with this function.

4. Actually commit the hardware state.

5. Call drm_atomic_helper_cleanup_planes() with state, which since step 3 contains the old state. Also do any other cleanup required with that state.

stall must be set when nonblocking commits for this driver directly access the drm_plane.state, drm_crtc.state or drm_connector.state pointer. With the current atomic helpers this is almost always the case, since the helpers don't pass the right state structures to the callbacks.

Return

Returns 0 on success. Can return -ERESTARTSYS when stall is true and the waiting for the previous commits has been interrupted.

int drm_atomic_helper_update_plane(struct drm_plane * plane, struct drm_crtc * crtc, struct drm_framebuffer * fb, int crtc_x, int crtc_y, unsigned int crtc_w, unsigned int crtc_h, uint32_t src_x, uint32_t src_y, uint32_t src_w, uint32_t src_h, struct drm_modeset_acquire_ctx * ctx)

Helper for primary plane update using atomic

Parameters

struct drm_plane * plane

plane object to update

struct drm_crtc * crtc

owning CRTC of owning plane

struct drm_framebuffer * fb

framebuffer to flip onto plane

int crtc_x

x offset of primary plane on crtc

int crtc_y

y offset of primary plane on crtc

unsigned int crtc_w

width of primary plane rectangle on crtc

unsigned int crtc_h

height of primary plane rectangle on crtc

uint32_t src_x

x offset of fb for panning

uint32_t src_y

y offset of fb for panning

uint32_t src_w

width of source rectangle in fb

uint32_t src_h

height of source rectangle in fb

struct drm_modeset_acquire_ctx * ctx

lock acquire context

Description

Provides a default plane update handler using the atomic driver interface.

Return

Zero on success, error code on failure

int drm_atomic_helper_disable_plane(struct drm_plane * plane, struct drm_modeset_acquire_ctx * ctx)

Helper for primary plane disable using * atomic

Parameters

struct drm_plane * plane

plane to disable

struct drm_modeset_acquire_ctx * ctx

lock acquire context

Description

Provides a default plane disable handler using the atomic driver interface.

Return

Zero on success, error code on failure

int drm_atomic_helper_set_config(struct drm_mode_set * set, struct drm_modeset_acquire_ctx * ctx)

set a new config from userspace

Parameters

struct drm_mode_set * set

mode set configuration

struct drm_modeset_acquire_ctx * ctx

lock acquisition context

Description

Provides a default crtc set_config handler using the atomic driver interface.

NOTE

For backwards compatibility with old userspace this automatically resets the "link-status" property to GOOD, to force any link re-training. The SETCRTC ioctl does not define whether an update does need a full modeset or just a plane update, hence we're allowed to do that. See also drm_connector_set_link_status_property().

Return

Returns 0 on success, negative errno numbers on failure.

int drm_atomic_helper_disable_all(struct drm_device * dev, struct drm_modeset_acquire_ctx * ctx)

disable all currently active outputs

Parameters

struct drm_device * dev

DRM device

struct drm_modeset_acquire_ctx * ctx

lock acquisition context

Description

Loops through all connectors, finding those that aren't turned off and then turns them off by setting their DPMS mode to OFF and deactivating the CRTC that they are connected to.

This is used for example in suspend/resume to disable all currently active functions when suspending. If you just want to shut down everything at e.g. driver unload, look at drm_atomic_helper_shutdown().

Note that if callers haven't already acquired all modeset locks this might return -EDEADLK, which must be handled by calling drm_modeset_backoff().

Return

0 on success or a negative error code on failure.

See also: drm_atomic_helper_suspend(), drm_atomic_helper_resume() and drm_atomic_helper_shutdown().

void drm_atomic_helper_shutdown(struct drm_device * dev)

shutdown all CRTC

Parameters

struct drm_device * dev

DRM device

Description

This shuts down all CRTC, which is useful for driver unloading. Shutdown on suspend should instead be handled with drm_atomic_helper_suspend(), since that also takes a snapshot of the modeset state to be restored on resume.

This is just a convenience wrapper around drm_atomic_helper_disable_all(), and it is the atomic version of drm_crtc_force_disable_all().

struct drm_atomic_state * drm_atomic_helper_duplicate_state(struct drm_device * dev, struct drm_modeset_acquire_ctx * ctx)

duplicate an atomic state object

Parameters

struct drm_device * dev

DRM device

struct drm_modeset_acquire_ctx * ctx

lock acquisition context

Description

Makes a copy of the current atomic state by looping over all objects and duplicating their respective states. This is used for example by suspend/ resume support code to save the state prior to suspend such that it can be restored upon resume.

Note that this treats atomic state as persistent between save and restore. Drivers must make sure that this is possible and won't result in confusion or erroneous behaviour.

Note that if callers haven't already acquired all modeset locks this might return -EDEADLK, which must be handled by calling drm_modeset_backoff().

Return

A pointer to the copy of the atomic state object on success or an ERR_PTR()-encoded error code on failure.

See also: drm_atomic_helper_suspend(), drm_atomic_helper_resume()

struct drm_atomic_state * drm_atomic_helper_suspend(struct drm_device * dev)

subsystem-level suspend helper

Parameters

struct drm_device * dev

DRM device

Description

Duplicates the current atomic state, disables all active outputs and then returns a pointer to the original atomic state to the caller. Drivers can pass this pointer to the drm_atomic_helper_resume() helper upon resume to restore the output configuration that was active at the time the system entered suspend.

Note that it is potentially unsafe to use this. The atomic state object returned by this function is assumed to be persistent. Drivers must ensure that this holds true. Before calling this function, drivers must make sure to suspend fbdev emulation so that nothing can be using the device.

Return

A pointer to a copy of the state before suspend on success or an ERR_PTR()- encoded error code on failure. Drivers should store the returned atomic state object and pass it to the drm_atomic_helper_resume() helper upon resume.

See also: drm_atomic_helper_duplicate_state(), drm_atomic_helper_disable_all(), drm_atomic_helper_resume(), drm_atomic_helper_commit_duplicated_state()

int drm_atomic_helper_commit_duplicated_state(struct drm_atomic_state * state, struct drm_modeset_acquire_ctx * ctx)

commit duplicated state

Parameters

struct drm_atomic_state * state

duplicated atomic state to commit

struct drm_modeset_acquire_ctx * ctx

pointer to acquire_ctx to use for commit.

Description

The state returned by drm_atomic_helper_duplicate_state() and drm_atomic_helper_suspend() is partially invalid, and needs to be fixed up before commit.

Return

0 on success or a negative error code on failure.

See also: drm_atomic_helper_suspend()

int drm_atomic_helper_resume(struct drm_device * dev, struct drm_atomic_state * state)

subsystem-level resume helper

Parameters

struct drm_device * dev

DRM device

struct drm_atomic_state * state

atomic state to resume to

Description

Calls drm_mode_config_reset() to synchronize hardware and software states, grabs all modeset locks and commits the atomic state object. This can be used in conjunction with the drm_atomic_helper_suspend() helper to implement suspend/resume for drivers that support atomic mode-setting.

Return

0 on success or a negative error code on failure.

See also: drm_atomic_helper_suspend()

int drm_atomic_helper_page_flip(struct drm_crtc * crtc, struct drm_framebuffer * fb, struct drm_pending_vblank_event * event, uint32_t flags, struct drm_modeset_acquire_ctx * ctx)

execute a legacy page flip

Parameters

struct drm_crtc * crtc

DRM crtc

struct drm_framebuffer * fb

DRM framebuffer

struct drm_pending_vblank_event * event

optional DRM event to signal upon completion

uint32_t flags

flip flags for non-vblank sync'ed updates

struct drm_modeset_acquire_ctx * ctx

lock acquisition context

Description

Provides a default drm_crtc_funcs.page_flip implementation using the atomic driver interface.

Return

Returns 0 on success, negative errno numbers on failure.

See also: drm_atomic_helper_page_flip_target()

int drm_atomic_helper_page_flip_target(struct drm_crtc * crtc, struct drm_framebuffer * fb, struct drm_pending_vblank_event * event, uint32_t flags, uint32_t target, struct drm_modeset_acquire_ctx * ctx)

do page flip on target vblank period.

Parameters

struct drm_crtc * crtc

DRM crtc

struct drm_framebuffer * fb

DRM framebuffer

struct drm_pending_vblank_event * event

optional DRM event to signal upon completion

uint32_t flags

flip flags for non-vblank sync'ed updates

uint32_t target

specifying the target vblank period when the flip to take effect

struct drm_modeset_acquire_ctx * ctx

lock acquisition context

Description

Provides a default drm_crtc_funcs.page_flip_target implementation. Similar to drm_atomic_helper_page_flip() with extra parameter to specify target vblank period to flip.

Return

Returns 0 on success, negative errno numbers on failure.

int drm_atomic_helper_legacy_gamma_set(struct drm_crtc * crtc, u16 * red, u16 * green, u16 * blue, uint32_t size, struct drm_modeset_acquire_ctx * ctx)

set the legacy gamma correction table

Parameters

struct drm_crtc * crtc

CRTC object

u16 * red

red correction table

u16 * green

green correction table

u16 * blue

green correction table

uint32_t size

size of the tables

struct drm_modeset_acquire_ctx * ctx

lock acquire context

Description

Implements support for legacy gamma correction table for drivers that support color management through the DEGAMMA_LUT/GAMMA_LUT properties. See drm_crtc_enable_color_mgmt() and the containing chapter for how the atomic color management and gamma tables work.

Atomic State Reset and Initialization

Both the drm core and the atomic helpers assume that there is always the full and correct atomic software state for all connectors, CRTCs and planes available. Which is a bit a problem on driver load and also after system suspend. One way to solve this is to have a hardware state read-out infrastructure which reconstructs the full software state (e.g. the i915 driver).

The simpler solution is to just reset the software state to everything off, which is easiest to do by calling drm_mode_config_reset(). To facilitate this the atomic helpers provide default reset implementations for all hooks.

On the upside the precise state tracking of atomic simplifies system suspend and resume a lot. For drivers using drm_mode_config_reset() a complete recipe is implemented in drm_atomic_helper_suspend() and drm_atomic_helper_resume(). For other drivers the building blocks are split out, see the documentation for these functions.

Atomic State Helper Reference

void __drm_atomic_helper_crtc_reset(struct drm_crtc * crtc, struct drm_crtc_state * crtc_state)

reset state on CRTC

Parameters

struct drm_crtc * crtc

drm CRTC

struct drm_crtc_state * crtc_state

CRTC state to assign

Description

Initializes the newly allocated crtc_state and assigns it to the drm_crtc->state pointer of crtc, usually required when initializing the drivers or when called from the drm_crtc_funcs.reset hook.

This is useful for drivers that subclass the CRTC state.

void drm_atomic_helper_crtc_reset(struct drm_crtc * crtc)

default drm_crtc_funcs.reset hook for CRTCs

Parameters

struct drm_crtc * crtc

drm CRTC

Description

Resets the atomic state for crtc by freeing the state pointer (which might be NULL, e.g. at driver load time) and allocating a new empty state object.

void __drm_atomic_helper_crtc_duplicate_state(struct drm_crtc * crtc, struct drm_crtc_state * state)

copy atomic CRTC state

Parameters

struct drm_crtc * crtc

CRTC object

struct drm_crtc_state * state

atomic CRTC state

Description

Copies atomic state from a CRTC's current state and resets inferred values. This is useful for drivers that subclass the CRTC state.

struct drm_crtc_state * drm_atomic_helper_crtc_duplicate_state(struct drm_crtc * crtc)

default state duplicate hook

Parameters

struct drm_crtc * crtc

drm CRTC

Description

Default CRTC state duplicate hook for drivers which don't have their own subclassed CRTC state structure.

void __drm_atomic_helper_crtc_destroy_state(struct drm_crtc_state * state)

release CRTC state

Parameters

struct drm_crtc_state * state

CRTC state object to release

Description

Releases all resources stored in the CRTC state without actually freeing the memory of the CRTC state. This is useful for drivers that subclass the CRTC state.

void drm_atomic_helper_crtc_destroy_state(struct drm_crtc * crtc, struct drm_crtc_state * state)

default state destroy hook

Parameters

struct drm_crtc * crtc

drm CRTC

struct drm_crtc_state * state

CRTC state object to release

Description

Default CRTC state destroy hook for drivers which don't have their own subclassed CRTC state structure.

void __drm_atomic_helper_plane_reset(struct drm_plane * plane, struct drm_plane_state * state)

resets planes state to default values

Parameters

struct drm_plane * plane

plane object, must not be NULL

struct drm_plane_state * state

atomic plane state, must not be NULL

Description

Initializes plane state to default. This is useful for drivers that subclass the plane state.

void drm_atomic_helper_plane_reset(struct drm_plane * plane)

default drm_plane_funcs.reset hook for planes

Parameters

struct drm_plane * plane

drm plane

Description

Resets the atomic state for plane by freeing the state pointer (which might be NULL, e.g. at driver load time) and allocating a new empty state object.

void __drm_atomic_helper_plane_duplicate_state(struct drm_plane * plane, struct drm_plane_state * state)

copy atomic plane state

Parameters

struct drm_plane * plane

plane object

struct drm_plane_state * state

atomic plane state

Description

Copies atomic state from a plane's current state. This is useful for drivers that subclass the plane state.

struct drm_plane_state * drm_atomic_helper_plane_duplicate_state(struct drm_plane * plane)

default state duplicate hook

Parameters

struct drm_plane * plane

drm plane

Description

Default plane state duplicate hook for drivers which don't have their own subclassed plane state structure.

void __drm_atomic_helper_plane_destroy_state(struct drm_plane_state * state)

release plane state

Parameters

struct drm_plane_state * state

plane state object to release

Description

Releases all resources stored in the plane state without actually freeing the memory of the plane state. This is useful for drivers that subclass the plane state.

void drm_atomic_helper_plane_destroy_state(struct drm_plane * plane, struct drm_plane_state * state)

default state destroy hook

Parameters

struct drm_plane * plane

drm plane

struct drm_plane_state * state

plane state object to release

Description

Default plane state destroy hook for drivers which don't have their own subclassed plane state structure.

void __drm_atomic_helper_connector_reset(struct drm_connector * connector, struct drm_connector_state * conn_state)

reset state on connector

Parameters

struct drm_connector * connector

drm connector

struct drm_connector_state * conn_state

connector state to assign

Description

Initializes the newly allocated conn_state and assigns it to the drm_connector->state pointer of connector, usually required when initializing the drivers or when called from the drm_connector_funcs.reset hook.

This is useful for drivers that subclass the connector state.

void drm_atomic_helper_connector_reset(struct drm_connector * connector)

default drm_connector_funcs.reset hook for connectors

Parameters

struct drm_connector * connector

drm connector

Description

Resets the atomic state for connector by freeing the state pointer (which might be NULL, e.g. at driver load time) and allocating a new empty state object.

void drm_atomic_helper_connector_tv_reset(struct drm_connector * connector)

Resets TV connector properties

Parameters

struct drm_connector * connector

DRM connector

Description

Resets the TV-related properties attached to a connector.

void __drm_atomic_helper_connector_duplicate_state(struct drm_connector * connector, struct drm_connector_state * state)

copy atomic connector state

Parameters

struct drm_connector * connector

connector object

struct drm_connector_state * state

atomic connector state

Description

Copies atomic state from a connector's current state. This is useful for drivers that subclass the connector state.

struct drm_connector_state * drm_atomic_helper_connector_duplicate_state(struct drm_connector * connector)

default state duplicate hook

Parameters

struct drm_connector * connector

drm connector

Description

Default connector state duplicate hook for drivers which don't have their own subclassed connector state structure.

void __drm_atomic_helper_connector_destroy_state(struct drm_connector_state * state)

release connector state

Parameters

struct drm_connector_state * state

connector state object to release

Description

Releases all resources stored in the connector state without actually freeing the memory of the connector state. This is useful for drivers that subclass the connector state.

void drm_atomic_helper_connector_destroy_state(struct drm_connector * connector, struct drm_connector_state * state)

default state destroy hook

Parameters

struct drm_connector * connector

drm connector

struct drm_connector_state * state

connector state object to release

Description

Default connector state destroy hook for drivers which don't have their own subclassed connector state structure.

void __drm_atomic_helper_private_obj_duplicate_state(struct drm_private_obj * obj, struct drm_private_state * state)

copy atomic private state

Parameters

struct drm_private_obj * obj

CRTC object

struct drm_private_state * state

new private object state

Description

Copies atomic state from a private objects's current state and resets inferred values. This is useful for drivers that subclass the private state.

Simple KMS Helper Reference

This helper library provides helpers for drivers for simple display hardware.

drm_simple_display_pipe_init() initializes a simple display pipeline which has only one full-screen scanout buffer feeding one output. The pipeline is represented by struct drm_simple_display_pipe and binds together drm_plane, drm_crtc and drm_encoder structures into one fixed entity. Some flexibility for code reuse is provided through a separately allocated drm_connector object and supporting optional drm_bridge encoder drivers.

struct drm_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_crtc *crtc, 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 the crtc used in this simple display pipe. This should be implemented if the display pipe has some sort of restriction in the modes it can display. For example, a given display pipe may be responsible to set a clock value. If the clock can not produce all the values for the available modes then this callback can be used to restrict the number of modes to only the ones that can be displayed. Another reason can be bandwidth mitigation: the memory port on the display controller can have bandwidth limitations not allowing pixel data to be fetched at any rate.

This hook is used by the probe helpers to filter the mode list in drm_helper_probe_single_connector_modes(), and it is used by the atomic helpers to validate modes supplied by userspace in drm_atomic_helper_check_modeset().

This function is optional.

NOTE:

Since this function is both called from the check phase of an atomic commit, and the mode validation in the probe paths it is not allowed to look at anything else but the passed-in mode, and validate it against 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 is not scaled, fills the entire visible area and is always enabled when the crtc is also enabled. This hook is optional.

RETURNS:

0 on success, -EINVAL if the state or the transition can't be supported, -ENOMEM on memory allocation failure and -EDEADLK if an attempt to obtain another state object ran into a drm_modeset_lock deadlock.

update

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

This is the function drivers should submit the drm_pending_vblank_event from. Using either drm_crtc_arm_vblank_event(), when the driver supports vblank interrupt handling, or drm_crtc_send_vblank_event() directly in case the hardware lacks vblank support entirely.

prepare_fb

Optional, called by drm_plane_helper_funcs.prepare_fb. Please read the documentation for the drm_plane_helper_funcs.prepare_fb hook for more details.

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

cleanup_fb

Optional, called by drm_plane_helper_funcs.cleanup_fb. Please read the documentation for the drm_plane_helper_funcs.cleanup_fb hook for more details.

enable_vblank

Optional, called by drm_crtc_funcs.enable_vblank. Please read the documentation for the drm_crtc_funcs.enable_vblank hook for more details.

disable_vblank

Optional, called by drm_crtc_funcs.disable_vblank. Please read the documentation for the drm_crtc_funcs.disable_vblank hook for more details.

struct drm_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 one entity. It should be initialized by calling drm_simple_display_pipe_init().

int drm_simple_display_pipe_attach_bridge(struct drm_simple_display_pipe * pipe, struct drm_bridge * bridge)

Attach a bridge to the display pipe

Parameters

struct drm_simple_display_pipe * pipe

simple display pipe object

struct drm_bridge * bridge

bridge to attach

Description

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

Note that you probably want to initialize the pipe by passing a NULL connector to drm_simple_display_pipe_init().

Return

Zero on success, negative error code on failure.

int drm_simple_display_pipe_init(struct drm_device * dev, struct drm_simple_display_pipe * pipe, const struct drm_simple_display_pipe_funcs * funcs, const uint32_t * formats, unsigned int format_count, const uint64_t * format_modifiers, struct drm_connector * connector)

Initialize a simple display pipeline

Parameters

struct drm_device * dev

DRM device

struct drm_simple_display_pipe * pipe

simple display pipe object to initialize

const struct drm_simple_display_pipe_funcs * funcs

callbacks for the display pipe (optional)

const uint32_t * formats

array of supported formats (DRM_FORMAT_*)

unsigned int format_count

number of elements in formats

const uint64_t * format_modifiers

array of formats modifiers

struct drm_connector * connector

connector to attach and register (optional)

Description

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

If a connector is supplied, the pipe will be coupled with the provided connector. You may supply a NULL connector when using drm bridges, that handle connectors themselves (see drm_simple_display_pipe_attach_bridge()).

Teardown of a simple display pipe is all handled automatically by the drm core through calling drm_mode_config_cleanup(). Drivers afterwards need to release 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 kernel mode setting driver. They can be used mostly independently from the crtc helper functions used by many drivers to implement the kernel mode setting interfaces.

Drivers that support a dumb buffer with a virtual address and mmap support, should try out the generic fbdev emulation using drm_fbdev_generic_setup().

Setup fbdev emulation by calling drm_fb_helper_fbdev_setup() and tear it down by calling drm_fb_helper_fbdev_teardown().

At runtime drivers should restore the fbdev console by using drm_fb_helper_lastclose() as their drm_driver.lastclose callback. They should also notify the fb helper code from updates to the output configuration by using drm_fb_helper_output_poll_changed() as their drm_mode_config_funcs.output_poll_changed callback.

For suspend/resume consider using drm_mode_config_helper_suspend() and drm_mode_config_helper_resume() which takes care of fbdev as well.

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

It is possible, though perhaps somewhat tricky, to implement race-free hotplug detection using the fbdev helpers. The drm_fb_helper_prepare() helper must be called first to initialize the minimum required to make hotplug detection work. Drivers also need to make sure to properly set up the drm_mode_config.funcs member. After calling drm_kms_helper_poll_init() it is safe to enable interrupts and start processing hotplug events. At the same time, drivers should initialize all modeset objects such as CRTCs, encoders and connectors. To finish up the fbdev helper initialization, the drm_fb_helper_init() function is called. To probe for all attached displays and set up an initial configuration using the detected hardware, drivers should call drm_fb_helper_initial_config().

If drm_framebuffer_funcs.dirty is set, the drm_fb_helper_{cfb,sys}_{write,fillrect,copyarea,imageblit} functions will accumulate changes and schedule drm_fb_helper.dirty_work to run right away. This worker then calls the dirty() function ensuring that it will always run in process context since the fb_*() function could be running in atomic context. If drm_fb_helper_deferred_io() is used as the deferred_io callback it will also schedule dirty_work with the damage collected from the mmap page writes. Drivers can use drm_fb_helper_defio_init() to setup deferred I/O (coupled with drm_fb_helper_fbdev_teardown()).

struct drm_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 fbdev width/height. In case of multiple displays, the scanout surface is sized according to the largest width/height (so it is large enough for all CRTCs to scanout). But the fbdev width/height is sized to the minimum width/ height of all the displays. This ensures that fbcon fits on the smallest of the attached displays. fb_width/fb_height is used by drm_fb_helper_fill_info() to fill out the fb_info.var structure.

struct drm_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 to back the fbdev.

This callback is mandatory.

RETURNS:

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

Description

Driver callbacks used by the fbdev emulation helper library.

struct drm_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 to the screen buffer

dirty_lock

spinlock protecting dirty_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 data structures and lists, such as connector_info and crtc_info.

FIXME: fbdev emulation locking is a mess and long term we want to protect all helper internal state with this lock as well as reduce core 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 DRM device, i.e. another KMS master was active. The output configuration needs to be reprobe when fbdev is in control again.

deferred_setup

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

Protected by lock.

preferred_bpp

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

See also: deferred_setup

Description

This is the main structure used by the fbdev helpers. Drivers supporting fbdev emulation should embedded this into their overall driver structure. Drivers must also fill out a struct drm_fb_helper_funcs with a few operations.

DRM_FB_HELPER_DEFAULT_OPS()

helper define for drm drivers

Parameters

Description

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

int drm_fb_helper_remove_conflicting_framebuffers(struct apertures_struct * a, const char * name, bool primary)

remove firmware-configured framebuffers

Parameters

struct apertures_struct * a

memory range, users of which are to be removed

const char * name

requesting driver name

bool primary

also kick vga16fb if present

Description

This function removes framebuffer devices (initialized by firmware/bootloader) which use memory range described by a. If a is NULL all such devices are removed.

int drm_fb_helper_remove_conflicting_pci_framebuffers(struct pci_dev * pdev, int resource_id, const char * name)

remove firmware-configured framebuffers for PCI devices

Parameters

struct pci_dev * pdev

PCI device

int resource_id

index of PCI BAR configuring framebuffer memory

const char * name

requesting driver name

Description

This function removes framebuffer devices (eg. initialized by firmware) using memory range configured for pdev's BAR resource_id.

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

int drm_fb_helper_debug_enter(struct fb_info * info)

implementation for fb_ops.fb_debug_enter

Parameters

struct fb_info * info

fbdev registered by the helper

int drm_fb_helper_debug_leave(struct fb_info * info)

implementation for fb_ops.fb_debug_leave

Parameters

struct fb_info * info

fbdev registered by the helper

int drm_fb_helper_restore_fbdev_mode_unlocked(struct drm_fb_helper * fb_helper)

restore fbdev configuration

Parameters

struct drm_fb_helper * fb_helper

driver-allocated fbdev helper, can be NULL

Description

This should be called from driver's drm drm_driver.lastclose callback when implementing an fbcon on top of kms using this helper. This ensures that the user isn't greeted with a black screen when e.g. X dies.

Return

Zero if everything went ok, negative error code otherwise.

int drm_fb_helper_blank(int blank, struct fb_info * info)

implementation for fb_ops.fb_blank

Parameters

int blank

desired blanking state

struct fb_info * info

fbdev registered by the helper

void drm_fb_helper_prepare(struct drm_device * dev, struct drm_fb_helper * helper, const struct drm_fb_helper_funcs * funcs)

setup a drm_fb_helper structure

Parameters

struct drm_device * dev

DRM device

struct drm_fb_helper * helper

driver-allocated fbdev helper structure to set up

const struct drm_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 is useful to implement race-free initialization of the polling helpers.

int drm_fb_helper_init(struct drm_device * dev, struct drm_fb_helper * fb_helper, int max_conn_count)

initialize a struct drm_fb_helper

Parameters

struct drm_device * dev

drm device

struct drm_fb_helper * fb_helper

driver-allocated fbdev helper structure to initialize

int max_conn_count

max connector count (not used)

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 in drm_fb_helper_initial_config() to allow driver writes more control over the exact init sequence.

Drivers must call drm_fb_helper_prepare() before calling this function.

Return

Zero if everything went ok, nonzero otherwise.

struct fb_info * drm_fb_helper_alloc_fbi(struct drm_fb_helper * fb_helper)

allocate fb_info and some of its members

Parameters

struct drm_fb_helper * fb_helper

driver-allocated fbdev helper

Description

A helper to alloc fb_info and the members cmap and apertures. Called by the driver within the fb_probe fb_helper callback function. Drivers do not need to release the allocated fb_info structure themselves, this is automatically done when calling drm_fb_helper_fini().

Return

fb_info pointer if things went okay, pointer containing error code otherwise

void drm_fb_helper_unregister_fbi(struct drm_fb_helper * fb_helper)

unregister fb_info framebuffer device

Parameters

struct drm_fb_helper * fb_helper

driver-allocated fbdev helper, can be NULL

Description

A wrapper around unregister_framebuffer, to release the fb_info framebuffer device. This must be called before releasing all resources for fb_helper by calling drm_fb_helper_fini().

void drm_fb_helper_fini(struct drm_fb_helper * fb_helper)

finialize a struct drm_fb_helper

Parameters

struct drm_fb_helper * fb_helper

driver-allocated fbdev helper, can be NULL

Description

This cleans up all remaining resources associated with fb_helper. Must be called after drm_fb_helper_unlink_fbi() was called.

void drm_fb_helper_unlink_fbi(struct drm_fb_helper * fb_helper)

wrapper around unlink_framebuffer

Parameters

struct drm_fb_helper * fb_helper

driver-allocated fbdev helper, can be NULL

Description

A wrapper around unlink_framebuffer implemented by fbdev core

void drm_fb_helper_deferred_io(struct fb_info * info, struct list_head * pagelist)

fbdev deferred_io callback function

Parameters

struct fb_info * info

fb_info struct pointer

struct list_head * pagelist

list of dirty mmap framebuffer pages

Description

This function is used as the fb_deferred_io.deferred_io callback function for flushing the fbdev mmap writes.

int drm_fb_helper_defio_init(struct drm_fb_helper * fb_helper)

fbdev deferred I/O initialization

Parameters

struct drm_fb_helper * fb_helper

driver-allocated fbdev helper

Description

This function allocates fb_deferred_io, sets callback to drm_fb_helper_deferred_io(), delay to 50ms and calls fb_deferred_io_init(). It should be called from the drm_fb_helper_funcs->fb_probe callback. drm_fb_helper_fbdev_teardown() cleans up deferred I/O.

NOTE

A copy of fb_ops is made and assigned to info->fbops. This is done because fb_deferred_io_cleanup() clears fbops->fb_mmap and would thereby affect other instances of that fb_ops.

Return

0 on success or a negative error code on failure.

ssize_t drm_fb_helper_sys_read(struct fb_info * info, char __user * buf, size_t count, loff_t * ppos)

wrapper around fb_sys_read

Parameters

struct fb_info * info

fb_info struct pointer

char __user * buf

userspace buffer to read from framebuffer memory

size_t count

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_t drm_fb_helper_sys_write(struct fb_info * info, const char __user * buf, size_t count, loff_t * ppos)

wrapper around fb_sys_write

Parameters

struct fb_info * info

fb_info struct pointer

const char __user * buf

userspace buffer to write to framebuffer memory

size_t count

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

void drm_fb_helper_sys_fillrect(struct fb_info * info, const struct fb_fillrect * rect)

wrapper around sys_fillrect

Parameters

struct fb_info * info

fbdev registered by the helper

const struct fb_fillrect * rect

info about rectangle to fill

Description

A wrapper around sys_fillrect implemented by fbdev core

void drm_fb_helper_sys_copyarea(struct fb_info * info, const struct fb_copyarea * area)

wrapper around sys_copyarea

Parameters

struct fb_info * info

fbdev registered by the helper

const struct fb_copyarea * area

info about area to copy

Description

A wrapper around sys_copyarea implemented by fbdev core

void drm_fb_helper_sys_imageblit(struct fb_info * info, const struct fb_image * image)

wrapper around sys_imageblit

Parameters

struct fb_info * info

fbdev registered by the helper

const struct fb_image * image

info about image to blit

Description

A wrapper around sys_imageblit implemented by fbdev core

void drm_fb_helper_cfb_fillrect(struct fb_info * info, const struct fb_fillrect * rect)

wrapper around cfb_fillrect

Parameters

struct fb_info * info

fbdev registered by the helper

const struct fb_fillrect * rect

info about rectangle to fill

Description

A wrapper around cfb_fillrect implemented by fbdev core

void drm_fb_helper_cfb_copyarea(struct fb_info * info, const struct fb_copyarea * area)

wrapper around cfb_copyarea

Parameters

struct fb_info * info

fbdev registered by the helper

const struct fb_copyarea * area

info about area to copy

Description

A wrapper around cfb_copyarea implemented by fbdev core

void drm_fb_helper_cfb_imageblit(struct fb_info * info, const struct fb_image * image)

wrapper around cfb_imageblit

Parameters

struct fb_info * info

fbdev registered by the helper

const struct fb_image * image

info about image to blit

Description

A wrapper around cfb_imageblit implemented by fbdev core

void drm_fb_helper_set_suspend(struct drm_fb_helper * fb_helper, bool suspend)

wrapper around fb_set_suspend

Parameters

struct drm_fb_helper * fb_helper

driver-allocated fbdev helper, can be NULL

bool suspend

whether to suspend or resume

Description

A wrapper around fb_set_suspend implemented by fbdev core. Use drm_fb_helper_set_suspend_unlocked() if you don't need to take the lock yourself

void drm_fb_helper_set_suspend_unlocked(struct drm_fb_helper * fb_helper, bool suspend)

wrapper around fb_set_suspend that also takes the console lock

Parameters

struct drm_fb_helper * fb_helper

driver-allocated fbdev helper, can be NULL

bool suspend

whether to suspend or resume

Description

A wrapper around fb_set_suspend() that takes the console lock. If the lock isn't available on resume, a worker is tasked with waiting for the lock to become available. The console lock can be pretty contented on resume due to all the printk activity.

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

Use drm_fb_helper_set_suspend() if you need to take the lock yourself.

int drm_fb_helper_setcmap(struct fb_cmap * cmap, struct fb_info * info)

implementation for fb_ops.fb_setcmap

Parameters

struct fb_cmap * cmap

cmap to set

struct fb_info * info

fbdev registered by the helper

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

legacy ioctl implementation

Parameters

struct fb_info * info

fbdev registered by the helper

unsigned int cmd

ioctl command

unsigned long arg

ioctl argument

Description

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

int drm_fb_helper_check_var(struct fb_var_screeninfo * var, struct fb_info * info)

implementation for fb_ops.fb_check_var

Parameters

struct fb_var_screeninfo * var

screeninfo to check

struct fb_info * info

fbdev registered by the helper

int drm_fb_helper_set_par(struct fb_info * info)

implementation for fb_ops.fb_set_par

Parameters

struct fb_info * info

fbdev registered by the helper

Description

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

int drm_fb_helper_pan_display(struct fb_var_screeninfo * var, struct fb_info * info)

implementation for fb_ops.fb_pan_display

Parameters

struct fb_var_screeninfo * var

updated screen information

struct fb_info * info

fbdev registered by the helper

void drm_fb_helper_fill_info(struct fb_info * info, struct drm_fb_helper * fb_helper, struct drm_fb_helper_surface_size * sizes)

initializes fbdev information

Parameters

struct fb_info * info

fbdev instance to set up

struct drm_fb_helper * fb_helper

fb helper instance to use as template

struct drm_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 helper instance and the drm framebuffer allocated in drm_fb_helper.fb.

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

int drm_fb_helper_initial_config(struct drm_fb_helper * fb_helper, int bpp_sel)

setup a sane initial connector configuration

Parameters

struct drm_fb_helper * fb_helper

fb_helper device struct

int bpp_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 with a new framebuffer object as the backing store.

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

This function will call down into the drm_fb_helper_funcs.fb_probe callback to let the driver allocate and initialize the fbdev info structure and the drm framebuffer used to back the fbdev. drm_fb_helper_fill_info() is provided as 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 do a full modeset to setup the fbdev console. Due to locking misdesign in the VT/fbdev subsystem that entire modeset sequence has to be done while holding console_lock. Until console_unlock is called no dmesg lines will be sent out to 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 of printk() you place within your own driver or in the drm core modeset code will also never show up.

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

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

Return

Zero if everything went ok, nonzero otherwise.

int drm_fb_helper_hotplug_event(struct drm_fb_helper * fb_helper)

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

Parameters

struct drm_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 a setup after notification of a change in output configuration.

Called at runtime, takes the mode config locks to be able to check/change the modeset configuration. Must be run from process context (which usually means either the output polling work or a work item launched from the driver's hotplug interrupt).

Note that drivers may call this even before calling drm_fb_helper_initial_config but only after drm_fb_helper_init. This allows for a race-free fbcon setup and will make sure that the fbdev emulation will not miss any hotplug events.

Return

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

int drm_fb_helper_fbdev_setup(struct drm_device * dev, struct drm_fb_helper * fb_helper, const struct drm_fb_helper_funcs * funcs, unsigned int preferred_bpp, unsigned int max_conn_count)

Setup fbdev emulation

Parameters

struct drm_device * dev

DRM device

struct drm_fb_helper * fb_helper

fbdev helper structure to set up

const struct drm_fb_helper_funcs * funcs

fbdev helper functions

unsigned int preferred_bpp

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

unsigned int max_conn_count

Maximum number of connectors (not used)

Description

This function sets up fbdev emulation and registers fbdev for access by userspace. If all connectors are disconnected, setup is deferred to the next time drm_fb_helper_hotplug_event() is called. The caller must to provide a drm_fb_helper_funcs->fb_probe callback function.

Use drm_fb_helper_fbdev_teardown() to destroy the fbdev.

See also: drm_fb_helper_initial_config(), drm_fbdev_generic_setup().

Return

Zero on success or negative error code on failure.

void drm_fb_helper_fbdev_teardown(struct drm_device * dev)

Tear down fbdev emulation

Parameters

struct drm_device * dev

DRM device

Description

This function unregisters fbdev if not already done and cleans up the associated resources including the drm_framebuffer. The driver is responsible for freeing the drm_fb_helper structure which is stored in drm_device->fb_helper. Do note that this pointer has been cleared when this function returns.

In order to support device removal/unplug while file handles are still open, drm_fb_helper_unregister_fbi() should be called on device removal and drm_fb_helper_fbdev_teardown() in the drm_driver->release callback when file handles are closed.

void drm_fb_helper_lastclose(struct drm_device * dev)

DRM driver lastclose helper for fbdev emulation

Parameters

struct drm_device * dev

DRM device

Description

This function can be used as the drm_driver->lastclose callback for drivers that only need to call drm_fb_helper_restore_fbdev_mode_unlocked().

void drm_fb_helper_output_poll_changed(struct drm_device * dev)

DRM mode config .output_poll_changed helper for fbdev emulation

Parameters

struct drm_device * dev

DRM device

Description

This function can be used as the drm_mode_config_funcs.output_poll_changed callback for drivers that only need to call drm_fb_helper_hotplug_event().

int drm_fb_helper_generic_probe(struct drm_fb_helper * fb_helper, struct drm_fb_helper_surface_size * sizes)

Generic fbdev emulation probe helper

Parameters

struct drm_fb_helper * fb_helper

fbdev helper structure

struct drm_fb_helper_surface_size * sizes

describes fbdev size and scanout surface size

Description

This function uses the client API to create a framebuffer backed by a dumb buffer.

The _sys_ versions are used for fb_ops.fb_read, fb_write, fb_fillrect, fb_copyarea, fb_imageblit.

Return

Zero on success or negative error code on failure.

int drm_fbdev_generic_setup(struct drm_device * dev, unsigned int preferred_bpp)

Setup generic fbdev emulation

Parameters

struct drm_device * dev

DRM device

unsigned int preferred_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 supports dumb buffers with a virtual address and that can be mmap'ed. If the driver does not support these functions, it could use drm_fb_helper_fbdev_setup().

Restore, hotplug events and teardown are all taken care of. Drivers that do suspend/resume need to call drm_fb_helper_set_suspend_unlocked() themselves. Simple drivers might use drm_mode_config_helper_suspend().

Drivers that set the dirty callback on their framebuffer will get a shadow fbdev buffer that is blitted onto the real buffer. This is done in order to make deferred I/O work with all kinds of buffers.

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 by drm_dev_unregister().

Return

Zero on success or negative error code on failure.

format Helper Functions Reference

void drm_fb_memcpy(void * dst, void * vaddr, struct drm_framebuffer * fb, struct drm_rect * clip)

Copy clip buffer

Parameters

void * dst

Destination buffer

void * vaddr

Source buffer

struct drm_framebuffer * fb

DRM framebuffer

struct drm_rect * clip

Clip rectangle area to copy

Description

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

void drm_fb_memcpy_dstclip(void __iomem * dst, void * vaddr, struct drm_framebuffer * fb, struct drm_rect * clip)

Copy clip buffer

Parameters

void __iomem * dst

Destination buffer (iomem)

void * vaddr

Source buffer

struct drm_framebuffer * fb

DRM framebuffer

struct drm_rect * clip

Clip rectangle area to copy

Description

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

void drm_fb_swab16(u16 * dst, void * vaddr, struct drm_framebuffer * fb, struct drm_rect * clip)

Swap bytes into clip buffer

Parameters

u16 * dst

RGB565 destination buffer

void * vaddr

RGB565 source buffer

struct drm_framebuffer * fb

DRM framebuffer

struct drm_rect * clip

Clip rectangle area to copy

void drm_fb_xrgb8888_to_rgb565(void * dst, void * vaddr, struct drm_framebuffer * fb, struct drm_rect * clip, bool swab)

Convert XRGB8888 to RGB565 clip buffer

Parameters

void * dst

RGB565 destination buffer

void * vaddr

XRGB8888 source buffer

struct drm_framebuffer * fb

DRM framebuffer

struct drm_rect * clip

Clip rectangle area to copy

bool swab

Swap bytes

Description

Drivers can use this function for RGB565 devices that don't natively support XRGB8888.

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

void drm_fb_xrgb8888_to_rgb565_dstclip(void __iomem * dst, unsigned int dst_pitch, void * vaddr, struct drm_framebuffer * fb, struct drm_rect * clip, bool swab)

Convert XRGB8888 to RGB565 clip buffer

Parameters

void __iomem * dst

RGB565 destination buffer (iomem)

unsigned int dst_pitch

destination buffer pitch

void * vaddr

XRGB8888 source buffer

struct drm_framebuffer * fb

DRM framebuffer

struct drm_rect * clip

Clip rectangle area to copy

bool swab

Swap bytes

Description

Drivers can use this function for RGB565 devices that don't natively support XRGB8888.

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

void drm_fb_xrgb8888_to_rgb888_dstclip(void __iomem * dst, unsigned int dst_pitch, void * vaddr, struct drm_framebuffer * fb, struct drm_rect * clip)

Convert XRGB8888 to RGB888 clip buffer

Parameters

void __iomem * dst

RGB565 destination buffer (iomem)

unsigned int dst_pitch

destination buffer pitch

void * vaddr

XRGB8888 source buffer

struct drm_framebuffer * fb

DRM framebuffer

struct drm_rect * clip

Clip rectangle area to copy

Description

Drivers can use this function for RGB888 devices that don't natively support XRGB8888.

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

void drm_fb_xrgb8888_to_gray8(u8 * dst, void * vaddr, struct drm_framebuffer * fb, struct drm_rect * clip)

Convert XRGB8888 to grayscale

Parameters

u8 * dst

8-bit grayscale destination buffer

void * vaddr

XRGB8888 source buffer

struct drm_framebuffer * fb

DRM framebuffer

struct drm_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 userspace and 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 the drm_mode_config_funcs.fb_create callback function to create a cma backed framebuffer.

struct drm_gem_cma_object * drm_fb_cma_get_gem_obj(struct drm_framebuffer * fb, unsigned int plane)

Get CMA GEM object for framebuffer

Parameters

struct drm_framebuffer * fb

The framebuffer

unsigned int plane

Which plane

Description

Return the CMA GEM object for given framebuffer.

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

dma_addr_t drm_fb_cma_get_gem_addr(struct drm_framebuffer * fb, struct drm_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

struct drm_framebuffer * fb

The framebuffer

struct drm_plane_state * state

Which state of drm plane

unsigned int plane

Which plane Return 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 subclass drm_framebuffer and use drm_gem_object for their backing storage.

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

struct drm_gem_object * drm_gem_fb_get_obj(struct drm_framebuffer * fb, unsigned int plane)

Get GEM object backing the framebuffer

Parameters

struct drm_framebuffer * fb

Framebuffer

unsigned int plane

Plane index

Description

No additional reference is taken beyond the one that the drm_frambuffer already holds.

Return

Pointer to drm_gem_object for the given framebuffer and plane index or NULL if it does not exist.

void drm_gem_fb_destroy(struct drm_framebuffer * fb)

Free GEM backed framebuffer

Parameters

struct drm_framebuffer * fb

Framebuffer

Description

Frees a GEM backed framebuffer with its backing buffer(s) and the structure itself. Drivers can use this as their drm_framebuffer_funcs->destroy callback.

int drm_gem_fb_create_handle(struct drm_framebuffer * fb, struct drm_file * file, unsigned int * handle)

Create handle for GEM backed framebuffer

Parameters

struct drm_framebuffer * fb

Framebuffer

struct drm_file * file

DRM file to register the handle for

unsigned int * 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 their drm_framebuffer_funcs->create_handle callback. The GETFB IOCTL calls into this callback.

Return

0 on success or a negative error code on failure.

struct drm_framebuffer * drm_gem_fb_create_with_funcs(struct drm_device * dev, struct drm_file * file, const struct drm_mode_fb_cmd2 * mode_cmd, const struct drm_framebuffer_funcs * funcs)

Helper function for the drm_mode_config_funcs.fb_create callback

Parameters

struct drm_device * dev

DRM device

struct drm_file * file

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

const struct drm_mode_fb_cmd2 * mode_cmd

Metadata from the userspace framebuffer creation request

const struct drm_framebuffer_funcs * funcs

vtable to be used for the new framebuffer object

Description

This function can be used to set drm_framebuffer_funcs for drivers that need custom framebuffer callbacks. Use drm_gem_fb_create() if you don't need to change drm_framebuffer_funcs. The function does buffer size validation.

Return

Pointer to a drm_framebuffer on success or an error pointer on failure.

struct drm_framebuffer * drm_gem_fb_create(struct drm_device * dev, struct drm_file * file, const struct drm_mode_fb_cmd2 * mode_cmd)

Helper function for the drm_mode_config_funcs.fb_create callback

Parameters

struct drm_device * dev

DRM device

struct drm_file * file

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

const struct drm_mode_fb_cmd2 * mode_cmd

Metadata from the userspace framebuffer creation request

Description

This function creates a new framebuffer object described by drm_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 be checked before calling this function. The function does buffer size validation. Use drm_gem_fb_create_with_dirty() if you need framebuffer flushing.

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

Return

Pointer to a drm_framebuffer on success or an error pointer on failure.

struct drm_framebuffer * drm_gem_fb_create_with_dirty(struct drm_device * dev, struct drm_file * file, const struct drm_mode_fb_cmd2 * mode_cmd)

Helper function for the drm_mode_config_funcs.fb_create callback

Parameters

struct drm_device * dev

DRM device

struct drm_file * file

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

const struct drm_mode_fb_cmd2 * mode_cmd

Metadata from the userspace framebuffer creation request

Description

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

Drivers should also call drm_plane_enable_fb_damage_clips() on all planes to enable userspace to use damage clips also with the ATOMIC IOCTL.

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

Return

Pointer to a drm_framebuffer on success or an error pointer on failure.

int drm_gem_fb_prepare_fb(struct drm_plane * plane, struct drm_plane_state * state)

Prepare a GEM backed framebuffer

Parameters

struct drm_plane * plane

Plane

struct drm_plane_state * state

Plane state the fence will be attached to

Description

This function extracts the exclusive fence from drm_gem_object.resv and attaches it to plane state for the atomic helper to wait on. This is necessary to correctly implement implicit synchronization for any buffers shared as a struct dma_buf. This function can be used as the drm_plane_helper_funcs.prepare_fb callback.

There is no need for drm_plane_helper_funcs.cleanup_fb hook for simple gem based framebuffer drivers which have their buffers always pinned in memory.

See drm_atomic_set_fence_for_plane() for a discussion of implicit and explicit fencing in atomic modeset updates.

int drm_gem_fb_simple_display_pipe_prepare_fb(struct drm_simple_display_pipe * pipe, struct drm_plane_state * plane_state)

prepare_fb helper for drm_simple_display_pipe

Parameters

struct drm_simple_display_pipe * pipe

Simple display pipe

struct drm_plane_state * plane_state

Plane state

Description

This function uses drm_gem_fb_prepare_fb() to extract the exclusive fence from drm_gem_object.resv and attaches it to plane state for the atomic helper to wait on. This is necessary to correctly implement implicit synchronization for any buffers shared as a struct dma_buf. Drivers can use this as their drm_simple_display_pipe_funcs.prepare_fb callback.

See drm_atomic_set_fence_for_plane() for a discussion of implicit and explicit fencing in atomic modeset updates.

Bridges

Overview

struct drm_bridge represents a device that hangs on to an encoder. These are handy when a regular drm_encoder entity isn't enough to represent the entire encoder chain.

A bridge is always attached to a single drm_encoder at a time, but can be either connected to it directly, or through an intermediate bridge:

encoder ---> bridge B ---> bridge A

Here, the output of the encoder feeds to bridge B, and that furthers feeds to bridge A.

The driver using the bridge is responsible to make the associations between the encoder and bridges. Once these links are made, the bridges will participate along with encoder functions to perform mode_set/enable/disable through the ops provided in drm_bridge_funcs.

drm_bridge, like drm_panel, aren't drm_mode_object entities like planes, CRTCs, encoders or connectors and hence are not visible to userspace. They just provide additional hooks to get the desired output at the end of the encoder chain.

Bridges can also be chained up using the drm_bridge.next pointer.

Both legacy CRTC helpers and the new atomic modeset helpers support bridges.

Default bridge callback sequence

The drm_bridge_funcs ops are populated by the bridge driver. The DRM internals (atomic and CRTC helpers) use the helpers defined in drm_bridge.c These helpers call a specific drm_bridge_funcs op for all the bridges during encoder configuration.

For detailed specification of the bridge callbacks see drm_bridge_funcs.

Bridge Helper Reference

struct drm_bridge_funcs

drm_bridge control functions

Definition

struct drm_bridge_funcs {
  int (*attach)(struct drm_bridge *bridge);
  void (*detach)(struct drm_bridge *bridge);
  enum drm_mode_status (*mode_valid)(struct drm_bridge *bridge, 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_atomic_state *state);
  void (*atomic_enable)(struct drm_bridge *bridge, struct drm_atomic_state *state);
  void (*atomic_disable)(struct drm_bridge *bridge, struct drm_atomic_state *state);
  void (*atomic_post_disable)(struct drm_bridge *bridge, struct drm_atomic_state *state);
};

Members

attach

This callback is invoked whenever our bridge is being attached to a drm_encoder.

The attach callback is optional.

RETURNS:

Zero on success, error code on failure.

detach

This callback is invoked whenever our bridge is being detached from a drm_encoder.

The detach callback is optional.

mode_valid

This callback is used to check if a specific mode is valid in this bridge. This should be implemented if the bridge has some sort of restriction in the modes it can display. For example, a given bridge may be responsible to set a clock value. If the clock can not produce all the values for the available modes then this callback can be used to restrict the number of modes to only the ones that can be displayed.

This hook is used by the probe helpers to filter the mode list in drm_helper_probe_single_connector_modes(), and it is used by the atomic helpers to validate modes supplied by userspace in drm_atomic_helper_check_modeset().

This function is optional.

NOTE:

Since this function is both called from the check phase of an atomic commit, and the mode validation in the probe paths it is not allowed to look at anything else but the passed-in mode, and validate it against configuration-invariant hardward constraints. Any further limits which depend upon the configuration can only be checked in mode_fixup.

RETURNS:

drm_mode_status Enum

mode_fixup

This callback is used to validate and adjust a mode. The parameter mode is the display mode that should be fed to the next element in the display chain, either the final drm_connector or the next drm_bridge. The parameter adjusted_mode is the input mode the bridge requires. It can be modified by this callback and does not need to match mode. See also drm_crtc_state.adjusted_mode for more details.

This is the only hook that allows a bridge to reject a modeset. If this function passes all other callbacks must succeed for this configuration.

The mode_fixup callback is optional.

NOTE:

This function is called in the check phase of atomic modesets, which can be aborted for any reason (including on userspace's request to just check whether a configuration would be possible). Drivers MUST NOT touch any persistent state (hardware or software) or data structures except the passed in state parameter.

Also beware that userspace can request its own custom modes, neither core nor helpers filter modes to the list of probe modes reported by the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure that modes are filtered consistently put any bridge constraints and limits checks into mode_valid.

RETURNS:

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

disable

This callback should disable the bridge. It is called right before the preceding element in the display pipe is disabled. If the preceding element is a bridge this means it's called before that bridge's disable vfunc. If the preceding element is a drm_encoder it's called right before the drm_encoder_helper_funcs.disable, drm_encoder_helper_funcs.prepare or drm_encoder_helper_funcs.dpms hook.

The bridge can assume that the display pipe (i.e. clocks and timing signals) feeding it is still running when this callback is called.

The disable callback is optional.

post_disable

This callback should disable the bridge. It is called right after the preceding element in the display pipe is disabled. If the preceding element is a bridge this means it's called after that bridge's post_disable function. If the preceding element is a drm_encoder it's called right after the encoder's drm_encoder_helper_funcs.disable, drm_encoder_helper_funcs.prepare or drm_encoder_helper_funcs.dpms hook.

The bridge must assume that the display pipe (i.e. clocks and timing singals) feeding it is no longer running when this callback is called.

The post_disable callback is optional.

mode_set

This callback should set the given mode on the bridge. It is called after the mode_set callback for the preceding element in the display pipeline has been called already. If the bridge is the first element then this would be drm_encoder_helper_funcs.mode_set. The display pipe (i.e. clocks and timing signals) is off when this function is called.

The adjusted_mode parameter is the mode output by the CRTC for the first bridge in the chain. It can be different from the mode parameter that contains the desired mode for the connector at the end of the bridges chain, for instance when the first bridge in the chain performs scaling. The adjusted mode is mostly useful for the first bridge in the chain and is likely irrelevant for the other bridges.

For atomic drivers the adjusted_mode is the mode stored in drm_crtc_state.adjusted_mode.

NOTE:

If a need arises to store and access modes adjusted for other locations than the connection between the CRTC and the first bridge, the DRM framework will have to be extended with DRM bridge states.

pre_enable

This callback should enable the bridge. It is called right before the preceding element in the display pipe is enabled. If the preceding element is a bridge this means it's called before that bridge's pre_enable function. If the preceding element is a drm_encoder it's called right before the encoder's drm_encoder_helper_funcs.enable, drm_encoder_helper_funcs.commit or drm_encoder_helper_funcs.dpms hook.

The display pipe (i.e. clocks and timing signals) feeding this bridge will not yet be running when this callback is called. The bridge must not enable the display link feeding the next bridge in the chain (if there is one) when this callback is called.

The pre_enable callback is optional.

enable

This callback should enable the bridge. It is called right after the preceding element in the display pipe is enabled. If the preceding element is a bridge this means it's called after that bridge's enable function. If the preceding element is a drm_encoder it's called right after the encoder's drm_encoder_helper_funcs.enable, drm_encoder_helper_funcs.commit or drm_encoder_helper_funcs.dpms hook.

The bridge can assume that the display pipe (i.e. clocks and timing signals) feeding it is running when this callback is called. This callback must enable the display link feeding the next bridge in the chain if there is one.

The enable callback is optional.

atomic_pre_enable

This callback should enable the bridge. It is called right before the preceding element in the display pipe is enabled. If the preceding element is a bridge this means it's called before that bridge's atomic_pre_enable or pre_enable function. If the preceding element is a drm_encoder it's called right before the encoder's drm_encoder_helper_funcs.atomic_enable hook.

The display pipe (i.e. clocks and timing signals) feeding this bridge will not yet be running when this callback is called. The bridge must not enable the display link feeding the next bridge in the chain (if there is one) when this callback is called.

Note that this function will only be invoked in the context of an atomic commit. It will not be invoked from drm_bridge_pre_enable. It would be prudent to also provide an implementation of pre_enable if you are expecting driver calls into drm_bridge_pre_enable.

The atomic_pre_enable callback is optional.

atomic_enable

This callback should enable the bridge. It is called right after the preceding element in the display pipe is enabled. If the preceding element is a bridge this means it's called after that bridge's atomic_enable or enable function. If the preceding element is a drm_encoder it's called right after the encoder's drm_encoder_helper_funcs.atomic_enable hook.

The bridge can assume that the display pipe (i.e. clocks and timing signals) feeding it is running when this callback is called. This callback must enable the display link feeding the next bridge in the chain if there is one.

Note that this function will only be invoked in the context of an atomic commit. It will not be invoked from drm_bridge_enable. It would be prudent to also provide an implementation of enable if you are expecting driver calls into drm_bridge_enable.

The enable callback is optional.

atomic_disable

This callback should disable the bridge. It is called right before the preceding element in the display pipe is disabled. If the preceding element is a bridge this means it's called before that bridge's atomic_disable or disable vfunc. If the preceding element is a drm_encoder it's called right before the drm_encoder_helper_funcs.atomic_disable hook.

The bridge can assume that the display pipe (i.e. clocks and timing signals) feeding it is still running when this callback is called.

Note that this function will only be invoked in the context of an atomic commit. It will not be invoked from drm_bridge_disable. It would be prudent to also provide an implementation of disable if you are expecting driver calls into drm_bridge_disable.

The disable callback is optional.

atomic_post_disable

This callback should disable the bridge. It is called right after the preceding element in the display pipe is disabled. If the preceding element is a bridge this means it's called after that bridge's atomic_post_disable or post_disable function. If the preceding element is a drm_encoder it's called right after the encoder's drm_encoder_helper_funcs.atomic_disable hook.

The bridge must assume that the display pipe (i.e. clocks and timing signals) feeding it is no longer running when this callback is called.

Note that this function will only be invoked in the context of an atomic commit. It will not be invoked from drm_bridge_post_disable. It would be prudent to also provide an implementation of post_disable if you are expecting driver calls into drm_bridge_post_disable.

The post_disable callback is optional.

struct drm_bridge_timings

timing information for the bridge

Definition

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

Members

input_bus_flags

Tells what additional settings for the pixel data on the bus this bridge requires (like pixel signal polarity). See also drm_display_info->bus_flags.

setup_time_ps

Defines the time in picoseconds the input data lines must be stable before the clock edge.

hold_time_ps

Defines the time in picoseconds taken for the bridge to sample the input signal after the clock edge.

dual_link

True if the bus operates in dual-link mode. The exact meaning is dependent on the bus type. For LVDS buses, this indicates that even- and odd-numbered pixels are received on separate links.

struct drm_bridge

central DRM bridge control structure

Definition

struct drm_bridge {
  struct drm_device *dev;
  struct drm_encoder *encoder;
  struct drm_bridge *next;
#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;
};

Members

dev

DRM device this bridge belongs to

encoder

encoder to which this bridge is connected

next

the next bridge in the encoder chain

of_node

device node pointer to the bridge

list

to keep track of all added bridges

timings

the timing specification for the bridge, if any (may be NULL)

funcs

control functions

driver_private

pointer to the bridge driver's internal context

void drm_bridge_add(struct drm_bridge * bridge)

add the given bridge to the global bridge list

Parameters

struct drm_bridge * bridge

bridge control structure

void drm_bridge_remove(struct drm_bridge * bridge)

remove the given bridge from the global bridge list

Parameters

struct drm_bridge * bridge

bridge control structure

int drm_bridge_attach(struct drm_encoder * encoder, struct drm_bridge * bridge, struct drm_bridge * previous)

attach the bridge to an encoder's chain

Parameters

struct drm_encoder * encoder

DRM encoder

struct drm_bridge * bridge

bridge to attach

struct drm_bridge * previous

previous bridge in the chain (optional)

Description

Called by a kms driver to link the bridge to an encoder's chain. The previous argument specifies the previous bridge in the chain. If NULL, the bridge is linked directly at the encoder's output. Otherwise it is linked at the previous bridge's output.

If non-NULL the previous bridge must be already attached by a call to this function.

Note that bridges attached to encoders are auto-detached during encoder cleanup in drm_encoder_cleanup(), so drm_bridge_attach() should generally not be balanced with a drm_bridge_detach() in driver code.

Return

Zero on success, error code on failure

bool drm_bridge_mode_fixup(struct drm_bridge * bridge, const struct drm_display_mode * mode, struct drm_display_mode * adjusted_mode)

fixup proposed mode for all bridges in the encoder chain

Parameters

struct drm_bridge * bridge

bridge control structure

const struct drm_display_mode * mode

desired mode to be set for the bridge

struct drm_display_mode * adjusted_mode

updated mode that works for this bridge

Description

Calls drm_bridge_funcs.mode_fixup for all the bridges in the encoder chain, starting from the first bridge to the last.

Note

the bridge passed should be the one closest to the encoder

Return

true on success, false on failure

enum drm_mode_status drm_bridge_mode_valid(struct drm_bridge * bridge, const struct drm_display_mode * mode)

validate the mode against all bridges in the encoder chain.

Parameters

struct drm_bridge * bridge

bridge control structure

const struct drm_display_mode * mode

desired mode to be validated

Description

Calls drm_bridge_funcs.mode_valid for all the bridges in the encoder chain, starting from the first bridge to the last. If at least one bridge does not accept the mode the function returns the error code.

Note

the bridge passed should be the one closest to the encoder.

Return

MODE_OK on success, drm_mode_status Enum error code on failure

void drm_bridge_disable(struct drm_bridge * bridge)

disables all bridges in the encoder chain

Parameters

struct drm_bridge * bridge

bridge control structure

Description

Calls drm_bridge_funcs.disable op for all the bridges in the encoder chain, starting from the last bridge to the first. These are called before calling the encoder's prepare op.

Note

the bridge passed should be the one closest to the encoder

void drm_bridge_post_disable(struct drm_bridge * bridge)

cleans up after disabling all bridges in the encoder chain

Parameters

struct drm_bridge * bridge

bridge control structure

Description

Calls drm_bridge_funcs.post_disable op for all the bridges in the encoder chain, starting from the first bridge to the last. These are called after completing the encoder's prepare op.

Note

the bridge passed should be the one closest to the encoder

void drm_bridge_mode_set(struct drm_bridge * bridge, const struct drm_display_mode * mode, const struct drm_display_mode * adjusted_mode)

set proposed mode for all bridges in the encoder chain

Parameters

struct drm_bridge * bridge

bridge control structure

const struct drm_display_mode * mode

desired mode to be set for the bridge

const struct drm_display_mode * adjusted_mode

updated mode that works for this bridge

Description

Calls drm_bridge_funcs.mode_set op for all the bridges in the encoder chain, starting from the first bridge to the last.

Note

the bridge passed should be the one closest to the encoder

void drm_bridge_pre_enable(struct drm_bridge * bridge)

prepares for enabling all bridges in the encoder chain

Parameters

struct drm_bridge * bridge

bridge control structure

Description

Calls drm_bridge_funcs.pre_enable op for all the bridges in the encoder chain, starting from the last bridge to the first. These are called before calling the encoder's commit op.

Note

the bridge passed should be the one closest to the encoder

void drm_bridge_enable(struct drm_bridge * bridge)

enables all bridges in the encoder chain

Parameters

struct drm_bridge * bridge

bridge control structure

Description

Calls drm_bridge_funcs.enable op for all the bridges in the encoder chain, starting from the first bridge to the last. These are called after completing the encoder's commit op.

Note that the bridge passed should be the one closest to the encoder

void drm_atomic_bridge_disable(struct drm_bridge * bridge, struct drm_atomic_state * state)

disables all bridges in the encoder chain

Parameters

struct drm_bridge * bridge

bridge control structure

struct drm_atomic_state * state

atomic state being committed

Description

Calls drm_bridge_funcs.atomic_disable (falls back on drm_bridge_funcs.disable) op for all the bridges in the encoder chain, starting from the last bridge to the first. These are called before calling drm_encoder_helper_funcs.atomic_disable

Note

the bridge passed should be the one closest to the encoder

void drm_atomic_bridge_post_disable(struct drm_bridge * bridge, struct drm_atomic_state * state)

cleans up after disabling all bridges in the encoder chain

Parameters

struct drm_bridge * bridge

bridge control structure

struct drm_atomic_state * state

atomic state being committed

Description

Calls drm_bridge_funcs.atomic_post_disable (falls back on drm_bridge_funcs.post_disable) op for all the bridges in the encoder chain, starting from the first bridge to the last. These are called after completing drm_encoder_helper_funcs.atomic_disable

Note

the bridge passed should be the one closest to the encoder

void drm_atomic_bridge_pre_enable(struct drm_bridge * bridge, struct drm_atomic_state * state)

prepares for enabling all bridges in the encoder chain

Parameters

struct drm_bridge * bridge

bridge control structure

struct drm_atomic_state * state

atomic state being committed

Description

Calls drm_bridge_funcs.atomic_pre_enable (falls back on drm_bridge_funcs.pre_enable) op for all the bridges in the encoder chain, starting from the last bridge to the first. These are called before calling drm_encoder_helper_funcs.atomic_enable

Note

the bridge passed should be the one closest to the encoder

void drm_atomic_bridge_enable(struct drm_bridge * bridge, struct drm_atomic_state * state)

enables all bridges in the encoder chain

Parameters

struct drm_bridge * bridge

bridge control structure

struct drm_atomic_state * state

atomic state being committed

Description

Calls drm_bridge_funcs.atomic_enable (falls back on drm_bridge_funcs.enable) op for all the bridges in the encoder chain, starting from the first bridge to the last. These are called after completing drm_encoder_helper_funcs.atomic_enable

Note

the bridge passed should be the one closest to the encoder

struct drm_bridge * of_drm_find_bridge(struct device_node * np)

find the bridge corresponding to the device node in the global bridge list

Parameters

struct device_node * np

device node

Return

drm_bridge control struct on success, NULL on failure

Panel-Bridge Helper Reference

struct drm_bridge * drm_panel_bridge_add(struct drm_panel * panel, u32 connector_type)

Creates a drm_bridge and drm_connector that just calls the appropriate functions from drm_panel.

Parameters

struct drm_panel * panel

The drm_panel being wrapped. Must be non-NULL.

u32 connector_type

The DRM_MODE_CONNECTOR_* for the connector to be created.

Description

For drivers converting from directly using drm_panel: The expected usage pattern is that during either encoder module probe or DSI host attach, a drm_panel will be looked up through drm_of_find_panel_or_bridge(). drm_panel_bridge_add() is used to wrap that panel in the new bridge, and the result can then be passed to drm_bridge_attach(). The drm_panel_prepare() and related functions can be dropped from the encoder driver (they're now called by the KMS helpers before calling into the encoder), along with connector creation. When done with the bridge (after drm_mode_config_cleanup() if the bridge has already been attached), then drm_panel_bridge_remove() to free it.

See devm_drm_panel_bridge_add() for an automatically manged version of this function.

void drm_panel_bridge_remove(struct drm_bridge * bridge)

Unregisters and frees a drm_bridge created by drm_panel_bridge_add().

Parameters

struct drm_bridge * bridge

The drm_bridge being freed.

struct drm_bridge * devm_drm_panel_bridge_add(struct device * dev, struct drm_panel * panel, u32 connector_type)

Creates a managed drm_bridge and drm_connector that just calls the appropriate functions from drm_panel.

Parameters

struct device * dev

device to tie the bridge lifetime to

struct drm_panel * panel

The drm_panel being wrapped. Must be non-NULL.

u32 connector_type

The DRM_MODE_CONNECTOR_* for the connector to be created.

Description

This is the managed version of drm_panel_bridge_add() which automatically calls drm_panel_bridge_remove() when dev is unbound.

Panel Helper Reference

The DRM panel helpers allow drivers to register panel objects with a central registry and provide functions to retrieve those panels in display drivers.

For easy integration into drivers using the drm_bridge infrastructure please take look at drm_panel_bridge_add() and devm_drm_panel_bridge_add().

struct drm_panel_funcs

perform operations on a given panel

Definition

struct drm_panel_funcs {
  int (*prepare)(struct drm_panel *panel);
  int (*enable)(struct drm_panel *panel);
  int (*disable)(struct drm_panel *panel);
  int (*unprepare)(struct drm_panel *panel);
  int (*get_modes)(struct drm_panel *panel);
  int (*get_timings)(struct drm_panel *panel, unsigned int num_timings, struct display_timing *timings);
};

Members

prepare

Turn on panel and perform set up.

enable

Enable panel (turn on back light, etc.).

disable

Disable panel (turn off back light, etc.).

unprepare

Turn off panel.

get_modes

Add modes to the connector that the panel is attached to and return the number of modes added.

get_timings

Copy display timings into the provided array and return the number of display timings available.

Description

The .prepare() function is typically called before the display controller starts to transmit video data. Panel drivers can use this to turn the panel on and wait for it to become ready. If additional configuration is required (via a control bus such as I2C, SPI or DSI for example) this is a good time to do that.

After the display controller has started transmitting video data, it's safe to call the .enable() function. This will typically enable the backlight to make the image on screen visible. Some panels require a certain amount of time or frames before the image is displayed. This function is responsible for taking this into account before enabling the backlight to avoid visual glitches.

Before stopping video transmission from the display controller it can be necessary to turn off the panel to avoid visual glitches. This is done in the .disable() function. Analogously to .enable() this typically involves turning off the backlight and waiting for some time to make sure no image is visible on the panel. It is then safe for the display controller to cease transmission of video data.

To save power when no video data is transmitted, a driver can power down the panel. This is the job of the .unprepare() function.

struct drm_panel

DRM panel object

Definition

struct drm_panel {
  struct drm_device *drm;
  struct drm_connector *connector;
  struct device *dev;
  const struct drm_panel_funcs *funcs;
  struct list_head list;
};

Members

drm

DRM device owning the panel.

connector

DRM connector that the panel is attached to.

dev

Parent device of the panel.

funcs

Operations that can be performed on the panel.

list

Panel entry in registry.

void drm_panel_init(struct drm_panel * panel)

initialize a panel

Parameters

struct drm_panel * panel

DRM panel

Description

Sets up internal fields of the panel so that it can subsequently be added to the registry.

int drm_panel_add(struct drm_panel * panel)

add a panel to the global registry

Parameters

struct drm_panel * panel

panel to add

Description

Add a panel to the global registry so that it can be looked up by display drivers.

Return

0 on success or a negative error code on failure.

void drm_panel_remove(struct drm_panel * panel)

remove a panel from the global registry

Parameters

struct drm_panel * panel

DRM panel

Description

Removes a panel from the global registry.

int drm_panel_attach(struct drm_panel * panel, struct drm_connector * connector)

attach a panel to a connector

Parameters

struct drm_panel * panel

DRM panel

struct drm_connector * connector

DRM connector

Description

After obtaining a pointer to a DRM panel a display driver calls this function to attach a panel to a connector.

An error is returned if the panel is already attached to another connector.

When unloading, the driver should detach from the panel by calling drm_panel_detach().

Return

0 on success or a negative error code on failure.

void drm_panel_detach(struct drm_panel * panel)

detach a panel from a connector

Parameters

struct drm_panel * panel

DRM panel

Description

Detaches a panel from the connector it is attached to. If a panel is not attached to any connector this is effectively a no-op.

This function should not be called by the panel device itself. It is only for the drm device that called drm_panel_attach().

int drm_panel_prepare(struct drm_panel * panel)

power on a panel

Parameters

struct drm_panel * panel

DRM panel

Description

Calling this function will enable power and deassert any reset signals to the panel. After this has completed it is possible to communicate with any integrated circuitry via a command bus.

Return

0 on success or a negative error code on failure.

int drm_panel_unprepare(struct drm_panel * panel)

power off a panel

Parameters

struct drm_panel * panel

DRM panel

Description

Calling this function will completely power off a panel (assert the panel's reset, turn off power supplies, ...). After this function has completed, it is usually no longer possible to communicate with the panel until another call to drm_panel_prepare().

Return

0 on success or a negative error code on failure.

int drm_panel_enable(struct drm_panel * panel)

enable a panel

Parameters

struct drm_panel * panel

DRM panel

Description

Calling this function will cause the panel display drivers to be turned on and the backlight to be enabled. Content will be visible on screen after this call completes.

Return

0 on success or a negative error code on failure.

int drm_panel_disable(struct drm_panel * panel)

disable a panel

Parameters

struct drm_panel * panel

DRM panel

Description

This will typically turn off the panel's backlight or disable the display drivers. For smart panels it should still be possible to communicate with the integrated circuitry via any command bus after this call.

Return

0 on success or a negative error code on failure.

int drm_panel_get_modes(struct drm_panel * panel)

probe the available display modes of a panel

Parameters

struct drm_panel * panel

DRM panel

Description

The modes probed from the panel are automatically added to the connector that the panel is attached to.

Return

The number of modes available from the panel on success or a negative error code on failure.

struct drm_panel * of_drm_find_panel(const struct device_node * np)

look up a panel using a device tree node

Parameters

const struct device_node * np

device tree node of the panel

Description

Searches the set of registered panels for one that matches the given device tree node. If a matching panel is found, return a pointer to it.

Return

A pointer to the panel registered for the specified device tree node or an ERR_PTR() if no panel matching the device tree node can be found.

Possible error codes returned by this function:

• EPROBE_DEFER: the panel device has not been probed yet, and the caller should retry later

• ENODEV: the device is not available (status != "okay" or "ok")

int drm_get_panel_orientation_quirk(int width, int height)

Check for panel orientation quirks

Parameters

int width

width in pixels of the panel

int height

height in pixels of the panel

Description

This function checks for platform specific (e.g. DMI based) quirks providing info on panel_orientation for systems where this cannot be probed from the hard-/firm-ware. To avoid false-positive this function takes the panel resolution as argument and checks that against the resolution expected by the quirk-table entry.

Note this function is also used outside of the drm-subsys, by for example the efifb code. Because of this this function gets compiled into its own kernel-module when built as a module.

Return

A DRM_MODE_PANEL_ORIENTATION_* value if there is a quirk for this system, or DRM_MODE_PANEL_ORIENTATION_UNKNOWN if there is no quirk.

Panel Self Refresh Helper Reference

This helper library provides an easy way for drivers to leverage the atomic framework to implement panel self refresh (SR) support. Drivers are responsible for initializing and cleaning up the SR helpers on load/unload (see drm_self_refresh_helper_init/drm_self_refresh_helper_cleanup). The connector is responsible for setting drm_connector_state.self_refresh_aware to true at runtime if it is SR-aware (meaning it knows how to initiate self refresh on the panel).

Once a crtc has enabled SR using drm_self_refresh_helper_init, the helpers will monitor activity and call back into the driver to enable/disable SR as appropriate. The best way to think about this is that it's a DPMS on/off request with drm_crtc_state.self_refresh_active set in crtc state that tells you to disable/enable SR on the panel instead of power-cycling it.

During SR, drivers may choose to fully disable their crtc/encoder/bridge hardware (in which case no driver changes are necessary), or they can inspect drm_crtc_state.self_refresh_active if they want to enter low power mode without full disable (in case full disable/enable is too slow).

SR will be deactivated if there are any atomic updates affecting the pipe that is in SR mode. If a crtc is driving multiple connectors, all connectors must be SR aware and all will enter/exit SR mode at the same time.

If the crtc and connector are SR aware, but the panel connected does not support it (or is otherwise unable to enter SR), the driver should fail atomic_check when drm_crtc_state.self_refresh_active is true.

void drm_self_refresh_helper_update_avg_times(struct drm_atomic_state * state, unsigned int commit_time_ms)

Updates a crtc's SR time averages

Parameters

struct drm_atomic_state * state

the state which has just been applied to hardware

unsigned int commit_time_ms

the amount of time in ms that this commit took to complete

Description

Called after drm_mode_config_funcs.atomic_commit_tail, this function will update the average entry/exit self refresh times on self refresh transitions. These averages will be used when calculating how long to delay before entering self refresh mode after activity.

void drm_self_refresh_helper_alter_state(struct drm_atomic_state * state)

Alters the atomic state for SR exit

Parameters

struct drm_atomic_state * state

the state currently being checked

Description

Called at the end of atomic check. This function checks the state for flags incompatible with self refresh exit and changes them. This is a bit disingenuous since userspace is expecting one thing and we're giving it another. However in order to keep self refresh entirely hidden from userspace, this is required.

At the end, we queue up the self refresh entry work so we can enter PSR after the desired delay.

int drm_self_refresh_helper_init(struct drm_crtc * crtc)

Initializes self refresh helpers for a crtc

Parameters

struct drm_crtc * crtc

the crtc which supports self refresh supported displays

Description

Returns zero if successful or -errno on failure

void drm_self_refresh_helper_cleanup(struct drm_crtc * crtc)

Cleans up self refresh helpers for a crtc

Parameters

struct drm_crtc * crtc

the crtc to cleanup

HDCP Helper Functions Reference

bool drm_hdcp_check_ksvs_revoked(struct drm_device * drm_dev, u8 * ksvs, u32 ksv_count)

Check the revoked status of the IDs

Parameters

struct drm_device * drm_dev

drm_device for which HDCP revocation check is requested

u8 * ksvs

List of KSVs (HDCP receiver IDs)

u32 ksv_count

KSV count passed in through ksvs

Description

This function reads the HDCP System renewability Message(SRM Table) from userspace as a firmware and parses it for the revoked HDCP KSVs(Receiver IDs) detected by DCP LLC. Once the revoked KSVs are known, revoked state of the KSVs in the list passed in by display drivers are decided and response is sent.

SRM should be presented in the name of "display_hdcp_srm.bin".

Format of the SRM table, that userspace needs to write into the binary file, is defined at: 1. Renewability chapter on 55th page of HDCP 1.4 specification https://www.digital-cp.com/sites/default/files/specifications/HDCP``20Specification````20Rev1_4_Secure``.pdf 2. Renewability chapter on 63rd page of HDCP 2.2 specification https://www.digital-cp.com/sites/default/files/specifications/HDCP``20on````20HDMI````20Specification````20Rev2_2_Final1``.pdf

Return

TRUE on any of the KSV is revoked, else FALSE.

int drm_connector_attach_content_protection_property(struct drm_connector * connector, bool hdcp_content_type)

attach content protection property

Parameters

struct drm_connector * connector

connector to attach CP property on.

bool hdcp_content_type

is HDCP Content Type property needed for connector

Description

This is used to add support for content protection on select connectors. Content Protection is intentionally vague to allow for different underlying technologies, however it is most implemented by HDCP.

When hdcp_content_type is true enum property called HDCP Content Type is created (if it is not already) and attached to the connector.

This property is used for sending the protected content's stream type from userspace to kernel on selected connectors. Protected content provider will decide their type of their content and declare the same to kernel.

Content type will be used during the HDCP 2.2 authentication. Content type will be set to drm_connector_state.hdcp_content_type.

The content protection will be set to drm_connector_state.content_protection

When kernel triggered content protection state change like DESIRED->ENABLED and ENABLED->DESIRED, will use drm_hdcp_update_content_protection() to update the content protection state of a connector.

Return

Zero on success, negative errno on failure.

void drm_hdcp_update_content_protection(struct drm_connector * connector, u64 val)

Updates the content protection state of a connector

Parameters

struct drm_connector * connector

drm_connector on which content protection state needs an update

u64 val

New state of the content protection property

Description

This function can be used by display drivers, to update the kernel triggered content protection state changes of a drm_connector such as DESIRED->ENABLED and ENABLED->DESIRED. No uevent for DESIRED->UNDESIRED or ENABLED->UNDESIRED, as userspace is triggering such state change and kernel performs it without fail.This function update the new state of the property into the connector's state and generate an uevent to notify the userspace.

Display Port Helper Functions Reference

These functions contain some common logic and helpers at various abstraction levels to deal with Display Port sink devices and related things like DP aux channel transfers, EDID reading over DP aux channels, decoding certain DPCD blocks, ...

The DisplayPort AUX channel is an abstraction to allow generic, driver- independent access to AUX functionality. Drivers can take advantage of this by filling in the fields of the drm_dp_aux structure.

Transactions are described using a hardware-independent drm_dp_aux_msg structure, which is passed into a driver's .transfer() implementation. Both native and I2C-over-AUX transactions are supported.

struct dp_sdp_header

DP secondary data packet header

Definition

struct dp_sdp_header {
  u8 HB0;
  u8 HB1;
  u8 HB2;
  u8 HB3;
};

Members

HB0

Secondary Data Packet ID

HB1

Secondary Data Packet Type

HB2

Secondary Data Packet Specific header, Byte 0

HB3

Secondary Data packet Specific header, Byte 1

struct dp_sdp

DP secondary data packet

Definition

struct dp_sdp {
  struct dp_sdp_header sdp_header;
  u8 db[32];
};

Members

sdp_header

DP secondary data packet header

db

DP secondaray data packet data blocks VSC SDP Payload for PSR db[0]: Stereo Interface db[1]: 0 - PSR State; 1 - Update RFB; 2 - CRC Valid db[2]: CRC value bits 7:0 of the R or Cr component db[3]: CRC value bits 15:8 of the R or Cr component db[4]: CRC value bits 7:0 of the G or Y component db[5]: CRC value bits 15:8 of the G or Y component db[6]: CRC value bits 7:0 of the B or Cb component db[7]: CRC value bits 15:8 of the B or Cb component db[8] - db[31]: Reserved VSC SDP Payload for Pixel Encoding/Colorimetry Format db[0] - db[15]: Reserved db[16]: Pixel Encoding and Colorimetry Formats db[17]: Dynamic Range and Component Bit Depth db[18]: Content Type db[19] - db[31]: Reserved

struct drm_dp_aux_msg

DisplayPort AUX channel transaction

Definition

struct drm_dp_aux_msg {
  unsigned int address;
  u8 request;
  u8 reply;
  void *buffer;
  size_t size;
};

Members

address

address of the (first) register to access

request

contains the type of transaction (see DP_AUX_* macros)

reply

upon completion, contains the reply type of the transaction

buffer

pointer to a transmission or reception buffer

size

size of buffer

struct drm_dp_aux_cec

DisplayPort CEC-Tunneling-over-AUX

Definition

struct drm_dp_aux_cec {
  struct mutex lock;
  struct cec_adapter *adap;
  const char *name;
  struct device *parent;
  struct delayed_work unregister_work;
};

Members

lock

mutex protecting this struct

adap

the CEC adapter for CEC-Tunneling-over-AUX support.

name

name of the CEC adapter

parent

parent device of the CEC adapter

unregister_work

unregister the CEC adapter

struct drm_dp_aux

DisplayPort AUX channel

Definition

struct drm_dp_aux {
  const char *name;
  struct i2c_adapter ddc;
  struct device *dev;
  struct drm_crtc *crtc;
  struct mutex hw_mutex;
  struct work_struct crc_work;
  u8 crc_count;
  ssize_t (*transfer)(struct drm_dp_aux *aux, struct drm_dp_aux_msg *msg);
  unsigned i2c_nack_count;
  unsigned i2c_defer_count;
  struct drm_dp_aux_cec cec;
  bool is_remote;
};

Members

name

user-visible name of this AUX channel and the I2C-over-AUX adapter

ddc

I2C adapter that can be used for I2C-over-AUX communication

dev

pointer to struct device that is the parent for this AUX channel

crtc

backpointer to the crtc that is currently using this AUX channel

hw_mutex

internal mutex used for locking transfers

crc_work

worker that captures CRCs for each frame

crc_count

counter of captured frame CRCs

transfer

transfers a message representing a single AUX transaction

i2c_nack_count

Counts I2C NACKs, used for DP validation.

i2c_defer_count

Counts I2C DEFERs, used for DP validation.

cec

struct containing fields used for CEC-Tunneling-over-AUX.

is_remote

Is this AUX CH actually using sideband messaging.

Description

The .dev field should be set to a pointer to the device that implements the AUX channel.

The .name field may be used to specify the name of the I2C adapter. If set to NULL, dev_name() of .dev will be used.

Drivers provide a hardware-specific implementation of how transactions are executed via the .transfer() function. A pointer to a drm_dp_aux_msg structure describing the transaction is passed into this function. Upon success, the implementation should return the number of payload bytes that were transferred, or a negative error-code on failure. Helpers propagate errors from the .transfer() function, with the exception of the -EBUSY error, which causes a transaction to be retried. On a short, helpers will return -EPROTO to make it simpler to check for failure.

An AUX channel can also be used to transport I2C messages to a sink. A typical application of that is to access an EDID that's present in the sink device. The .transfer() function can also be used to execute such transactions. The drm_dp_aux_register() function registers an I2C adapter that can be passed to drm_probe_ddc(). Upon removal, drivers should call drm_dp_aux_unregister() to remove the I2C adapter. The I2C adapter uses long transfers by default; if a partial response is received, the adapter will drop down to the size given by the partial response for this transaction only.

Note that the aux helper code assumes that the .transfer() function only modifies the reply field of the drm_dp_aux_msg structure. The retry logic and i2c helpers assume this is the case.

ssize_t drm_dp_dpcd_readb(struct drm_dp_aux * aux, unsigned int offset, u8 * valuep)

read a single byte from the DPCD

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

unsigned int offset

address of the register to read

u8 * valuep

location where the value of the register will be stored

Description

Returns the number of bytes transferred (1) on success, or a negative error code on failure.

ssize_t drm_dp_dpcd_writeb(struct drm_dp_aux * aux, unsigned int offset, u8 value)

write a single byte to the DPCD

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

unsigned int offset

address of the register to write

u8 value

value to write to the register

Description

Returns the number of bytes transferred (1) on success, or a negative error code on failure.

struct drm_dp_desc

DP branch/sink device descriptor

Definition

struct drm_dp_desc {
  struct drm_dp_dpcd_ident ident;
  u32 quirks;
};

Members

ident

DP device identification from DPCD 0x400 (sink) or 0x500 (branch).

quirks

Quirks; use drm_dp_has_quirk() to query for the quirks.

enum drm_dp_quirk

Display Port sink/branch device specific quirks

Constants

DP_DPCD_QUIRK_CONSTANT_N

The device requires main link attributes Mvid and Nvid to be limited to 16 bits. So will give a constant value (0x8000) for compatability.

DP_DPCD_QUIRK_NO_PSR

The device does not support PSR even if reports that it supports or driver still need to implement proper handling for such device.

DP_DPCD_QUIRK_NO_SINK_COUNT

The device does not set SINK_COUNT to a non-zero value. The driver should ignore SINK_COUNT during detection.

Description

Display Port sink and branch devices in the wild have a variety of bugs, try to collect them here. The quirks are shared, but it's up to the drivers to implement workarounds for them.

bool drm_dp_has_quirk(const struct drm_dp_desc * desc, enum drm_dp_quirk quirk)

does the DP device have a specific quirk

Parameters

const struct drm_dp_desc * desc

Device decriptor filled by drm_dp_read_desc()

enum drm_dp_quirk quirk

Quirk to query for

Description

Return true if DP device identified by desc has quirk.

ssize_t drm_dp_dpcd_read(struct drm_dp_aux * aux, unsigned int offset, void * buffer, size_t size)

read a series of bytes from the DPCD

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

unsigned int offset

address of the (first) register to read

void * buffer

buffer to store the register values

size_t size

number of bytes in buffer

Description

Returns the number of bytes transferred on success, or a negative error code on failure. -EIO is returned if the request was NAKed by the sink or if the retry count was exceeded. If not all bytes were transferred, this function returns -EPROTO. Errors from the underlying AUX channel transfer function, with the exception of -EBUSY (which causes the transaction to be retried), are propagated to the caller.

ssize_t drm_dp_dpcd_write(struct drm_dp_aux * aux, unsigned int offset, void * buffer, size_t size)

write a series of bytes to the DPCD

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

unsigned int offset

address of the (first) register to write

void * buffer

buffer containing the values to write

size_t size

number of bytes in buffer

Description

Returns the number of bytes transferred on success, or a negative error code on failure. -EIO is returned if the request was NAKed by the sink or if the retry count was exceeded. If not all bytes were transferred, this function returns -EPROTO. Errors from the underlying AUX channel transfer function, with the exception of -EBUSY (which causes the transaction to be retried), are propagated to the caller.

int drm_dp_dpcd_read_link_status(struct drm_dp_aux * aux, u8 status)

read DPCD link status (bytes 0x202-0x207)

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

u8 status

buffer to store the link status in (must be at least 6 bytes)

Description

Returns the number of bytes transferred on success or a negative error code on failure.

int drm_dp_link_probe(struct drm_dp_aux * aux, struct drm_dp_link * link)

probe a DisplayPort link for capabilities

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

struct drm_dp_link * link

pointer to structure in which to return link capabilities

Description

The structure filled in by this function can usually be passed directly into drm_dp_link_power_up() and drm_dp_link_configure() to power up and configure the link based on the link's capabilities.

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

int drm_dp_link_power_up(struct drm_dp_aux * aux, struct drm_dp_link * link)

power up a DisplayPort link

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

struct drm_dp_link * link

pointer to a structure containing the link configuration

Description

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

int drm_dp_link_power_down(struct drm_dp_aux * aux, struct drm_dp_link * link)

power down a DisplayPort link

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

struct drm_dp_link * link

pointer to a structure containing the link configuration

Description

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

int drm_dp_link_configure(struct drm_dp_aux * aux, struct drm_dp_link * link)

configure a DisplayPort link

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

struct drm_dp_link * link

pointer to a structure containing the link configuration

Description

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

int drm_dp_downstream_max_clock(const u8 dpcd, const u8 port_cap)

extract branch device max pixel rate for legacy VGA converter or max TMDS clock rate for others

Parameters

const u8 dpcd

DisplayPort configuration data

const u8 port_cap

port capabilities

Description

Returns max clock in kHz on success or 0 if max clock not defined

int drm_dp_downstream_max_bpc(const u8 dpcd, const u8 port_cap)

extract branch device max bits per component

Parameters

const u8 dpcd

DisplayPort configuration data

const u8 port_cap

port capabilities

Description

Returns max bpc on success or 0 if max bpc not defined

int drm_dp_downstream_id(struct drm_dp_aux * aux, char id)

identify branch device

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

char id

DisplayPort branch device id

Description

Returns branch device id on success or NULL on failure

void drm_dp_downstream_debug(struct seq_file * m, const u8 dpcd, const u8 port_cap, struct drm_dp_aux * aux)

debug DP branch devices

Parameters

struct seq_file * m

pointer for debugfs file

const u8 dpcd

DisplayPort configuration data

const u8 port_cap

port capabilities

struct drm_dp_aux * aux

DisplayPort AUX channel

void drm_dp_aux_init(struct drm_dp_aux * aux)

minimally initialise an aux channel

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

Description

If you need to use the drm_dp_aux's i2c adapter prior to registering it with the outside world, call drm_dp_aux_init() first. You must still call drm_dp_aux_register() once the connector has been registered to allow userspace access to the auxiliary DP channel.

int drm_dp_aux_register(struct drm_dp_aux * aux)

initialise and register aux channel

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

Description

Automatically calls drm_dp_aux_init() if this hasn't been done yet.

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

void drm_dp_aux_unregister(struct drm_dp_aux * aux)

unregister an AUX adapter

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

int drm_dp_psr_setup_time(const u8 psr_cap)

PSR setup in time usec

Parameters

const u8 psr_cap

PSR capabilities from DPCD

Return

PSR setup time for the panel in microseconds, negative error code on failure.

int drm_dp_start_crc(struct drm_dp_aux * aux, struct drm_crtc * crtc)

start capture of frame CRCs

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

struct drm_crtc * crtc

CRTC displaying the frames whose CRCs are to be captured

Description

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

int drm_dp_stop_crc(struct drm_dp_aux * aux)

stop capture of frame CRCs

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

Description

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

int drm_dp_read_desc(struct drm_dp_aux * aux, struct drm_dp_desc * desc, bool is_branch)

read sink/branch descriptor from DPCD

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

struct drm_dp_desc * desc

Device decriptor to fill from DPCD

bool is_branch

true for branch devices, false for sink devices

Description

Read DPCD 0x400 (sink) or 0x500 (branch) into desc. Also debug log the identification.

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

u8 drm_dp_dsc_sink_max_slice_count(const u8 dsc_dpcd, bool is_edp)

Get the max slice count supported by the DSC sink.

Parameters

const u8 dsc_dpcd

DSC capabilities from DPCD

bool is_edp

true if its eDP, false for DP

Description

Read the slice capabilities DPCD register from DSC sink to get the maximum slice count supported. This is used to populate the DSC parameters in the struct drm_dsc_config by the driver. Driver creates an infoframe using these parameters to populate struct drm_dsc_pps_infoframe. These are sent to the sink using DSC infoframe using the helper function drm_dsc_pps_infoframe_pack()

Return

Maximum slice count supported by DSC sink or 0 its invalid

u8 drm_dp_dsc_sink_line_buf_depth(const u8 dsc_dpcd)

Get the line buffer depth in bits

Parameters

const u8 dsc_dpcd

DSC capabilities from DPCD

Description

Read the DSC DPCD register to parse the line buffer depth in bits which is number of bits of precision within the decoder line buffer supported by the DSC sink. This is used to populate the DSC parameters in the struct drm_dsc_config by the driver. Driver creates an infoframe using these parameters to populate struct drm_dsc_pps_infoframe. These are sent to the sink using DSC infoframe using the helper function drm_dsc_pps_infoframe_pack()

Return

Line buffer depth supported by DSC panel or 0 its invalid

int drm_dp_dsc_sink_supported_input_bpcs(const u8 dsc_dpcd, u8 dsc_bpc)

Get all the input bits per component values supported by the DSC sink.

Parameters

const u8 dsc_dpcd

DSC capabilities from DPCD

u8 dsc_bpc

An array to be filled by this helper with supported input bpcs.

Description

Read the DSC DPCD from the sink device to parse the supported bits per component values. This is used to populate the DSC parameters in the struct drm_dsc_config by the driver. Driver creates an infoframe using these parameters to populate struct drm_dsc_pps_infoframe. These are sent to the sink using DSC infoframe using the helper function drm_dsc_pps_infoframe_pack()

Return

Number of input BPC values parsed from the DPCD

Display Port CEC Helper Functions Reference

These functions take care of supporting the CEC-Tunneling-over-AUX feature of DisplayPort-to-HDMI adapters.

void drm_dp_cec_irq(struct drm_dp_aux * aux)

handle CEC interrupt, if any

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

Description

Should be called when handling an IRQ_HPD request. If CEC-tunneling-over-AUX is present, then it will check for a CEC_IRQ and handle it accordingly.

void drm_dp_cec_register_connector(struct drm_dp_aux * aux, const char * name, struct device * parent)

register a new connector

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

const char * name

name of the CEC device

struct device * parent

parent device

Description

A new connector was registered with associated CEC adapter name and CEC adapter parent device. After registering the name and parent drm_dp_cec_set_edid() is called to check if the connector supports CEC and to register a CEC adapter if that is the case.

void drm_dp_cec_unregister_connector(struct drm_dp_aux * aux)

unregister the CEC adapter, if any

Parameters

struct drm_dp_aux * aux

DisplayPort AUX channel

Display Port Dual Mode Adaptor Helper Functions Reference

Helper functions to deal with DP dual mode (aka. DP++) adaptors.

Type 1: Adaptor registers (if any) and the sink DDC bus may be accessed via I2C.

Type 2: Adaptor registers and sink DDC bus can be accessed either via I2C or I2C-over-AUX. Source devices may choose to implement either of these access methods.

enum drm_lspcon_mode

Constants

DRM_LSPCON_MODE_INVALID

No LSPCON.

DRM_LSPCON_MODE_LS

Level shifter mode of LSPCON which drives DP++ to HDMI 1.4 conversion.

DRM_LSPCON_MODE_PCON

Protocol converter mode of LSPCON which drives DP++ to HDMI 2.0 active conversion.

enum drm_dp_dual_mode_type

Type of the DP dual mode adaptor

Constants

DRM_DP_DUAL_MODE_NONE

No DP dual mode adaptor

DRM_DP_DUAL_MODE_UNKNOWN

Could be either none or type 1 DVI adaptor

DRM_DP_DUAL_MODE_TYPE1_DVI

Type 1 DVI adaptor

DRM_DP_DUAL_MODE_TYPE1_HDMI

Type 1 HDMI adaptor

DRM_DP_DUAL_MODE_TYPE2_DVI

Type 2 DVI adaptor

DRM_DP_DUAL_MODE_TYPE2_HDMI

Type 2 HDMI adaptor

DRM_DP_DUAL_MODE_LSPCON

Level shifter / protocol converter

ssize_t drm_dp_dual_mode_read(struct i2c_adapter * adapter, u8 offset, void * buffer, size_t size)

Read from the DP dual mode adaptor register(s)

Parameters

struct i2c_adapter * adapter

I2C adapter for the DDC bus

u8 offset

register offset

void * buffer

buffer for return data

size_t size

sizo of the buffer

Description

Reads size bytes from the DP dual mode adaptor registers starting at offset.

Return

0 on success, negative error code on failure

ssize_t drm_dp_dual_mode_write(struct i2c_adapter * adapter, u8 offset, const void * buffer, size_t size)

Write to the DP dual mode adaptor register(s)

Parameters

struct i2c_adapter * adapter

I2C adapter for the DDC bus

u8 offset

register offset

const void * buffer

buffer for write data

size_t size

sizo of the buffer

Description

Writes size bytes to the DP dual mode adaptor registers starting at offset.

Return

0 on success, negative error code on failure

enum drm_dp_dual_mode_type drm_dp_dual_mode_detect(struct i2c_adapter * adapter)

Identify the DP dual mode adaptor

Parameters

struct i2c_adapter * adapter

I2C adapter for the DDC bus

Description

Attempt to identify the type of the DP dual mode adaptor used.

Note that when the answer is DRM_DP_DUAL_MODE_UNKNOWN it's not certain whether we're dealing with a native HDMI port or a type 1 DVI dual mode adaptor. The driver will have to use some other hardware/driver specific mechanism to make that distinction.

Return

The type of the DP dual mode adaptor used

int drm_dp_dual_mode_max_tmds_clock(enum drm_dp_dual_mode_type type, struct i2c_adapter * adapter)

Max TMDS clock for DP dual mode adaptor

Parameters

enum drm_dp_dual_mode_type type

DP dual mode adaptor type

struct i2c_adapter * adapter

I2C adapter for the DDC bus

Description

Determine the max TMDS clock the adaptor supports based on the type of the dual mode adaptor and the DP_DUAL_MODE_MAX_TMDS_CLOCK register (on type2 adaptors). As some type 1 adaptors have problems with registers (see comments in drm_dp_dual_mode_detect()) we don't read the register on those, instead we simply assume a 165 MHz limit based on the specification.

Return

Maximum supported TMDS clock rate for the DP dual mode adaptor in kHz.

int drm_dp_dual_mode_get_tmds_output(enum drm_dp_dual_mode_type type, struct i2c_adapter * adapter, bool * enabled)

Get the state of the TMDS output buffers in the DP dual mode adaptor

Parameters

enum drm_dp_dual_mode_type type

DP dual mode adaptor type

struct i2c_adapter * adapter

I2C adapter for the DDC bus

bool * enabled

current state of the TMDS output buffers

Description

Get the state of the TMDS output buffers in the adaptor. For type2 adaptors this is queried from the DP_DUAL_MODE_TMDS_OEN register. As some type 1 adaptors have problems with registers (see comments in drm_dp_dual_mode_detect()) we don't read the register on those, instead we simply assume that the buffers are always enabled.

Return

0 on success, negative error code on failure

int drm_dp_dual_mode_set_tmds_output(enum drm_dp_dual_mode_type type, struct i2c_adapter * adapter, bool enable)

Enable/disable TMDS output buffers in the DP dual mode adaptor

Parameters

enum drm_dp_dual_mode_type type

DP dual mode adaptor type

struct i2c_adapter * adapter

I2C adapter for the DDC bus

bool enable

enable (as opposed to disable) the TMDS output buffers

Description

Set the state of the TMDS output buffers in the adaptor. For type2 this is set via the DP_DUAL_MODE_TMDS_OEN register. As some type 1 adaptors have problems with registers (see comments in drm_dp_dual_mode_detect()) we avoid touching the register, making this function a no-op on type 1 adaptors.

Return

0 on success, negative error code on failure

const char * drm_dp_get_dual_mode_type_name(enum drm_dp_dual_mode_type type)

Get the name of the DP dual mode adaptor type as a string

Parameters

enum drm_dp_dual_mode_type type

DP dual mode adaptor type

Return

String representation of the DP dual mode adaptor type

int drm_lspcon_get_mode(struct i2c_adapter * adapter, enum drm_lspcon_mode * mode)

Parameters

struct i2c_adapter * adapter

I2C-over-aux adapter

enum drm_lspcon_mode * mode

current lspcon mode of operation output variable

Description

reading offset (0x80, 0x41)

Return

0 on success, sets the current_mode value to appropriate mode -error on failure

int drm_lspcon_set_mode(struct i2c_adapter * adapter, enum drm_lspcon_mode mode)

Parameters

struct i2c_adapter * adapter

I2C-over-aux adapter

enum drm_lspcon_mode mode

required mode of operation

Description

writing offset (0x80, 0x40)

Return

0 on success, -error on failure/timeout

Display Port MST Helpers

Overview

These functions contain parts of the DisplayPort 1.2a MultiStream Transport protocol. The helpers contain a topology manager and bandwidth manager. The helpers encapsulate the sending and received of sideband msgs.

Topology refcount overview

The refcounting schemes for struct drm_dp_mst_branch and struct drm_dp_mst_port are somewhat unusual. Both ports and branch devices have two different kinds of refcounts: topology refcounts, and malloc refcounts.

Topology refcounts are not exposed to drivers, and are handled internally by the DP MST helpers. The helpers use them in order to prevent the in-memory topology state from being changed in the middle of critical operations like changing the internal state of payload allocations. This means each branch and port will be considered to be connected to the rest of the topology until its topology refcount reaches zero. Additionally, for ports this means that their associated struct drm_connector will stay registered with userspace until the port's refcount reaches 0.

Malloc refcount overview

Malloc references are used to keep a struct drm_dp_mst_port or struct drm_dp_mst_branch allocated even after all of its topology references have been dropped, so that the driver or MST helpers can safely access each branch's last known state before it was disconnected from the topology. When the malloc refcount of a port or branch reaches 0, the memory allocation containing the struct drm_dp_mst_branch or struct drm_dp_mst_port respectively will be freed.

For struct drm_dp_mst_branch, malloc refcounts are not currently exposed to drivers. As of writing this documentation, there are no drivers that have a usecase for accessing struct drm_dp_mst_branch outside of the MST helpers. Exposing this API to drivers in a race-free manner would take more tweaking of the refcounting scheme, however patches are welcome provided there is a legitimate driver usecase for this.

Refcount relationships in a topology

Let's take a look at why the relationship between topology and malloc refcounts is designed the way it is.

An example of topology and malloc refs in a DP MST topology with two active payloads. Topology refcount increments are indicated by solid lines, and malloc refcount increments are indicated by dashed lines. Each starts from the branch which incremented the refcount, and ends at the branch to which the refcount belongs to, i.e. the arrow points the same way as the C pointers used to reference a structure.

As you can see in the above figure, every branch increments the topology refcount of its children, and increments the malloc refcount of its parent. Additionally, every payload increments the malloc refcount of its assigned port by 1.

So, what would happen if MSTB #3 from the above figure was unplugged from the system, but the driver hadn't yet removed payload #2 from port #3? The topology would start to look like the figure below.

Ports and branch devices which have been released from memory are colored grey, and references which have been removed are colored red.

Whenever a port or branch device's topology refcount reaches zero, it will decrement the topology refcounts of all its children, the malloc refcount of its parent, and finally its own malloc refcount. For MSTB #4 and port #4, this means they both have been disconnected from the topology and freed from memory. But, because payload #2 is still holding a reference to port #3, port #3 is removed from the topology but its struct drm_dp_mst_port is still accessible from memory. This also means port #3 has not yet decremented the malloc refcount of MSTB #3, so its struct drm_dp_mst_branch will also stay allocated in memory until port #3's malloc refcount reaches 0.

This relationship is necessary because in order to release payload #2, we need to be able to figure out the last relative of port #3 that's still connected to the topology. In this case, we would travel up the topology as shown below.

And finally, remove payload #2 by communicating with port #2 through sideband transactions.

Functions Reference

struct drm_dp_vcpi

Virtual Channel Payload Identifier

Definition

struct drm_dp_vcpi {
  int vcpi;
  int pbn;
  int aligned_pbn;
  int num_slots;
};

Members

vcpi

Virtual channel ID.

pbn

Payload Bandwidth Number for this channel

aligned_pbn

PBN aligned with slot size

num_slots

number of slots for this PBN

struct drm_dp_mst_port

MST port

Definition

struct drm_dp_mst_port {
  struct kref topology_kref;
  struct kref malloc_kref;
  u8 port_num;
  bool input;
  bool mcs;
  bool ddps;
  u8 pdt;
  bool ldps;
  u8 dpcd_rev;
  u8 num_sdp_streams;
  u8 num_sdp_stream_sinks;
  uint16_t available_pbn;
  struct list_head next;
  struct drm_dp_mst_branch *mstb;
  struct drm_dp_aux aux;
  struct drm_dp_mst_branch *parent;
  struct drm_dp_vcpi vcpi;
  struct drm_connector *connector;
  struct drm_dp_mst_topology_mgr *mgr;
  struct edid *cached_edid;
  bool has_audio;
};

Members

topology_kref

refcount for this port's lifetime in the topology, only the DP MST helpers should need to touch this

malloc_kref

refcount for the memory allocation containing this structure. See drm_dp_mst_get_port_malloc() and drm_dp_mst_put_port_malloc().

port_num

port number

input

if this port is an input port.

mcs

message capability status - DP 1.2 spec.

ddps

DisplayPort Device Plug Status - DP 1.2

pdt

Peer Device Type

ldps

Legacy Device Plug Status

dpcd_rev

DPCD revision of device on this port

num_sdp_streams

Number of simultaneous streams

num_sdp_stream_sinks

Number of stream sinks

available_pbn

Available bandwidth for this port.

next

link to next port on this branch device

mstb

branch device attach below this port

aux

i2c aux transport to talk to device connected to this port.

parent

branch device parent of this port

vcpi

Virtual Channel Payload info for this port.

connector

DRM connector this port is connected to.

mgr

topology manager this port lives under.

cached_edid

for DP logical ports - make tiling work by ensuring that the EDID for all connectors is read immediately.

has_audio

Tracks whether the sink connector to this port is audio-capable.

Description

This structure represents an MST port endpoint on a device somewhere in the MST topology.

struct drm_dp_mst_branch

MST branch device.

Definition

struct drm_dp_mst_branch {
  struct kref topology_kref;
  struct kref malloc_kref;
  u8 rad[8];
  u8 lct;
  int num_ports;
  int msg_slots;
  struct list_head ports;
  struct drm_dp_mst_port *port_parent;
  struct drm_dp_mst_topology_mgr *mgr;
  struct drm_dp_sideband_msg_tx *tx_slots[2];
  int last_seqno;
  bool link_address_sent;
  u8 guid[16];
};

Members

topology_kref

refcount for this branch device's lifetime in the topology, only the DP MST helpers should need to touch this

malloc_kref

refcount for the memory allocation containing this structure. See drm_dp_mst_get_mstb_malloc() and drm_dp_mst_put_mstb_malloc().

rad

Relative Address to talk to this branch device.

lct

Link count total to talk to this branch device.

num_ports

number of ports on the branch.

msg_slots

one bit per transmitted msg slot.

ports

linked list of ports on this branch.

port_parent

pointer to the port parent, NULL if toplevel.

mgr

topology manager for this branch device.

tx_slots

transmission slots for this device.

last_seqno

last sequence number used to talk to this.

link_address_sent

if a link address message has been sent to this device yet.

guid

guid for DP 1.2 branch device. port under this branch can be identified by port #.

Description

This structure represents an MST branch device, there is one primary branch device at the root, along with any other branches connected to downstream port of parent branches.

struct drm_dp_mst_topology_mgr

DisplayPort MST manager

Definition

struct drm_dp_mst_topology_mgr {
  struct drm_private_obj base;
  struct drm_device *dev;
  const struct drm_dp_mst_topology_cbs *cbs;
  int max_dpcd_transaction_bytes;
  struct drm_dp_aux *aux;
  int max_payloads;
  int conn_base_id;
  struct drm_dp_sideband_msg_rx down_rep_recv;
  struct drm_dp_sideband_msg_rx up_req_recv;
  struct mutex lock;
  bool mst_state;
  struct drm_dp_mst_branch *mst_primary;
  u8 dpcd[DP_RECEIVER_CAP_SIZE];
  u8 sink_count;
  int pbn_div;
  const struct drm_private_state_funcs *funcs;
  struct mutex qlock;
  struct list_head tx_msg_downq;
  struct mutex payload_lock;
  struct drm_dp_vcpi **proposed_vcpis;
  struct drm_dp_payload *payloads;
  unsigned long payload_mask;
  unsigned long vcpi_mask;
  wait_queue_head_t tx_waitq;
  struct work_struct work;
  struct work_struct tx_work;
  struct list_head destroy_connector_list;
  struct mutex destroy_connector_lock;
  struct work_struct destroy_connector_work;
};

Members

base

Base private object for atomic

dev

device pointer for adding i2c devices etc.

cbs

callbacks for connector addition and destruction.

max_dpcd_transaction_bytes

maximum number of bytes to read/write in one go.

aux

AUX channel for the DP MST connector this topolgy mgr is controlling.

max_payloads

maximum number of payloads the GPU can generate.

conn_base_id

DRM connector ID this mgr is connected to. Only used to build the MST connector path value.

down_rep_recv

Message receiver state for down replies. This and up_req_recv are only ever access from the work item, which is serialised.

up_req_recv

Message receiver state for up requests. This and down_rep_recv are only ever access from the work item, which is serialised.

lock

protects mst state, primary, dpcd.

mst_state

If this manager is enabled for an MST capable port. False if no MST sink/branch devices is connected.

mst_primary

Pointer to the primary/first branch device.

dpcd

Cache of DPCD for primary port.

sink_count

Sink count from DEVICE_SERVICE_IRQ_VECTOR_ESI0.

pbn_div

PBN to slots divisor.

funcs

Atomic helper callbacks

qlock

protects tx_msg_downq, the drm_dp_mst_branch.txslost and drm_dp_sideband_msg_tx.state once they are queued

tx_msg_downq

List of pending down replies.

payload_lock

Protect payload information.

proposed_vcpis

Array of pointers for the new VCPI allocation. The VCPI structure itself is drm_dp_mst_port.vcpi.

payloads

Array of payloads.

payload_mask

Elements of payloads actually in use. Since reallocation of active outputs isn't possible gaps can be created by disabling outputs out of order compared to how they've been enabled.

vcpi_mask

Similar to payload_mask, but for proposed_vcpis.

tx_waitq

Wait to queue stall for the tx worker.

work

Probe work.

tx_work

Sideband transmit worker. This can nest within the main work worker for each transaction work launches.

destroy_connector_list

List of to be destroyed connectors.

destroy_connector_lock

Protects connector_list.

destroy_connector_work

Work item to destroy connectors. Needed to avoid locking inversion.

Description

This struct represents the toplevel displayport MST topology manager. There should be one instance of this for every MST capable DP connector on the GPU.

bool __drm_dp_mst_state_iter_get(struct drm_atomic_state * state, struct drm_dp_mst_topology_mgr ** mgr, struct drm_dp_mst_topology_state ** old_state, struct drm_dp_mst_topology_state ** new_state, int i)

private atomic state iterator function for macro-internal use

Parameters

struct drm_atomic_state * state

struct drm_atomic_state pointer

struct drm_dp_mst_topology_mgr ** mgr

pointer to the struct drm_dp_mst_topology_mgr iteration cursor

struct drm_dp_mst_topology_state ** old_state

optional pointer to the old struct drm_dp_mst_topology_state iteration cursor

struct drm_dp_mst_topology_state ** new_state

optional pointer to the new struct drm_dp_mst_topology_state iteration cursor

int i

int iteration cursor, for macro-internal use

Description

Used by for_each_oldnew_mst_mgr_in_state(), for_each_old_mst_mgr_in_state(), and for_each_new_mst_mgr_in_state(). Don't call this directly.

Return

True if the current struct drm_private_obj is a struct drm_dp_mst_topology_mgr, false otherwise.

for_each_oldnew_mst_mgr_in_state(__state, mgr, old_state, new_state, __i)

iterate over all DP MST topology managers in an atomic update

Parameters

__state

struct drm_atomic_state pointer

mgr

struct drm_dp_mst_topology_mgr iteration cursor

old_state

struct drm_dp_mst_topology_state iteration cursor for the old state

new_state

struct drm_dp_mst_topology_state iteration cursor for the new state

__i

int iteration cursor, for macro-internal use

Description

This iterates over all DRM DP MST topology managers in an atomic update, tracking both old and new state. This is useful in places where the state delta needs to be considered, for example in atomic check functions.

for_each_old_mst_mgr_in_state(__state, mgr, old_state, __i)

iterate over all DP MST topology managers in an atomic update

Parameters

__state

struct drm_atomic_state pointer

mgr

struct drm_dp_mst_topology_mgr iteration cursor

old_state

struct drm_dp_mst_topology_state iteration cursor for the old state

__i

int iteration cursor, for macro-internal use

Description

This iterates over all DRM DP MST topology managers in an atomic update, tracking only the old state. This is useful in disable functions, where we need the old state the hardware is still in.

for_each_new_mst_mgr_in_state(__state, mgr, new_state, __i)

iterate over all DP MST topology managers in an atomic update

Parameters

__state

struct drm_atomic_state pointer

mgr

struct drm_dp_mst_topology_mgr iteration cursor

new_state

struct drm_dp_mst_topology_state iteration cursor for the new state

__i

int iteration cursor, for macro-internal use

Description

This iterates over all DRM DP MST topology managers in an atomic update, tracking only the new state. This is useful in enable functions, where we need the new state the hardware should be in when the atomic commit operation has completed.

void drm_dp_mst_get_port_malloc(struct drm_dp_mst_port * port)

Increment the malloc refcount of an MST port

Parameters

struct drm_dp_mst_port * port

The struct drm_dp_mst_port to increment the malloc refcount of

Description

Increments drm_dp_mst_port.malloc_kref. When drm_dp_mst_port.malloc_kref reaches 0, the memory allocation for port will be released and port may no longer be used.

Because port could potentially be freed at any time by the DP MST helpers if drm_dp_mst_port.malloc_kref reaches 0, including during a call to this function, drivers that which to make use of struct drm_dp_mst_port should ensure that they grab at least one main malloc reference to their MST ports in drm_dp_mst_topology_cbs.add_connector. This callback is called before there is any chance for drm_dp_mst_port.malloc_kref to reach 0.

See also: drm_dp_mst_put_port_malloc()

void drm_dp_mst_put_port_malloc(struct drm_dp_mst_port * port)

Decrement the malloc refcount of an MST port

Parameters

struct drm_dp_mst_port * port

The struct drm_dp_mst_port to decrement the malloc refcount of

Description

Decrements drm_dp_mst_port.malloc_kref. When drm_dp_mst_port.malloc_kref reaches 0, the memory allocation for port will be released and port may no longer be used.

See also: drm_dp_mst_get_port_malloc()

int drm_dp_mst_connector_late_register(struct drm_connector * connector, struct drm_dp_mst_port * port)

Late MST connector registration

Parameters

struct drm_connector * connector

The MST connector

struct drm_dp_mst_port * port

The MST port for this connector

Description

Helper to register the remote aux device for this MST port. Drivers should call this from their mst connector's late_register hook to enable MST aux devices.

Return

0 on success, negative error code on failure.

void drm_dp_mst_connector_early_unregister(struct drm_connector * connector, struct drm_dp_mst_port * port)

Early MST connector unregistration

Parameters

struct drm_connector * connector

The MST connector

struct drm_dp_mst_port * port

The MST port for this connector

Description

Helper to unregister the remote aux device for this MST port, registered by drm_dp_mst_connector_late_register(). Drivers should call this from their mst connector's early_unregister hook.

int drm_dp_update_payload_part1(struct drm_dp_mst_topology_mgr * mgr)

Execute payload update part 1

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager to use.

Description

This iterates over all proposed virtual channels, and tries to allocate space in the link for them. For 0->slots transitions, this step just writes the VCPI to the MST device. For slots->0 transitions, this writes the updated VCPIs and removes the remote VC payloads.

after calling this the driver should generate ACT and payload packets.

int drm_dp_update_payload_part2(struct drm_dp_mst_topology_mgr * mgr)

Execute payload update part 2

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager to use.

Description

This iterates over all proposed virtual channels, and tries to allocate space in the link for them. For 0->slots transitions, this step writes the remote VC payload commands. For slots->0 this just resets some internal state.

int drm_dp_mst_topology_mgr_set_mst(struct drm_dp_mst_topology_mgr * mgr, bool mst_state)

Set the MST state for a topology manager

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager to set state for

bool mst_state

true to enable MST on this connector - false to disable.

Description

This is called by the driver when it detects an MST capable device plugged into a DP MST capable port, or when a DP MST capable device is unplugged.

void drm_dp_mst_topology_mgr_suspend(struct drm_dp_mst_topology_mgr * mgr)

suspend the MST manager

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager to suspend

Description

This function tells the MST device that we can't handle UP messages anymore. This should stop it from sending any since we are suspended.

int drm_dp_mst_topology_mgr_resume(struct drm_dp_mst_topology_mgr * mgr)

resume the MST manager

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager to resume

Description

This will fetch DPCD and see if the device is still there, if it is, it will rewrite the MSTM control bits, and return.

if the device fails this returns -1, and the driver should do a full MST reprobe, in case we were undocked.

int drm_dp_mst_hpd_irq(struct drm_dp_mst_topology_mgr * mgr, u8 * esi, bool * handled)

MST hotplug IRQ notify

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager to notify irq for.

u8 * esi

4 bytes from SINK_COUNT_ESI

bool * handled

whether the hpd interrupt was consumed or not

Description

This should be called from the driver when it detects a short IRQ, along with the value of the DEVICE_SERVICE_IRQ_VECTOR_ESI0. The topology manager will process the sideband messages received as a result of this.

enum drm_connector_status drm_dp_mst_detect_port(struct drm_connector * connector, struct drm_dp_mst_topology_mgr * mgr, struct drm_dp_mst_port * port)

get connection status for an MST port

Parameters

struct drm_connector * connector

DRM connector for this port

struct drm_dp_mst_topology_mgr * mgr

manager for this port

struct drm_dp_mst_port * port

unverified pointer to a port

Description

This returns the current connection state for a port. It validates the port pointer still exists so the caller doesn't require a reference

bool drm_dp_mst_port_has_audio(struct drm_dp_mst_topology_mgr * mgr, struct drm_dp_mst_port * port)

Check whether port has audio capability or not

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager for this port

struct drm_dp_mst_port * port

unverified pointer to a port.

Description

This returns whether the port supports audio or not.

struct edid * drm_dp_mst_get_edid(struct drm_connector * connector, struct drm_dp_mst_topology_mgr * mgr, struct drm_dp_mst_port * port)

get EDID for an MST port

Parameters

struct drm_connector * connector

toplevel connector to get EDID for

struct drm_dp_mst_topology_mgr * mgr

manager for this port

struct drm_dp_mst_port * port

unverified pointer to a port.

Description

This returns an EDID for the port connected to a connector, It validates the pointer still exists so the caller doesn't require a reference.

int drm_dp_find_vcpi_slots(struct drm_dp_mst_topology_mgr * mgr, int pbn)

Find VCPI slots for this PBN value

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager to use

int pbn

payload bandwidth to convert into slots.

Description

Calculate the number of VCPI slots that will be required for the given PBN value. This function is deprecated, and should not be used in atomic drivers.

Return

The total slots required for this port, or error.

int drm_dp_atomic_find_vcpi_slots(struct drm_atomic_state * state, struct drm_dp_mst_topology_mgr * mgr, struct drm_dp_mst_port * port, int pbn)

Find and add VCPI slots to the state

Parameters

struct drm_atomic_state * state

global atomic state

struct drm_dp_mst_topology_mgr * mgr

MST topology manager for the port

struct drm_dp_mst_port * port

port to find vcpi slots for

int pbn

bandwidth required for the mode in PBN

Description

Allocates VCPI slots to port, replacing any previous VCPI allocations it may have had. Any atomic drivers which support MST must call this function in their drm_encoder_helper_funcs.atomic_check() callback to change the current VCPI allocation for the new state, but only when drm_crtc_state.mode_changed or drm_crtc_state.connectors_changed is set to ensure compatibility with userspace applications that still use the legacy modesetting UAPI.

Allocations set by this function are not checked against the bandwidth restraints of mgr until the driver calls drm_dp_mst_atomic_check().

Additionally, it is OK to call this function multiple times on the same port as needed. It is not OK however, to call this function and drm_dp_atomic_release_vcpi_slots() in the same atomic check phase.

See also: drm_dp_atomic_release_vcpi_slots() drm_dp_mst_atomic_check()

Return

Total slots in the atomic state assigned for this port, or a negative error code if the port no longer exists

int drm_dp_atomic_release_vcpi_slots(struct drm_atomic_state * state, struct drm_dp_mst_topology_mgr * mgr, struct drm_dp_mst_port * port)

Release allocated vcpi slots

Parameters

struct drm_atomic_state * state

global atomic state

struct drm_dp_mst_topology_mgr * mgr

MST topology manager for the port

struct drm_dp_mst_port * port

The port to release the VCPI slots from

Description

Releases any VCPI slots that have been allocated to a port in the atomic state. Any atomic drivers which support MST must call this function in their drm_connector_helper_funcs.atomic_check() callback when the connector will no longer have VCPI allocated (e.g. because its CRTC was removed) when it had VCPI allocated in the previous atomic state.

It is OK to call this even if port has been removed from the system. Additionally, it is OK to call this function multiple times on the same port as needed. It is not OK however, to call this function and drm_dp_atomic_find_vcpi_slots() on the same port in a single atomic check phase.

See also: drm_dp_atomic_find_vcpi_slots() drm_dp_mst_atomic_check()

Return

0 if all slots for this port were added back to drm_dp_mst_topology_state.avail_slots or negative error code

bool drm_dp_mst_allocate_vcpi(struct drm_dp_mst_topology_mgr * mgr, struct drm_dp_mst_port * port, int pbn, int slots)

Allocate a virtual channel

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager for this port

struct drm_dp_mst_port * port

port to allocate a virtual channel for.

int pbn

payload bandwidth number to request

int slots

returned number of slots for this PBN.

void drm_dp_mst_reset_vcpi_slots(struct drm_dp_mst_topology_mgr * mgr, struct drm_dp_mst_port * port)

Reset number of slots to 0 for VCPI

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager for this port

struct drm_dp_mst_port * port

unverified pointer to a port.

Description

This just resets the number of slots for the ports VCPI for later programming.

void drm_dp_mst_deallocate_vcpi(struct drm_dp_mst_topology_mgr * mgr, struct drm_dp_mst_port * port)

deallocate a VCPI

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager for this port

struct drm_dp_mst_port * port

port to deallocate vcpi for

Description

This can be called unconditionally, regardless of whether drm_dp_mst_allocate_vcpi() succeeded or not.

int drm_dp_check_act_status(struct drm_dp_mst_topology_mgr * mgr)

Check ACT handled status.

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager to use

Description

Check the payload status bits in the DPCD for ACT handled completion.

int drm_dp_calc_pbn_mode(int clock, int bpp)

Calculate the PBN for a mode.

Parameters

int clock

dot clock for the mode

int bpp

bpp for the mode.

Description

This uses the formula in the spec to calculate the PBN value for a mode.

void drm_dp_mst_dump_topology(struct seq_file * m, struct drm_dp_mst_topology_mgr * mgr)

Parameters

struct seq_file * m

seq_file to dump output to

struct drm_dp_mst_topology_mgr * mgr

manager to dump current topology for.

Description

helper to dump MST topology to a seq file for debugfs.

int drm_dp_mst_atomic_check(struct drm_atomic_state * state)

Check that the new state of an MST topology in an atomic update is valid

Parameters

struct drm_atomic_state * state

Pointer to the new struct drm_dp_mst_topology_state

Description

Checks the given topology state for an atomic update to ensure that it's valid. This includes checking whether there's enough bandwidth to support the new VCPI allocations in the atomic update.

Any atomic drivers supporting DP MST must make sure to call this after checking the rest of their state in their drm_mode_config_funcs.atomic_check() callback.

See also: drm_dp_atomic_find_vcpi_slots() drm_dp_atomic_release_vcpi_slots()

Return

0 if the new state is valid, negative error code otherwise.

struct drm_dp_mst_topology_state * drm_atomic_get_mst_topology_state(struct drm_atomic_state * state, struct drm_dp_mst_topology_mgr * mgr)

Parameters

struct drm_atomic_state * state

global atomic state

struct drm_dp_mst_topology_mgr * mgr

MST topology manager, also the private object in this case

Description

This function wraps drm_atomic_get_priv_obj_state() passing in the MST atomic state vtable so that the private object state returned is that of a MST topology object. Also, drm_atomic_get_private_obj_state() expects the caller to care of the locking, so warn if don't hold the connection_mutex.

Return

The MST topology state or error pointer.

int drm_dp_mst_topology_mgr_init(struct drm_dp_mst_topology_mgr * mgr, struct drm_device * dev, struct drm_dp_aux * aux, int max_dpcd_transaction_bytes, int max_payloads, int conn_base_id)

initialise a topology manager

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager struct to initialise

struct drm_device * dev

device providing this structure - for i2c addition.

struct drm_dp_aux * aux

DP helper aux channel to talk to this device

int max_dpcd_transaction_bytes

hw specific DPCD transaction limit

int max_payloads

maximum number of payloads this GPU can source

int conn_base_id

the connector object ID the MST device is connected to.

Description

Return 0 for success, or negative error code on failure

void drm_dp_mst_topology_mgr_destroy(struct drm_dp_mst_topology_mgr * mgr)

destroy topology manager.

Parameters

struct drm_dp_mst_topology_mgr * mgr

manager to destroy

Topology Lifetime Internals

These functions aren't exported to drivers, but are documented here to help make the MST topology helpers easier to understand

void drm_dp_mst_get_mstb_malloc(struct drm_dp_mst_branch * mstb)

Increment the malloc refcount of a branch device

Parameters

struct drm_dp_mst_branch * mstb

The struct drm_dp_mst_branch to increment the malloc refcount of

Description

Increments drm_dp_mst_branch.malloc_kref. When drm_dp_mst_branch.malloc_kref reaches 0, the memory allocation for mstb will be released and mstb may no longer be used.

See also: drm_dp_mst_put_mstb_malloc()

void drm_dp_mst_put_mstb_malloc(struct drm_dp_mst_branch * mstb)

Decrement the malloc refcount of a branch device

Parameters

struct drm_dp_mst_branch * mstb

The struct drm_dp_mst_branch to decrement the malloc refcount of

Description

Decrements drm_dp_mst_branch.malloc_kref. When drm_dp_mst_branch.malloc_kref reaches 0, the memory allocation for mstb will be released and mstb may no longer be used.

See also: drm_dp_mst_get_mstb_malloc()

int drm_dp_mst_topology_try_get_mstb(struct drm_dp_mst_branch * mstb)

Increment the topology refcount of a branch device unless it's zero

Parameters

struct drm_dp_mst_branch * mstb

struct drm_dp_mst_branch to increment the topology refcount of

Description

Attempts to grab a topology reference to mstb, if it hasn't yet been removed from the topology (e.g. drm_dp_mst_branch.topology_kref has reached 0). Holding a topology reference implies that a malloc reference will be held to mstb as long as the user holds the topology reference.

Care should be taken to ensure that the user has at least one malloc reference to mstb. If you already have a topology reference to mstb, you should use drm_dp_mst_topology_get_mstb() instead.

See also: drm_dp_mst_topology_get_mstb() drm_dp_mst_topology_put_mstb()

Return

• 1: A topology reference was grabbed successfully

• 0: port is no longer in the topology, no reference was grabbed

void drm_dp_mst_topology_get_mstb(struct drm_dp_mst_branch * mstb)

Increment the topology refcount of a branch device

Parameters

struct drm_dp_mst_branch * mstb

The struct drm_dp_mst_branch to increment the topology refcount of

Description

Increments drm_dp_mst_branch.topology_refcount without checking whether or not it's already reached 0. This is only valid to use in scenarios where you are already guaranteed to have at least one active topology reference to mstb. Otherwise, drm_dp_mst_topology_try_get_mstb() must be used.

See also: drm_dp_mst_topology_try_get_mstb() drm_dp_mst_topology_put_mstb()

void drm_dp_mst_topology_put_mstb(struct drm_dp_mst_branch * mstb)

release a topology reference to a branch device

Parameters

struct drm_dp_mst_branch * mstb

The struct drm_dp_mst_branch to release the topology reference from

Description

Releases a topology reference from mstb by decrementing drm_dp_mst_branch.topology_kref.

See also: drm_dp_mst_topology_try_get_mstb() drm_dp_mst_topology_get_mstb()

int drm_dp_mst_topology_try_get_port(struct drm_dp_mst_port * port)

Increment the topology refcount of a port unless it's zero

Parameters

struct drm_dp_mst_port * port

struct drm_dp_mst_port to increment the topology refcount of

Description

Attempts to grab a topology reference to port, if it hasn't yet been removed from the topology (e.g. drm_dp_mst_port.topology_kref has reached 0). Holding a topology reference implies that a malloc reference will be held to port as long as the user holds the topology reference.

Care should be taken to ensure that the user has at least one malloc reference to port. If you already have a topology reference to port, you should use drm_dp_mst_topology_get_port() instead.

See also: drm_dp_mst_topology_get_port() drm_dp_mst_topology_put_port()

Return

• 1: A topology reference was grabbed successfully

• 0: port is no longer in the topology, no reference was grabbed

void drm_dp_mst_topology_get_port(struct drm_dp_mst_port * port)

Increment the topology refcount of a port

Parameters

struct drm_dp_mst_port * port

The struct drm_dp_mst_port to increment the topology refcount of

Description

Increments drm_dp_mst_port.topology_refcount without checking whether or not it's already reached 0. This is only valid to use in scenarios where you are already guaranteed to have at least one active topology reference to port. Otherwise, drm_dp_mst_topology_try_get_port() must be used.

See also: drm_dp_mst_topology_try_get_port() drm_dp_mst_topology_put_port()

void drm_dp_mst_topology_put_port(struct drm_dp_mst_port * port)

release a topology reference to a port

Parameters

struct drm_dp_mst_port * port

The struct drm_dp_mst_port to release the topology reference from

Description

Releases a topology reference from port by decrementing drm_dp_mst_port.topology_kref.

See also: drm_dp_mst_topology_try_get_port() drm_dp_mst_topology_get_port()

MIPI DBI Helper Functions Reference

This library provides helpers for MIPI Display Bus Interface (DBI) compatible display controllers.

Many controllers for tiny lcd displays are MIPI compliant and can use this library. If a controller uses registers 0x2A and 0x2B to set the area to update and uses register 0x2C to write to frame memory, it is most likely MIPI compliant.

Only MIPI Type 1 displays are supported since a full frame memory is needed.

There are 3 MIPI DBI implementation types:

1. Motorola 6800 type parallel bus

2. Intel 8080 type parallel bus

3. SPI type with 3 options:

   1. 9-bit with the Data/Command signal as the ninth bit

   2. Same as above except it's sent as 16 bits

   3. 8-bit with the Data/Command signal as a separate D/CX pin

Currently mipi_dbi only supports Type C options 1 and 3 with mipi_dbi_spi_init().

struct mipi_dbi

MIPI DBI interface

Definition

struct mipi_dbi {
  struct mutex cmdlock;
  int (*command)(struct mipi_dbi *dbi, u8 *cmd, u8 *param, size_t num);
  const u8 *read_commands;
  bool swap_bytes;
  struct gpio_desc *reset;
  struct spi_device *spi;
  struct gpio_desc *dc;
  void *tx_buf9;
  size_t tx_buf9_len;
};

Members

cmdlock

Command lock

command

Bus specific callback executing commands.

read_commands

Array of read commands terminated by a zero entry.

Reading is disabled if this is NULL.

swap_bytes

Swap bytes in buffer before transfer

reset

Optional reset gpio

spi

SPI device

dc

Optional D/C gpio.

tx_buf9

Buffer used for Option 1 9-bit conversion

tx_buf9_len

Size of tx_buf9.

struct mipi_dbi_dev

MIPI DBI device

Definition

struct mipi_dbi_dev {
  struct drm_device drm;
  struct drm_simple_display_pipe pipe;
  struct drm_connector connector;
  struct drm_display_mode mode;
  bool enabled;
  u16 *tx_buf;
  unsigned int rotation;
  struct backlight_device *backlight;
  struct regulator *regulator;
  struct mipi_dbi dbi;
};

Members

drm

DRM device

pipe

Display pipe structure

connector

Connector

mode

Fixed display mode

enabled

Pipeline is enabled

tx_buf

Buffer used for transfer (copy clip rect area)

rotation

initial rotation in degrees Counter Clock Wise

backlight

backlight device (optional)

regulator

power regulator (optional)

dbi

MIPI DBI interface

mipi_dbi_command(dbi, cmd, seq...)

MIPI DCS command with optional parameter(s)

Parameters

dbi

MIPI DBI structure

cmd

Command

seq...

Optional parameter(s)

Description

Send MIPI DCS command to the controller. Use mipi_dbi_command_read() for get/read.

Return

Zero on success, negative error code on failure.

int mipi_dbi_command_read(struct mipi_dbi * dbi, u8 cmd, u8 * val)

MIPI DCS read command

Parameters

struct mipi_dbi * dbi

MIPI DBI structure

u8 cmd

Command

u8 * val

Value read

Description

Send MIPI DCS read command to the controller.

Return

Zero on success, negative error code on failure.

int mipi_dbi_command_buf(struct mipi_dbi * dbi, u8 cmd, u8 * data, size_t len)

MIPI DCS command with parameter(s) in an array

Parameters

struct mipi_dbi * dbi

MIPI DBI structure

u8 cmd

Command

u8 * data

Parameter buffer

size_t len

Buffer length

Return

Zero on success, negative error code on failure.

int mipi_dbi_buf_copy(void * dst, struct drm_framebuffer * fb, struct drm_rect * clip, bool swap)

Copy a framebuffer, transforming it if necessary

Parameters

void * dst

The destination buffer

struct drm_framebuffer * fb

The source framebuffer

struct drm_rect * clip

Clipping rectangle of the area to be copied

bool swap

When true, swap MSB/LSB of 16-bit values

Return

Zero on success, negative error code on failure.

void mipi_dbi_pipe_update(struct drm_simple_display_pipe * pipe, struct drm_plane_state * old_state)

Display pipe update helper

Parameters

struct drm_simple_display_pipe * pipe

Simple display pipe

struct drm_plane_state * old_state

Old plane state

Description

This function handles framebuffer flushing and vblank events. Drivers can use this as their drm_simple_display_pipe_funcs->update callback.

void mipi_dbi_enable_flush(struct mipi_dbi_dev * dbidev, struct drm_crtc_state * crtc_state, struct drm_plane_state * plane_state)

MIPI DBI enable helper

Parameters

struct mipi_dbi_dev * dbidev

MIPI DBI device structure

struct drm_crtc_state * crtc_state

CRTC state

struct drm_plane_state * plane_state

Plane state

Description

This function sets mipi_dbi->enabled, flushes the whole framebuffer and enables the backlight. Drivers can use this in their drm_simple_display_pipe_funcs->enable callback.

Note

Drivers which don't use mipi_dbi_pipe_update() because they have custom framebuffer flushing, can't use this function since they both use the same flushing code.

void mipi_dbi_pipe_disable(struct drm_simple_display_pipe * pipe)

MIPI DBI pipe disable helper

Parameters

struct drm_simple_display_pipe * pipe

Display pipe

Description

This function disables backlight if present, if not the display memory is blanked. The regulator is disabled if in use. Drivers can use this as their drm_simple_display_pipe_funcs->disable callback.

int mipi_dbi_dev_init_with_formats(struct mipi_dbi_dev * dbidev, const struct drm_simple_display_pipe_funcs * funcs, const uint32_t * formats, unsigned int format_count, const struct drm_display_mode * mode, unsigned int rotation, size_t tx_buf_size)

MIPI DBI device initialization with custom formats

Parameters

struct mipi_dbi_dev * dbidev

MIPI DBI device structure to initialize

const struct drm_simple_display_pipe_funcs * funcs

Display pipe functions

const uint32_t * formats

Array of supported formats (DRM_FORMAT_*).

unsigned int format_count

Number of elements in formats

const struct drm_display_mode * mode

Display mode

unsigned int rotation

Initial rotation in degrees Counter Clock Wise

size_t tx_buf_size

Allocate a transmit buffer of this size.

Description

This function sets up a drm_simple_display_pipe with a drm_connector that has one fixed drm_display_mode which is rotated according to rotation. This mode is used to set the mode config min/max width/height properties.

Use mipi_dbi_dev_init() if you don't need custom formats.

Note

Some of the helper functions expects RGB565 to be the default format and the transmit buffer sized to fit that.

Return

Zero on success, negative error code on failure.

int mipi_dbi_dev_init(struct mipi_dbi_dev * dbidev, const struct drm_simple_display_pipe_funcs * funcs, const struct drm_display_mode * mode, unsigned int rotation)

MIPI DBI device initialization

Parameters

struct mipi_dbi_dev * dbidev

MIPI DBI device structure to initialize

const struct drm_simple_display_pipe_funcs * funcs

Display pipe functions

const struct drm_display_mode * mode

Display mode

unsigned int rotation

Initial rotation in degrees Counter Clock Wise

Description

This function sets up a drm_simple_display_pipe with a drm_connector that has one fixed drm_display_mode which is rotated according to rotation. This mode is used to set the mode config min/max width/height properties. Additionally mipi_dbi.tx_buf is allocated.

Supported formats: Native RGB565 and emulated XRGB8888.

Return

Zero on success, negative error code on failure.

void mipi_dbi_release(struct drm_device * drm)

DRM driver release helper

Parameters

struct drm_device * drm

DRM device

Description

This function finalizes and frees mipi_dbi.

Drivers can use this as their drm_driver->release callback.

void mipi_dbi_hw_reset(struct mipi_dbi * dbi)

Hardware reset of controller

Parameters

struct mipi_dbi * dbi

MIPI DBI structure

Description

Reset controller if the mipi_dbi->reset gpio is set.

bool mipi_dbi_display_is_on(struct mipi_dbi * dbi)

Check if display is on

Parameters

struct mipi_dbi * dbi

MIPI DBI structure

Description

This function checks the Power Mode register (if readable) to see if display output is turned on. This can be used to see if the bootloader has already turned on the display avoiding flicker when the pipeline is enabled.

Return

true if the display can be verified to be on, false otherwise.

int mipi_dbi_poweron_reset(struct mipi_dbi_dev * dbidev)

MIPI DBI poweron and reset

Parameters

struct mipi_dbi_dev * dbidev

MIPI DBI device structure

Description

This function enables the regulator if used and does a hardware and software reset.

Return

Zero on success, or a negative error code.

int mipi_dbi_poweron_conditional_reset(struct mipi_dbi_dev * dbidev)

MIPI DBI poweron and conditional reset

Parameters

struct mipi_dbi_dev * dbidev

MIPI DBI device structure

Description

This function enables the regulator if used and if the display is off, it does a hardware and software reset. If mipi_dbi_display_is_on() determines that the display is on, no reset is performed.

Return

Zero if the controller was reset, 1 if the display was already on, or a negative error code.

u32 mipi_dbi_spi_cmd_max_speed(struct spi_device * spi, size_t len)

get the maximum SPI bus speed

Parameters

struct spi_device * spi

SPI device

size_t len

The transfer buffer length.

Description

Many controllers have a max speed of 10MHz, but can be pushed way beyond that. Increase reliability by running pixel data at max speed and the rest at 10MHz, preventing transfer glitches from messing up the init settings.

int mipi_dbi_spi_init(struct spi_device * spi, struct mipi_dbi * dbi, struct gpio_desc * dc)

Initialize MIPI DBI SPI interface

Parameters

struct spi_device * spi

SPI device

struct mipi_dbi * dbi

MIPI DBI structure to initialize

struct gpio_desc * dc

D/C gpio (optional)

Description

This function sets mipi_dbi->command, enables mipi_dbi->read_commands for the usual read commands. It should be followed by a call to mipi_dbi_dev_init() or a driver-specific init.

If dc is set, a Type C Option 3 interface is assumed, if not Type C Option 1.

If the SPI master driver doesn't support the necessary bits per word, the following transformation is used:

• 9-bit: reorder buffer as 9x 8-bit words, padded with no-op command.

• 16-bit: if big endian send as 8-bit, if little endian swap bytes

Return

Zero on success, negative error code on failure.

int mipi_dbi_spi_transfer(struct spi_device * spi, u32 speed_hz, u8 bpw, const void * buf, size_t len)

SPI transfer helper

Parameters

struct spi_device * spi

SPI device

u32 speed_hz

Override speed (optional)

u8 bpw

Bits per word

const void * buf

Buffer to transfer

size_t len

Buffer length

Description

This SPI transfer helper breaks up the transfer of buf into chunks which the SPI controller driver can handle.

Return

Zero on success, negative error code on failure.

int mipi_dbi_debugfs_init(struct drm_minor * minor)

Create debugfs entries

Parameters

struct drm_minor * minor

DRM minor

Description

This function creates a 'command' debugfs file for sending commands to the controller or getting the read command values. Drivers can use this as their drm_driver->debugfs_init callback.

Return

Zero on success, negative error code on failure.

MIPI DSI Helper Functions Reference

These functions contain some common logic and helpers to deal with MIPI DSI peripherals.

Helpers are provided for a number of standard MIPI DSI command as well as a subset of the MIPI DCS command set.

struct mipi_dsi_msg

read/write DSI buffer

Definition

struct mipi_dsi_msg {
  u8 channel;
  u8 type;
  u16 flags;
  size_t tx_len;
  const void *tx_buf;
  size_t rx_len;
  void *rx_buf;
};

Members

channel

virtual channel id

type

payload data type

flags

flags controlling this message transmission

tx_len

length of tx_buf

tx_buf

data to be written

rx_len

length of rx_buf

rx_buf

data to be read, or NULL

struct mipi_dsi_packet

represents a MIPI DSI packet in protocol format

Definition

struct mipi_dsi_packet {
  size_t size;
  u8 header[4];
  size_t payload_length;
  const u8 *payload;
};

Members

size

size (in bytes) of the packet

header

the four bytes that make up the header (Data ID, Word Count or Packet Data, and ECC)

payload_length

number of bytes in the payload

payload

a pointer to a buffer containing the payload, if any

struct mipi_dsi_host_ops

DSI bus operations

Definition

struct mipi_dsi_host_ops {
  int (*attach)(struct mipi_dsi_host *host, struct mipi_dsi_device *dsi);
  int (*detach)(struct mipi_dsi_host *host, struct mipi_dsi_device *dsi);
  ssize_t (*transfer)(struct mipi_dsi_host *host, const struct mipi_dsi_msg *msg);
};

Members

attach

attach DSI device to DSI host

detach

detach DSI device from DSI host

transfer

transmit a DSI packet

Description

DSI packets transmitted by .transfer() are passed in as mipi_dsi_msg structures. This structure contains information about the type of packet being transmitted as well as the transmit and receive buffers. When an error is encountered during transmission, this function will return a negative error code. On success it shall return the number of bytes transmitted for write packets or the number of bytes received for read packets.

Note that typically DSI packet transmission is atomic, so the .transfer() function will seldomly return anything other than the number of bytes contained in the transmit buffer on success.

struct mipi_dsi_host

DSI host device

Definition

struct mipi_dsi_host {
  struct device *dev;
  const struct mipi_dsi_host_ops *ops;
  struct list_head list;
};

Members

dev

driver model device node for this DSI host

ops

DSI host operations

list

list management

struct mipi_dsi_device_info

template for creating a mipi_dsi_device

Definition

struct mipi_dsi_device_info {
  char type[DSI_DEV_NAME_SIZE];
  u32 channel;
  struct device_node *node;
};

Members

type

DSI peripheral chip type

channel

DSI virtual channel assigned to peripheral

node

pointer to OF device node or NULL

Description

This is populated and passed to mipi_dsi_device_new to create a new DSI device

struct mipi_dsi_device

DSI peripheral device

Definition

struct mipi_dsi_device {
  struct mipi_dsi_host *host;
  struct device dev;
  char name[DSI_DEV_NAME_SIZE];
  unsigned int channel;
  unsigned int lanes;
  enum mipi_dsi_pixel_format format;
  unsigned long mode_flags;
  unsigned long hs_rate;
  unsigned long lp_rate;
};

Members

host

DSI host for this peripheral

dev

driver model device node for this peripheral

name

DSI peripheral chip type

channel

virtual channel assigned to the peripheral

lanes

number of active data lanes

format

pixel format for video mode

mode_flags

DSI operation mode related flags

hs_rate

maximum lane frequency for high speed mode in hertz, this should be set to the real limits of the hardware, zero is only accepted for legacy drivers

lp_rate

maximum lane frequency for low power mode in hertz, this should be set to the real limits of the hardware, zero is only accepted for legacy drivers

int mipi_dsi_pixel_format_to_bpp(enum mipi_dsi_pixel_format fmt)

obtain the number of bits per pixel for any given pixel format defined by the MIPI DSI specification

Parameters

enum mipi_dsi_pixel_format fmt

MIPI DSI pixel format

Return

The number of bits per pixel of the given pixel format.

enum mipi_dsi_dcs_tear_mode

Tearing Effect Output Line mode

Constants

MIPI_DSI_DCS_TEAR_MODE_VBLANK

the TE output line consists of V-Blanking information only

MIPI_DSI_DCS_TEAR_MODE_VHBLANK

the TE output line consists of both V-Blanking and H-Blanking information

struct mipi_dsi_driver

DSI driver

Definition

struct mipi_dsi_driver {
  struct device_driver driver;
  int(*probe)(struct mipi_dsi_device *dsi);
  int(*remove)(struct mipi_dsi_device *dsi);
  void (*shutdown)(struct mipi_dsi_device *dsi);
};

Members

driver

device driver model driver

probe

callback for device binding

remove

callback for device unbinding

shutdown

called at shutdown time to quiesce the device

struct mipi_dsi_device * of_find_mipi_dsi_device_by_node(struct device_node * np)

find the MIPI DSI device matching a device tree node

Parameters

struct device_node * np

device tree node

Return

A pointer to the MIPI DSI device corresponding to np or NULL if no

such device exists (or has not been registered yet).

struct mipi_dsi_device * mipi_dsi_device_register_full(struct mipi_dsi_host * host, const struct mipi_dsi_device_info * info)

create a MIPI DSI device

Parameters

struct mipi_dsi_host * host

DSI host to which this device is connected

const struct mipi_dsi_device_info * info

pointer to template containing DSI device information

Description

Create a MIPI DSI device by using the device information provided by mipi_dsi_device_info template

Return

A pointer to the newly created MIPI DSI device, or, a pointer encoded with an error

void mipi_dsi_device_unregister(struct mipi_dsi_device * dsi)

unregister MIPI DSI device

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

struct mipi_dsi_host * of_find_mipi_dsi_host_by_node(struct device_node * node)

find the MIPI DSI host matching a device tree node

Parameters

struct device_node * node

device tree node

Return

A pointer to the MIPI DSI host corresponding to node or NULL if no such device exists (or has not been registered yet).

int mipi_dsi_attach(struct mipi_dsi_device * dsi)

attach a DSI device to its DSI host

Parameters

struct mipi_dsi_device * dsi

DSI peripheral

int mipi_dsi_detach(struct mipi_dsi_device * dsi)

detach a DSI device from its DSI host

Parameters

struct mipi_dsi_device * dsi

DSI peripheral

bool mipi_dsi_packet_format_is_short(u8 type)

check if a packet is of the short format

Parameters

u8 type

MIPI DSI data type of the packet

Return

true if the packet for the given data type is a short packet, false otherwise.

bool mipi_dsi_packet_format_is_long(u8 type)

check if a packet is of the long format

Parameters

u8 type

MIPI DSI data type of the packet

Return

true if the packet for the given data type is a long packet, false otherwise.

int mipi_dsi_create_packet(struct mipi_dsi_packet * packet, const struct mipi_dsi_msg * msg)

create a packet from a message according to the DSI protocol

Parameters

struct mipi_dsi_packet * packet

pointer to a DSI packet structure

const struct mipi_dsi_msg * msg

message to translate into a packet

Return

0 on success or a negative error code on failure.

int mipi_dsi_shutdown_peripheral(struct mipi_dsi_device * dsi)

sends a Shutdown Peripheral command

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

Return

0 on success or a negative error code on failure.

int mipi_dsi_turn_on_peripheral(struct mipi_dsi_device * dsi)

sends a Turn On Peripheral command

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

Return

0 on success or a negative error code on failure.

ssize_t mipi_dsi_generic_write(struct mipi_dsi_device * dsi, const void * payload, size_t size)

transmit data using a generic write packet

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

const void * payload

buffer containing the payload

size_t size

size of payload buffer

Description

This function will automatically choose the right data type depending on the payload length.

Return

The number of bytes transmitted on success or a negative error code on failure.

ssize_t mipi_dsi_generic_read(struct mipi_dsi_device * dsi, const void * params, size_t num_params, void * data, size_t size)

receive data using a generic read packet

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

const void * params

buffer containing the request parameters

size_t num_params

number of request parameters

void * data

buffer in which to return the received data

size_t size

size of receive buffer

Description

This function will automatically choose the right data type depending on the number of parameters passed in.

Return

The number of bytes successfully read or a negative error code on failure.

ssize_t mipi_dsi_dcs_write_buffer(struct mipi_dsi_device * dsi, const void * data, size_t len)

transmit a DCS command with payload

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

const void * data

buffer containing data to be transmitted

size_t len

size of transmission buffer

Description

This function will automatically choose the right data type depending on the command payload length.

Return

The number of bytes successfully transmitted or a negative error code on failure.

ssize_t mipi_dsi_dcs_write(struct mipi_dsi_device * dsi, u8 cmd, const void * data, size_t len)

send DCS write command

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

u8 cmd

DCS command

const void * data

buffer containing the command payload

size_t len

command payload length

Description

This function will automatically choose the right data type depending on the command payload length.

Return

The number of bytes successfully transmitted or a negative error code on failure.

ssize_t mipi_dsi_dcs_read(struct mipi_dsi_device * dsi, u8 cmd, void * data, size_t len)

send DCS read request command

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

u8 cmd

DCS command

void * data

buffer in which to receive data

size_t len

size of receive buffer

Return

The number of bytes read or a negative error code on failure.

int mipi_dsi_dcs_nop(struct mipi_dsi_device * dsi)

send DCS nop packet

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_soft_reset(struct mipi_dsi_device * dsi)

perform a software reset of the display module

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_get_power_mode(struct mipi_dsi_device * dsi, u8 * mode)

query the display module's current power mode

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

u8 * mode

return location for the current power mode

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_get_pixel_format(struct mipi_dsi_device * dsi, u8 * format)

gets the pixel format for the RGB image data used by the interface

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

u8 * format

return location for the pixel format

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_enter_sleep_mode(struct mipi_dsi_device * dsi)

disable all unnecessary blocks inside the display module except interface communication

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_exit_sleep_mode(struct mipi_dsi_device * dsi)

enable all blocks inside the display module

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_set_display_off(struct mipi_dsi_device * dsi)

stop displaying the image data on the display device

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_set_display_on(struct mipi_dsi_device * dsi)

start displaying the image data on the display device

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

Return

0 on success or a negative error code on failure

int mipi_dsi_dcs_set_column_address(struct mipi_dsi_device * dsi, u16 start, u16 end)

define the column extent of the frame memory accessed by the host processor

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

u16 start

first column of frame memory

u16 end

last column of frame memory

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_set_page_address(struct mipi_dsi_device * dsi, u16 start, u16 end)

define the page extent of the frame memory accessed by the host processor

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

u16 start

first page of frame memory

u16 end

last page of frame memory

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_set_tear_off(struct mipi_dsi_device * dsi)

turn off the display module's Tearing Effect output signal on the TE signal line

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

Return

0 on success or a negative error code on failure

int mipi_dsi_dcs_set_tear_on(struct mipi_dsi_device * dsi, enum mipi_dsi_dcs_tear_mode mode)

turn on the display module's Tearing Effect output signal on the TE signal line.

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

enum mipi_dsi_dcs_tear_mode mode

the Tearing Effect Output Line mode

Return

0 on success or a negative error code on failure

int mipi_dsi_dcs_set_pixel_format(struct mipi_dsi_device * dsi, u8 format)

sets the pixel format for the RGB image data used by the interface

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

u8 format

pixel format

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_set_tear_scanline(struct mipi_dsi_device * dsi, u16 scanline)

set the scanline to use as trigger for the Tearing Effect output signal of the display module

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

u16 scanline

scanline to use as trigger

Return

0 on success or a negative error code on failure

int mipi_dsi_dcs_set_display_brightness(struct mipi_dsi_device * dsi, u16 brightness)

sets the brightness value of the display

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

u16 brightness

brightness value

Return

0 on success or a negative error code on failure.

int mipi_dsi_dcs_get_display_brightness(struct mipi_dsi_device * dsi, u16 * brightness)

gets the current brightness value of the display

Parameters

struct mipi_dsi_device * dsi

DSI peripheral device

u16 * brightness

brightness value

Return

0 on success or a negative error code on failure.

int mipi_dsi_driver_register_full(struct mipi_dsi_driver * drv, struct module * owner)

register a driver for DSI devices

Parameters

struct mipi_dsi_driver * drv

DSI driver structure

struct module * owner

owner module

Return

0 on success or a negative error code on failure.

void mipi_dsi_driver_unregister(struct mipi_dsi_driver * drv)

unregister a driver for DSI devices

Parameters

struct mipi_dsi_driver * drv

DSI driver structure

Return

0 on success or a negative error code on failure.

Display Stream Compression Helper Functions Reference

VESA specification for DP 1.4 adds a new feature called Display Stream Compression (DSC) used to compress the pixel bits before sending it on DP/eDP/MIPI DSI interface. DSC is required to be enabled so that the existing display interfaces can support high resolutions at higher frames rates uisng the maximum available link capacity of these interfaces.

These functions contain some common logic and helpers to deal with VESA Display Stream Compression standard required for DSC on Display Port/eDP or MIPI display interfaces.

struct drm_dsc_rc_range_parameters

DSC Rate Control range parameters

Definition

struct drm_dsc_rc_range_parameters {
  u8 range_min_qp;
  u8 range_max_qp;
  u8 range_bpg_offset;
};

Members

range_min_qp

Min Quantization Parameters allowed for this range

range_max_qp

Max Quantization Parameters allowed for this range

range_bpg_offset

Bits/group offset to apply to target for this group

Description

This defines different rate control parameters used by the DSC engine to compress the frame.

struct drm_dsc_config

Parameters required to configure DSC

Definition

struct drm_dsc_config {
  u8 line_buf_depth;
  u8 bits_per_component;
  bool convert_rgb;
  u8 slice_count;
  u16 slice_width;
  u16 slice_height;
  bool simple_422;
  u16 pic_width;
  u16 pic_height;
  u8 rc_tgt_offset_high;
  u8 rc_tgt_offset_low;
  u16 bits_per_pixel;
  u8 rc_edge_factor;
  u8 rc_quant_incr_limit1;
  u8 rc_quant_incr_limit0;
  u16 initial_xmit_delay;
  u16 initial_dec_delay;
  bool block_pred_enable;
  u8 first_line_bpg_offset;
  u16 initial_offset;
  u16 rc_buf_thresh[DSC_NUM_BUF_RANGES - 1];
  struct drm_dsc_rc_range_parameters rc_range_params[DSC_NUM_BUF_RANGES];
  u16 rc_model_size;
  u8 flatness_min_qp;
  u8 flatness_max_qp;
  u8 initial_scale_value;
  u16 scale_decrement_interval;
  u16 scale_increment_interval;
  u16 nfl_bpg_offset;
  u16 slice_bpg_offset;
  u16 final_offset;
  bool vbr_enable;
  u8 mux_word_size;
  u16 slice_chunk_size;
  u16 rc_bits;
  u8 dsc_version_minor;
  u8 dsc_version_major;
  bool native_422;
  bool native_420;
  u8 second_line_bpg_offset;
  u16 nsl_bpg_offset;
  u16 second_line_offset_adj;
};

Members

line_buf_depth

Bits per component for previous reconstructed line buffer

bits_per_component

Bits per component to code (8/10/12)

convert_rgb

Flag to indicate if RGB - YCoCg conversion is needed True if RGB input, False if YCoCg input

slice_count

Number fo slices per line used by the DSC encoder

slice_width

Width of each slice in pixels

slice_height

Slice height in pixels

simple_422

True if simple 4_2_2 mode is enabled else False

pic_width

Width of the input display frame in pixels

pic_height

Vertical height of the input display frame

rc_tgt_offset_high

Offset to bits/group used by RC to determine QP adjustment

rc_tgt_offset_low

Offset to bits/group used by RC to determine QP adjustment

bits_per_pixel

Target bits per pixel with 4 fractional bits, bits_per_pixel << 4

rc_edge_factor

Factor to determine if an edge is present based on the bits produced

rc_quant_incr_limit1

Slow down incrementing once the range reaches this value

rc_quant_incr_limit0

Slow down incrementing once the range reaches this value

initial_xmit_delay

Number of pixels to delay the initial transmission

initial_dec_delay

Initial decoder delay, number of pixel times that the decoder accumulates data in its rate buffer before starting to decode and output pixels.

block_pred_enable

True if block prediction is used to code any groups within the picture. False if BP not used

first_line_bpg_offset

Number of additional bits allocated for each group on the first line of slice.

initial_offset

Value to use for RC model offset at slice start

rc_buf_thresh

Thresholds defining each of the buffer ranges

rc_range_params

Parameters for each of the RC ranges defined in struct drm_dsc_rc_range_parameters

rc_model_size

Total size of RC model

flatness_min_qp

Minimum QP where flatness information is sent

flatness_max_qp

Maximum QP where flatness information is sent

initial_scale_value

Initial value for the scale factor

scale_decrement_interval

Specifies number of group times between decrementing the scale factor at beginning of a slice.

scale_increment_interval

Number of group times between incrementing the scale factor value used at the beginning of a slice.

nfl_bpg_offset

Non first line BPG offset to be used

slice_bpg_offset

BPG offset used to enforce slice bit

final_offset

Final RC linear transformation offset value

vbr_enable

True if VBR mode is enabled, false if disabled

mux_word_size

Mux word size (in bits) for SSM mode

slice_chunk_size

The (max) size in bytes of the "chunks" that are used in slice multiplexing.

rc_bits

Rate control buffer size in bits

dsc_version_minor

DSC minor version

dsc_version_major

DSC major version

native_422

True if Native 4:2:2 supported, else false

native_420

True if Native 4:2:0 supported else false.

second_line_bpg_offset

Additional bits/grp for seconnd line of slice for native 4:2:0

nsl_bpg_offset

Num of bits deallocated for each grp that is not in second line of slice

second_line_offset_adj

Offset adjustment for second line in Native 4:2:0 mode

Description

Driver populates this structure with all the parameters required to configure the display stream compression on the source.

struct drm_dsc_picture_parameter_set

Represents 128 bytes of Picture Parameter Set

Definition

struct drm_dsc_picture_parameter_set {
  u8 dsc_version;
  u8 pps_identifier;
  u8 pps_reserved;
  u8 pps_3;
  u8 pps_4;
  u8 bits_per_pixel_low;
  __be16 pic_height;
  __be16 pic_width;
  __be16 slice_height;
  __be16 slice_width;
  __be16 chunk_size;
  u8 initial_xmit_delay_high;
  u8 initial_xmit_delay_low;
  __be16 initial_dec_delay;
  u8 pps20_reserved;
  u8 initial_scale_value;
  __be16 scale_increment_interval;
  u8 scale_decrement_interval_high;
  u8 scale_decrement_interval_low;
  u8 pps26_reserved;
  u8 first_line_bpg_offset;
  __be16 nfl_bpg_offset;
  __be16 slice_bpg_offset;
  __be16 initial_offset;
  __be16 final_offset;
  u8 flatness_min_qp;
  u8 flatness_max_qp;
  __be16 rc_model_size;
  u8 rc_edge_factor;
  u8 rc_quant_incr_limit0;
  u8 rc_quant_incr_limit1;
  u8 rc_tgt_offset;
  u8 rc_buf_thresh[DSC_NUM_BUF_RANGES - 1];
  __be16 rc_range_parameters[DSC_NUM_BUF_RANGES];
  u8 native_422_420;
  u8 second_line_bpg_offset;
  __be16 nsl_bpg_offset;
  __be16 second_line_offset_adj;
  u32 pps_long_94_reserved;
  u32 pps_long_98_reserved;
  u32 pps_long_102_reserved;
  u32 pps_long_106_reserved;
  u32 pps_long_110_reserved;
  u32 pps_long_114_reserved;
  u32 pps_long_118_reserved;
  u32 pps_long_122_reserved;
  __be16 pps_short_126_reserved;
};

Members

dsc_version

PPS0[3:0] - dsc_version_minor: Contains Minor version of DSC PPS0[7:4] - dsc_version_major: Contains major version of DSC

pps_identifier

PPS1[7:0] - Application specific identifier that can be used to differentiate between different PPS tables.

pps_reserved

PPS2[7:0]- RESERVED Byte

pps_3

PPS3[3:0] - linebuf_depth: Contains linebuffer bit depth used to generate the bitstream. (0x0 - 16 bits for DSC 1.2, 0x8 - 8 bits, 0xA - 10 bits, 0xB - 11 bits, 0xC - 12 bits, 0xD - 13 bits, 0xE - 14 bits for DSC1.2, 0xF - 14 bits for DSC 1.2. PPS3[7:4] - bits_per_component: Bits per component for the original pixels of the encoded picture. 0x0 = 16bpc (allowed only when dsc_version_minor = 0x2) 0x8 = 8bpc, 0xA = 10bpc, 0xC = 12bpc, 0xE = 14bpc (also allowed only when dsc_minor_version = 0x2)

pps_4

PPS4[1:0] -These are the most significant 2 bits of compressed BPP bits_per_pixel[9:0] syntax element. PPS4[2] - vbr_enable: 0 = VBR disabled, 1 = VBR enabled PPS4[3] - simple_422: Indicates if decoder drops samples to reconstruct the 4:2:2 picture. PPS4[4] - Convert_rgb: Indicates if DSC color space conversion is active. PPS4[5] - blobk_pred_enable: Indicates if BP is used to code any groups in picture PPS4[7:6] - Reseved bits

bits_per_pixel_low

PPS5[7:0] - This indicates the lower significant 8 bits of the compressed BPP bits_per_pixel[9:0] element.

pic_height

PPS6[7:0], PPS7[7:0] -pic_height: Specifies the number of pixel rows within the raster.

pic_width

PPS8[7:0], PPS9[7:0] - pic_width: Number of pixel columns within the raster.

slice_height

PPS10[7:0], PPS11[7:0] - Slice height in units of pixels.

slice_width

PPS12[7:0], PPS13[7:0] - Slice width in terms of pixels.

chunk_size

PPS14[7:0], PPS15[7:0] - Size in units of bytes of the chunks that are used for slice multiplexing.

initial_xmit_delay_high

PPS16[1:0] - Most Significant two bits of initial transmission delay. It specifies the number of pixel times that the encoder waits before transmitting data from its rate buffer. PPS16[7:2] - Reserved

initial_xmit_delay_low

PPS17[7:0] - Least significant 8 bits of initial transmission delay.

initial_dec_delay

PPS18[7:0], PPS19[7:0] - Initial decoding delay which is the number of pixel times that the decoder accumulates data in its rate buffer before starting to decode and output pixels.

pps20_reserved

PPS20[7:0] - Reserved

initial_scale_value

PPS21[5:0] - Initial rcXformScale factor used at beginning of a slice. PPS21[7:6] - Reserved

scale_increment_interval

PPS22[7:0], PPS23[7:0] - Number of group times between incrementing the rcXformScale factor at end of a slice.

scale_decrement_interval_high

PPS24[3:0] - Higher 4 bits indicating number of group times between decrementing the rcXformScale factor at beginning of a slice. PPS24[7:4] - Reserved

scale_decrement_interval_low

PPS25[7:0] - Lower 8 bits of scale decrement interval

pps26_reserved

PPS26[7:0]

first_line_bpg_offset

PPS27[4:0] - Number of additional bits that are allocated for each group on first line of a slice. PPS27[7:5] - Reserved

nfl_bpg_offset

PPS28[7:0], PPS29[7:0] - Number of bits including frac bits deallocated for each group for groups after the first line of slice.

slice_bpg_offset

PPS30, PPS31[7:0] - Number of bits that are deallocated for each group to enforce the slice constraint.

initial_offset

PPS32,33[7:0] - Initial value for rcXformOffset

final_offset

PPS34,35[7:0] - Maximum end-of-slice value for rcXformOffset

flatness_min_qp

PPS36[4:0] - Minimum QP at which flatness is signaled and flatness QP adjustment is made. PPS36[7:5] - Reserved

flatness_max_qp

PPS37[4:0] - Max QP at which flatness is signalled and the flatness adjustment is made. PPS37[7:5] - Reserved

rc_model_size

PPS38,39[7:0] - Number of bits within RC Model.

rc_edge_factor

PPS40[3:0] - Ratio of current activity vs, previous activity to determine presence of edge. PPS40[7:4] - Reserved

rc_quant_incr_limit0

PPS41[4:0] - QP threshold used in short term RC PPS41[7:5] - Reserved

rc_quant_incr_limit1

PPS42[4:0] - QP threshold used in short term RC PPS42[7:5] - Reserved

rc_tgt_offset

PPS43[3:0] - Lower end of the variability range around the target bits per group that is allowed by short term RC. PPS43[7:4]- Upper end of the variability range around the target bits per group that i allowed by short term rc.

rc_buf_thresh

PPS44[7:0] - PPS57[7:0] - Specifies the thresholds in RC model for the 15 ranges defined by 14 thresholds.

rc_range_parameters

PPS58[7:0] - PPS87[7:0] Parameters that correspond to each of the 15 ranges.

native_422_420

PPS88[0] - 0 = Native 4:2:2 not used 1 = Native 4:2:2 used PPS88[1] - 0 = Native 4:2:0 not use 1 = Native 4:2:0 used PPS88[7:2] - Reserved 6 bits

second_line_bpg_offset

PPS89[4:0] - Additional bits/group budget for the second line of a slice in Native 4:2:0 mode. Set to 0 if DSC minor version is 1 or native420 is 0. PPS89[7:5] - Reserved

nsl_bpg_offset

PPS90[7:0], PPS91[7:0] - Number of bits that are deallocated for each group that is not in the second line of a slice.

second_line_offset_adj

PPS92[7:0], PPS93[7:0] - Used as offset adjustment for the second line in Native 4:2:0 mode.

pps_long_94_reserved

PPS 94, 95, 96, 97 - Reserved

pps_long_98_reserved

PPS 98, 99, 100, 101 - Reserved

pps_long_102_reserved

PPS 102, 103, 104, 105 - Reserved

pps_long_106_reserved

PPS 106, 107, 108, 109 - reserved

pps_long_110_reserved

PPS 110, 111, 112, 113 - reserved

pps_long_114_reserved

PPS 114 - 117 - reserved

pps_long_118_reserved

PPS 118 - 121 - reserved

pps_long_122_reserved

PPS 122- 125 - reserved

pps_short_126_reserved

PPS 126, 127 - reserved

Description

The VESA DSC standard defines picture parameter set (PPS) which display stream compression encoders must communicate to decoders. The PPS is encapsulated in 128 bytes (PPS 0 through PPS 127). The fields in this structure are as per Table 4.1 in Vesa DSC specification v1.1/v1.2. The PPS fields that span over more than a byte should be stored in Big Endian format.

struct drm_dsc_pps_infoframe

DSC infoframe carrying the Picture Parameter Set Metadata

Definition

struct drm_dsc_pps_infoframe {
  struct dp_sdp_header pps_header;
  struct drm_dsc_picture_parameter_set pps_payload;
};

Members

pps_header

Header for PPS as per DP SDP header format of type struct dp_sdp_header

pps_payload

PPS payload fields as per DSC specification Table 4-1 as represented in struct drm_dsc_picture_parameter_set

Description

This structure represents the DSC PPS infoframe required to send the Picture Parameter Set metadata required before enabling VESA Display Stream Compression. This is based on the DP Secondary Data Packet structure and comprises of SDP Header as defined struct struct dp_sdp_header in drm_dp_helper.h and PPS payload defined in struct drm_dsc_picture_parameter_set.

void drm_dsc_dp_pps_header_init(struct dp_sdp_header * pps_header)

Initializes the PPS Header for DisplayPort as per the DP 1.4 spec.

Parameters

struct dp_sdp_header * pps_header

Secondary data packet header for DSC Picture Parameter Set as defined in struct dp_sdp_header

Description

DP 1.4 spec defines the secondary data packet for sending the picture parameter infoframes from the source to the sink. This function populates the SDP header defined in struct dp_sdp_header.

void drm_dsc_pps_payload_pack(struct drm_dsc_picture_parameter_set * pps_payload, const struct drm_dsc_config * dsc_cfg)

Populates the DSC PPS

Parameters

struct drm_dsc_picture_parameter_set * pps_payload

Bitwise struct for DSC Picture Parameter Set. This is defined by struct drm_dsc_picture_parameter_set

const struct drm_dsc_config * dsc_cfg

DSC Configuration data filled by driver as defined by struct drm_dsc_config

Description

DSC source device sends a picture parameter set (PPS) containing the information required by the sink to decode the compressed frame. Driver populates the DSC PPS struct using the DSC configuration parameters in the order expected by the DSC Display Sink device. For the DSC, the sink device expects the PPS payload in big endian format for fields that span more than 1 byte.

int drm_dsc_compute_rc_parameters(struct drm_dsc_config * vdsc_cfg)

Write rate control parameters to the dsc configuration defined in struct drm_dsc_config in accordance with the DSC 1.2 specification. Some configuration fields must be present beforehand.

Parameters

struct drm_dsc_config * vdsc_cfg

DSC Configuration data partially filled by driver

Output Probing Helper Functions Reference

This library provides some helper code for output probing. It provides an implementation of the core drm_connector_funcs.fill_modes interface with drm_helper_probe_single_connector_modes().

It also provides support for polling connectors with a work item and for generic hotplug interrupt handling where the driver doesn't or cannot keep track of a per-connector hpd interrupt.

This helper library can be used independently of the modeset helper library. Drivers can also overwrite different parts e.g. use their own hotplug handling code to avoid probing unrelated outputs.

The probe helpers share the function table structures with other display helper libraries. See struct drm_connector_helper_funcs for the details.

void drm_kms_helper_poll_enable(struct drm_device * dev)

re-enable output polling.

Parameters

struct drm_device * dev

drm_device

Description

This function re-enables the output polling work, after it has been temporarily disabled using drm_kms_helper_poll_disable(), for example over suspend/resume.

Drivers can call this helper from their device resume implementation. It is not an error to call this even when output polling isn't enabled.

Note that calls to enable and disable polling must be strictly ordered, which is automatically the case when they're only call from suspend/resume callbacks.

int drm_helper_probe_detect(struct drm_connector * connector, struct drm_modeset_acquire_ctx * ctx, bool force)

probe connector status

Parameters

struct drm_connector * connector

connector to probe

struct drm_modeset_acquire_ctx * ctx

acquire_ctx, or NULL to let this function handle locking.

bool force

Whether destructive probe operations should be performed.

Description

This function calls the detect callbacks of the connector. This function returns drm_connector_status, or if ctx is set, it might also return -EDEADLK.

int drm_helper_probe_single_connector_modes(struct drm_connector * connector, uint32_t maxX, uint32_t maxY)

get complete set of display modes

Parameters

struct drm_connector * connector

connector to probe

uint32_t maxX

max width for modes

uint32_t maxY

max height for modes

Description

Based on the helper callbacks implemented by connector in struct drm_connector_helper_funcs try to detect all valid modes. Modes will first be added to the connector's probed_modes list, then culled (based on validity and the maxX, maxY parameters) and put into the normal modes list.

Intended to be used as a generic implementation of the drm_connector_funcs.fill_modes() vfunc for drivers that use the CRTC helpers for output mode filtering and detection.

The basic procedure is as follows

1. All modes currently on the connector's modes list are marked as stale

2. New modes are added to the connector's probed_modes list with drm_mode_probed_add(). New modes start their life with status as OK. Modes are added from a single source using the following priority order.

   • drm_connector_helper_funcs.get_modes vfunc

   • if the connector status is connector_status_connected, standard VESA DMT modes up to 1024x768 are automatically added (drm_add_modes_noedid())

   Finally modes specified via the kernel command line (video=...) are added in addition to what the earlier probes produced (drm_helper_probe_add_cmdline_mode()). These modes are generated using the VESA GTF/CVT formulas.

3. Modes are moved from the probed_modes list to the modes list. Potential duplicates are merged together (see drm_connector_list_update()). After this step the probed_modes list will be empty again.

4. Any non-stale mode on the modes list then undergoes validation

   • drm_mode_validate_basic() performs basic sanity checks

   • drm_mode_validate_size() filters out modes larger than maxX and maxY (if specified)

   • drm_mode_validate_flag() checks the modes against basic connector capabilities (interlace_allowed,doublescan_allowed,stereo_allowed)

   • the optional drm_connector_helper_funcs.mode_valid helper can perform driver and/or sink specific checks

   • the optional drm_crtc_helper_funcs.mode_valid, drm_bridge_funcs.mode_valid and drm_encoder_helper_funcs.mode_valid helpers can perform driver and/or source specific checks which are also enforced by the modeset/atomic helpers

5. Any mode whose status is not OK is pruned from the connector's modes list, accompanied by a debug message indicating the reason for the mode's rejection (see drm_mode_prune_invalid()).

Return

The number of modes found on connector.

void drm_kms_helper_hotplug_event(struct drm_device * dev)

fire off KMS hotplug events

Parameters

struct drm_device * dev

drm_device whose connector state changed

Description

This function fires off the uevent for userspace and also calls the output_poll_changed function, which is most commonly used to inform the fbdev emulation code and allow it to update the fbcon output configuration.

Drivers should call this from their hotplug handling code when a change is detected. Note that this function does not do any output detection of its own, like drm_helper_hpd_irq_event() does - this is assumed to be done by the driver already.

This function must be called from process context with no mode setting locks held.

bool drm_kms_helper_is_poll_worker(void)

is current task an output poll worker?

Parameters

void

no arguments

Description

Determine if current task is an output poll worker. This can be used to select distinct code paths for output polling versus other contexts.

One use case is to avoid a deadlock between the output poll worker and the autosuspend worker wherein the latter waits for polling to finish upon calling drm_kms_helper_poll_disable(), while the former waits for runtime suspend to finish upon calling pm_runtime_get_sync() in a connector ->detect hook.

void drm_kms_helper_poll_disable(struct drm_device * dev)

disable output polling

Parameters

struct drm_device * dev

drm_device

Description

This function disables the output polling work.

Drivers can call this helper from their device suspend implementation. It is not an error to call this even when output polling isn't enabled or already disabled. Polling is re-enabled by calling drm_kms_helper_poll_enable().

Note that calls to enable and disable polling must be strictly ordered, which is automatically the case when they're only call from suspend/resume callbacks.

void drm_kms_helper_poll_init(struct drm_device * dev)

initialize and enable output polling

Parameters

struct drm_device * dev

drm_device

Description

This function intializes and then also enables output polling support for dev. Drivers which do not have reliable hotplug support in hardware can use this helper infrastructure to regularly poll such connectors for changes in their connection state.

Drivers can control which connectors are polled by setting the DRM_CONNECTOR_POLL_CONNECT and DRM_CONNECTOR_POLL_DISCONNECT flags. On connectors where probing live outputs can result in visual distortion drivers should not set the DRM_CONNECTOR_POLL_DISCONNECT flag to avoid this. Connectors which have no flag or only DRM_CONNECTOR_POLL_HPD set are completely ignored by the polling logic.

Note that a connector can be both polled and probed from the hotplug handler, in case the hotplug interrupt is known to be unreliable.

void drm_kms_helper_poll_fini(struct drm_device * dev)

disable output polling and clean it up

Parameters

struct drm_device * dev

drm_device

bool drm_helper_hpd_irq_event(struct drm_device * dev)

hotplug processing

Parameters

struct drm_device * dev

drm_device

Description

Drivers can use this helper function to run a detect cycle on all connectors which have the DRM_CONNECTOR_POLL_HPD flag set in their polled member. All other connectors are ignored, which is useful to avoid reprobing fixed panels.

This helper function is useful for drivers which can't or don't track hotplug interrupts for each connector.

Drivers which support hotplug interrupts for each connector individually and which have a more fine-grained detect logic should bypass this code and directly call drm_kms_helper_hotplug_event() in case the connector state changed.

This function must be called from process context with no mode setting locks held.

Note that a connector can be both polled and probed from the hotplug handler, in case the hotplug interrupt is known to be unreliable.

EDID Helper Functions Reference

int drm_eld_mnl(const uint8_t * eld)

Get ELD monitor name length in bytes.

Parameters

const uint8_t * eld

pointer to an eld memory structure with mnl set

const uint8_t * drm_eld_sad(const uint8_t * eld)

Get ELD SAD structures.

Parameters

const uint8_t * eld

pointer to an eld memory structure with sad_count set

int drm_eld_sad_count(const uint8_t * eld)

Get ELD SAD count.

Parameters

const uint8_t * eld

pointer to an eld memory structure with sad_count set

int drm_eld_calc_baseline_block_size(const uint8_t * eld)

Calculate baseline block size in bytes

Parameters

const uint8_t * eld

pointer to an eld memory structure with mnl and sad_count set

Description

This is a helper for determining the payload size of the baseline block, in bytes, for e.g. setting the Baseline_ELD_Len field in the ELD header block.

int drm_eld_size(const uint8_t * eld)

Get ELD size in bytes

Parameters

const uint8_t * eld

pointer to a complete eld memory structure

Description

The returned value does not include the vendor block. It's vendor specific, and comprises of the remaining bytes in the ELD memory buffer after drm_eld_size() bytes of header and baseline block.

The returned value is guaranteed to be a multiple of 4.

u8 drm_eld_get_spk_alloc(const uint8_t * eld)

Get speaker allocation

Parameters

const uint8_t * eld

pointer to an ELD memory structure

Description

The returned value is the speakers mask. User has to use DRM_ELD_SPEAKER field definitions to identify speakers.

u8 drm_eld_get_conn_type(const uint8_t * eld)

Get device type hdmi/dp connected

Parameters

const uint8_t * eld

pointer to an ELD memory structure

Description

The caller need to use DRM_ELD_CONN_TYPE_HDMI or DRM_ELD_CONN_TYPE_DP to identify the display type connected.

int drm_edid_header_is_valid(const u8 * raw_edid)

sanity check the header of the base EDID block

Parameters

const u8 * raw_edid

pointer to raw base EDID block

Description

Sanity check the header of the base EDID block.

Return

8 if the header is perfect, down to 0 if it's totally wrong.

bool drm_edid_block_valid(u8 * raw_edid, int block, bool print_bad_edid, bool * edid_corrupt)

Sanity check the EDID block (base or extension)

Parameters

u8 * raw_edid

pointer to raw EDID block

int block

type of block to validate (0 for base, extension otherwise)

bool print_bad_edid

if true, dump bad EDID blocks to the console

bool * edid_corrupt

if true, the header or checksum is invalid

Description

Validate a base or extension EDID block and optionally dump bad blocks to the console.

Return

True if the block is valid, false otherwise.

bool drm_edid_is_valid(struct edid * edid)

sanity check EDID data

Parameters

struct edid * edid

EDID data

Description

Sanity-check an entire EDID record (including extensions)

Return

True if the EDID data is valid, false otherwise.

int drm_add_override_edid_modes(struct drm_connector * connector)

add modes from override/firmware EDID

Parameters

struct drm_connector * connector

connector we're probing

Description

Add modes from the override/firmware EDID, if available. Only to be used from drm_helper_probe_single_connector_modes() as a fallback for when DDC probe failed during drm_get_edid() and caused the override/firmware EDID to be skipped.

Return

The number of modes added or 0 if we couldn't find any.

struct edid * drm_do_get_edid(struct drm_connector * connector, int (*get_edid_block) (void *data, u8 *buf, unsigned int block, size_t len, void * data)

get EDID data using a custom EDID block read function

Parameters

struct drm_connector * connector

connector we're probing

int (*)(void *data, u8 *buf, unsigned int block, size_t len) get_edid_block

EDID block read function

void * data

private data passed to the block read function

Description

When the I2C adapter connected to the DDC bus is hidden behind a device that exposes a different interface to read EDID blocks this function can be used to get EDID data using a custom block read function.

As in the general case the DDC bus is accessible by the kernel at the I2C level, drivers must make all reasonable efforts to expose it as an I2C adapter and use drm_get_edid() instead of abusing this function.

The EDID may be overridden using debugfs override_edid or firmare EDID (drm_load_edid_firmware() and drm.edid_firmware parameter), in this priority order. Having either of them bypasses actual EDID reads.

Return

Pointer to valid EDID or NULL if we couldn't find any.

bool drm_probe_ddc(struct i2c_adapter * adapter)

probe DDC presence

Parameters

struct i2c_adapter * adapter

I2C adapter to probe

Return

True on success, false on failure.

struct edid * drm_get_edid(struct drm_connector * connector, struct i2c_adapter * adapter)

get EDID data, if available

Parameters

struct drm_connector * connector

connector we're probing

struct i2c_adapter * adapter

I2C adapter to use for DDC

Description

Poke the given I2C channel to grab EDID data if possible. If found, attach it to the connector.

Return

Pointer to valid EDID or NULL if we couldn't find any.

struct edid * drm_get_edid_switcheroo(struct drm_connector * connector, struct i2c_adapter * adapter)

get EDID data for a vga_switcheroo output

Parameters

struct drm_connector * connector

connector we're probing

struct i2c_adapter * adapter

I2C adapter to use for DDC

Description

Wrapper around drm_get_edid() for laptops with dual GPUs using one set of outputs. The wrapper adds the requisite vga_switcheroo calls to temporarily switch DDC to the GPU which is retrieving EDID.

Return

Pointer to valid EDID or NULL if we couldn't find any.

struct edid * drm_edid_duplicate(const struct edid * edid)

duplicate an EDID and the extensions

Parameters

const struct edid * edid

EDID to duplicate

Return

Pointer to duplicated EDID or NULL on allocation failure.

u8 drm_match_cea_mode(const struct drm_display_mode * to_match)

look for a CEA mode matching given mode

Parameters

const struct drm_display_mode * to_match

display mode

Return

The CEA Video ID (VIC) of the mode or 0 if it isn't a CEA-861 mode.

enum hdmi_picture_aspect drm_get_cea_aspect_ratio(const u8 video_code)

get the picture aspect ratio corresponding to the input VIC from the CEA mode list

Parameters

const u8 video_code

ID given to each of the CEA modes

Description

Returns picture aspect ratio

void drm_edid_get_monitor_name(struct edid * edid, char * name, int bufsize)

fetch the monitor name from the edid

Parameters

struct edid * edid

monitor EDID information

char * name

pointer to a character array to hold the name of the monitor

int bufsize

The size of the name buffer (should be at least 14 chars.)

int drm_edid_to_sad(struct edid * edid, struct cea_sad ** sads)

extracts SADs from EDID

Parameters

struct edid * edid

EDID to parse

struct cea_sad ** sads

pointer that will be set to the extracted SADs

Description

Looks for CEA EDID block and extracts SADs (Short Audio Descriptors) from it.

Note

The returned pointer needs to be freed using kfree().

Return

The number of found SADs or negative number on error.

int drm_edid_to_speaker_allocation(struct edid * edid, u8 ** sadb)

extracts Speaker Allocation Data Blocks from EDID

Parameters

struct edid * edid

EDID to parse

u8 ** sadb

pointer to the speaker block

Description

Looks for CEA EDID block and extracts the Speaker Allocation Data Block from it.

Note

The returned pointer needs to be freed using kfree().

Return

The number of found Speaker Allocation Blocks or negative number on error.

int drm_av_sync_delay(struct drm_connector * connector, const struct drm_display_mode * mode)

compute the HDMI/DP sink audio-video sync delay

Parameters

struct drm_connector * connector

connector associated with the HDMI/DP sink

const struct drm_display_mode * mode

the display mode

Return

The HDMI/DP sink's audio-video sync delay in milliseconds or 0 if the sink doesn't support audio or video.

bool drm_detect_hdmi_monitor(struct edid * edid)

detect whether monitor is HDMI

Parameters

struct edid * edid

monitor EDID information

Description

Parse the CEA extension according to CEA-861-B.

Return

True if the monitor is HDMI, false if not or unknown.

bool drm_detect_monitor_audio(struct edid * edid)

check monitor audio capability

Parameters

struct edid * edid

EDID block to scan

Description

Monitor should have CEA extension block. If monitor has 'basic audio', but no CEA audio blocks, it's 'basic audio' only. If there is any audio extension block and supported audio format, assume at least 'basic audio' support, even if 'basic audio' is not defined in EDID.

Return

True if the monitor supports audio, false otherwise.

enum hdmi_quantization_range drm_default_rgb_quant_range(const struct drm_display_mode * mode)

default RGB quantization range

Parameters

const struct drm_display_mode * mode

display mode

Description

Determine the default RGB quantization range for the mode, as specified in CEA-861.

Return

The default RGB quantization range for the mode

int drm_add_edid_modes(struct drm_connector * connector, struct edid * edid)

add modes from EDID data, if available

Parameters

struct drm_connector * connector

connector we're probing

struct edid * edid

EDID data

Description

Add the specified modes to the connector's mode list. Also fills out the drm_display_info structure and ELD in connector with any information which can be derived from the edid.

Return

The number of modes added or 0 if we couldn't find any.

int drm_add_modes_noedid(struct drm_connector * connector, int hdisplay, int vdisplay)

add modes for the connectors without EDID

Parameters

struct drm_connector * connector

connector we're probing

int hdisplay

the horizontal display limit

int vdisplay

the vertical display limit

Description

Add the specified modes to the connector's mode list. Only when the hdisplay/vdisplay is not beyond the given limit, it will be added.

Return

The number of modes added or 0 if we couldn't find any.

void drm_set_preferred_mode(struct drm_connector * connector, int hpref, int vpref)

Sets the preferred mode of a connector

Parameters

struct drm_connector * connector

connector whose mode list should be processed

int hpref

horizontal resolution of preferred mode

int vpref

vertical resolution of preferred mode

Description

Marks a mode as preferred if it matches the resolution specified by hpref and vpref.

int drm_hdmi_infoframe_set_hdr_metadata(struct hdmi_drm_infoframe * frame, const struct drm_connector_state * conn_state)

fill an HDMI DRM infoframe with HDR metadata from userspace

Parameters

struct hdmi_drm_infoframe * frame

HDMI DRM infoframe

const struct drm_connector_state * conn_state

Connector state containing HDR metadata

Return

0 on success or a negative error code on failure.

int drm_hdmi_avi_infoframe_from_display_mode(struct hdmi_avi_infoframe * frame, struct drm_connector * connector, const struct drm_display_mode * mode)

fill an HDMI AVI infoframe with data from a DRM display mode

Parameters

struct hdmi_avi_infoframe * frame

HDMI AVI infoframe

struct drm_connector * connector

the connector

const struct drm_display_mode * mode

DRM display mode

Return

0 on success or a negative error code on failure.

void drm_hdmi_avi_infoframe_colorspace(struct hdmi_avi_infoframe * frame, const struct drm_connector_state * conn_state)

fill the HDMI AVI infoframe colorspace information

Parameters

struct hdmi_avi_infoframe * frame

HDMI AVI infoframe

const struct drm_connector_state * conn_state

connector state

void drm_hdmi_avi_infoframe_quant_range(struct hdmi_avi_infoframe * frame, struct drm_connector * connector, const struct drm_display_mode * mode, enum hdmi_quantization_range rgb_quant_range)

fill the HDMI AVI infoframe quantization range information

Parameters

struct hdmi_avi_infoframe * frame

HDMI AVI infoframe

struct drm_connector * connector

the connector

const struct drm_display_mode * mode

DRM display mode

enum hdmi_quantization_range rgb_quant_range

RGB quantization range (Q)

int drm_hdmi_vendor_infoframe_from_display_mode(struct hdmi_vendor_infoframe * frame, struct drm_connector * connector, const struct drm_display_mode * mode)

fill an HDMI infoframe with data from a DRM display mode

Parameters

struct hdmi_vendor_infoframe * frame

HDMI vendor infoframe

struct drm_connector * connector

the connector

const struct drm_display_mode * mode

DRM display mode

Description

Note that there's is a need to send HDMI vendor infoframes only when using a 4k or stereoscopic 3D mode. So when giving any other mode as input this function will return -EINVAL, error that can be safely ignored.

Return

0 on success or a negative error code on failure.

SCDC Helper Functions Reference

Status and Control Data Channel (SCDC) is a mechanism introduced by the HDMI 2.0 specification. It is a point-to-point protocol that allows the HDMI source and HDMI sink to exchange data. The same I2C interface that is used to access EDID serves as the transport mechanism for SCDC.

int drm_scdc_readb(struct i2c_adapter * adapter, u8 offset, u8 * value)

read a single byte from SCDC

Parameters

struct i2c_adapter * adapter

I2C adapter

u8 offset

offset of register to read

u8 * value

return location for the register value

Description

Reads a single byte from SCDC. This is a convenience wrapper around the drm_scdc_read() function.

Return

0 on success or a negative error code on failure.

int drm_scdc_writeb(struct i2c_adapter * adapter, u8 offset, u8 value)

write a single byte to SCDC

Parameters

struct i2c_adapter * adapter

I2C adapter

u8 offset

offset of register to read

u8 value

return location for the register value

Description

Writes a single byte to SCDC. This is a convenience wrapper around the drm_scdc_write() function.

Return

0 on success or a negative error code on failure.

ssize_t drm_scdc_read(struct i2c_adapter * adapter, u8 offset, void * buffer, size_t size)

read a block of data from SCDC

Parameters

struct i2c_adapter * adapter

I2C controller

u8 offset

start offset of block to read

void * buffer

return location for the block to read

size_t size

size of the block to read

Description

Reads a block of data from SCDC, starting at a given offset.

Return

0 on success, negative error code on failure.

ssize_t drm_scdc_write(struct i2c_adapter * adapter, u8 offset, const void * buffer, size_t size)

write a block of data to SCDC

Parameters

struct i2c_adapter * adapter

I2C controller

u8 offset

start offset of block to write

const void * buffer

block of data to write

size_t size

size of the block to write

Description

Writes a block of data to SCDC, starting at a given offset.

Return

0 on success, negative error code on failure.

bool drm_scdc_get_scrambling_status(struct i2c_adapter * adapter)

what is status of scrambling?

Parameters

struct i2c_adapter * adapter

I2C adapter for DDC channel

Description

Reads the scrambler status over SCDC, and checks the scrambling status.

Return

True if the scrambling is enabled, false otherwise.

bool drm_scdc_set_scrambling(struct i2c_adapter * adapter, bool enable)

enable scrambling

Parameters

struct i2c_adapter * adapter

I2C adapter for DDC channel

bool enable

bool to indicate if scrambling is to be enabled/disabled

Description

Writes the TMDS config register over SCDC channel, and: enables scrambling when enable = 1 disables scrambling when enable = 0

Return

True if scrambling is set/reset successfully, false otherwise.

bool drm_scdc_set_high_tmds_clock_ratio(struct i2c_adapter * adapter, bool set)

set TMDS clock ratio

Parameters

struct i2c_adapter * adapter

I2C adapter for DDC channel

bool set

ret or reset the high clock ratio

Description

TMDS clock ratio calculations go like this:

TMDS character = 10 bit TMDS encoded value

TMDS character rate = The rate at which TMDS characters are transmitted (Mcsc)

TMDS bit rate = 10x TMDS character rate

As per the spec:

TMDS clock rate for pixel clock < 340 MHz = 1x the character rate = 1/10 pixel clock rate

TMDS clock rate for pixel clock > 340 MHz = 0.25x the character rate = 1/40 pixel clock rate

Writes to the TMDS config register over SCDC channel, and:

sets TMDS clock ratio to 1/40 when set = 1

sets TMDS clock ratio to 1/10 when set = 0

Return

True if write is successful, false otherwise.

HDMI Infoframes Helper Reference

Strictly speaking this is not a DRM helper library but generally useable by any driver interfacing with HDMI outputs like v4l or alsa drivers. But it nicely fits into the overall topic of mode setting helper libraries and hence is also included here.

struct hdr_sink_metadata

HDR sink metadata

Definition

struct hdr_sink_metadata {
  __u32 metadata_type;
  union {
    struct hdr_static_metadata hdmi_type1;
  };
};

Members

metadata_type

Static_Metadata_Descriptor_ID.

{unnamed_union}

anonymous

hdmi_type1

HDR Metadata Infoframe.

Description

Metadata Information read from Sink's EDID

union hdmi_infoframe

overall union of all abstract infoframe representations

Definition

union hdmi_infoframe {
  struct hdmi_any_infoframe any;
  struct hdmi_avi_infoframe avi;
  struct hdmi_spd_infoframe spd;
  union hdmi_vendor_any_infoframe vendor;
  struct hdmi_audio_infoframe audio;
  struct hdmi_drm_infoframe drm;
};

Members

any

generic infoframe

avi

avi infoframe

spd

spd infoframe

vendor

union of all vendor infoframes

audio

audio infoframe

drm

Dynamic Range and Mastering infoframe

Description

This is used by the generic pack function. This works since all infoframes have the same header which also indicates which type of infoframe should be packed.

int hdmi_avi_infoframe_init(struct hdmi_avi_infoframe * frame)

initialize an HDMI AVI infoframe

Parameters

struct hdmi_avi_infoframe * frame

HDMI AVI infoframe

Description

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

int hdmi_avi_infoframe_check(struct hdmi_avi_infoframe * frame)

check a HDMI AVI infoframe

Parameters

struct hdmi_avi_infoframe * frame

HDMI AVI infoframe

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields.

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

ssize_t hdmi_avi_infoframe_pack_only(const struct hdmi_avi_infoframe * frame, void * buffer, size_t size)

write HDMI AVI infoframe to binary buffer

Parameters

const struct hdmi_avi_infoframe * frame

HDMI AVI infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. Also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

ssize_t hdmi_avi_infoframe_pack(struct hdmi_avi_infoframe * frame, void * buffer, size_t size)

check a HDMI AVI infoframe, and write it to binary buffer

Parameters

struct hdmi_avi_infoframe * frame

HDMI AVI infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields, after which it packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. This function also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

int hdmi_spd_infoframe_init(struct hdmi_spd_infoframe * frame, const char * vendor, const char * product)

initialize an HDMI SPD infoframe

Parameters

struct hdmi_spd_infoframe * frame

HDMI SPD infoframe

const char * vendor

vendor string

const char * product

product string

Description

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

int hdmi_spd_infoframe_check(struct hdmi_spd_infoframe * frame)

check a HDMI SPD infoframe

Parameters

struct hdmi_spd_infoframe * frame

HDMI SPD infoframe

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields.

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

ssize_t hdmi_spd_infoframe_pack_only(const struct hdmi_spd_infoframe * frame, void * buffer, size_t size)

write HDMI SPD infoframe to binary buffer

Parameters

const struct hdmi_spd_infoframe * frame

HDMI SPD infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. Also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

ssize_t hdmi_spd_infoframe_pack(struct hdmi_spd_infoframe * frame, void * buffer, size_t size)

check a HDMI SPD infoframe, and write it to binary buffer

Parameters

struct hdmi_spd_infoframe * frame

HDMI SPD infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields, after which it packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. This function also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

int hdmi_audio_infoframe_init(struct hdmi_audio_infoframe * frame)

initialize an HDMI audio infoframe

Parameters

struct hdmi_audio_infoframe * frame

HDMI audio infoframe

Description

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

int hdmi_audio_infoframe_check(struct hdmi_audio_infoframe * frame)

check a HDMI audio infoframe

Parameters

struct hdmi_audio_infoframe * frame

HDMI audio infoframe

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields.

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

ssize_t hdmi_audio_infoframe_pack_only(const struct hdmi_audio_infoframe * frame, void * buffer, size_t size)

write HDMI audio infoframe to binary buffer

Parameters

const struct hdmi_audio_infoframe * frame

HDMI audio infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. Also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

ssize_t hdmi_audio_infoframe_pack(struct hdmi_audio_infoframe * frame, void * buffer, size_t size)

check a HDMI Audio infoframe, and write it to binary buffer

Parameters

struct hdmi_audio_infoframe * frame

HDMI Audio infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields, after which it packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. This function also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

int hdmi_vendor_infoframe_init(struct hdmi_vendor_infoframe * frame)

initialize an HDMI vendor infoframe

Parameters

struct hdmi_vendor_infoframe * frame

HDMI vendor infoframe

Description

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

int hdmi_vendor_infoframe_check(struct hdmi_vendor_infoframe * frame)

check a HDMI vendor infoframe

Parameters

struct hdmi_vendor_infoframe * frame

HDMI infoframe

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields.

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

ssize_t hdmi_vendor_infoframe_pack_only(const struct hdmi_vendor_infoframe * frame, void * buffer, size_t size)

write a HDMI vendor infoframe to binary buffer

Parameters

const struct hdmi_vendor_infoframe * frame

HDMI infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. Also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

ssize_t hdmi_vendor_infoframe_pack(struct hdmi_vendor_infoframe * frame, void * buffer, size_t size)

check a HDMI Vendor infoframe, and write it to binary buffer

Parameters

struct hdmi_vendor_infoframe * frame

HDMI Vendor infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields, after which it packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. This function also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

int hdmi_drm_infoframe_init(struct hdmi_drm_infoframe * frame)

initialize an HDMI Dynaminc Range and mastering infoframe

Parameters

struct hdmi_drm_infoframe * frame

HDMI DRM infoframe

Description

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

int hdmi_drm_infoframe_check(struct hdmi_drm_infoframe * frame)

check a HDMI DRM infoframe

Parameters

struct hdmi_drm_infoframe * frame

HDMI DRM infoframe

Description

Validates that the infoframe is consistent. Returns 0 on success or a negative error code on failure.

ssize_t hdmi_drm_infoframe_pack_only(const struct hdmi_drm_infoframe * frame, void * buffer, size_t size)

write HDMI DRM infoframe to binary buffer

Parameters

const struct hdmi_drm_infoframe * frame

HDMI DRM infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. Also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

ssize_t hdmi_drm_infoframe_pack(struct hdmi_drm_infoframe * frame, void * buffer, size_t size)

check a HDMI DRM infoframe, and write it to binary buffer

Parameters

struct hdmi_drm_infoframe * frame

HDMI DRM infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields, after which it packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. This function also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

int hdmi_infoframe_check(union hdmi_infoframe * frame)

check a HDMI infoframe

Parameters

union hdmi_infoframe * frame

HDMI infoframe

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields.

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

ssize_t hdmi_infoframe_pack_only(const union hdmi_infoframe * frame, void * buffer, size_t size)

write a HDMI infoframe to binary buffer

Parameters

const union hdmi_infoframe * frame

HDMI infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. Also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

ssize_t hdmi_infoframe_pack(union hdmi_infoframe * frame, void * buffer, size_t size)

check a HDMI infoframe, and write it to binary buffer

Parameters

union hdmi_infoframe * frame

HDMI infoframe

void * buffer

destination buffer

size_t size

size of buffer

Description

Validates that the infoframe is consistent and updates derived fields (eg. length) based on other fields, after which it packs the information contained in the frame structure into a binary representation that can be written into the corresponding controller registers. This function also computes the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

Returns the number of bytes packed into the binary buffer or a negative error code on failure.

void hdmi_infoframe_log(const char * level, struct device * dev, const union hdmi_infoframe * frame)

log info of HDMI infoframe

Parameters

const char * level

logging level

struct device * dev

device

const union hdmi_infoframe * frame

HDMI infoframe

int hdmi_infoframe_unpack(union hdmi_infoframe * frame, const void * buffer, size_t size)

unpack binary buffer to a HDMI infoframe

Parameters

union hdmi_infoframe * frame

HDMI infoframe

const void * buffer

source buffer

size_t size

size of buffer

Description

Unpacks the information contained in binary buffer buffer into a structured frame of a HDMI infoframe. Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4 specification.

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

Rectangle Utilities Reference

Utility functions to help manage rectangular areas for clipping, scaling, etc. calculations.

struct drm_rect

two dimensional rectangle

Definition

struct drm_rect {
  int x1, y1, x2, y2;
};

Members

x1

horizontal starting coordinate (inclusive)

y1

vertical starting coordinate (inclusive)

x2

horizontal ending coordinate (exclusive)

y2

vertical ending coordinate (exclusive)

DRM_RECT_FMT()

printf string for struct drm_rect

Parameters

DRM_RECT_ARG(r)

printf arguments for struct drm_rect

Parameters

r

rectangle struct

DRM_RECT_FP_FMT()

printf string for struct drm_rect in 16.16 fixed point

Parameters

DRM_RECT_FP_ARG(r)

printf arguments for struct drm_rect in 16.16 fixed point

Parameters

r

rectangle struct

Description

This is useful for e.g. printing plane source rectangles, which are in 16.16 fixed point.

void drm_rect_adjust_size(struct drm_rect * r, int dw, int dh)

adjust the size of the rectangle

Parameters

struct drm_rect * r

rectangle to be adjusted

int dw

horizontal adjustment

int dh

vertical adjustment

Description

Change the size of rectangle r by dw in the horizontal direction, and by dh in the vertical direction, while keeping the center of r stationary.

Positive dw and dh increase the size, negative values decrease it.

void drm_rect_translate(struct drm_rect * r, int dx, int dy)

translate the rectangle

Parameters

struct drm_rect * r

rectangle to be tranlated

int dx

horizontal translation

int dy

vertical translation

Description

Move rectangle r by dx in the horizontal direction, and by dy in the vertical direction.

void drm_rect_downscale(struct drm_rect * r, int horz, int vert)

downscale a rectangle

Parameters

struct drm_rect * r

rectangle to be downscaled

int horz

horizontal downscale factor

int vert

vertical downscale factor

Description

Divide the coordinates of rectangle r by horz and vert.

int drm_rect_width(const struct drm_rect * r)

determine the rectangle width

Parameters

const struct drm_rect * r

rectangle whose width is returned

Return

The width of the rectangle.

int drm_rect_height(const struct drm_rect * r)

determine the rectangle height

Parameters

const struct drm_rect * r

rectangle whose height is returned

Return

The height of the rectangle.

bool drm_rect_visible(const struct drm_rect * r)

determine if the the rectangle is visible

Parameters

const struct drm_rect * r

rectangle whose visibility is returned

Return

true if the rectangle is visible, false otherwise.

bool drm_rect_equals(const struct drm_rect * r1, const struct drm_rect * r2)

determine if two rectangles are equal

Parameters

const struct drm_rect * r1

first rectangle

const struct drm_rect * r2

second rectangle

Return

true if the rectangles are equal, false otherwise.

bool drm_rect_intersect(struct drm_rect * r1, const struct drm_rect * r2)

intersect two rectangles

Parameters

struct drm_rect * r1

first rectangle

const struct drm_rect * r2

second rectangle

Description

Calculate the intersection of rectangles r1 and r2. r1 will be overwritten with the intersection.

Return

true if rectangle r1 is still visible after the operation, false otherwise.

bool drm_rect_clip_scaled(struct drm_rect * src, struct drm_rect * dst, const struct drm_rect * clip)

perform a scaled clip operation

Parameters

struct drm_rect * src

source window rectangle

struct drm_rect * dst

destination window rectangle

const struct drm_rect * clip

clip rectangle

Description

Clip rectangle dst by rectangle clip. Clip rectangle src by the same amounts multiplied by hscale and vscale.

Return

true if rectangle dst is still visible after being clipped, false otherwise

int drm_rect_calc_hscale(const struct drm_rect * src, const struct drm_rect * dst, int min_hscale, int max_hscale)

calculate the horizontal scaling factor

Parameters

const struct drm_rect * src

source window rectangle

const struct drm_rect * dst

destination window rectangle

int min_hscale

minimum allowed horizontal scaling factor

int max_hscale

maximum allowed horizontal scaling factor

Description

Calculate the horizontal scaling factor as (src width) / (dst width).

If the scale is below 1 << 16, round down. If the scale is above 1 << 16, round up. This will calculate the scale with the most pessimistic limit calculation.

Return

The horizontal scaling factor, or errno of out of limits.

int drm_rect_calc_vscale(const struct drm_rect * src, const struct drm_rect * dst, int min_vscale, int max_vscale)

calculate the vertical scaling factor

Parameters

const struct drm_rect * src

source window rectangle

const struct drm_rect * dst

destination window rectangle

int min_vscale

minimum allowed vertical scaling factor

int max_vscale

maximum allowed vertical scaling factor

Description

Calculate the vertical scaling factor as (src height) / (dst height).

If the scale is below 1 << 16, round down. If the scale is above 1 << 16, round up. This will calculate the scale with the most pessimistic limit calculation.

Return

The vertical scaling factor, or errno of out of limits.

void drm_rect_debug_print(const char * prefix, const struct drm_rect * r, bool fixed_point)

print the rectangle information

Parameters

const char * prefix

prefix string

const struct drm_rect * r

rectangle to print

bool fixed_point

rectangle is in 16.16 fixed point format

void drm_rect_rotate(struct drm_rect * r, int width, int height, unsigned int rotation)

Rotate the rectangle

Parameters

struct drm_rect * r

rectangle to be rotated

int width

Width of the coordinate space

int height

Height of the coordinate space

unsigned int rotation

Transformation to be applied

Description

Apply rotation to the coordinates of rectangle r.

width and height combined with rotation define the location of the new origin.

width correcsponds to the horizontal and height to the vertical axis of the untransformed coordinate space.

void drm_rect_rotate_inv(struct drm_rect * r, int width, int height, unsigned int rotation)

Inverse rotate the rectangle

Parameters

struct drm_rect * r

rectangle to be rotated

int width

Width of the coordinate space

int height

Height of the coordinate space

unsigned int rotation

Transformation whose inverse is to be applied

Description

Apply the inverse of rotation to the coordinates of rectangle r.

width and height combined with rotation define the location of the new origin.

width correcsponds to the horizontal and height to the vertical axis of the original untransformed coordinate space, so that you never have to flip them when doing a rotatation and its inverse. That is, if you do

drm_rect_rotate(&r, width, height, rotation);
drm_rect_rotate_inv(&r, width, height, rotation);

you will always get back the original rectangle.

Flip-work Helper Reference

Util to queue up work to run from work-queue context after flip/vblank. Typically this can be used to defer unref of framebuffer's, cursor bo's, etc until after vblank. The APIs are all thread-safe. Moreover, drm_flip_work_queue_task and drm_flip_work_queue can be called in atomic context.

struct drm_flip_task

flip work task

Definition

struct drm_flip_task {
  struct list_head node;
  void *data;
};

Members

node

list entry element

data

data to pass to drm_flip_work.func

struct drm_flip_work

flip work queue

Definition

struct drm_flip_work {
  const char *name;
  drm_flip_func_t func;
  struct work_struct worker;
  struct list_head queued;
  struct list_head commited;
  spinlock_t lock;
};

Members

name

debug name

func

callback fxn called for each committed item

worker

worker which calls func

queued

queued tasks

commited

commited tasks

lock

lock to access queued and commited lists

struct drm_flip_task * drm_flip_work_allocate_task(void * data, gfp_t flags)

allocate a flip-work task

Parameters

void * data

data associated to the task

gfp_t flags

allocator flags

Description

Allocate a drm_flip_task object and attach private data to it.

void drm_flip_work_queue_task(struct drm_flip_work * work, struct drm_flip_task * task)

queue a specific task

Parameters

struct drm_flip_work * work

the flip-work

struct drm_flip_task * task

the task to handle

Description

Queues task, that will later be run (passed back to drm_flip_func_t func) on a work queue after drm_flip_work_commit() is called.

void drm_flip_work_queue(struct drm_flip_work * work, void * val)

queue work

Parameters

struct drm_flip_work * work

the flip-work

void * val

the value to queue

Description

Queues work, that will later be run (passed back to drm_flip_func_t func) on a work queue after drm_flip_work_commit() is called.

void drm_flip_work_commit(struct drm_flip_work * work, struct workqueue_struct * wq)

commit queued work

Parameters

struct drm_flip_work * work

the flip-work

struct workqueue_struct * wq

the work-queue to run the queued work on

Description

Trigger work previously queued by drm_flip_work_queue() to run on a workqueue. The typical usage would be to queue work (via drm_flip_work_queue()) at any point (from vblank irq and/or prior), and then from vblank irq commit the queued work.

void drm_flip_work_init(struct drm_flip_work * work, const char * name, drm_flip_func_t func)

initialize flip-work

Parameters

struct drm_flip_work * work

the flip-work to initialize

const char * name

debug name

drm_flip_func_t func

the callback work function

Description

Initializes/allocates resources for the flip-work

void drm_flip_work_cleanup(struct drm_flip_work * work)

cleans up flip-work

Parameters

struct drm_flip_work * work

the flip-work to cleanup

Description

Destroy resources allocated for the flip-work

Auxiliary Modeset Helpers

This helper library contains various one-off functions which don't really fit anywhere else in the DRM modeset helper library.

void drm_helper_move_panel_connectors_to_head(struct drm_device * dev)

move panels to the front in the connector list

Parameters

struct drm_device * dev

drm device to operate on

Description

Some userspace presumes that the first connected connector is the main display, where it's supposed to display e.g. the login screen. For laptops, this should be the main panel. Use this function to sort all (eDP/LVDS/DSI) panels to the front of the connector list, instead of painstakingly trying to initialize them in the right order.

void drm_helper_mode_fill_fb_struct(struct drm_device * dev, struct drm_framebuffer * fb, const struct drm_mode_fb_cmd2 * mode_cmd)

fill out framebuffer metadata

Parameters

struct drm_device * dev

DRM device

struct drm_framebuffer * fb

drm_framebuffer object to fill out

const struct drm_mode_fb_cmd2 * mode_cmd

metadata from the userspace fb creation request

Description

This helper can be used in a drivers fb_create callback to pre-fill the fb's metadata fields.

int drm_crtc_init(struct drm_device * dev, struct drm_crtc * crtc, const struct drm_crtc_funcs * funcs)

Legacy CRTC initialization function

Parameters

struct drm_device * dev

DRM device

struct drm_crtc * crtc

CRTC object to init

const struct drm_crtc_funcs * funcs

callbacks for the new CRTC

Description

Initialize a CRTC object with a default helper-provided primary plane and no cursor plane.

Note that we make some assumptions about hardware limitations that may not be true for all hardware:

1. Primary plane cannot be repositioned.

2. Primary plane cannot be scaled.

3. Primary plane must cover the entire CRTC.

4. Subpixel positioning is not supported.

5. The primary plane must always be on if the CRTC is enabled.

This is purely a backwards compatibility helper for old drivers. Drivers should instead implement their own primary plane. Atomic drivers must do so. Drivers with the above hardware restriction can look into using struct drm_simple_display_pipe, which encapsulates the above limitations into a nice interface.

Return

Zero on success, error code on failure.

int drm_mode_config_helper_suspend(struct drm_device * dev)

Modeset suspend helper

Parameters

struct drm_device * dev

DRM device

Description

This helper function takes care of suspending the modeset side. It disables output polling if initialized, suspends fbdev if used and finally calls drm_atomic_helper_suspend(). If suspending fails, fbdev and polling is re-enabled.

Return

Zero on success, negative error code on error.

See also: drm_kms_helper_poll_disable() and drm_fb_helper_set_suspend_unlocked().

int drm_mode_config_helper_resume(struct drm_device * dev)

Modeset resume helper

Parameters

struct drm_device * dev

DRM device

Description

This helper function takes care of resuming the modeset side. It calls drm_atomic_helper_resume(), resumes fbdev if used and enables output polling if initiaized.

Return

Zero on success, negative error code on error.

See also: drm_fb_helper_set_suspend_unlocked() and drm_kms_helper_poll_enable().

OF/DT Helpers

A set of helper functions to aid DRM drivers in parsing standard DT properties.

uint32_t drm_of_crtc_port_mask(struct drm_device * dev, struct device_node * port)

find the mask of a registered CRTC by port OF node

Parameters

struct drm_device * dev

DRM device

struct device_node * port

port OF node

Description

Given a port OF node, return the possible mask of the corresponding CRTC within a device's list of CRTCs. Returns zero if not found.

uint32_t drm_of_find_possible_crtcs(struct drm_device * dev, struct device_node * port)

find the possible CRTCs for an encoder port

Parameters

struct drm_device * dev

DRM device

struct device_node * port

encoder port to scan for endpoints

Description

Scan all endpoints attached to a port, locate their attached CRTCs, and generate the DRM mask of CRTCs which may be attached to this encoder.

See Documentation/devicetree/bindings/graph.txt for the bindings.

void drm_of_component_match_add(struct device * master, struct component_match ** matchptr, int (*compare) (struct device *, void *, struct device_node * node)

Add a component helper OF node match rule

Parameters

struct device * master

master device

struct component_match ** matchptr

component match pointer

int (*)(struct device *, void *) compare

compare function used for matching component

struct device_node * node

of_node

int drm_of_component_probe(struct device * dev, int (*compare_of) (struct device *, void *, const struct component_master_ops * m_ops)

Generic probe function for a component based master

Parameters

struct device * dev

master device containing the OF node

int (*)(struct device *, void *) compare_of

compare function used for matching components

const struct component_master_ops * m_ops

component master ops to be used

Description

Parse the platform device OF node and bind all the components associated with the master. Interface ports are added before the encoders in order to satisfy their .bind requirements See Documentation/devicetree/bindings/graph.txt for the bindings.

Returns zero if successful, or one of the standard error codes if it fails.

int drm_of_find_panel_or_bridge(const struct device_node * np, int port, int endpoint, struct drm_panel ** panel, struct drm_bridge ** bridge)

return connected panel or bridge device

Parameters

const struct device_node * np

device tree node containing encoder output ports

int port

port in the device tree node

int endpoint

endpoint in the device tree node

struct drm_panel ** panel

pointer to hold returned drm_panel

struct drm_bridge ** bridge

pointer to hold returned drm_bridge

Description

Given a DT node's port and endpoint number, find the connected node and return either the associated struct drm_panel or drm_bridge device. Either panel or bridge must not be NULL.

Returns zero if successful, or one of the standard error codes if it fails.

Legacy Plane Helper Reference

This helper library has two parts. The first part has support to implement primary plane support on top of the normal CRTC configuration interface. Since the legacy drm_mode_config_funcs.set_config interface ties the primary plane together with the CRTC state this does not allow userspace to disable the primary plane itself. The default primary plane only expose XRBG8888 and ARGB8888 as valid pixel formats for the attached framebuffer.

Drivers are highly recommended to implement proper support for primary planes, and newly merged drivers must not rely upon these transitional helpers.

The second part also implements transitional helpers which allow drivers to gradually switch to the atomic helper infrastructure for plane updates. Once that switch is complete drivers shouldn't use these any longer, instead using the proper legacy implementations for update and disable plane hooks provided by the atomic helpers.

Again drivers are strongly urged to switch to the new interfaces.

The plane helpers share the function table structures with other helpers, specifically also the atomic helpers. See struct drm_plane_helper_funcs for the details.

void drm_primary_helper_destroy(struct drm_plane * plane)

Helper for primary plane destruction

Parameters

struct drm_plane * plane

plane to destroy

Description

Provides a default plane destroy handler for primary planes. This handler is called during CRTC destruction. We disable the primary plane, remove it from the DRM plane list, and deallocate the plane structure.

Legacy CRTC/Modeset Helper Functions Reference

The CRTC modeset helper library provides a default set_config implementation in drm_crtc_helper_set_config(). Plus a few other convenience functions using the same callbacks which drivers can use to e.g. restore the modeset configuration on resume with drm_helper_resume_force_mode().

Note that this helper library doesn't track the current power state of CRTCs and encoders. It can call callbacks like drm_encoder_helper_funcs.dpms even though the hardware is already in the desired state. This deficiency has been fixed in the atomic helpers.

The driver callbacks are mostly compatible with the atomic modeset helpers, except for the handling of the primary plane: Atomic helpers require that the primary plane is implemented as a real standalone plane and not directly tied to the CRTC state. For easier transition this library provides functions to implement the old semantics required by the CRTC helpers using the new plane and atomic helper callbacks.

Drivers are strongly urged to convert to the atomic helpers (by way of first converting to the plane helpers). New drivers must not use these functions but need to implement the atomic interface instead, potentially using the atomic helpers for that.

These legacy modeset helpers use the same function table structures as all other modesetting helpers. See the documentation for struct drm_crtc_helper_funcs, struct drm_encoder_helper_funcs and struct drm_connector_helper_funcs.

bool drm_helper_encoder_in_use(struct drm_encoder * encoder)

check if a given encoder is in use

Parameters

struct drm_encoder * encoder

encoder to check

Description

Checks whether encoder is with the current mode setting output configuration in use by any connector. This doesn't mean that it is actually enabled since the DPMS state is tracked separately.

Return

True if encoder is used, false otherwise.

bool drm_helper_crtc_in_use(struct drm_crtc * crtc)

check if a given CRTC is in a mode_config

Parameters

struct drm_crtc * crtc

CRTC to check

Description

Checks whether crtc is with the current mode setting output configuration in use by any connector. This doesn't mean that it is actually enabled since the DPMS state is tracked separately.

Return

True if crtc is used, false otherwise.

void drm_helper_disable_unused_functions(struct drm_device * dev)

disable unused objects

Parameters

struct drm_device * dev

DRM device

Description

This function walks through the entire mode setting configuration of dev. It will remove any CRTC links of unused encoders and encoder links of disconnected connectors. Then it will disable all unused encoders and CRTCs either by calling their disable callback if available or by calling their dpms callback with DRM_MODE_DPMS_OFF.

NOTE

This function is part of the legacy modeset helper library and will cause major confusion with atomic drivers. This is because atomic helpers guarantee to never call ->disable() hooks on a disabled function, or ->enable() hooks on an enabled functions. drm_helper_disable_unused_functions() on the other hand throws such guarantees into the wind and calls disable hooks unconditionally on unused functions.

bool drm_crtc_helper_set_mode(struct drm_crtc * crtc, struct drm_display_mode * mode, int x, int y, struct drm_framebuffer * old_fb)

internal helper to set a mode

Parameters

struct drm_crtc * crtc

CRTC to program

struct drm_display_mode * mode

mode to use

int x

horizontal offset into the surface

int y

vertical offset into the surface

struct drm_framebuffer * old_fb

old framebuffer, for cleanup

Description

Try to set mode on crtc. Give crtc and its associated connectors a chance to fixup or reject the mode prior to trying to set it. This is an internal helper that drivers could e.g. use to update properties that require the entire output pipe to be disabled and re-enabled in a new configuration. For example for changing whether audio is enabled on a hdmi link or for changing panel fitter or dither attributes. It is also called by the drm_crtc_helper_set_config() helper function to drive the mode setting sequence.

Return

True if the mode was set successfully, false otherwise.

int drm_crtc_helper_set_config(struct drm_mode_set * set, struct drm_modeset_acquire_ctx * ctx)

set a new config from userspace

Parameters

struct drm_mode_set * set

mode set configuration

struct drm_modeset_acquire_ctx * ctx

lock acquire context, not used here

Description

The drm_crtc_helper_set_config() helper function implements the of drm_crtc_funcs.set_config callback for drivers using the legacy CRTC helpers.

It first tries to locate the best encoder for each connector by calling the connector drm_connector_helper_funcs.best_encoder helper operation.

After locating the appropriate encoders, the helper function will call the mode_fixup encoder and CRTC helper operations to adjust the requested mode, or reject it completely in which case an error will be returned to the application. If the new configuration after mode adjustment is identical to the current configuration the helper function will return without performing any other operation.

If the adjusted mode is identical to the current mode but changes to the frame buffer need to be applied, the drm_crtc_helper_set_config() function will call the CRTC drm_crtc_helper_funcs.mode_set_base helper operation.

If the adjusted mode differs from the current mode, or if the ->mode_set_base() helper operation is not provided, the helper function performs a full mode set sequence by calling the ->prepare(), ->mode_set() and ->commit() CRTC and encoder helper operations, in that order. Alternatively it can also use the dpms and disable helper operations. For details see struct drm_crtc_helper_funcs and struct drm_encoder_helper_funcs.

This function is deprecated. New drivers must implement atomic modeset support, for which this function is unsuitable. Instead drivers should use drm_atomic_helper_set_config().

Return

Returns 0 on success, negative errno numbers on failure.

int drm_helper_connector_dpms(struct drm_connector * connector, int mode)

connector dpms helper implementation

Parameters

struct drm_connector * connector

affected connector

int mode

DPMS mode

Description

The drm_helper_connector_dpms() helper function implements the drm_connector_funcs.dpms callback for drivers using the legacy CRTC helpers.

This is the main helper function provided by the CRTC helper framework for implementing the DPMS connector attribute. It computes the new desired DPMS state for all encoders and CRTCs in the output mesh and calls the drm_crtc_helper_funcs.dpms and drm_encoder_helper_funcs.dpms callbacks provided by the driver.

This function is deprecated. New drivers must implement atomic modeset support, where DPMS is handled in the DRM core.

Return

Always returns 0.

void drm_helper_resume_force_mode(struct drm_device * dev)

force-restore mode setting configuration

Parameters

struct drm_device * dev

drm_device which should be restored

Description

Drivers which use the mode setting helpers can use this function to force-restore the mode setting configuration e.g. on resume or when something else might have trampled over the hw state (like some overzealous old BIOSen tended to do).

This helper doesn't provide a error return value since restoring the old config should never fail due to resource allocation issues since the driver has successfully set the restored configuration already. Hence this should boil down to the equivalent of a few dpms on calls, which also don't provide an error code.

Drivers where simply restoring an old configuration again might fail (e.g. due to slight differences in allocating shared resources when the configuration is restored in a different order than when userspace set it up) need to use their own restore logic.

This function is deprecated. New drivers should implement atomic mode- setting and use the atomic suspend/resume helpers.

See also: drm_atomic_helper_suspend(), drm_atomic_helper_resume()

int drm_helper_force_disable_all(struct drm_device * dev)

Forcibly turn off all enabled CRTCs

Parameters

struct drm_device * dev

DRM device whose CRTCs to turn off

Description

Drivers may want to call this on unload to ensure that all displays are unlit and the GPU is in a consistent, low power state. Takes modeset locks.

Note

This should only be used by non-atomic legacy drivers. For an atomic version look at drm_atomic_helper_shutdown().

Return

Zero on success, error code on failure.

SHMEM GEM Helper Reference

This library provides helpers for GEM objects backed by shmem buffers allocated using anonymous pageable memory.

struct drm_gem_shmem_object

GEM object backed by shmem

Definition

struct drm_gem_shmem_object {
  struct drm_gem_object base;
  struct mutex pages_lock;
  struct page **pages;
  unsigned int pages_use_count;
  int madv;
  struct list_head madv_list;
  unsigned int pages_mark_dirty_on_put    : 1;
  unsigned int pages_mark_accessed_on_put : 1;
  struct sg_table *sgt;
  struct mutex vmap_lock;
  void *vaddr;
  unsigned int vmap_use_count;
};

Members

base

Base GEM object

pages_lock

Protects the page table and use count

pages

Page table

pages_use_count

Reference count on the pages table. The pages are put when the count reaches zero.

pages_mark_dirty_on_put

Mark pages as dirty when they are put.

pages_mark_accessed_on_put

Mark pages as accessed when they are put.

sgt

Scatter/gather table for imported PRIME buffers

vmap_lock

Protects the vmap address and use count

vaddr

Kernel virtual address of the backing memory

vmap_use_count

Reference count on the virtual address. The address are un-mapped when the count reaches zero.

DEFINE_DRM_GEM_SHMEM_FOPS(name)

Macro to generate file operations for shmem drivers

Parameters

name

name for the generated structure

Description

This macro autogenerates a suitable struct file_operations for shmem based drivers, which can be assigned to drm_driver.fops. Note that this structure cannot be shared between drivers, because it contains a reference to the current module using THIS_MODULE.

Note that the declaration is already marked as static - if you need a non-static version of this you're probably doing it wrong and will break the THIS_MODULE reference by accident.

DRM_GEM_SHMEM_DRIVER_OPS()

Default shmem GEM operations

Parameters

Description

This macro provides a shortcut for setting the shmem GEM operations in the drm_driver structure.

struct drm_gem_shmem_object * drm_gem_shmem_create(struct drm_device * dev, size_t size)

Allocate an object with the given size

Parameters

struct drm_device * dev

DRM device

size_t size

Size of the object to allocate

Description

This function creates a shmem GEM object.

Return

A struct drm_gem_shmem_object * on success or an ERR_PTR()-encoded negative error code on failure.

void drm_gem_shmem_free_object(struct drm_gem_object * obj)

Free resources associated with a shmem GEM object

Parameters

struct drm_gem_object * obj

GEM object to free

Description

This function cleans up the GEM object state and frees the memory used to store the object itself.

int drm_gem_shmem_pin(struct drm_gem_object * obj)

Pin backing pages for a shmem GEM object

Parameters

struct drm_gem_object * obj

GEM object

Description

This function makes sure the backing pages are pinned in memory while the buffer is exported.

Return

0 on success or a negative error code on failure.

void drm_gem_shmem_unpin(struct drm_gem_object * obj)

Unpin backing pages for a shmem GEM object

Parameters

struct drm_gem_object * obj

GEM object

Description

This function removes the requirement that the backing pages are pinned in memory.

int drm_gem_shmem_dumb_create(struct drm_file * file, struct drm_device * dev, struct drm_mode_create_dumb * args)

Create a dumb shmem buffer object

Parameters

struct drm_file * file

DRM file structure to create the dumb buffer for

struct drm_device * dev

DRM device

struct drm_mode_create_dumb * args

IOCTL data

Description

This function computes the pitch of the dumb buffer and rounds it up to an integer number of bytes per pixel. Drivers for hardware that doesn't have any additional restrictions on the pitch can directly use this function as their drm_driver.dumb_create callback.

For hardware with additional restrictions, drivers can adjust the fields set up by userspace before calling into this function.

Return

0 on success or a negative error code on failure.

int drm_gem_shmem_mmap(struct file * filp, struct vm_area_struct * vma)

Memory-map a shmem GEM object

Parameters

struct file * filp

File object

struct vm_area_struct * vma

VMA for the area to be mapped

Description

This function implements an augmented version of the GEM DRM file mmap operation for shmem objects. Drivers which employ the shmem helpers should use this function as their file_operations.mmap handler in the DRM device file's file_operations structure.

Instead of directly referencing this function, drivers should use the DEFINE_DRM_GEM_SHMEM_FOPS() macro.

Return

0 on success or a negative error code on failure.

void drm_gem_shmem_print_info(struct drm_printer * p, unsigned int indent, const struct drm_gem_object * obj)

Print drm_gem_shmem_object info for debugfs

Parameters

struct drm_printer * p

DRM printer

unsigned int indent

Tab indentation level

const struct drm_gem_object * obj

GEM object

struct sg_table * drm_gem_shmem_get_sg_table(struct drm_gem_object * obj)

Provide a scatter/gather table of pinned pages for a shmem GEM object

Parameters

struct drm_gem_object * obj

GEM object

Description

This function exports a scatter/gather table suitable for PRIME usage by calling the standard DMA mapping API.

Return

A pointer to the scatter/gather table of pinned pages or NULL on failure.

struct sg_table * drm_gem_shmem_get_pages_sgt(struct drm_gem_object * obj)

Pin pages, dma map them, and return a scatter/gather table for a shmem GEM object.

Parameters

struct drm_gem_object * obj

GEM object

Description

This function returns a scatter/gather table suitable for driver usage. If the sg table doesn't exist, the pages are pinned, dma-mapped, and a sg table created.

Return

A pointer to the scatter/gather table of pinned pages or errno on failure.

struct drm_gem_object * drm_gem_shmem_prime_import_sg_table(struct drm_device * dev, struct dma_buf_attachment * attach, struct sg_table * sgt)

Produce a shmem GEM object from another driver's scatter/gather table of pinned pages

Parameters

struct drm_device * dev

Device to import into

struct dma_buf_attachment * attach

DMA-BUF attachment

struct sg_table * sgt

Scatter/gather table of pinned pages

Description

This function imports a scatter/gather table exported via DMA-BUF by another driver. Drivers that use the shmem helpers should set this as their drm_driver.gem_prime_import_sg_table callback.

Return

A pointer to a newly created GEM object or an ERR_PTR-encoded negative error code on failure.