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 struct drm_crtc_funcs, struct drm_encoder_funcs and struct 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.

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

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.

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 (for ->:c:func: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) ->:c:func: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) ->:c:func: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.

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 and calls down into ->mode_fixup functions of the driver backend.

crtc_state->mode_changed is set when the input mode is changed. crtc_state->connectors_changed is set when a connector is added or removed from the crtc. crtc_state->active_changed is set when crtc_state->active changes, which is used for dpms.

IMPORTANT:

Drivers which update ->mode_changed (e.g. in their ->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 ->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_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 ->atomic_check hooks provided by the driver.

It also sets 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 ->:c:func: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 ->atomic_check functions depend upon an updated adjusted_mode.clock to e.g. properly compute watermarks.

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.

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.

void drm_atomic_helper_wait_for_fences(struct drm_device * dev, struct drm_atomic_state * state)¶: 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

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)

bool drm_atomic_helper_framebuffer_changed(struct drm_device * dev, struct drm_atomic_state * old_state, struct drm_crtc * crtc)¶: check if framebuffer has changed

Parameters

struct drm_device * dev: DRM device
struct drm_atomic_state * old_state: atomic state object with old state structures
struct drm_crtc * crtc: DRM crtc

Description

Checks whether the framebuffer used for this CRTC changes as a result of the atomic update. This is useful for drivers which cannot use drm_atomic_helper_wait_for_vblanks() and need to reimplement its functionality.

Return

true if the framebuffer changed.

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.

void drm_atomic_helper_commit_tail(struct drm_atomic_state * state)¶: commit atomic update to hardware

Parameters

struct drm_atomic_state * state: new modeset state to be committed

Description

This is the default implemenation for the ->:c:func:atomic_commit_tail() hook of the drm_mode_config_helper_funcs vtable.

Note that the default ordering of how the various stages are called is to match the legacy modeset helper library closest. One peculiarity of that is that it doesn’t mesh well with runtime PM at all.

For drivers supporting runtime PM the recommended sequence is instead

drm_atomic_helper_commit_modeset_disables(dev, state);

drm_atomic_helper_commit_modeset_enables(dev, state);

drm_atomic_helper_commit_planes(dev, state, true);

for committing the atomic update to hardware. See the kerneldoc entries for these three functions for more details.

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.

Note that right now this function does not support nonblocking commits, hence driver writers must implement their own version for now.

Committing the actual hardware state is done through the ->:c:func:atomic_commit_tail() callback of the drm_mode_config_helper_funcs vtable, or it’s 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 ->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 it’s stall parameter, for when a driver’s commit hooks look at the ->state pointers of struct drm_crtc, drm_plane or drm_connector 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 esay-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 * state)¶: wait for required preceeding commits

Parameters

struct drm_atomic_state * state: new modeset state to be committed

Description

This function waits for all preceeding commits that touch the same CRTC as 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_vblank_send_event on the event member of drm_crtc_state).

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 * state)¶: setup possible nonblocking commit

Parameters

struct drm_atomic_state * state: new modeset state to be committed

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 * state)¶: signal completion of commit

Parameters

struct drm_atomic_state * state: new modeset state to be committed

Description

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

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. If any failure is encountered this function will call ->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, bool active_only)¶: commit plane state

Parameters

struct drm_device * dev: DRM device
struct drm_atomic_state * old_state: atomic state object with old state structures
bool active_only: Only commit on active CRTC if set

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 parameters to true 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.

The drm_atomic_helper_commit() default implementation only sets active_only to false 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 * crtc, bool atomic)¶: helper to disable CRTC’s planes

Parameters

struct drm_crtc * crtc: CRTC
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 disable callback to disable all planes before shutting down the display pipeline.

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 ->:c:func: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().

void 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 proceeding 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 swaped into state.

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

Call drm_atomic_helper_prepare_planes() with the staged atomic state.
Do any other steps that might fail.
Put the staged state into the current state pointers with this function.
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 ->state pointer of drm_plane, drm_crtc or drm_connector. With the current atomic helpers this is almost always the case, since the helpers don’t pass the right state structures to the callbacks.

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)¶: 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

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)¶: Helper for primary plane disable using * atomic

Parameters

struct drm_plane * plane: plane to disable

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)¶: set a new config from userspace

Parameters

struct drm_mode_set * set: mode set configuration

Description

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

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.

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.

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.

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.

Modeset Helper Reference for Common Vtables¶

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);
  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 (* load_lut) (struct drm_crtc *crtc);
  void (* disable) (struct drm_crtc *crtc);
  void (* enable) (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);
};

Members

void (*)(struct drm_crtc *crtc, int mode) 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 enable and disable should be used.

void (*)(struct drm_crtc *crtc) 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 disable should be used.

void (*)(struct drm_crtc *crtc) 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 enable should be used.

bool (*)(struct drm_crtc *crtc,const struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode) 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 ->:c:func:mode_fixup() functions. If the CRTC cannot support the requested conversion from mode to adjusted_mode it should reject the modeset.

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.

Also beware that neither core nor helpers filter modes before passing them to the driver: While the list of modes that is advertised to userspace is filtered using the connector’s ->:c:func:mode_valid() callback, neither the core nor the helpers do any filtering on modes passed in from userspace when setting a mode. It is therefore possible for userspace to pass in a mode that was previously filtered out using ->:c:func:mode_valid() or add a custom mode that wasn’t probed from EDID or similar to begin with. Even though this is an advanced feature and rarely used nowadays, some users rely on being able to specify modes manually so drivers must be prepared to deal with it. Specifically this means that all drivers need not only validate modes in ->:c:func:mode_valid() but also in ->:c:func:mode_fixup() to make sure invalid modes passed in from userspace are rejected.

RETURNS:

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

int (*)(struct drm_crtc *crtc, struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode, int x, int y,struct drm_framebuffer *old_fb) 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.

void (*)(struct drm_crtc *crtc) 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 enable callback.

This callback is optional.

int (*)(struct drm_crtc *crtc, int x, int y,struct drm_framebuffer *old_fb) 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 ->:c:func: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.

int (*)(struct drm_crtc *crtc,struct drm_framebuffer *fb, int x, int y,enum mode_set_atomic) 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.

void (*)(struct drm_crtc *crtc) load_lut

Load a LUT prepared with the gamma_set functions from drm_fb_helper_funcs.

This callback is optional and is only used by the fbdev emulation helpers.

FIXME:

This callback is functionally redundant with the core gamma table support and simply exists because the fbdev hasn’t yet been refactored to use the core gamma table interfaces.

void (*)(struct drm_crtc *crtc) 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 ->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 enable for atomic drivers.

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.

void (*)(struct drm_crtc *crtc) 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 ->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 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 enable must be the inverse of disable for atomic drivers.

int (*)(struct drm_crtc *crtc,struct drm_crtc_state *state) 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() CRTCs’ ->:c:func:atomic_check() hooks are called after the ones for planes, which allows drivers to assign shared resources requested by planes in the CRTC 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:c:type: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.

void (*)(struct drm_crtc *crtc,struct drm_crtc_state *old_crtc_state) 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_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.

void (*)(struct drm_crtc *crtc,struct drm_crtc_state *old_crtc_state) 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_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.

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);
  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);
  struct drm_crtc *(* get_crtc) (struct drm_encoder *encoder);
  enum drm_connector_status (* detect) (struct drm_encoder *encoder,struct drm_connector *connector);
  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

void (*)(struct drm_encoder *encoder, int mode) 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.

bool (*)(struct drm_encoder *encoder,const struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode) 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.

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.

Also beware that neither core nor helpers filter modes before passing them to the driver: While the list of modes that is advertised to userspace is filtered using the connector’s ->:c:func:mode_valid() callback, neither the core nor the helpers do any filtering on modes passed in from userspace when setting a mode. It is therefore possible for userspace to pass in a mode that was previously filtered out using ->:c:func:mode_valid() or add a custom mode that wasn’t probed from EDID or similar to begin with. Even though this is an advanced feature and rarely used nowadays, some users rely on being able to specify modes manually so drivers must be prepared to deal with it. Specifically this means that all drivers need not only validate modes in ->:c:func:mode_valid() but also in ->:c:func:mode_fixup() to make sure invalid modes passed in from userspace are rejected.

RETURNS:

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

void (*)(struct drm_encoder *encoder) 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.

void (*)(struct drm_encoder *encoder) 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.

void (*)(struct drm_encoder *encoder,struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode) 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 ->:c:func:enable() callback.

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

struct drm_crtc *(*)(struct drm_encoder *encoder) 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.

enum drm_connector_status (*)(struct drm_encoder *encoder,struct drm_connector *connector) 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.

void (*)(struct drm_encoder *encoder) 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 the CRTC’s own ->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.

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.

void (*)(struct drm_encoder *encoder) 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 the CRTC’s own ->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 used only by atomic helpers, for symmetry with 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.

int (*)(struct drm_encoder *encoder,struct drm_crtc_state *crtc_state,struct drm_connector_state *conn_state) 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.

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.

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

Members

int (*)(struct drm_connector *connector) get_modes

This function should fill in all modes currently valid for the sink into the connector->probed_modes list. It should also update the EDID property by calling drm_mode_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 display_info, width_mm and height_mm fields of the struct drm_connector 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().

Finally drivers that support audio probably want to update the ELD data, too, using drm_edid_to_eld().

This function is only called after the ->:c:func: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().

RETURNS:

The number of modes added by calling drm_mode_probed_add().

enum drm_mode_status (*)(struct drm_connector *connector,struct drm_display_mode *mode) 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().

NOTE:

This only filters the mode list supplied to userspace in the GETCONNECOTR IOCTL. Userspace is free to create modes of its own and ask the kernel to use them. It this case the atomic helpers or legacy CRTC helpers will not call this function. Drivers therefore must still fully validate any mode passed in in a modeset request.

RETURNS:

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

struct drm_encoder *(*)(struct drm_connector *connector) 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.

struct drm_encoder *(*)(struct drm_connector *connector,struct drm_connector_state *connector_state) 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.

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,const struct drm_plane_state *new_state);
  void (* cleanup_fb) (struct drm_plane *plane,const 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);
};

Members

int (*)(struct drm_plane *plane,const struct drm_plane_state *new_state) prepare_fb

This hook is to prepare a framebuffer for scanout by e.g. pinning it’s 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 fence member 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.

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 atomic_commit hook in drm_mode_config_funcs. When using helpers this callback is the only one which can fail an atomic commit, everything else must complete successfully.

void (*)(struct drm_plane *plane,const struct drm_plane_state *old_state) 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.

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

Drivers should check plane specific constraints in this hook.

When using drm_atomic_helper_check_planes() plane’s ->:c:func: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:c:type: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.

void (*)(struct drm_plane *plane,struct drm_plane_state *old_state) atomic_update

Drivers should use this function to update the plane state. This hook is called in-between the ->:c:func:atomic_begin() and ->:c:func:atomic_flush() of drm_crtc_helper_funcs.

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

void (*)(struct drm_plane *plane,struct drm_plane_state *old_state) atomic_disable

Drivers should use this function to unconditionally disable a plane. This hook is called in-between the ->:c:func:atomic_begin() and ->:c:func:atomic_flush() of drm_crtc_helper_funcs. 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 ->:c:func:disable() hook in drm_crtc_helper_funcs.

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

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

void (*)(struct drm_atomic_state *state) 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 hook should first commit the given atomic state to the hardware. 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(), 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.

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.

Legacy CRTC/Modeset Helper Functions Reference¶

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) panels to the front of the connector list, instead of painstakingly trying to initialize them in the right order.

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 ->:c:func:disable() hooks on a disabled function, or ->:c:func: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)¶: set a new config from userspace

Parameters

struct drm_mode_set * set: mode set configuration

Description

The drm_crtc_helper_set_config() helper function implements the set_config callback of struct drm_crtc_funcs for drivers using the legacy CRTC helpers.

It first tries to locate the best encoder for each connector by calling the connector ->:c:func:best_encoder() (struct drm_connector_helper_funcs) 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 ->:c:func:mode_set_base() (struct drm_crtc_helper_funcs) helper operation.

If the adjusted mode differs from the current mode, or if the ->:c:func:mode_set_base() helper operation is not provided, the helper function performs a full mode set sequence by calling the ->:c:func:prepare(), ->:c:func:mode_set() and ->:c:func: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 ->:c:func:dpms() callback of struct drm_connector_funcs 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 ->:c:func:dpms() callbacks provided by the driver in struct drm_crtc_helper_funcs and struct drm_encoder_helper_funcs appropriately.

This function is deprecated. New drivers must implement atomic modeset support, for which this function is unsuitable. Instead drivers should use drm_atomic_helper_connector_dpms().

Return

Always returns 0.

void drm_helper_mode_fill_fb_struct(struct drm_framebuffer * fb, const struct drm_mode_fb_cmd2 * mode_cmd)¶: fill out framebuffer metadata

Parameters

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.

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.

int drm_helper_crtc_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)¶: mode_set implementation for atomic plane helpers

Parameters

struct drm_crtc * crtc: DRM CRTC
struct drm_display_mode * mode: DRM display mode which userspace requested
struct drm_display_mode * adjusted_mode: DRM display mode adjusted by ->mode_fixup callbacks
int x: x offset of the CRTC scanout area on the underlying framebuffer
int y: y offset of the CRTC scanout area on the underlying framebuffer
struct drm_framebuffer * old_fb: previous framebuffer

Description

This function implements a callback useable as the ->mode_set callback required by the CRTC helpers. Besides the atomic plane helper functions for the primary plane the driver must also provide the ->mode_set_nofb callback to set up the CRTC.

This is a transitional helper useful for converting drivers to the atomic interfaces.

int drm_helper_crtc_mode_set_base(struct drm_crtc * crtc, int x, int y, struct drm_framebuffer * old_fb)¶: mode_set_base implementation for atomic plane helpers

Parameters

struct drm_crtc * crtc: DRM CRTC
int x: x offset of the CRTC scanout area on the underlying framebuffer
int y: y offset of the CRTC scanout area on the underlying framebuffer
struct drm_framebuffer * old_fb: previous framebuffer

Description

This function implements a callback useable as the ->mode_set_base used required by the CRTC helpers. The driver must provide the atomic plane helper functions for the primary plane.

This is a transitional helper useful for converting drivers to the atomic interfaces.

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 ->:c:func: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.

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.

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_locked(struct drm_device * dev)¶: re-enable output polling.

Parameters

struct drm_device * dev: drm_device

Description

This function re-enables the output polling work without locking the mode_config mutex.

This is like drm_kms_helper_poll_enable() however it is to be called from a context where the mode_config mutex is locked already.

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 ->:c:func:fill_modes() connector vfunc for drivers that use the CRTC helpers for output mode filtering and detection.

The basic procedure is as follows

All modes currently on the connector’s modes list are marked as stale
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.
- debugfs ‘override_edid’ (used for testing only)
- firmware EDID (drm_load_edid_firmware())
- connector helper ->:c:func: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.
Modes are moved from the probed_modes list to the modes list. Potential duplicates are merged together (see drm_mode_connector_list_update()). After this step the probed_modes list will be empty again.
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 againt basic connector capabilites (interlace_allowed,doublescan_allowed,stereo_allowed)
- the optional connector ->:c:func:mode_valid() helper can perform driver and/or hardware specific checks
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.

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 arlready disabled.

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.

Drivers can call this helper from their device resume implementation. It is an error to call this when the output polling support has not yet been set up.

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.

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

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.

int drm_fb_helper_single_add_all_connectors(struct drm_fb_helper * fb_helper)¶: add all connectors to fbdev emulation helper

Parameters

struct drm_fb_helper * fb_helper: fbdev initialized with drm_fb_helper_init

Description

This functions adds all the available connectors for use with the given fb_helper. This is a separate step to allow drivers to freely assign connectors to the fbdev, e.g. if some are reserved for special purposes or not adequate to be used for the fbcon.

This function is protected against concurrent connector hotadds/removals using drm_fb_helper_add_one_connector() and drm_fb_helper_remove_one_connector().

int drm_fb_helper_debug_enter(struct fb_info * info)¶: implementation for ->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_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: fbcon to restore

Description

This should be called from driver’s drm ->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_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 crtc_count, int max_conn_count)¶: initialize a drm_fb_helper structure

Parameters

struct drm_device * dev: drm device
struct drm_fb_helper * fb_helper: driver-allocated fbdev helper structure to initialize
int crtc_count: maximum number of crtcs to support in this fbdev emulation
int max_conn_count: max connector count

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.

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

Description

A wrapper around unregister_framebuffer, to release the fb_info framebuffer device

void drm_fb_helper_release_fbi(struct drm_fb_helper * fb_helper)¶: dealloc fb_info and its members

Parameters

struct drm_fb_helper * fb_helper: driver-allocated fbdev helper

Description

A helper to free memory taken by fb_info and the members cmap and apertures

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

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.

ssize_t drm_fb_helper_sys_read(struct fb_info * info, char * 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 * 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_imageblit 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, int state)¶: wrapper around fb_set_suspend

Parameters

struct drm_fb_helper * fb_helper: driver-allocated fbdev helper
int state: desired state, zero to resume, non-zero to suspend

Description

A wrapper around fb_set_suspend implemented by fbdev core

int drm_fb_helper_setcmap(struct fb_cmap * cmap, struct fb_info * info)¶: implementation for ->fb_setcmap

Parameters

struct fb_cmap * cmap: cmap to set
struct fb_info * info: fbdev registered by the helper

int drm_fb_helper_check_var(struct fb_var_screeninfo * var, struct fb_info * info)¶: implementation for ->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_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_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_fix(struct fb_info * info, uint32_t pitch, uint32_t depth)¶: initializes fixed fbdev information

Parameters

struct fb_info * info: fbdev registered by the helper
uint32_t pitch: desired pitch
uint32_t depth: desired depth

Description

Helper to fill in the fixed fbdev information useful for a non-accelerated fbdev emulations. Drivers which support acceleration methods which impose additional constraints need to set up their own limits.

Drivers should call this (or their equivalent setup code) from their ->fb_probe callback.

void drm_fb_helper_fill_var(struct fb_info * info, struct drm_fb_helper * fb_helper, uint32_t fb_width, uint32_t fb_height)¶: initalizes variable 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
uint32_t fb_width: desired fb width
uint32_t fb_height: desired fb height

Description

Sets up the variable fbdev metainformation from the given fb helper instance and the drm framebuffer allocated in fb_helper->fb.

Drivers should call this (or their equivalent setup code) from their ->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 ->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_var() and drm_fb_helper_fill_fix() are provided as helpers 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: the drm_fb_helper

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.

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

u32 fb_width: fbdev width
u32 fb_height: fbdev height
u32 surface_width: scanout buffer width
u32 surface_height: scanout buffer height
u32 surface_bpp: scanout buffer bpp
u32 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.

So what is passed to drm_fb_helper_fill_var() should be fb_width/fb_height, rather than the surface size.

struct drm_fb_helper_funcs¶: driver callbacks for the fbdev emulation library

Definition

struct drm_fb_helper_funcs {
  void (* gamma_set) (struct drm_crtc *crtc, u16 red, u16 green,u16 blue, int regno);
  void (* gamma_get) (struct drm_crtc *crtc, u16 *red, u16 *green,u16 *blue, int regno);
  int (* fb_probe) (struct drm_fb_helper *helper,struct drm_fb_helper_surface_size *sizes);
  bool (* initial_config) (struct drm_fb_helper *fb_helper,struct drm_fb_helper_crtc **crtcs,struct drm_display_mode **modes,struct drm_fb_offset *offsets,bool *enabled, int width, int height);
};

Members

void (*)(struct drm_crtc *crtc, u16 red, u16 green,u16 blue, int regno) gamma_set

Set the given gamma LUT register on the given CRTC.

This callback is optional.

FIXME:

This callback is functionally redundant with the core gamma table support and simply exists because the fbdev hasn’t yet been refactored to use the core gamma table interfaces.

void (*)(struct drm_crtc *crtc, u16 *red, u16 *green,u16 *blue, int regno) gamma_get

Read the given gamma LUT register on the given CRTC, used to save the current LUT when force-restoring the fbdev for e.g. kdbg.

This callback is optional.

FIXME:

This callback is functionally redundant with the core gamma table support and simply exists because the fbdev hasn’t yet been refactored to use the core gamma table interfaces.

int (*)(struct drm_fb_helper *helper,struct drm_fb_helper_surface_size *sizes) 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.

bool (*)(struct drm_fb_helper *fb_helper,struct drm_fb_helper_crtc **crtcs,struct drm_display_mode **modes,struct drm_fb_offset *offsets,bool *enabled, int width, int height) initial_config

Driver callback to setup an initial fbdev display configuration. Drivers can use this callback to tell the fbdev emulation what the preferred initial configuration is. This is useful to implement smooth booting where the fbdev (and subsequently all userspace) never changes the mode, but always inherits the existing configuration.

This callback is optional.

RETURNS:

The driver should return true if a suitable initial configuration has been filled out and false when the fbdev helper should fall back to the default probing logic.

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_framebuffer * fb;
  struct drm_device * dev;
  int crtc_count;
  struct drm_fb_helper_crtc * crtc_info;
  int connector_count;
  int connector_info_alloc_count;
  struct drm_fb_helper_connector ** connector_info;
  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 list_head kernel_fb_list;
  bool delayed_hotplug;
};

Members

struct drm_framebuffer * fb: Scanout framebuffer object
struct drm_device * dev: DRM device
int crtc_count: number of possible CRTCs
struct drm_fb_helper_crtc * crtc_info: per-CRTC helper state (mode, x/y offset, etc)
int connector_count: number of connected connectors
int connector_info_alloc_count: size of connector_info
struct drm_fb_helper_connector ** connector_info: array of per-connector information
const struct drm_fb_helper_funcs * funcs: driver callbacks for fb helper
struct fb_info * fbdev: emulated fbdev device info struct
u32 pseudo_palette[17]: fake palette of 16 colors
struct drm_clip_rect dirty_clip: clip rectangle used with deferred_io to accumulate damage to the screen buffer
spinlock_t dirty_lock: spinlock protecting dirty_clip
struct work_struct dirty_work: worker used to flush the framebuffer
struct list_head kernel_fb_list: Entry on the global kernel_fb_helper_list, used for kgdb entry/exit.
bool 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.

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.

Framebuffer CMA Helper Functions Reference¶

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

drm_fb_cma_create() is used in the drm_mode_config_funcs ->fb_create callback function to create a cma backed framebuffer.

An fbdev framebuffer backed by cma is also available by calling drm_fbdev_cma_init(). drm_fbdev_cma_fini() tears it down. If the drm_framebuffer_funcs ->dirty callback is set, fb_deferred_io will be set up automatically. dirty() is called by drm_fb_helper_deferred_io() in process context (struct delayed_work).

Example fbdev deferred io code:

static int driver_fbdev_fb_dirty(struct drm_framebuffer *fb,
                                 struct drm_file *file_priv,
                                 unsigned flags, unsigned color,
                                 struct drm_clip_rect *clips,
                                 unsigned num_clips)
{
    struct drm_gem_cma_object *cma = drm_fb_cma_get_gem_obj(fb, 0);
    ... push changes ...
    return 0;
}

static struct drm_framebuffer_funcs driver_fbdev_fb_funcs = {
    .destroy       = drm_fb_cma_destroy,
    .create_handle = drm_fb_cma_create_handle,
    .dirty         = driver_fbdev_fb_dirty,
};

static int driver_fbdev_create(struct drm_fb_helper *helper,
        struct drm_fb_helper_surface_size *sizes)
{
    return drm_fbdev_cma_create_with_funcs(helper, sizes,
                                           :c:type:`driver_fbdev_fb_funcs`);
}

static const struct drm_fb_helper_funcs driver_fb_helper_funcs = {
    .fb_probe = driver_fbdev_create,
};

Initialize:
fbdev = drm_fbdev_cma_init_with_funcs(dev, 16,
                                      dev->mode_config.num_crtc,
                                      dev->mode_config.num_connector,
                                      :c:type:`driver_fb_helper_funcs`);

struct drm_framebuffer * drm_fb_cma_create_with_funcs(struct drm_device * dev, struct drm_file * file_priv, 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 function

Parameters

struct drm_device * dev: DRM device
struct drm_file * file_priv: drm file for the ioctl call
const struct drm_mode_fb_cmd2 * mode_cmd: metadata from the userspace fb creation request
const struct drm_framebuffer_funcs * funcs: vtable to be used for the new framebuffer object

Description

This can be used to set drm_framebuffer_funcs for drivers that need the dirty() callback. Use drm_fb_cma_create() if you don’t need to change drm_framebuffer_funcs.

struct drm_framebuffer * drm_fb_cma_create(struct drm_device * dev, struct drm_file * file_priv, const struct drm_mode_fb_cmd2 * mode_cmd)¶: drm_mode_config_funcs ->fb_create callback function

Parameters

struct drm_device * dev: DRM device
struct drm_file * file_priv: drm file for the ioctl call
const struct drm_mode_fb_cmd2 * mode_cmd: metadata from the userspace fb creation request

Description

If your hardware has special alignment or pitch requirements these should be checked before calling this function. Use drm_fb_cma_create_with_funcs() if you need to set drm_framebuffer_funcs ->dirty.

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.

int drm_fb_cma_debugfs_show(struct seq_file * m, void * arg)¶: Helper to list CMA framebuffer objects in debugfs.

Parameters

struct seq_file * m: output file
void * arg: private data for the callback

struct drm_fbdev_cma * drm_fbdev_cma_init_with_funcs(struct drm_device * dev, unsigned int preferred_bpp, unsigned int num_crtc, unsigned int max_conn_count, const struct drm_fb_helper_funcs * funcs)¶: Allocate and initializes a drm_fbdev_cma struct

Parameters

struct drm_device * dev: DRM device
unsigned int preferred_bpp: Preferred bits per pixel for the device
unsigned int num_crtc: Number of CRTCs
unsigned int max_conn_count: Maximum number of connectors
const struct drm_fb_helper_funcs * funcs: fb helper functions, in particular fb_probe()

Description

Returns a newly allocated drm_fbdev_cma struct or a ERR_PTR.

struct drm_fbdev_cma * drm_fbdev_cma_init(struct drm_device * dev, unsigned int preferred_bpp, unsigned int num_crtc, unsigned int max_conn_count)¶: Allocate and initializes a drm_fbdev_cma struct

Parameters

struct drm_device * dev: DRM device
unsigned int preferred_bpp: Preferred bits per pixel for the device
unsigned int num_crtc: Number of CRTCs
unsigned int max_conn_count: Maximum number of connectors

Description

Returns a newly allocated drm_fbdev_cma struct or a ERR_PTR.

void drm_fbdev_cma_fini(struct drm_fbdev_cma * fbdev_cma)¶: Free drm_fbdev_cma struct

Parameters

struct drm_fbdev_cma * fbdev_cma: The drm_fbdev_cma struct

void drm_fbdev_cma_restore_mode(struct drm_fbdev_cma * fbdev_cma)¶: Restores initial framebuffer mode

Parameters

struct drm_fbdev_cma * fbdev_cma: The drm_fbdev_cma struct, may be NULL

Description

This function is usually called from the DRM drivers lastclose callback.

void drm_fbdev_cma_hotplug_event(struct drm_fbdev_cma * fbdev_cma)¶: Poll for hotpulug events

Parameters

struct drm_fbdev_cma * fbdev_cma: The drm_fbdev_cma struct, may be NULL

Description

This function is usually called from the DRM drivers output_poll_changed callback.

void drm_fbdev_cma_set_suspend(struct drm_fbdev_cma * fbdev_cma, int state)¶: wrapper around drm_fb_helper_set_suspend

Parameters

struct drm_fbdev_cma * fbdev_cma: The drm_fbdev_cma struct, may be NULL
int state: desired state, zero to resume, non-zero to suspend

Description

Calls drm_fb_helper_set_suspend, which is a wrapper around fb_set_suspend implemented by fbdev core.

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 .:c:func:transfer() implementation. Both native and I2C-over-AUX transactions are supported.

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

unsigned int address: address of the (first) register to access
u8 request: contains the type of transaction (see DP_AUX_* macros)
u8 reply: upon completion, contains the reply type of the transaction
void * buffer: pointer to a transmission or reception buffer
size_t size: size of buffer

struct drm_dp_aux¶: DisplayPort AUX channel

Definition

struct drm_dp_aux {
  const char * name;
  struct i2c_adapter ddc;
  struct device * dev;
  struct mutex hw_mutex;
  ssize_t (* transfer) (struct drm_dp_aux *aux,struct drm_dp_aux_msg *msg);
  unsigned i2c_nack_count;
  unsigned i2c_defer_count;
};

Members

const char * name: user-visible name of this AUX channel and the I2C-over-AUX adapter
struct i2c_adapter ddc: I2C adapter that can be used for I2C-over-AUX communication
struct device * dev: pointer to struct device that is the parent for this AUX channel
struct mutex hw_mutex: internal mutex used for locking transfers
ssize_t (*)(struct drm_dp_aux *aux,struct drm_dp_aux_msg *msg) transfer: transfers a message representing a single AUX transaction
unsigned i2c_nack_count: Counts I2C NACKs, used for DP validation.
unsigned i2c_defer_count: Counts I2C DEFERs, used for DP validation.

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 .:c:func: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 .:c:func: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 .:c:func: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 .:c:func: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.

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[DP_LINK_STATUS_SIZE])¶: read DPCD link status (bytes 0x202-0x207)

Parameters

struct drm_dp_aux * aux: DisplayPort AUX channel
u8 status[DP_LINK_STATUS_SIZE]: undescribed

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.

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[EDP_PSR_RECEIVER_CAP_SIZE])¶: PSR setup in time usec

Parameters

const u8 psr_cap[EDP_PSR_RECEIVER_CAP_SIZE]: undescribed

Return

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

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_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

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

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.

struct drm_dp_vcpi¶: Virtual Channel Payload Identifier

Definition

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

Members

int vcpi: Virtual channel ID.
int pbn: Payload Bandwidth Number for this channel
int aligned_pbn: PBN aligned with slot size
int num_slots: number of slots for this PBN

struct drm_dp_mst_port¶: MST port

Definition

struct drm_dp_mst_port {
  struct kref 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

struct kref kref: reference count for this port.
u8 port_num: port number
bool input: if this port is an input port.
bool mcs: message capability status - DP 1.2 spec.
bool ddps: DisplayPort Device Plug Status - DP 1.2
u8 pdt: Peer Device Type
bool ldps: Legacy Device Plug Status
u8 dpcd_rev: DPCD revision of device on this port
u8 num_sdp_streams: Number of simultaneous streams
u8 num_sdp_stream_sinks: Number of stream sinks
uint16_t available_pbn: Available bandwidth for this port.
struct list_head next: link to next port on this branch device
struct drm_dp_mst_branch * mstb: branch device attach below this port
struct drm_dp_aux aux: i2c aux transport to talk to device connected to this port.
struct drm_dp_mst_branch * parent: branch device parent of this port
struct drm_dp_vcpi vcpi: Virtual Channel Payload info for this port.
struct drm_connector * connector: DRM connector this port is connected to.
struct drm_dp_mst_topology_mgr * mgr: topology manager this port lives under.
struct edid * cached_edid: for DP logical ports - make tiling work by ensuring that the EDID for all connectors is read immediately.
bool 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 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

struct kref kref: reference count for this port.
u8 rad[8]: Relative Address to talk to this branch device.
u8 lct: Link count total to talk to this branch device.
int num_ports: number of ports on the branch.
int msg_slots: one bit per transmitted msg slot.
struct list_head ports: linked list of ports on this branch.
struct drm_dp_mst_port * port_parent: pointer to the port parent, NULL if toplevel.
struct drm_dp_mst_topology_mgr * mgr: topology manager for this branch device.
struct drm_dp_sideband_msg_tx * tx_slots[2]: transmission slots for this device.
int last_seqno: last sequence number used to talk to this.
bool link_address_sent: if a link address message has been sent to this device yet.
u8 guid[16]: 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 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;
  int total_slots;
  int avail_slots;
  int total_pbn;
  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

struct device * dev: device pointer for adding i2c devices etc.
const struct drm_dp_mst_topology_cbs * cbs: callbacks for connector addition and destruction.
int max_dpcd_transaction_bytes: maximum number of bytes to read/write in one go.
struct drm_dp_aux * aux: AUX channel for the DP MST connector this topolgy mgr is controlling.
int max_payloads: maximum number of payloads the GPU can generate.
int conn_base_id: DRM connector ID this mgr is connected to. Only used to build the MST connector path value.
struct drm_dp_sideband_msg_rx 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.
struct drm_dp_sideband_msg_rx 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.
struct mutex lock: protects mst state, primary, dpcd.
bool mst_state: If this manager is enabled for an MST capable port. False if no MST sink/branch devices is connected.
struct drm_dp_mst_branch * mst_primary: Pointer to the primary/first branch device.
u8 dpcd[DP_RECEIVER_CAP_SIZE]: Cache of DPCD for primary port.
u8 sink_count: Sink count from DEVICE_SERVICE_IRQ_VECTOR_ESI0.
int pbn_div: PBN to slots divisor.
int total_slots: Total slots that can be allocated.
int avail_slots: Still available slots that can be allocated.
int total_pbn: Total PBN count.
struct mutex qlock: protects tx_msg_downq, the tx_slots in struct drm_dp_mst_branch and txmsg->state once they are queued
struct list_head tx_msg_downq: List of pending down replies.
struct mutex payload_lock: Protect payload information.
struct drm_dp_vcpi ** proposed_vcpis: Array of pointers for the new VCPI allocation. The VCPI structure itself is embedded into the corresponding drm_dp_mst_port structure.
struct drm_dp_payload * payloads: Array of payloads.
unsigned long 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.
unsigned long vcpi_mask: Similar to payload_mask, but for proposed_vcpis.
wait_queue_head_t tx_waitq: Wait to queue stall for the tx worker.
struct work_struct work: Probe work.
struct work_struct tx_work: Sideband transmit worker. This can nest within the main work worker for each transaction work launches.
struct list_head destroy_connector_list: List of to be destroyed connectors.
struct mutex destroy_connector_lock: Protects connector_list.
struct work_struct 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.

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 slots for this PBN value

Parameters

struct drm_dp_mst_topology_mgr * mgr: manager to use
int pbn: payload bandwidth to convert into slots.

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: unverified port to deallocate vcpi for

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_topology_mgr_init(struct drm_dp_mst_topology_mgr * mgr, struct 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 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

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

u8 channel: virtual channel id
u8 type: payload data type
u16 flags: flags controlling this message transmission
size_t tx_len: length of tx_buf
const void * tx_buf: data to be written
size_t rx_len: length of rx_buf
void * 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_t size: size (in bytes) of the packet
u8 header[4]: the four bytes that make up the header (Data ID, Word Count or Packet Data, and ECC)
size_t payload_length: number of bytes in the payload
const u8 * 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

int (*)(struct mipi_dsi_host *host,struct mipi_dsi_device *dsi) attach: attach DSI device to DSI host
int (*)(struct mipi_dsi_host *host,struct mipi_dsi_device *dsi) detach: detach DSI device from DSI host
ssize_t (*)(struct mipi_dsi_host *host,const struct mipi_dsi_msg *msg) transfer: transmit a DSI packet

Description

DSI packets transmitted by .:c:func: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 .:c:func: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

struct device * dev: driver model device node for this DSI host
const struct mipi_dsi_host_ops * ops: DSI host operations
struct list_head 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

char type[DSI_DEV_NAME_SIZE]: DSI peripheral chip type
u32 channel: DSI virtual channel assigned to peripheral
struct device_node * 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;
};

Members

struct mipi_dsi_host * host: DSI host for this peripheral
struct device dev: driver model device node for this peripheral
char name[DSI_DEV_NAME_SIZE]: DSI peripheral chip type
unsigned int channel: virtual channel assigned to the peripheral
unsigned int lanes: number of active data lanes
enum mipi_dsi_pixel_format format: pixel format for video mode
unsigned long mode_flags: DSI operation mode related flags

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

struct device_driver driver: device driver model driver
int(*)(struct mipi_dsi_device *dsi) probe: callback for device binding
int(*)(struct mipi_dsi_device *dsi) remove: callback for device unbinding
void (*)(struct mipi_dsi_device *dsi) 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_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_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_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.

EDID Helper Functions Reference¶

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.

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.

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

void drm_edid_to_eld(struct drm_connector * connector, struct edid * edid)¶: build ELD from EDID

Parameters

struct drm_connector * connector: connector corresponding to the HDMI/DP sink
struct edid * edid: EDID to parse

Description

Fill the ELD (EDID-Like Data) buffer for passing to the audio driver. The Conn_Type, HDCP and Port_ID ELD fields are left for the graphics driver to fill in.

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.

struct drm_connector * drm_select_eld(struct drm_encoder * encoder)¶: select one ELD from multiple HDMI/DP sinks

Parameters

struct drm_encoder * encoder: the encoder just changed display mode

Description

It’s possible for one encoder to be associated with multiple HDMI/DP sinks. The policy is now hard coded to simply use the first HDMI/DP sink’s ELD.

Return

The connector associated with the first HDMI/DP sink that has ELD attached to it.

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.

bool drm_rgb_quant_range_selectable(struct edid * edid)¶: is RGB quantization range selectable?

Parameters

struct edid * edid: EDID block to scan

Description

Check whether the monitor reports the RGB quantization range selection as supported. The AVI infoframe can then be used to inform the monitor which quantization range (full or limited) is used.

Return

True if the RGB quantization range is selectable, false otherwise.

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.

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_avi_infoframe_from_display_mode(struct hdmi_avi_infoframe * frame, 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
const struct drm_display_mode * mode: DRM display mode

Return

0 on success or a negative error code on failure.

int drm_hdmi_vendor_infoframe_from_display_mode(struct hdmi_vendor_infoframe * frame, 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
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.

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;
  int y1;
  int x2;
  int y2;
};

Members

int x1: horizontal starting coordinate (inclusive)
int y1: vertical starting coordinate (inclusive)
int x2: horizontal ending coordinate (exclusive)
int y2: vertical ending coordinate (exclusive)

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, int hscale, int vscale)¶: 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
int hscale: horizontal scaling factor
int vscale: vertical scaling factor

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

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

Return

The vertical scaling factor, or errno of out of limits.

int drm_rect_calc_hscale_relaxed(struct drm_rect * src, struct drm_rect * dst, int min_hscale, int max_hscale)¶: calculate the horizontal scaling factor

Parameters

struct drm_rect * src: source window rectangle
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 calculated scaling factor is below min_vscale, decrease the height of rectangle dst to compensate.

If the calculated scaling factor is above max_vscale, decrease the height of rectangle src to compensate.

Return

The horizontal scaling factor.

int drm_rect_calc_vscale_relaxed(struct drm_rect * src, struct drm_rect * dst, int min_vscale, int max_vscale)¶: calculate the vertical scaling factor

Parameters

struct drm_rect * src: source window rectangle
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 calculated scaling factor is below min_vscale, decrease the height of rectangle dst to compensate.

If the calculated scaling factor is above max_vscale, decrease the height of rectangle src to compensate.

Return

The vertical scaling factor.

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_rotate(r, width, height, rotation); drm_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

struct list_head node: list entry element
void * data: data to pass to 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

const char * name: debug name
drm_flip_func_t func: callback fxn called for each committed item
struct work_struct worker: worker which calls func
struct list_head queued: queued tasks
struct list_head commited: commited tasks
spinlock_t 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

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.

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;
};

Members

struct hdmi_any_infoframe any: generic infoframe
struct hdmi_avi_infoframe avi: avi infoframe
struct hdmi_spd_infoframe spd: spd infoframe
union hdmi_vendor_any_infoframe vendor: union of all vendor infoframes
struct hdmi_audio_infoframe audio: audio 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.

ssize_t hdmi_avi_infoframe_pack(struct hdmi_avi_infoframe * frame, void * buffer, size_t size)¶: write HDMI AVI infoframe to binary buffer

Parameters

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.

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.

ssize_t hdmi_spd_infoframe_pack(struct hdmi_spd_infoframe * frame, void * buffer, size_t size)¶: write HDMI SPD infoframe to binary buffer

Parameters

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.

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.

ssize_t hdmi_audio_infoframe_pack(struct hdmi_audio_infoframe * frame, void * buffer, size_t size)¶: write HDMI audio infoframe to binary buffer

Parameters

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.

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.

ssize_t hdmi_vendor_infoframe_pack(struct hdmi_vendor_infoframe * frame, void * buffer, size_t size)¶: write a HDMI vendor infoframe to binary buffer

Parameters

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_infoframe_pack(union hdmi_infoframe * frame, void * buffer, size_t size)¶: write a HDMI infoframe to binary buffer

Parameters

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.

void hdmi_infoframe_log(const char * level, struct device * dev, union hdmi_infoframe * frame)¶: log info of HDMI infoframe

Parameters

const char * level: logging level
struct device * dev: device
union hdmi_infoframe * frame: HDMI infoframe

int hdmi_infoframe_unpack(union hdmi_infoframe * frame, void * buffer)¶: unpack binary buffer to a HDMI infoframe

Parameters

union hdmi_infoframe * frame: HDMI infoframe
void * buffer: source 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.

Plane Helper Reference¶

int drm_plane_helper_check_update(struct drm_plane * plane, struct drm_crtc * crtc, struct drm_framebuffer * fb, struct drm_rect * src, struct drm_rect * dest, const struct drm_rect * clip, unsigned int rotation, int min_scale, int max_scale, bool can_position, bool can_update_disabled, bool * visible)¶: Check plane update for validity

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
struct drm_rect * src: source coordinates in 16.16 fixed point
struct drm_rect * dest: integer destination coordinates
const struct drm_rect * clip: integer clipping coordinates
unsigned int rotation: plane rotation
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?
bool * visible: output parameter indicating whether plane is still visible after clipping

Description

Checks that a desired plane update is valid. 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_primary_helper_update(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)¶: Helper for primary plane update

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

Description

Provides a default plane update handler for primary planes. This is handler is called in response to a userspace SetPlane operation on the plane with a non-NULL framebuffer. We call the driver’s modeset handler to update the framebuffer.

SetPlane() on a primary plane of a disabled CRTC is not supported, and will return an error.

Note that we make some assumptions about hardware limitations that may not be true for all hardware –

Primary plane cannot be repositioned.
Primary plane cannot be scaled.
Primary plane must cover the entire CRTC.
Subpixel positioning is not supported.

Drivers for hardware that don’t have these restrictions can provide their own implementation rather than using this helper.

Return

Zero on success, error code on failure

int drm_primary_helper_disable(struct drm_plane * plane)¶: Helper for primary plane disable

Parameters

struct drm_plane * plane: plane to disable

Description

Provides a default plane disable handler for primary planes. This is handler is called in response to a userspace SetPlane operation on the plane with a NULL framebuffer parameter. It unconditionally fails the disable call with -EINVAL the only way to disable the primary plane without driver support is to disable the entier CRTC. Which does not match the plane ->disable hook.

Note that some hardware may be able to disable the primary plane without disabling the whole CRTC. Drivers for such hardware should provide their own disable handler that disables just the primary plane (and they’ll likely need to provide their own update handler as well to properly re-enable a disabled primary plane).

Return

Unconditionally returns -EINVAL.

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.

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.

Return

Zero on success, error code on failure.

int drm_plane_helper_update(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)¶: Transitional helper for plane update

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

Description

Provides a default plane update handler using the atomic plane update functions. It is fully left to the driver to check plane constraints and handle corner-cases like a fully occluded or otherwise invisible plane.

This is useful for piecewise transitioning of a driver to the atomic helpers.

Return

Zero on success, error code on failure

int drm_plane_helper_disable(struct drm_plane * plane)¶: Transitional helper for plane disable

Parameters

struct drm_plane * plane: plane to disable

Description

Provides a default plane disable handler using the atomic plane update functions. It is fully left to the driver to check plane constraints and handle corner-cases like a fully occluded or otherwise invisible plane.

This is useful for piecewise transitioning of a driver to the atomic helpers.

Return

Zero on success, error code on failure

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.

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.

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¶

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 next pointer in struct drm_bridge.

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.

int drm_bridge_add(struct drm_bridge * bridge)¶: add the given bridge to the global bridge list

Parameters

struct drm_bridge * bridge: bridge control structure

Return

Unconditionally returns Zero.

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_device * dev, struct drm_bridge * bridge)¶: associate given bridge to our DRM device

Parameters

struct drm_device * dev: DRM device
struct drm_bridge * bridge: bridge control structure

Description

called by a kms driver to link one of our encoder/bridge to the given bridge.

Note that setting up links between the bridge and our encoder/bridge objects needs to be handled by the kms driver itself

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 ->:c:func:mode_fixup() drm_bridge_funcs 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

Return

true on success, false on failure

void drm_bridge_disable(struct drm_bridge * bridge)¶: calls ->:c:func:disable() drm_bridge_funcs op for all bridges in the encoder chain.

Parameters

struct drm_bridge * bridge: bridge control structure

Description

Calls ->:c:func:disable() drm_bridge_funcs 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)¶: calls ->:c:func:post_disable() drm_bridge_funcs op for all bridges in the encoder chain.

Parameters

struct drm_bridge * bridge: bridge control structure

Description

Calls ->:c:func:post_disable() drm_bridge_funcs 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, struct drm_display_mode * mode, struct drm_display_mode * adjusted_mode)¶: set proposed mode for all bridges in the encoder chain

Parameters

struct drm_bridge * bridge: bridge control structure
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 ->:c:func:mode_set() drm_bridge_funcs 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)¶: calls ->:c:func:pre_enable() drm_bridge_funcs op for all bridges in the encoder chain.

Parameters

struct drm_bridge * bridge: bridge control structure

Description

Calls ->:c:func:pre_enable() drm_bridge_funcs 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)¶: calls ->:c:func:enable() drm_bridge_funcs op for all bridges in the encoder chain.

Parameters

struct drm_bridge * bridge: bridge control structure

Description

Calls ->:c:func:enable() drm_bridge_funcs 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

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 Helper Reference¶

struct drm_panel_funcs¶: perform operations on a given panel

Definition

struct drm_panel_funcs {
  int (* disable) (struct drm_panel *panel);
  int (* unprepare) (struct drm_panel *panel);
  int (* prepare) (struct drm_panel *panel);
  int (* enable) (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

int (*)(struct drm_panel *panel) disable: disable panel (turn off back light, etc.)
int (*)(struct drm_panel *panel) unprepare: turn off panel
int (*)(struct drm_panel *panel) prepare: turn on panel and perform set up
int (*)(struct drm_panel *panel) enable: enable panel (turn on back light, etc.)
int (*)(struct drm_panel *panel) get_modes: add modes to the connector that the panel is attached to and return the number of modes added
int (*)(struct drm_panel *panel, unsigned int num_timings,struct display_timing *timings) get_timings: copy display timings into the provided array and return the number of display timings available

Description

The .:c:func: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 .:c:func: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 .:c:func:disable() function. Analogously to .:c:func: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 .:c:func: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

struct drm_device * drm: DRM device owning the panel
struct drm_connector * connector: DRM connector that the panel is attached to
struct device * dev: parent device of the panel
const struct drm_panel_funcs * funcs: operations that can be performed on the panel
struct list_head list: panel entry in registry

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

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.

Return

0 on success or a negative error code on failure.

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

Return

0 on success or a negative error code on failure.

struct drm_panel * of_drm_find_panel(struct device_node * np)¶: look up a panel using a device tree node

Parameters

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 NULL if no panel matching the device tree node can be found.

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

Simple KMS Helper Reference¶

struct drm_simple_display_pipe_funcs¶: helper operations for a simple display pipeline

Definition

struct drm_simple_display_pipe_funcs {
  void (* enable) (struct drm_simple_display_pipe *pipe,struct drm_crtc_state *crtc_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 *plane_state);
};

Members

void (*)(struct drm_simple_display_pipe *pipe,struct drm_crtc_state *crtc_state) enable

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

void (*)(struct drm_simple_display_pipe *pipe) disable

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

int (*)(struct drm_simple_display_pipe *pipe,struct drm_plane_state *plane_state,struct drm_crtc_state *crtc_state) 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.

void (*)(struct drm_simple_display_pipe *pipe,struct drm_plane_state *plane_state) update

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

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

struct drm_crtc crtc: CRTC control structure
struct drm_plane plane: Plane control structure
struct drm_encoder encoder: Encoder control structure
struct drm_connector * connector: Connector control structure
const struct drm_simple_display_pipe_funcs * 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_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, 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
struct drm_connector * connector: connector to attach and register

Description

Sets up a display pipeline which consist of a really simple plane-crtc-encoder pipe coupled with the provided connector. 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.

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.