drm_atomic_commit Struct Reference

#include <drm_atomic.h>

Collaboration diagram for drm_atomic_commit:

Public Attributes
struct kref	ref
struct drm_device *	dev
bool	allow_modeset: 1
bool	legacy_cursor_update: 1
bool	async_update: 1
bool	duplicated: 1
bool	checked: 1
bool	plane_color_pipeline: 1
struct __drm_colorops_state *	colorops
struct __drm_planes_state *	planes
struct __drm_crtcs_state *	crtcs
int	num_connector
struct __drm_connnectors_state *	connectors
int	num_private_objs
struct __drm_private_objs_state *	private_objs
struct drm_modeset_acquire_ctx *	acquire_ctx
struct drm_crtc_commit *	fake_commit
struct work_struct	commit_work

Detailed Description

struct drm_atomic_commit - Atomic commit structure

This structure is the kernel counterpart of @drm_mode_atomic and represents an atomic commit that transitions from an old to a new display state. It contains all the objects affected by the atomic commit and both the new state structures and pointers to the old state structures for these.

States are added to an atomic update by calling drm_atomic_get_crtc_state(), drm_atomic_get_plane_state(), drm_atomic_get_connector_state(), or for private state structures, drm_atomic_get_private_obj_state().

NOTE: struct drm_atomic_commit first started as a single collection of entities state pointers (drm_plane_state, drm_crtc_state, etc.).

At atomic_check time, you could get the state about to be committed from drm_atomic_commit, and the one currently running from the entities state pointer (drm_crtc.state, for example). After the call to drm_atomic_helper_swap_state(), the entities state pointer would contain the state previously checked, and the drm_atomic_commit structure the old state.

Over time, and in order to avoid confusion, drm_atomic_commit has grown to have both the old state (ie, the state we replace) and the new state (ie, the state we want to apply). Those names are stable during the commit process, which makes it easier to reason about.

You can still find some traces of that evolution through some hooks or callbacks taking a drm_atomic_commit parameter called names like "old_state". This doesn't necessarily mean that the previous drm_atomic_commit is passed, but rather that this used to be the state collection we were replacing after drm_atomic_helper_swap_state(), but the variable name was never updated.

Some atomic operations implementations followed a similar process. We first started to pass the entity state only. However, it was pretty cumbersome for drivers, and especially CRTCs, to retrieve the states of other components. Thus, we switched to passing the whole drm_atomic_commit as a parameter to those operations. Similarly, the transition isn't complete yet, and one might still find atomic operations taking a drm_atomic_commit pointer, or a component state pointer. The former is the preferred form.

Member Data Documentation

acquire_ctx

struct drm_modeset_acquire_ctx* drm_atomic_commit::acquire_ctx

@acquire_ctx: acquire context for this atomic modeset state update

allow_modeset

bool drm_atomic_commit::allow_modeset

@allow_modeset:

Allow full modeset. This is used by the ATOMIC IOCTL handler to implement the DRM_MODE_ATOMIC_ALLOW_MODESET flag. Drivers should generally not consult this flag, but instead look at the output of drm_atomic_crtc_needs_modeset(). The detailed rules are:

• Drivers must not consult @allow_modeset in the atomic commit path. Use drm_atomic_crtc_needs_modeset() instead.
• Drivers must consult @allow_modeset before adding unrelated struct drm_crtc_state to this commit by calling drm_atomic_get_crtc_state(). See also the warning in the documentation for that function.
• Drivers must never change this flag, it is under the exclusive control of userspace.
• Drivers may consult @allow_modeset in the atomic check path, if they have the choice between an optimal hardware configuration which requires a modeset, and a less optimal configuration which can be committed without a modeset. An example would be suboptimal scanout FIFO allocation resulting in increased idle power consumption. This allows userspace to avoid flickering and delays for the normal composition loop at reasonable cost.

async_update

bool drm_atomic_commit::async_update

@async_update: hint for asynchronous plane update

checked

bool drm_atomic_commit::checked

@checked:

Indicates the state has been checked and thus must no longer be mutated. For internal use only, do not consult from drivers.

colorops

struct __drm_colorops_state* drm_atomic_commit::colorops

@colorops:

Pointer to array of @drm_colorop and @drm_colorop_state part of this update.

commit_work

struct work_struct drm_atomic_commit::commit_work

@commit_work:

Work item which can be used by the driver or helpers to execute the commit without blocking.

connectors

struct __drm_connnectors_state* drm_atomic_commit::connectors

@connectors:

Pointer to array of @drm_connector and @drm_connector_state part of this update.

crtcs

struct __drm_crtcs_state* drm_atomic_commit::crtcs

@crtcs:

Pointer to array of @drm_crtc and @drm_crtc_state part of this update.

dev

struct drm_device* drm_atomic_commit::dev

@dev: Parent DRM Device.

duplicated

bool drm_atomic_commit::duplicated

@duplicated:

Indicates whether or not this atomic state was duplicated using drm_atomic_helper_duplicate_state(). Drivers and atomic helpers should use this to fixup normal inconsistencies in duplicated states.

fake_commit

struct drm_crtc_commit* drm_atomic_commit::fake_commit

@fake_commit:

Used for signaling unbound planes/connectors. When a connector or plane is not bound to any CRTC, it's still important to preserve linearity to prevent the atomic states from being freed too early.

This commit (if set) is not bound to any CRTC, but will be completed when drm_atomic_helper_commit_hw_done() is called.

legacy_cursor_update

bool drm_atomic_commit::legacy_cursor_update

@legacy_cursor_update:

Hint to enforce legacy cursor IOCTL semantics.

WARNING: This is thoroughly broken and pretty much impossible to implement correctly. Drivers must ignore this and should instead implement &drm_plane_helper_funcs.atomic_async_check and &drm_plane_helper_funcs.atomic_async_commit hooks. New users of this flag are not allowed.

num_connector

int drm_atomic_commit::num_connector

@num_connector: size of the @connectors array

num_private_objs

int drm_atomic_commit::num_private_objs

@num_private_objs: size of the @private_objs array

plane_color_pipeline

bool drm_atomic_commit::plane_color_pipeline

@plane_color_pipeline:

Indicates whether this atomic state originated with a client that set the DRM_CLIENT_CAP_PLANE_COLOR_PIPELINE.

Drivers and helper functions should use this to ignore legacy properties that are incompatible with the drm_plane COLOR_PIPELINE behavior, such as:

• COLOR_RANGE
• COLOR_ENCODING

or any other driver-specific properties that might affect pixel values.

planes

struct __drm_planes_state* drm_atomic_commit::planes

@planes:

Pointer to array of @drm_plane and @drm_plane_state part of this update.

private_objs

struct __drm_private_objs_state* drm_atomic_commit::private_objs

@private_objs:

Pointer to array of @drm_private_obj and @drm_private_obj_state part of this update.

ref

struct kref drm_atomic_commit::ref

Count of all references to this update (will not be freed until zero).

---

The documentation for this struct was generated from the following file:

• XenevaOS/BaseHdr/drm/drm_atomic.h