Mode Setting Helper Functions
Prev | Chapter 2. DRM Internals | Next

## Mode Setting Helper Functions

The plane, CRTC, encoder and connector functions provided by the drivers implement the DRM API. They're called by the DRM core and ioctl handlers to handle device state changes and configuration request. As implementing those functions often requires logic not specific to drivers, mid-layer helper functions are available to avoid duplicating boilerplate code.

The DRM core contains one mid-layer implementation. The mid-layer provides implementations of several plane, CRTC, encoder and connector functions (called from the top of the mid-layer) that pre-process requests and call lower-level functions provided by the driver (at the bottom of the mid-layer). For instance, the `drm_crtc_helper_set_config` function can be used to fill the struct drm_crtc_funcs `set_config` field. When called, it will split the `set_config` operation in smaller, simpler operations and call the driver to handle them.

To use the mid-layer, drivers call `drm_crtc_helper_add`, `drm_encoder_helper_add` and `drm_connector_helper_add` functions to install their mid-layer bottom operations handlers, and fill the drm_crtc_funcs, drm_encoder_funcs and drm_connector_funcs structures with pointers to the mid-layer top API functions. Installing the mid-layer bottom operation handlers is best done right after registering the corresponding KMS object.

The mid-layer is not split between CRTC, encoder and connector operations. To use it, a driver must provide bottom functions for all of the three KMS entities.

### Helper Functions

-     int drm_crtc_helper_set_config(struct drm_mode_set *set);

  The `drm_crtc_helper_set_config` helper function is a CRTC `set_config` implementation. It first tries to locate the best encoder for each connector by calling the connector `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 `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.

-     void drm_helper_connector_dpms(struct drm_connector *connector, int mode);

  The `drm_helper_connector_dpms` helper function is a connector `dpms` implementation that tracks power state of connectors. To use the function, drivers must provide `dpms` helper operations for CRTCs and encoders to apply the DPMS state to the device.

  The mid-layer doesn't track the power state of CRTCs and encoders. The `dpms` helper operations can thus be called with a mode identical to the currently active mode.

-     int drm_helper_probe_single_connector_modes(struct drm_connector *connector,
                                                  uint32_t maxX, uint32_t maxY);

  The `drm_helper_probe_single_connector_modes` helper function is a connector `fill_modes` implementation that updates the connection status for the connector and then retrieves a list of modes by calling the connector `get_modes` helper operation.

  If the helper operation returns no mode, and if the connector status is connector_status_connected, standard VESA DMT modes up to 1024x768 are automatically added to the modes list by a call to `drm_add_modes_noedid`.

  The function then filters out modes larger than `max_width` and `max_height` if specified. It finally calls the optional connector `mode_valid` helper operation for each mode in the probed list to check whether the mode is valid for the connector.

### CRTC Helper Operations

-     bool (*mode_fixup)(struct drm_crtc *crtc,
                             const struct drm_display_mode *mode,
                             struct drm_display_mode *adjusted_mode);

  Let CRTCs adjust the requested mode or reject it completely. This operation returns true if the mode is accepted (possibly after being adjusted) or false if it is rejected.

  The `mode_fixup` operation should reject the mode if it can't reasonably use it. The definition of "reasonable" is currently fuzzy in this context. One possible behaviour would be to set the adjusted mode to the panel timings when a fixed-mode panel is used with hardware capable of scaling. Another behaviour would be to accept any input mode and adjust it to the closest mode supported by the hardware (FIXME: This needs to be clarified).

-     int (*mode_set_base)(struct drm_crtc *crtc, int x, int y,
                           struct drm_framebuffer *old_fb)

  Move the CRTC on the current frame buffer (stored in `crtc->fb`) to position (x,y). Any of the frame buffer, x position or y position may have been modified.

  This helper operation is optional. If not provided, the `drm_crtc_helper_set_config` function will fall back to the `mode_set` helper operation.

  ### Note

  FIXME: Why are x and y passed as arguments, as they can be accessed through `crtc->x` and `crtc->y`?

-     void (*prepare)(struct drm_crtc *crtc);

  Prepare the CRTC for mode setting. This operation is called after validating the requested mode. Drivers use it to perform device-specific operations required before setting the new 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);

  Set a new mode, position and frame buffer. Depending on the device requirements, the mode can be stored internally by the driver and applied in the `commit` operation, or programmed to the hardware immediately.

  The `mode_set` operation returns 0 on success or a negative error code if an error occurs.

-     void (*commit)(struct drm_crtc *crtc);

  Commit a mode. This operation is called after setting the new mode. Upon return the device must use the new mode and be fully operational.

### Encoder Helper Operations

-     bool (*mode_fixup)(struct drm_encoder *encoder,
                             const struct drm_display_mode *mode,
                             struct drm_display_mode *adjusted_mode);

  Let encoders adjust the requested mode or reject it completely. This operation returns true if the mode is accepted (possibly after being adjusted) or false if it is rejected. See the mode_fixup CRTC helper operation for an explanation of the allowed adjustments.

-     void (*prepare)(struct drm_encoder *encoder);

  Prepare the encoder for mode setting. This operation is called after validating the requested mode. Drivers use it to perform device-specific operations required before setting the new mode.

-     void (*mode_set)(struct drm_encoder *encoder,
                       struct drm_display_mode *mode,
                       struct drm_display_mode *adjusted_mode);

  Set a new mode. Depending on the device requirements, the mode can be stored internally by the driver and applied in the `commit` operation, or programmed to the hardware immediately.

-     void (*commit)(struct drm_encoder *encoder);

  Commit a mode. This operation is called after setting the new mode. Upon return the device must use the new mode and be fully operational.

### Connector Helper Operations

-     struct drm_encoder *(*best_encoder)(struct drm_connector *connector);

  Return a pointer to the best encoder for the connecter. Device that map connectors to encoders 1:1 simply return the pointer to the associated encoder. This operation is mandatory.

-     int (*get_modes)(struct drm_connector *connector);

  Fill the connector's `probed_modes` list by parsing EDID data with `drm_add_edid_modes`, adding standard VESA DMT modes with `drm_add_modes_noedid`, or calling `drm_mode_probed_add` directly for every supported mode and return the number of modes it has detected. This operation is mandatory.

  Note that the caller function will automatically add standard VESA DMT modes up to 1024x768 if the `get_modes` helper operation returns no mode and if the connector status is connector_status_connected. There is no need to call `drm_add_edid_modes` manually in that case.

  When adding modes manually the driver creates each mode with a call to `drm_mode_create` and must fill the following fields.

  -     __u32 type;

    Mode type bitmask, a combination of

    DRM_MODE_TYPE_BUILTIN

      not used?

    DRM_MODE_TYPE_CLOCK_C

      not used?

    DRM_MODE_TYPE_CRTC_C

      not used?

    DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector

      not used?

    DRM_MODE_TYPE_DEFAULT

      not used?

    DRM_MODE_TYPE_USERDEF

      not used?

    DRM_MODE_TYPE_DRIVER

      The mode has been created by the driver (as opposed to to user-created modes).

    Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they create, and set the DRM_MODE_TYPE_PREFERRED bit for the preferred mode.

  -     __u32 clock;

    Pixel clock frequency in kHz unit

  -     __u16 hdisplay, hsync_start, hsync_end, htotal;
            __u16 vdisplay, vsync_start, vsync_end, vtotal;

    Horizontal and vertical timing information

                     Active                 Front           Sync           Back
                     Region                 Porch                          Porch
            <-----------------------><----------------><-------------><-------------->

              //////////////////////|
             ////////////////////// |
            //////////////////////  |..................               ................
                                                       _______________

            <----- [hv]display ----->
            <------------- [hv]sync_start ------------>
            <--------------------- [hv]sync_end --------------------->
            <-------------------------------- [hv]total ----------------------------->

  -     __u16 hskew;
            __u16 vscan;

    Unknown

  -     __u32 flags;

    Mode flags, a combination of

    DRM_MODE_FLAG_PHSYNC

      Horizontal sync is active high

    DRM_MODE_FLAG_NHSYNC

      Horizontal sync is active low

    DRM_MODE_FLAG_PVSYNC

      Vertical sync is active high

    DRM_MODE_FLAG_NVSYNC

      Vertical sync is active low

    DRM_MODE_FLAG_INTERLACE

      Mode is interlaced

    DRM_MODE_FLAG_DBLSCAN

      Mode uses doublescan

    DRM_MODE_FLAG_CSYNC

      Mode uses composite sync

    DRM_MODE_FLAG_PCSYNC

      Composite sync is active high

    DRM_MODE_FLAG_NCSYNC

      Composite sync is active low

    DRM_MODE_FLAG_HSKEW

      hskew provided (not used?)

    DRM_MODE_FLAG_BCAST

      not used?

    DRM_MODE_FLAG_PIXMUX

      not used?

    DRM_MODE_FLAG_DBLCLK

      not used?

    DRM_MODE_FLAG_CLKDIV2

      ?

    Note that modes marked with the INTERLACE or DBLSCAN flags will be filtered out by `drm_helper_probe_single_connector_modes` if the connector's `interlace_allowed` or `doublescan_allowed` field is set to 0.

  -     char name[DRM_DISPLAY_MODE_LEN];

    Mode name. The driver must call `drm_mode_set_name` to fill the mode name from `hdisplay`, `vdisplay` and interlace flag after filling the corresponding fields.

  The `vrefresh` value is computed by `drm_helper_probe_single_connector_modes`.

  When parsing EDID data, `drm_add_edid_modes` fills the connector `display_info` `width_mm` and `height_mm` fields. When creating modes manually the `get_modes` helper operation must set the `display_info` `width_mm` and `height_mm` fields if they haven't been set already (for instance at initialization time when a fixed-size panel is attached to the connector). The mode `width_mm` and `height_mm` fields are only used internally during EDID parsing and should not be set when creating modes manually.

-     int (*mode_valid)(struct drm_connector *connector,
      		  struct drm_display_mode *mode);

  Verify whether a mode is valid for the connector. Return MODE_OK for supported modes and one of the enum drm_mode_status values (MODE_*) for unsupported modes. This operation is optional.

  As the mode rejection reason is currently not used beside for immediately removing the unsupported mode, an implementation can return MODE_BAD regardless of the exact reason why the mode is not valid.

  ### Note

  Note that the `mode_valid` helper operation is only called for modes detected by the device, and not for modes set by the user through the CRTC `set_config` operation.

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

#### Implementing Asynchronous Atomic Commit

For now the atomic helpers don't support async commit directly. If there is real need it could be added though, using the dma-buf fence infrastructure for generic synchronization with outstanding rendering.

For now drivers have to implement async commit themselves, with the following sequence being the recommended one:

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

For sufficient parallelism it is recommended to have a work item per crtc (for updates which don't touch global state) and a global one. Then we only need to synchronize with the crtc work items for changed crtcs and the global work item, which allows nice concurrent updates on disjoint sets of crtcs.

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 async worker runs means that async 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.

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

### 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`.

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.

### Output Probing Helper Functions Reference

This library provides some helper code for output probing. It provides an implementation of the core connector->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.

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

Initialization is done as a four-step process with `drm_fb_helper_prepare`, `drm_fb_helper_init`, `drm_fb_helper_single_add_all_connectors` and `drm_fb_helper_initial_config`. Drivers with fancier requirements than the default behaviour can override the third step with their own code. Teardown is done with `drm_fb_helper_fini`.

At runtime drivers should restore the fbdev console by calling `drm_fb_helper_restore_fbdev_mode_unlocked` from their ->lastclose callback. They should also notify the fb helper code from updates to the output configuration by calling `drm_fb_helper_hotplug_event`. For easier integration with the output polling code in drm_crtc_helper.c the modeset code provides a ->output_poll_changed callback.

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 dev->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_single_add_all_connectors` followed by `drm_fb_helper_initial_config`.

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

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

### Display Port MST Helper Functions Reference

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.

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

### EDID Helper Functions Reference

### Rectangle Utilities Reference

Utility functions to help manage rectangular areas for clipping, scaling, etc. calculations.

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

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

### 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 ->set_config interface ties the primary plane together with the CRTC state this does not allow userspace to disable the primary plane itself. To avoid too much duplicated code use `drm_plane_helper_check_update` which can be used to enforce the same restrictions as primary planes had thus. 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.

### Tile group

Tile groups are used to represent tiled monitors with a unique integer identifier. Tiled monitors using DisplayID v1.3 have a unique 8-byte handle, we store this in a tile group, so we have a common identifier for all tiles in a monitor group.

### Bridges

#### Overview

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 associated 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. They just provide additional hooks to get the desired output at the end of the encoder chain.

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

When creating a bridge driver, one can implement drm_bridge_funcs op with the help of these rough rules:

pre_enable: this contains things needed to be done for the bridge before its clock and timings are enabled by its source. For a bridge, its source is generally the encoder or bridge just before it in the encoder chain.

enable: this contains things needed to be done for the bridge once its source is enabled. In other words, enable is called once the source is ready with clock and timing needed by the bridge.

disable: this contains things needed to be done for the bridge assuming that its source is still enabled, i.e. clock and timings are still on.

post_disable: this contains things needed to be done for the bridge once its source is disabled, i.e. once clocks and timings are off.

mode_fixup: this should fixup the given mode for the bridge. It is called after the encoder's mode fixup. mode_fixup can also reject a mode completely if it's unsuitable for the hardware.

mode_set: this sets up the mode for the bridge. It assumes that its source (an encoder or a bridge) has set the mode too.

Prev | Up | Next
drm_modeset_lock_all_ctx | Home | drm_atomic_crtc_for_each_plane