The DRM subsystem aims for a strong separation between core code and helper
libraries. Core code takes care of general setup and teardown and decoding
userspace requests to kernel internal objects. Everything else is handled by a
large set of helper libraries, which can be combined freely to pick and choose
for each driver what fits, and avoid shared code where special behaviour is
needed.
This distinction between core code and helpers is especially strong in the
modesetting code, where there’s a shared userspace ABI for all drivers. This is
in contrast to the render side, where pretty much everything (with very few
exceptions) can be considered optional helper code.
There are a few areas these helpers can grouped into:
Helpers to implement modesetting. The important ones here are the atomic
helpers. Old drivers still often use the legacy CRTC helpers. They both share
the same set of common helper vtables. For really simple drivers (anything
that would have been a great fit in the deprecated fbdev subsystem) there’s
also the simple display pipe helpers.
There’s a big pile of helpers for handling outputs. First the generic bridge
helpers for handling encoder and transcoder IP blocks. Second the panel helpers
for handling panel-related information and logic. Plus then a big set of
helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally
there’s also generic helpers for handling output probing, and for dealing with
EDIDs.
The last group of helpers concerns itself with the frontend side of a display
pipeline: Planes, handling rectangles for visibility checking and scissoring,
flip queues and assorted bits.
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.
Callback to control power levels on the CRTC. If the mode passed in
is unsupported, the provider must use the next lowest power level.
This is used by the legacy CRTC helpers to implement DPMS
functionality in drm_helper_connector_dpms().
This callback is also used to disable a CRTC by calling it with
DRM_MODE_DPMS_OFF if the disable hook isn’t used.
This callback is used by the legacy CRTC helpers. Atomic helpers
also support using this hook for enabling and disabling a CRTC to
facilitate transitions to atomic, but it is deprecated. Instead
atomic_enable and atomic_disable should be used.
prepare
This callback should prepare the CRTC for a subsequent modeset, which
in practice means the driver should disable the CRTC if it is
running. Most drivers ended up implementing this by calling their
dpms hook with DRM_MODE_DPMS_OFF.
This callback is used by the legacy CRTC helpers. Atomic helpers
also support using this hook for disabling a CRTC to facilitate
transitions to atomic, but it is deprecated. Instead atomic_disable
should be used.
commit
This callback should commit the new mode on the CRTC after a modeset,
which in practice means the driver should enable the CRTC. Most
drivers ended up implementing this by calling their dpms hook with
DRM_MODE_DPMS_ON.
This callback is used by the legacy CRTC helpers. Atomic helpers
also support using this hook for enabling a CRTC to facilitate
transitions to atomic, but it is deprecated. Instead atomic_enable
should be used.
mode_valid
This callback is used to check if a specific mode is valid in this
crtc. This should be implemented if the crtc has some sort of
restriction in the modes it can display. For example, a given crtc
may be responsible to set a clock value. If the clock can not
produce all the values for the available modes then this callback
can be used to restrict the number of modes to only the ones that
can be displayed.
Since this function is both called from the check phase of an atomic
commit, and the mode validation in the probe paths it is not allowed
to look at anything else but the passed-in mode, and validate it
against configuration-invariant hardware constraints. Any further
limits which depend upon the configuration can only be checked in
mode_fixup or atomic_check.
RETURNS:
drm_mode_status Enum
mode_fixup
This callback is used to validate a mode. The parameter mode is the
display mode that userspace requested, adjusted_mode is the mode the
encoders need to be fed with. Note that this is the inverse semantics
of the meaning for the drm_encoder and drm_bridge_funcs.mode_fixup
vfunc. If the CRTC cannot support the requested conversion from mode
to adjusted_mode it should reject the modeset. See also
drm_crtc_state.adjusted_mode for more details.
This function is used by both legacy CRTC helpers and atomic helpers.
With atomic helpers it is optional.
NOTE:
This function is called in the check phase of atomic modesets, which
can be aborted for any reason (including on userspace’s request to
just check whether a configuration would be possible). Atomic drivers
MUST NOT touch any persistent state (hardware or software) or data
structures except the passed in adjusted_mode parameter.
This is in contrast to the legacy CRTC helpers where this was
allowed.
Atomic drivers which need to inspect and adjust more state should
instead use the atomic_check callback, but note that they’re not
perfectly equivalent: mode_valid is called from
drm_atomic_helper_check_modeset(), but atomic_check is called from
drm_atomic_helper_check_planes(), because originally it was meant for
plane update checks only.
Also beware that userspace can request its own custom modes, neither
core nor helpers filter modes to the list of probe modes reported by
the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure
that modes are filtered consistently put any CRTC constraints and
limits checks into mode_valid.
RETURNS:
True if an acceptable configuration is possible, false if the modeset
operation should be rejected.
mode_set
This callback is used by the legacy CRTC helpers to set a new mode,
position and framebuffer. Since it ties the primary plane to every
mode change it is incompatible with universal plane support. And
since it can’t update other planes it’s incompatible with atomic
modeset support.
This callback is only used by CRTC helpers and deprecated.
RETURNS:
0 on success or a negative error code on failure.
mode_set_nofb
This callback is used to update the display mode of a CRTC without
changing anything of the primary plane configuration. This fits the
requirement of atomic and hence is used by the atomic helpers.
Note that the display pipe is completely off when this function is
called. Atomic drivers which need hardware to be running before they
program the new display mode (e.g. because they implement runtime PM)
should not use this hook. This is because the helper library calls
this hook only once per mode change and not every time the display
pipeline is suspended using either DPMS or the new “ACTIVE” property.
Which means register values set in this callback might get reset when
the CRTC is suspended, but not restored. Such drivers should instead
move all their CRTC setup into the atomic_enable callback.
This callback is optional.
mode_set_base
This callback is used by the legacy CRTC helpers to set a new
framebuffer and scanout position. It is optional and used as an
optimized fast-path instead of a full mode set operation with all the
resulting flickering. If it is not present
drm_crtc_helper_set_config() will fall back to a full modeset, using
the mode_set callback. Since it can’t update other planes it’s
incompatible with atomic modeset support.
This callback is only used by the CRTC helpers and deprecated.
RETURNS:
0 on success or a negative error code on failure.
disable
This callback should be used to disable the CRTC. With the atomic
drivers it is called after all encoders connected to this CRTC have
been shut off already using their own
drm_encoder_helper_funcs.disable hook. If that sequence is too
simple drivers can just add their own hooks and call it from this
CRTC callback here by looping over all encoders connected to it using
for_each_encoder_on_crtc().
This hook is used both by legacy CRTC helpers and atomic helpers.
Atomic drivers don’t need to implement it if there’s no need to
disable anything at the CRTC level. To ensure that runtime PM
handling (using either DPMS or the new “ACTIVE” property) works
disable must be the inverse of atomic_enable for atomic drivers.
Atomic drivers should consider to use atomic_disable instead of
this one.
NOTE:
With legacy CRTC helpers there’s a big semantic difference between
disable and other hooks (like prepare or dpms) used to shut down a
CRTC: disable is only called when also logically disabling the
display pipeline and needs to release any resources acquired in
mode_set (like shared PLLs, or again release pinned framebuffers).
Therefore disable must be the inverse of mode_set plus commit for
drivers still using legacy CRTC helpers, which is different from the
rules under atomic.
atomic_check
Drivers should check plane-update related CRTC constraints in this
hook. They can also check mode related limitations but need to be
aware of the calling order, since this hook is used by
drm_atomic_helper_check_planes() whereas the preparations needed to
check output routing and the display mode is done in
drm_atomic_helper_check_modeset(). Therefore drivers that want to
check output routing and display mode constraints in this callback
must ensure that drm_atomic_helper_check_modeset() has been called
beforehand. This is calling order used by the default helper
implementation in drm_atomic_helper_check().
When using drm_atomic_helper_check_planes() this hook is called
after the drm_plane_helper_funcs.atomic_check hook for planes, which
allows drivers to assign shared resources requested by planes in this
callback here. For more complicated dependencies the driver can call
the provided check helpers multiple times until the computed state
has a final configuration and everything has been checked.
This function is also allowed to inspect any other object’s state and
can add more state objects to the atomic commit if needed. Care must
be taken though to ensure that state check and compute functions for
these added states are all called, and derived state in other objects
all updated. Again the recommendation is to just call check helpers
until a maximal configuration is reached.
This callback is used by the atomic modeset helpers, 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 object passed-in.
Also beware that userspace can request its own custom modes, neither
core nor helpers filter modes to the list of probe modes reported by
the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure
that modes are filtered consistently put any CRTC constraints and
limits checks into mode_valid.
RETURNS:
0 on success, -EINVAL if the state or the transition can’t be
supported, -ENOMEM on memory allocation failure and -EDEADLK if an
attempt to obtain another state object ran into a drm_modeset_lock
deadlock.
atomic_begin
Drivers should prepare for an atomic update of multiple planes on
a CRTC in this hook. Depending upon hardware this might be vblank
evasion, blocking updates by setting bits or doing preparatory work
for e.g. manual update display.
This hook is called before any plane commit functions are called.
Note that the power state of the display pipe when this function is
called depends upon the exact helpers and calling sequence the driver
has picked. See drm_atomic_helper_commit_planes() for a discussion of
the tradeoffs and variants of plane commit helpers.
This callback is used by the atomic modeset helpers, but it is
optional.
atomic_flush
Drivers should finalize an atomic update of multiple planes on
a CRTC in this hook. Depending upon hardware this might include
checking that vblank evasion was successful, unblocking updates by
setting bits or setting the GO bit to flush out all updates.
Simple hardware or hardware with special requirements can commit and
flush out all updates for all planes from this hook and forgo all the
other commit hooks for plane updates.
This hook is called after any plane commit functions are called.
Note that the power state of the display pipe when this function is
called depends upon the exact helpers and calling sequence the driver
has picked. See drm_atomic_helper_commit_planes() for a discussion of
the tradeoffs and variants of plane commit helpers.
This callback is used by the atomic modeset helpers, but it is
optional.
atomic_enable
This callback should be used to enable the CRTC. With the atomic
drivers it is called before all encoders connected to this CRTC are
enabled through the encoder’s own drm_encoder_helper_funcs.enable
hook. If that sequence is too simple drivers can just add their own
hooks and call it from this CRTC callback here by looping over all
encoders connected to it using for_each_encoder_on_crtc().
This hook is used only by atomic helpers, for symmetry with
atomic_disable. Atomic drivers don’t need to implement it if there’s
no need to enable anything at the CRTC level. To ensure that runtime
PM handling (using either DPMS or the new “ACTIVE” property) works
atomic_enable must be the inverse of atomic_disable for atomic
drivers.
This function is optional.
atomic_disable
This callback should be used to disable the CRTC. With the atomic
drivers it is called after all encoders connected to this CRTC have
been shut off already using their own
drm_encoder_helper_funcs.disable hook. If that sequence is too
simple drivers can just add their own hooks and call it from this
CRTC callback here by looping over all encoders connected to it using
for_each_encoder_on_crtc().
This hook is used only by atomic helpers. Atomic drivers don’t
need to implement it if there’s no need to disable anything at the
CRTC level.
This function is optional.
get_scanout_position
Called by vblank timestamping code.
Returns the current display scanout position from a CRTC and an
optional accurate ktime_get() timestamp of when the position was
measured. Note that this is a helper callback which is only used
if a driver uses drm_crtc_vblank_helper_get_vblank_timestamp()
for the drm_crtc_funcs.get_vblank_timestamp callback.
Parameters:
crtc:
The CRTC.
in_vblank_irq:
True when called from drm_crtc_handle_vblank(). Some drivers
need to apply some workarounds for gpu-specific vblank irq
quirks if the flag is set.
vpos:
Target location for current vertical scanout position.
hpos:
Target location for current horizontal scanout position.
stime:
Target location for timestamp taken immediately before
scanout position query. Can be NULL to skip timestamp.
etime:
Target location for timestamp taken immediately after
scanout position query. Can be NULL to skip timestamp.
mode:
Current display timings.
Returns vpos as a positive number while in active scanout area.
Returns vpos as a negative number inside vblank, counting the number
of scanlines to go until end of vblank, e.g., -1 means “one scanline
until start of active scanout / end of vblank.”
Returns:
True on success, false if a reliable scanout position counter could
not be read out.
handle_vblank_timeout
Handles timeouts of the vblank timer.
Called by CRTC’s the vblank timer on each timeout. Semantics is
equivalient to drm_crtc_handle_vblank(). Implementations should
invoke drm_crtc_handle_vblank() as part of processing the timeout.
This callback is optional. If unset, the vblank timer invokes
drm_crtc_handle_vblank() directly.
Description
These hooks are used by the legacy CRTC helpers and the new atomic
modesetting helpers.
Callback to control power levels on the encoder. If the mode passed in
is unsupported, the provider must use the next lowest power level.
This is used by the legacy encoder helpers to implement DPMS
functionality in drm_helper_connector_dpms().
This callback is also used to disable an encoder by calling it with
DRM_MODE_DPMS_OFF if the disable hook isn’t used.
This callback is used by the legacy CRTC helpers. Atomic helpers
also support using this hook for enabling and disabling an encoder to
facilitate transitions to atomic, but it is deprecated. Instead
enable and disable should be used.
mode_valid
This callback is used to check if a specific mode is valid in this
encoder. This should be implemented if the encoder has some sort
of restriction in the modes it can display. For example, a given
encoder may be responsible to set a clock value. If the clock can
not produce all the values for the available modes then this callback
can be used to restrict the number of modes to only the ones that
can be displayed.
Since this function is both called from the check phase of an atomic
commit, and the mode validation in the probe paths it is not allowed
to look at anything else but the passed-in mode, and validate it
against configuration-invariant hardware constraints. Any further
limits which depend upon the configuration can only be checked in
mode_fixup or atomic_check.
RETURNS:
drm_mode_status Enum
mode_fixup
This callback is used to validate and adjust a mode. The parameter
mode is the display mode that should be fed to the next element in
the display chain, either the final drm_connector or a drm_bridge.
The parameter adjusted_mode is the input mode the encoder requires. It
can be modified by this callback and does not need to match mode. See
also drm_crtc_state.adjusted_mode for more details.
This function is used by both legacy CRTC helpers and atomic helpers.
This hook is optional.
NOTE:
This function is called in the check phase of atomic modesets, which
can be aborted for any reason (including on userspace’s request to
just check whether a configuration would be possible). Atomic drivers
MUST NOT touch any persistent state (hardware or software) or data
structures except the passed in adjusted_mode parameter.
This is in contrast to the legacy CRTC helpers where this was
allowed.
Atomic drivers which need to inspect and adjust more state should
instead use the atomic_check callback. If atomic_check is used,
this hook isn’t called since atomic_check allows a strict superset
of the functionality of mode_fixup.
Also beware that userspace can request its own custom modes, neither
core nor helpers filter modes to the list of probe modes reported by
the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure
that modes are filtered consistently put any encoder constraints and
limits checks into mode_valid.
RETURNS:
True if an acceptable configuration is possible, false if the modeset
operation should be rejected.
prepare
This callback should prepare the encoder for a subsequent modeset,
which in practice means the driver should disable the encoder if it
is running. Most drivers ended up implementing this by calling their
dpms hook with DRM_MODE_DPMS_OFF.
This callback is used by the legacy CRTC helpers. Atomic helpers
also support using this hook for disabling an encoder to facilitate
transitions to atomic, but it is deprecated. Instead disable should
be used.
commit
This callback should commit the new mode on the encoder after a modeset,
which in practice means the driver should enable the encoder. Most
drivers ended up implementing this by calling their dpms hook with
DRM_MODE_DPMS_ON.
This callback is used by the legacy CRTC helpers. Atomic helpers
also support using this hook for enabling an encoder to facilitate
transitions to atomic, but it is deprecated. Instead enable should
be used.
mode_set
This callback is used to update the display mode of an encoder.
Note that the display pipe is completely off when this function is
called. Drivers which need hardware to be running before they program
the new display mode (because they implement runtime PM) should not
use this hook, because the helper library calls it only once and not
every time the display pipeline is suspend using either DPMS or the
new “ACTIVE” property. Such drivers should instead move all their
encoder setup into the enable callback.
This callback is used both by the legacy CRTC helpers and the atomic
modeset helpers. It is optional in the atomic helpers.
NOTE:
If the driver uses the atomic modeset helpers and needs to inspect
the connector state or connector display info during mode setting,
atomic_mode_set can be used instead.
atomic_mode_set
This callback is used to update the display mode of an encoder.
Note that the display pipe is completely off when this function is
called. Drivers which need hardware to be running before they program
the new display mode (because they implement runtime PM) should not
use this hook, because the helper library calls it only once and not
every time the display pipeline is suspended using either DPMS or the
new “ACTIVE” property. Such drivers should instead move all their
encoder setup into the enable callback.
This callback is used by the atomic modeset helpers in place of the
mode_set callback, if set by the driver. It is optional and should
be used instead of mode_set if the driver needs to inspect the
connector state or display info, since there is no direct way to
go from the encoder to the current connector.
detect
This callback can be used by drivers who want to do detection on the
encoder object instead of in connector functions.
It is not used by any helper and therefore has purely driver-specific
semantics. New drivers shouldn’t use this and instead just implement
their own private callbacks.
FIXME:
This should just be converted into a pile of driver vfuncs.
Currently radeon, amdgpu and nouveau are using it.
atomic_disable
This callback should be used to disable the encoder. With the atomic
drivers it is called before this encoder’s CRTC has been shut off
using their own drm_crtc_helper_funcs.atomic_disable hook. If that
sequence is too simple drivers can just add their own driver private
encoder hooks and call them from CRTC’s callback by looping over all
encoders connected to it using for_each_encoder_on_crtc().
This callback is a variant of disable that provides the atomic state
to the driver. If atomic_disable is implemented, disable is not
called by the helpers.
This hook is only used by atomic helpers. Atomic drivers don’t need
to implement it if there’s no need to disable anything at the encoder
level. To ensure that runtime PM handling (using either DPMS or the
new “ACTIVE” property) works atomic_disable must be the inverse of
atomic_enable.
atomic_enable
This callback should be used to enable the encoder. It is called
after this encoder’s CRTC has been enabled using their own
drm_crtc_helper_funcs.atomic_enable hook. If that sequence is
too simple drivers can just add their own driver private encoder
hooks and call them from CRTC’s callback by looping over all encoders
connected to it using for_each_encoder_on_crtc().
This callback is a variant of enable that provides the atomic state
to the driver. If atomic_enable is implemented, enable is not
called by the helpers.
This hook is only used by atomic helpers, it is the opposite of
atomic_disable. Atomic drivers don’t need to implement it if there’s
no need to enable anything at the encoder level. To ensure that
runtime PM handling works atomic_enable must be the inverse of
atomic_disable.
disable
This callback should be used to disable the encoder. With the atomic
drivers it is called before this encoder’s CRTC has been shut off
using their own drm_crtc_helper_funcs.disable hook. If that
sequence is too simple drivers can just add their own driver private
encoder hooks and call them from CRTC’s callback by looping over all
encoders connected to it using for_each_encoder_on_crtc().
This hook is used both by legacy CRTC helpers and atomic helpers.
Atomic drivers don’t need to implement it if there’s no need to
disable anything at the encoder level. To ensure that runtime PM
handling (using either DPMS or the new “ACTIVE” property) works
disable must be the inverse of enable for atomic drivers.
For atomic drivers also consider atomic_disable and save yourself
from having to read the NOTE below!
NOTE:
With legacy CRTC helpers there’s a big semantic difference between
disable and other hooks (like prepare or dpms) used to shut down a
encoder: disable is only called when also logically disabling the
display pipeline and needs to release any resources acquired in
mode_set (like shared PLLs, or again release pinned framebuffers).
Therefore disable must be the inverse of mode_set plus commit for
drivers still using legacy CRTC helpers, which is different from the
rules under atomic.
enable
This callback should be used to enable the encoder. With the atomic
drivers it is called after this encoder’s CRTC has been enabled using
their own drm_crtc_helper_funcs.enable hook. If that sequence is
too simple drivers can just add their own driver private encoder
hooks and call them from CRTC’s callback by looping over all encoders
connected to it using for_each_encoder_on_crtc().
This hook is only used by atomic helpers, it is the opposite of
disable. Atomic drivers don’t need to implement it if there’s no
need to enable anything at the encoder level. To ensure that
runtime PM handling (using either DPMS or the new “ACTIVE” property)
works enable must be the inverse of disable for atomic drivers.
atomic_check
This callback is used to validate encoder state for atomic drivers.
Since the encoder is the object connecting the CRTC and connector it
gets passed both states, to be able to validate interactions and
update the CRTC to match what the encoder needs for the requested
connector.
Since this provides a strict superset of the functionality of
mode_fixup (the requested and adjusted modes are both available
through the passed in structdrm_crtc_state) mode_fixup is not
called when atomic_check is implemented.
This function is used by the atomic helpers, but it is optional.
NOTE:
This function is called in the check phase of an atomic update. The
driver is not allowed to change anything outside of the free-standing
state objects passed-in or assembled in the overall drm_atomic_state
update tracking structure.
Also beware that userspace can request its own custom modes, neither
core nor helpers filter modes to the list of probe modes reported by
the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure
that modes are filtered consistently put any encoder constraints and
limits checks into mode_valid.
RETURNS:
0 on success, -EINVAL if the state or the transition can’t be
supported, -ENOMEM on memory allocation failure and -EDEADLK if an
attempt to obtain another state object ran into a drm_modeset_lock
deadlock.
Description
These hooks are used by the legacy CRTC helpers and the new atomic
modesetting helpers.
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 drive a
fixed panel can also manually add specific modes using
drm_mode_probed_add(). Drivers which manually add modes should also
make sure that the drm_connector.display_info,
drm_connector.width_mm and drm_connector.height_mm fields are
filled in.
Note that the caller function will automatically add standard VESA
DMT modes up to 1024x768 if the .get_modes() helper operation returns
no mode and if the connector status is connector_status_connected or
connector_status_unknown. There is no need to call
drm_add_modes_noedid() manually in that case.
This function is only called after the detect hook has indicated
that a sink is connected and when the EDID isn’t overridden through
sysfs or the kernel commandline.
The number of modes added by calling drm_mode_probed_add(). Return 0
on failures (no modes) instead of negative error codes.
detect_ctx
Check to see if anything is attached to the connector. The parameter
force is set to false whilst polling, true when checking the
connector due to a user request. force can be used by the driver to
avoid expensive, destructive operations during automated probing.
This callback is optional, if not implemented the connector will be
considered as always being attached.
To avoid races against concurrent connector state updates, the
helper libraries always call this with ctx set to a valid context,
and drm_mode_config.connection_mutex will always be locked with
the ctx parameter set to this ctx. This allows taking additional
locks as required.
Callback to validate a mode for a connector, irrespective of the
specific display configuration.
This callback is used by the probe helpers to filter the mode list
(which is usually derived from the EDID data block from the sink).
See e.g. drm_helper_probe_single_connector_modes().
This function is optional.
NOTE:
This only filters the mode list supplied to userspace in the
GETCONNECTOR IOCTL. Compared to drm_encoder_helper_funcs.mode_valid,
drm_crtc_helper_funcs.mode_valid and drm_bridge_funcs.mode_valid,
which are also called by the atomic helpers from
drm_atomic_helper_check_modeset(). This allows userspace to force and
ignore sink constraint (like the pixel clock limits in the screen’s
EDID), which is useful for e.g. testing, or working around a broken
EDID. Any source hardware constraint (which always need to be
enforced) therefore should be checked in one of the above callbacks,
and not this one here.
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().
To allow for accessing the atomic state of modesetting objects, the
helper libraries always call this with ctx set to a valid context,
and drm_mode_config.connection_mutex will always be locked with
the ctx parameter set to ctx. This allows for taking additional
locks as required.
Even though additional locks may be acquired, this callback is
still expected not to take any constraints into account which would
be influenced by the currently set display state - such constraints
should be handled in the driver’s atomic check. For example, if a
connector shares display bandwidth with other connectors then it
would be ok to validate the minimum bandwidth requirement of a mode
against the maximum possible bandwidth of the connector. But it
wouldn’t be ok to take the current bandwidth usage of other
connectors into account, as this would change depending on the
display state.
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. In this case, the core will call
drm_connector_get_single_encoder() for you.
RETURNS:
Encoder that should be used for the given connector and connector
state, or NULL if no suitable encoder exists. Note that the helpers
will ensure that encoders aren’t used twice, drivers should not check
for this.
atomic_best_encoder
This is the atomic version of best_encoder for atomic drivers which
need to select the best encoder depending upon the desired
configuration and can’t select it statically.
This function is used by drm_atomic_helper_check_modeset().
If it is not implemented, the core will fallback to best_encoder
(or drm_connector_get_single_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
drm_atomic_state update tracking structure passed in.
RETURNS:
Encoder that should be used for the given connector and connector
state, or NULL if no suitable encoder exists. Note that the helpers
will ensure that encoders aren’t used twice, drivers should not check
for this.
atomic_check
This hook is used to validate connector state. This function is
called from drm_atomic_helper_check_modeset, and is called when
a connector property is set, or a modeset on the crtc is forced.
Because drm_atomic_helper_check_modeset may be called multiple times,
this function should handle being called multiple times as well.
This function is also allowed to inspect any other object’s state and
can add more state objects to the atomic commit if needed. Care must
be taken though to ensure that state check and compute functions for
these added states are all called, and derived state in other objects
all updated. Again the recommendation is to just call check helpers
until a maximal configuration is reached.
NOTE:
This function is called in the check phase of an atomic update. The
driver is not allowed to change anything outside of the free-standing
state objects passed-in or assembled in the overall drm_atomic_state
update tracking structure.
RETURNS:
0 on success, -EINVAL if the state or the transition can’t be
supported, -ENOMEM on memory allocation failure and -EDEADLK if an
attempt to obtain another state object ran into a drm_modeset_lock
deadlock.
atomic_commit
This hook is to be used by drivers implementing writeback connectors
that need a point when to commit the writeback job to the hardware.
The writeback_job to commit is available in the new connector state,
in drm_connector_state.writeback_job.
This hook is optional.
This callback is used by the atomic modeset helpers.
prepare_writeback_job
As writeback jobs contain a framebuffer, drivers may need to
prepare and clean them up the same way they can prepare and
clean up framebuffers for planes. This optional connector operation
is used to support the preparation of writeback jobs. The job
prepare operation is called from drm_atomic_helper_prepare_planes()
for struct drm_writeback_connector connectors only.
This operation is optional.
This callback is used by the atomic modeset helpers.
cleanup_writeback_job
This optional connector operation is used to support the
cleanup of writeback jobs. The job cleanup operation is called
from the existing drm_writeback_cleanup_job() function, invoked
both when destroying the job as part of an aborted commit, or when
the job completes.
This operation is optional.
This callback is used by the atomic modeset helpers.
This operation does not need to perform any hpd state tracking as
the DRM core handles that maintenance and ensures the calls to enable
and disable hpd are balanced.
This operation does not need to perform any hpd state tracking as
the DRM core handles that maintenance and ensures the calls to enable
and disable hpd are balanced.
Description
These functions are used by the atomic and legacy modeset helpers and by the
probe helpers.
This hook is to prepare a framebuffer for scanout by e.g. pinning
its backing storage or relocating it into a contiguous block of
VRAM. Other possible preparatory work includes flushing caches.
This function must not block for outstanding rendering, since it is
called in the context of the atomic IOCTL even for async commits to
be able to return any errors to userspace. Instead the recommended
way is to fill out the drm_plane_state.fence of the passed-in
drm_plane_state. If the driver doesn’t support native fences then
equivalent functionality should be implemented through private
members in the plane structure.
For GEM drivers who neither have a prepare_fb nor cleanup_fb hook
set drm_gem_plane_helper_prepare_fb() is called automatically to
implement this. Other drivers which need additional plane processing
can call drm_gem_plane_helper_prepare_fb() from their prepare_fb
hook.
The resources acquired in prepare_fb persist after the end of
the atomic commit. Resources that can be release at the commit’s end
should be acquired in begin_fb_access and released in end_fb_access.
For example, a GEM buffer’s pin operation belongs into prepare_fb to
keep the buffer pinned after the commit. But a vmap operation for
shadow-plane helpers belongs into begin_fb_access, so that atomic
helpers remove the mapping at the end of the commit.
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, but it is
optional. See begin_fb_access for preparing per-commit resources.
RETURNS:
0 on success or one of the following negative error codes allowed by
the drm_mode_config_funcs.atomic_commit vfunc. When using helpers
this callback is the only one which can fail an atomic commit,
everything else must complete successfully.
cleanup_fb
This hook is called to clean up any resources allocated for the given
framebuffer and plane configuration in prepare_fb.
This callback is used by the atomic modeset helpers, but it is
optional.
begin_fb_access
This hook prepares the plane for access during an atomic commit.
In contrast to prepare_fb, resources acquired in begin_fb_access,
are released at the end of the atomic commit in end_fb_access.
For example, with shadow-plane helpers, the GEM buffer’s vmap
operation belongs into begin_fb_access, so that the buffer’s
memory will be unmapped at the end of the commit in end_fb_access.
But a GEM buffer’s pin operation belongs into prepare_fb
to keep the buffer pinned after the commit.
The callback is used by the atomic modeset helpers, but it is optional.
See end_fb_cleanup for undoing the effects of begin_fb_access and
prepare_fb for acquiring resources until the next pageflip.
Returns:
0 on success, or a negative errno code otherwise.
end_fb_access
This hook cleans up resources allocated by begin_fb_access. It it called
at the end of a commit for the new plane state.
atomic_check
Drivers should check plane specific constraints in this hook.
When using drm_atomic_helper_check_planes() plane’s atomic_check
hooks are called before the ones for CRTCs, which allows drivers to
request shared resources that the CRTC controls here. For more
complicated dependencies the driver can call the provided check helpers
multiple times until the computed state has a final configuration and
everything has been checked.
This function is also allowed to inspect any other object’s state and
can add more state objects to the atomic commit if needed. Care must
be taken though to ensure that state check and compute functions for
these added states are all called, and derived state in other objects
all updated. Again the recommendation is to just call check helpers
until a maximal configuration is reached.
This callback is used by the atomic modeset helpers, 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
drm_atomic_state update tracking structure.
RETURNS:
0 on success, -EINVAL if the state or the transition can’t be
supported, -ENOMEM on memory allocation failure and -EDEADLK if an
attempt to obtain another state object ran into a drm_modeset_lock
deadlock.
atomic_update
Drivers should use this function to update the plane state. This
hook is called in-between the drm_crtc_helper_funcs.atomic_begin and
drm_crtc_helper_funcs.atomic_flush callbacks.
Note that the power state of the display pipe when this function is
called depends upon the exact helpers and calling sequence the driver
has picked. See drm_atomic_helper_commit_planes() for a discussion of
the tradeoffs and variants of plane commit helpers.
This callback is used by the atomic modeset helpers, but it is optional.
atomic_enable
Drivers should use this function to unconditionally enable a plane.
This hook is called in-between the drm_crtc_helper_funcs.atomic_begin
and drm_crtc_helper_funcs.atomic_flush callbacks. It is called after
atomic_update, which will be called for all enabled planes. Drivers
that use atomic_enable should set up a plane in atomic_update and
afterwards enable the plane in atomic_enable. If a plane needs to be
enabled before installing the scanout buffer, drivers can still do
so in atomic_update.
Note that the power state of the display pipe when this function is
called depends upon the exact helpers and calling sequence the driver
has picked. See drm_atomic_helper_commit_planes() for a discussion of
the tradeoffs and variants of plane commit helpers.
This callback is used by the atomic modeset helpers, but it is
optional. If implemented, atomic_enable should be the inverse of
atomic_disable. Drivers that don’t want to use either can still
implement the complete plane update in atomic_update.
atomic_disable
Drivers should use this function to unconditionally disable a plane.
This hook is called in-between the
drm_crtc_helper_funcs.atomic_begin and
drm_crtc_helper_funcs.atomic_flush callbacks. It is an alternative to
atomic_update, which will be called for disabling planes, too, if
the atomic_disable hook isn’t implemented.
Note that the power state of the display pipe when this function is
called depends upon the exact helpers and calling sequence the driver
has picked. See drm_atomic_helper_commit_planes() for a discussion of
the tradeoffs and variants of plane commit helpers.
This callback is used by the atomic modeset helpers, but it is
optional. It’s intended to reverse the effects of atomic_enable.
atomic_async_check
Drivers should set this function pointer to check if the plane’s
atomic state can be updated in a async fashion. Here async means
“not vblank synchronized”.
This hook is called by drm_atomic_async_check() to establish if a
given update can be committed asynchronously, that is, if it can
jump ahead of the state currently queued for update.
This function is also used by drm_atomic_set_property() to determine
if the plane can be flipped in async. The flip flag is used to
distinguish if the function is used for just the plane state or for a
flip.
RETURNS:
Return 0 on success and any error returned indicates that the update
can not be applied in asynchronous manner.
atomic_async_update
Drivers should set this function pointer to perform asynchronous
updates of planes, that is, jump ahead of the currently queued
state and update the plane. Here async means “not vblank
synchronized”.
An async update will happen on legacy cursor updates. An async
update won’t happen if there is an outstanding commit modifying
the same plane.
When doing async_update drivers shouldn’t replace the
drm_plane_state but update the current one with the new plane
configurations in the new plane_state.
Drivers should also swap the framebuffers between current plane
state (drm_plane.state) and new_state.
This is required since cleanup for async commits is performed on
the new state, rather than old state like for traditional commits.
Since we want to give up the reference on the current (old) fb
instead of our brand new one, swap them in the driver during the
async commit.
FIXME:
It only works for single plane updates
Async Pageflips are not supported yet
Some hw might still scan out the old buffer until the next
vblank, however we let go of the fb references as soon as
we run this hook. For now drivers must implement their own workers
for deferring if needed, until a common solution is created.
get_scanout_buffer
Get the current scanout buffer, to display a message with drm_panic.
The driver should do the minimum changes to provide a buffer,
that can be used to display the panic screen. Currently only linear
buffers are supported. Non-linear buffer support is on the TODO list.
The device dev.mode_config.panic_lock is taken before calling this
function, so you can safely access the plane.state
It is called from a panic callback, and must follow its restrictions.
Please look the documentation at drm_panic_trylock() for an in-depth
discussions of what’s safe and what is not allowed.
It’s a best effort mode, so it’s expected that in some complex cases
the panic screen won’t be displayed.
The returned drm_scanout_buffer.map must be valid if no error code is
returned.
Return:
0 on success, negative errno on failure.
panic_flush
It is used by drm_panic, and is called after the panic screen is
drawn to the scanout buffer. In this function, the driver
can send additional commands to the hardware, to make the scanout
buffer visible.
It is only called if get_scanout_buffer() returned successfully, and
the dev.mode_config.panic_lock is held during the entire sequence.
It is called from a panic callback, and must follow its restrictions.
Please look the documentation at drm_panic_trylock() for an in-depth
discussions of what’s safe and what is not allowed.
This hook is used by the default atomic_commit() hook implemented in
drm_atomic_helper_commit() together with the nonblocking commit
helpers (see drm_atomic_helper_setup_commit() for a starting point)
to implement blocking and nonblocking commits easily. It is not used
by the atomic helpers
This function is called when the new atomic state has already been
swapped into the various state pointers. The passed in state
therefore contains copies of the old/previous state. This hook should
commit the new state into hardware. Note that the helpers have
already waited for preceding atomic commits and fences, but drivers
can add more waiting calls at the start of their implementation, e.g.
to wait for driver-internal request for implicit syncing, before
starting to commit the update to the hardware.
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 used by the default atomic_commit() hook implemented in
drm_atomic_helper_commit() together with the nonblocking helpers (see
drm_atomic_helper_setup_commit()) to extend the DRM commit setup. It
is not used by the atomic helpers.
This function is called at the end of
drm_atomic_helper_setup_commit(), so once the commit has been
properly setup across the generic DRM object states. It allows
drivers to do some additional commit tracking that isn’t related to a
CRTC, plane or connector, tracked in a drm_private_obj structure.
Note that the documentation of drm_private_obj has more details on
how one should implement this.
This hook is optional.
Description
These helper functions are used by the atomic helpers.
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(), and the various functions to implement
set_property callbacks. New drivers must not implement these functions
themselves but must use the provided helpers.
Nonblocking atomic commits should use struct drm_crtc_commit to sequence
different operations against each another. Locks, especially struct
drm_modeset_lock, should not be held in worker threads or any other
asynchronous context used to commit the hardware state.
1. Run drm_atomic_helper_prepare_planes(). Since this can fail and we
need to propagate out of memory/VRAM errors to userspace, it must be called
synchronously.
2. Synchronize with any outstanding nonblocking commit worker threads which
might be affected by the new state update. This is handled by
drm_atomic_helper_setup_commit().
Asynchronous workers need to have sufficient parallelism to be able to run
different atomic commits on different CRTCs in parallel. The simplest way to
achieve this is by running them on the system_unbound_wq work queue. Note
that drivers are not required to split up atomic commits and run an
individual commit in parallel - userspace is supposed to do that if it cares.
But it might be beneficial to do that for modesets, since those necessarily
must be done as one global operation, and enabling or disabling a CRTC can
take a long time. But even that is not required.
IMPORTANT: A drm_atomic_state update for multiple CRTCs is sequenced
against all CRTCs therein. Therefore for atomic state updates which only flip
planes the driver must not get the struct drm_crtc_state of unrelated CRTCs
in its atomic check code: This would prevent committing of atomic updates to
multiple CRTCs in parallel. In general, adding additional state structures
should be avoided as much as possible, because this reduces parallelism in
(nonblocking) commits, both due to locking and due to commit sequencing
requirements.
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. Note that commit
workers do not hold any locks; their access is only coordinated through
ordering. If workers would access state only through the pointers in the
free-standing state objects (currently not the case for any driver) then even
multiple pending commits could be in-flight at the same time.
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 scheduled work should synchronize against other workers
using the drm_crtc_commit infrastructure as needed. See
drm_atomic_helper_setup_commit() for more details.
Similar to drm_crtc_for_each_plane(), but iterates the planes that will be
attached if the specified state is applied. Useful during for example
in code called from drm_mode_config_funcs.atomic_check operations, to
validate the incoming state.
Similar to drm_crtc_for_each_plane(), but iterates the planes that will be
attached if the specified state is applied. Useful during for example
in code called from drm_mode_config_funcs.atomic_check operations, to
validate the incoming state.
Compared to just drm_atomic_crtc_state_for_each_plane() this also fills in a
const plane_state. This is useful when a driver just wants to peek at other
active planes on this CRTC, but does not need to change it.
Checks the atomic state of a plane to determine whether it’s being enabled
or not. This also WARNs if it detects an invalid state (both CRTC and FB
need to either both be NULL or both be non-NULL).
Return
True if the plane is being enabled, false otherwise.
Checks the atomic state of a plane to determine whether it’s being disabled
or not. This also WARNs if it detects an invalid state (both CRTC and FB
need to either both be NULL or both be non-NULL).
Return
True if the plane is being disabled, false otherwise.
Check the state object to see if the requested state is physically possible.
This does all the CRTC and connector related computations for an atomic
update and adds any additional connectors needed for full modesets. It calls
the various per-object callbacks in the follow order:
drm_encoder_helper_funcs.atomic_check is called to validate any encoder state.
This function is only called when the encoder will be part of a configured CRTC,
it must not be used for implementing connector property validation.
If this function is NULL, drm_atomic_encoder_helper_funcs.mode_fixup is called
instead.
Drivers which set drm_crtc_state.mode_changed (e.g. in their
drm_plane_helper_funcs.atomic_check hooks if a plane update can’t be done
without a full modeset) _must_ call this function after that change. It is
permitted to call this function multiple times for the same update, e.g.
when the drm_crtc_helper_funcs.atomic_check functions depend upon the
adjusted dotclock for fifo space allocation and watermark computation.
minimum src:dest scaling factor in 16.16 fixed point
intmax_scale
maximum src:dest scaling factor in 16.16 fixed point
boolcan_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.
boolcan_update_disabled
can the plane be updated while the CRTC
is disabled?
Description
Checks that a desired plane update is valid, and updates various
bits of derived state (clipped coordinates etc.). Drivers that provide
their own plane handling rather than helper-provided implementations may
still wish to call this function to avoid duplication of error checking
code.
Return
Zero if update appears valid, error code on failure
Checks that a CRTC has at least one primary plane attached to it, which is
a requirement on some hardware. Note that this only involves the CRTC side
of the test. To test if the primary plane is visible or if it can be updated
without the CRTC being enabled, use drm_atomic_helper_check_plane_state() in
the plane’s atomic check.
Return
0 if a primary plane is attached to the CRTC, or an error code otherwise
Check the state object to see if the requested state is physically possible.
Only CRTCs and planes have check callbacks, so for any additional (global)
checking that a driver needs it can simply wrap that around this function.
Drivers without such needs can directly use this as their
drm_mode_config_funcs.atomic_check callback.
This just wraps the two parts of the state checking for planes and modeset
state in the default order: First it calls drm_atomic_helper_check_modeset()
and then drm_atomic_helper_check_planes(). The assumption is that the
drm_plane_helper_funcs.atomic_check and drm_crtc_helper_funcs.atomic_check
functions depend upon an updated adjusted_mode.clock to e.g. properly compute
watermarks.
Note that zpos normalization will add all enable planes to the state which
might not desired for some drivers.
For example enable/disable of a cursor plane which have fixed zpos value
would trigger all other enabled planes to be forced to the state change.
This function updates all the various legacy modeset state pointers in
connectors, encoders and CRTCs.
Drivers can use this for building their own atomic commit if they don’t have
a pure helper-based modeset implementation.
Since these updates are not synchronized with lockings, only code paths
called from drm_mode_config_helper_funcs.atomic_commit_tail can look at the
legacy state filled out by this helper. Defacto this means this helper and
the legacy state pointers are only really useful for transitioning an
existing driver to the atomic world.
Loops over all connectors in the current state and if the mode has
changed, change the mode of the CRTC, then call down the bridge
chain and change the mode in all bridges as well.
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.
This loops over the connectors, checks if the new state requires
a writeback job to be issued and in that case issues an atomic
commit on each connector.
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.
If true, do an interruptible wait, and state is the new state.
Otherwise state is the old state.
Description
For implicit sync, driver should fish the exclusive fence out from the
incoming fb’s and stash it in the drm_plane_state. This is called after
drm_atomic_helper_swap_state() so it uses the current plane state (and
just uses the atomic state to find the changed planes)
Note that pre_swap is needed since the point where we block for fences moves
around depending upon whether an atomic commit is blocking or
non-blocking. For non-blocking commit all waiting needs to happen after
drm_atomic_helper_swap_state() is called, but for blocking commits we want
to wait before we do anything that can’t be easily rolled back. That is
before we call drm_atomic_helper_swap_state().
Helper to, after atomic commit, wait for vblanks on all affected
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.
Helper to, after atomic commit, wait for page flips on all affected
crtcs (ie. before cleaning up old framebuffers using
drm_atomic_helper_cleanup_planes()). Compared to
drm_atomic_helper_wait_for_vblanks() this waits for the completion on all
CRTCs, assuming that cursors-only updates are signalling their completion
immediately (or using a different path).
This helper will check if it is possible to commit the state asynchronously.
Async commits are not supposed to swap the states like normal sync commits
but just do in-place changes on the current state.
It will return 0 if the commit can happen in an asynchronous fashion or error
if not. Note that error just mean it can’t be committed asynchronously, if it
fails the commit should be treated like a normal synchronous commit.
This function commits a state asynchronously, i.e., not vblank
synchronized. It should be used on a state only when
drm_atomic_async_check() succeeds. Async commits are not supposed to swap
the states like normal sync commits, but just do in-place changes on the
current state.
TODO: Implement full swap instead of doing in-place changes.
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.
This function prepares state to be used by the atomic helper’s support for
nonblocking commits. Drivers using the nonblocking commit infrastructure
should always call this function from their
drm_mode_config_funcs.atomic_commit hook.
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().
This is all implemented by in drm_atomic_helper_commit(), giving drivers a
complete and easy-to-use default implementation of the atomic_commit() hook.
The tracking of asynchronously executed and still pending commits is done
using the core structure drm_crtc_commit.
By default there’s no need to clean up resources allocated by this function
explicitly: drm_atomic_state_default_clear() will take care of that
automatically.
Return
0 on success. -EBUSY when userspace schedules nonblocking commits too fast,
-ENOMEM on allocation failures and -EINTR when a signal is pending.
This function walks all CRTCs and fakes VBLANK events on those with
drm_crtc_state.no_vblank set to true and drm_crtc_state.event != NULL.
The primary use of this function is writeback connectors working in oneshot
mode and faking VBLANK events. In this case they only fake the VBLANK event
when a job is queued, and any change to the pipeline that does not touch the
connector is leading to timeouts when calling
drm_atomic_helper_wait_for_vblanks() or
drm_atomic_helper_wait_for_flip_done(). In addition to writeback
connectors, this function can also fake VBLANK events for CRTCs without
VBLANK interrupt.
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 signals completion of the atomic update state, including any
cleanup work. If used, it must be called right before calling
drm_atomic_state_put().
This function prepares plane state, specifically framebuffers, for the new
configuration, by calling drm_plane_helper_funcs.prepare_fb. If any failure
is encountered this function will call drm_plane_helper_funcs.cleanup_fb on
any already successfully prepared framebuffer.
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 state to know which planes and
crtcs need to be updated though.
Note that this function does all plane updates across all CRTCs in one step.
If the hardware can’t support this approach look at
drm_atomic_helper_commit_planes_on_crtc() instead.
Plane parameters can be updated by applications while the associated CRTC is
disabled. The DRM/KMS core will store the parameters in the plane state,
which will be available to the driver when the CRTC is turned on. As a result
most drivers don’t need to be immediately notified of plane updates for a
disabled CRTC.
Unless otherwise needed, drivers are advised to set the ACTIVE_ONLY flag in
flags in order not to receive plane update notifications related to a
disabled CRTC. This avoids the need to manually ignore plane updates in
driver code when the driver and/or hardware can’t or just don’t need to deal
with updates on disabled CRTCs, for example when supporting runtime PM.
Drivers may set the NO_DISABLE_AFTER_MODESET flag in flags if the relevant
display controllers require to disable a CRTC’s planes when the CRTC is
disabled. This function would skip the drm_plane_helper_funcs.atomic_disable
call for a plane if the CRTC of the old plane state needs a modesetting
operation. Of course, the drivers need to disable the planes in their CRTC
disable callbacks since no one else would do that.
The drm_atomic_helper_commit() default implementation doesn’t set the
ACTIVE_ONLY flag to most closely match the behaviour of the legacy helpers.
This should not be copied blindly by drivers.
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
dependencies. Callers need to ensure that either no such dependencies exist,
resolve them through ordering of commit calls or through some other means.
This function cleans up plane state, specifically framebuffers, from the old
configuration. Hence the old configuration must be perserved in state to
be able to call this function.
This function stores the atomic state into the current state pointers in all
driver objects. It should be called after all failing steps have been done
and succeeded, but before the actual hardware state is committed.
For cleanup and error recovery the current state for all changed objects will
be swapped into state.
With that sequence it fits perfectly into the plane prepare/cleanup sequence:
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 drm_plane.state, drm_crtc.state or drm_connector.state pointer. With
the current atomic helpers this is almost always the case, since the helpers
don’t pass the right state structures to the callbacks.
Return
Returns 0 on success. Can return -ERESTARTSYS when stall is true and the
waiting for the previous commits has been interrupted.
Provides a default CRTC set_config handler using the atomic driver interface.
NOTE
For backwards compatibility with old userspace this automatically
resets the “link-status” property to GOOD, to force any link
re-training. The SETCRTC ioctl does not define whether an update does
need a full modeset or just a plane update, hence we’re allowed to do
that. See also drm_connector_set_link_status_property().
Return
Returns 0 on success, negative errno numbers on failure.
Loops through all connectors, finding those that aren’t turned off and then
turns them off by setting their DPMS mode to OFF and deactivating the CRTC
that they are connected to.
This is used for example in suspend/resume to disable all currently active
functions when suspending. If you just want to shut down everything at e.g.
driver unload, look at drm_atomic_helper_shutdown().
Note that if callers haven’t already acquired all modeset locks this might
return -EDEADLK, which must be handled by calling drm_modeset_backoff().
Reset the active outputs by indicating that connectors have changed.
This implies a reset of all active components available between the CRTC and
connectors.
A variant of this function exists with
drm_bridge_helper_reset_crtc(), dedicated to bridges.
NOTE
This relies on resetting drm_crtc_state.connectors_changed.
For drivers which optimize out unnecessary modesets this will result in
a no-op commit, achieving nothing.
This shuts down all CRTC, which is useful for driver unloading. Shutdown on
suspend should instead be handled with drm_atomic_helper_suspend(), since
that also takes a snapshot of the modeset state to be restored on resume.
Makes a copy of the current atomic state by looping over all objects and
duplicating their respective states. This is used for example by suspend/
resume support code to save the state prior to suspend such that it can
be restored upon resume.
Note that this treats atomic state as persistent between save and restore.
Drivers must make sure that this is possible and won’t result in confusion
or erroneous behaviour.
Note that if callers haven’t already acquired all modeset locks this might
return -EDEADLK, which must be handled by calling drm_modeset_backoff().
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.
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.
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.
Propagate output format to the input end of a bridge
Parameters
structdrm_bridge*bridge
bridge control structure
structdrm_bridge_state*bridge_state
new bridge state
structdrm_crtc_state*crtc_state
new CRTC state
structdrm_connector_state*conn_state
new connector state
u32output_fmt
tested output bus format
unsignedint*num_input_fmts
will contain the size of the returned array
Description
This helper is a pluggable implementation of the
drm_bridge_funcs.atomic_get_input_bus_fmts operation for bridges that don’t
modify the bus configuration between their input and their output. It
returns an array of input formats with a single element set to output_fmt.
Return
a valid format array of size num_input_fmts, or NULL if the allocation
failed
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.
Initializes the newly allocated crtc_state and assigns it to
the drm_crtc->state pointer of crtc, usually required when
initializing the drivers or when called from the drm_crtc_funcs.reset
hook.
This is useful for drivers that subclass the CRTC state.
Releases all resources stored in the CRTC state without actually freeing
the memory of the CRTC state. This is useful for drivers that subclass the
CRTC state.
Initializes the newly allocated plane_state and assigns it to
the drm_crtc->state pointer of plane, usually required when
initializing the drivers or when called from the drm_plane_funcs.reset
hook.
This is useful for drivers that subclass the plane state.
Resets the atomic state for plane by freeing the state pointer (which might
be NULL, e.g. at driver load time) and allocating a new empty state object.
Releases all resources stored in the plane state without actually freeing
the memory of the plane state. This is useful for drivers that subclass the
plane state.
Initializes the newly allocated conn_state and assigns it to
the drm_connector->state pointer of connector, usually required when
initializing the drivers or when called from the drm_connector_funcs.reset
hook.
This is useful for drivers that subclass the connector state.
Resets the atomic state for connector by freeing the state pointer (which
might be NULL, e.g. at driver load time) and allocating a new empty state
object.
Releases all resources stored in the connector state without actually
freeing the memory of the connector state. This is useful for drivers that
subclass the connector state.
Allocates a new bridge state and initializes it with the current bridge
state values. This helper is meant to be used as a bridge
drm_bridge_funcs.atomic_duplicate_state hook for bridges that don’t
subclass the bridge state.
Initializes the bridge state to default values. This is meant to be called
by the bridge drm_bridge_funcs.atomic_reset hook for bridges that subclass
the bridge state.
Allocate and initialize a bridge state to its default
Parameters
structdrm_bridge*bridge
the bridge this state refers to
Description
Allocates the bridge state and initializes it to default values. This helper
is meant to be used as a bridge drm_bridge_funcs.atomic_reset hook for
bridges that don’t subclass the bridge state.
The GEM atomic helpers library implements generic atomic-commit
functions for drivers that use GEM objects. Currently, it provides
synchronization helpers, and plane state and framebuffer BO mappings
for planes with shadow buffers.
Before scanout, a plane’s framebuffer needs to be synchronized with
possible writers that draw into the framebuffer. All drivers should
call drm_gem_plane_helper_prepare_fb() from their implementation of
struct drm_plane_helper.prepare_fb . It sets the plane’s fence from
the framebuffer so that the DRM core can synchronize access automatically.
drm_gem_plane_helper_prepare_fb() can also be used directly as
implementation of prepare_fb.
A driver using a shadow buffer copies the content of the shadow buffers
into the HW’s framebuffer memory during an atomic update. This requires
a mapping of the shadow buffer into kernel address space. The mappings
cannot be established by commit-tail functions, such as atomic_update,
as this would violate locking rules around dma_buf_vmap().
The helpers for shadow-buffered planes establish and release mappings,
and provide structdrm_shadow_plane_state, which stores the plane’s mapping
for commit-tail functions.
Shadow-buffered planes can easily be enabled by using the provided macros
DRM_GEM_SHADOW_PLANE_FUNCS and DRM_GEM_SHADOW_PLANE_HELPER_FUNCS.
These macros set up the plane and plane-helper callbacks to point to the
shadow-buffer helpers.
voiddriver_plane_atomic_update(structdrm_plane*plane,structdrm_plane_state*old_plane_state){structdrm_plane_state*plane_state=plane->state;structdrm_shadow_plane_state*shadow_plane_state=to_drm_shadow_plane_state(plane_state);// access shadow buffer via shadow_plane_state->map}
A mapping address for each of the framebuffer’s buffer object is stored in
struct drm_shadow_plane_state.map. The mappings are valid while the state
is being used.
Drivers that use structdrm_simple_display_pipe can use
DRM_GEM_SIMPLE_DISPLAY_PIPE_SHADOW_PLANE_FUNCS to initialize the rsp
callbacks. Access to shadow-buffer mappings is similar to regular
atomic_update.
structdrm_simple_display_pipe_funcsdriver_pipe_funcs={...,DRM_GEM_SIMPLE_DISPLAY_PIPE_SHADOW_PLANE_FUNCS,};voiddriver_pipe_enable(structdrm_simple_display_pipe*pipe,structdrm_crtc_state*crtc_state,structdrm_plane_state*plane_state){structdrm_shadow_plane_state*shadow_plane_state=to_drm_shadow_plane_state(plane_state);// access shadow buffer via shadow_plane_state->map}
Maximum width of a plane’s shadow buffer in pixels
Description
For drivers with shadow planes, the maximum width of the framebuffer is
usually independent from hardware limitations. Drivers can initialize structdrm_mode_config.max_width from DRM_SHADOW_PLANE_MAX_WIDTH.
Maximum height of a plane’s shadow buffer in scanlines
Description
For drivers with shadow planes, the maximum height of the framebuffer is
usually independent from hardware limitations. Drivers can initialize structdrm_mode_config.max_height from DRM_SHADOW_PLANE_MAX_HEIGHT.
Per-plane state for format conversion.
Flags for copying shadow buffers into backend storage. Also holds
temporary storage for format conversion.
map
Mappings of the plane’s framebuffer BOs in to kernel address space
The memory mappings stored in map should be established in the plane’s
prepare_fb callback and removed in the cleanup_fb callback.
data
Address of each framebuffer BO’s data
The address of the data stored in each mapping. This is different
for framebuffers with non-zero offset fields.
Description
For planes that use a shadow buffer, structdrm_shadow_plane_state
provides the regular plane state plus mappings of the shadow buffer
into kernel address space.
Drivers may use GEM BOs as shadow buffers over the framebuffer memory. This
macro initializes structdrm_plane_helper_funcs to use the rsp helper
functions.
Drivers may use GEM BOs as shadow buffers over the framebuffer memory. This
macro initializes structdrm_simple_display_pipe_funcs to use the rsp helper
functions.
This function extracts the exclusive fence from drm_gem_object.resv and
attaches it to plane state for the atomic helper to wait on. This is
necessary to correctly implement implicit synchronization for any buffers
shared as a struct dma_buf. This function can be used as the
drm_plane_helper_funcs.prepare_fb callback.
There is no need for drm_plane_helper_funcs.cleanup_fb hook for simple
GEM based framebuffer drivers which have their buffers always pinned in
memory.
This function duplicates shadow-buffered plane state. This is helpful for drivers
that subclass structdrm_shadow_plane_state.
The function does not duplicate existing mappings of the shadow buffers.
Mappings are maintained during the atomic commit by the plane’s prepare_fb
and cleanup_fb helpers. See drm_gem_prepare_shadow_fb() and drm_gem_cleanup_shadow_fb()
for corresponding helpers.
The function does not duplicate existing mappings of the shadow buffers.
Mappings are maintained during the atomic commit by the plane’s prepare_fb
and cleanup_fb helpers. See drm_gem_prepare_shadow_fb() and drm_gem_cleanup_shadow_fb()
for corresponding helpers.
Return
A pointer to a new plane state on success, or NULL otherwise.
This function implements struct drm_plane_funcs.atomic_destroy_state
for shadow-buffered planes. It expects that mappings of shadow buffers
have been released already.
This function implements struct drm_plane_funcs.reset_plane for
shadow-buffered planes. It assumes the current plane state to be
of type structdrm_shadow_plane and it allocates the new state of
this type.
This function implements structdrm_simple_display_funcs.duplicate_plane_state
for shadow-buffered planes. It does not duplicate existing mappings of the shadow
buffers. Mappings are maintained during the atomic commit by the plane’s prepare_fb
and cleanup_fb helpers.
Return
A pointer to a new plane state on success, or NULL otherwise.
This function implements structdrm_simple_display_funcs.destroy_plane_state
for shadow-buffered planes. It expects that mappings of shadow buffers
have been released already.
The vblank helper library provides functions for supporting vertical
blanking in DRM drivers.
For vblank timers, several callback implementations are available.
Drivers enable support for vblank timers by setting the vblank callbacks
in struct drm_crtc_funcs to the helpers provided by this library. The
initializer macro DRM_CRTC_VBLANK_TIMER_FUNCS does this conveniently.
The driver further has to send the VBLANK event from its atomic_flush
callback and control vblank from the CRTC’s atomic_enable and atomic_disable
callbacks. The callbacks are located in struct drm_crtc_helper_funcs.
The vblank helper library provides implementations of these callbacks
for drivers without further requirements. The initializer macro
DRM_CRTC_HELPER_VBLANK_FUNCS sets them coveniently.
The helper drm_crtc_helper_get_vblank_timestamp_from_timer() implements
get_vblank_timestamp of structdrm_crtc_funcs for CRTCs that require a
VBLANK timer. It returns the timestamp according to the timer’s expiry
time.
Many drivers require only a very simple encoder that fulfills the minimum
requirements of the display pipeline and does not add additional
functionality. The function drm_simple_encoder_init() provides an
implementation of such an encoder.
This callback is used to check if a specific mode is valid in the
crtc used in this simple display pipe. This should be implemented
if the display pipe has some sort of restriction in the modes
it can display. For example, a given display pipe may be responsible
to set a clock value. If the clock can not produce all the values
for the available modes then this callback can be used to restrict
the number of modes to only the ones that can be displayed. Another
reason can be bandwidth mitigation: the memory port on the display
controller can have bandwidth limitations not allowing pixel data
to be fetched at any rate.
Since this function is both called from the check phase of an atomic
commit, and the mode validation in the probe paths it is not allowed
to look at anything else but the passed-in mode, and validate it
against configuration-invariant hardware constraints.
RETURNS:
drm_mode_status Enum
enable
This function should be used to enable the pipeline.
It is called when the underlying crtc is enabled.
This hook is optional.
disable
This function should be used to disable the pipeline.
It is called when the underlying crtc is disabled.
This hook is optional.
check
This function is called in the check phase of an atomic update,
specifically when the underlying plane is checked.
The simple display pipeline helpers already check that the plane is
not scaled, fills the entire visible area and is always enabled
when the crtc is also enabled.
This hook is optional.
RETURNS:
0 on success, -EINVAL if the state or the transition can’t be
supported, -ENOMEM on memory allocation failure and -EDEADLK if an
attempt to obtain another state object ran into a drm_modeset_lock
deadlock.
update
This function is called when the underlying plane state is updated.
This hook is optional.
For GEM drivers who neither have a prepare_fb nor cleanup_fb hook
set, drm_gem_plane_helper_prepare_fb() is called automatically
to implement this. Other drivers which need additional plane
processing can call drm_gem_plane_helper_prepare_fb() from
their prepare_fb hook.
Allocates and initializes an encoder that has no further functionality.
Settings for possible CRTC and clones are left to their initial values.
Cleanup is automatically handled through registering drm_encoder_cleanup()
with drmm_add_action().
Initialize a preallocated encoder with basic functionality.
Parameters
structdrm_device*dev
drm device
structdrm_encoder*encoder
the encoder to initialize
intencoder_type
user visible type of the encoder
Description
Initialises a preallocated encoder that has no further functionality.
Settings for possible CRTC and clones are left to their initial values.
The encoder will be cleaned up automatically as part of the mode-setting
cleanup.
The caller of drm_simple_encoder_init() is responsible for freeing
the encoder’s memory after the encoder has been cleaned up. At the
moment this only works reliably if the encoder data structure is
stored in the device structure. Free the encoder’s memory as part of
the device release function.
Sets up a display pipeline which consist of a really simple
plane-crtc-encoder pipe.
If a connector is supplied, the pipe will be coupled with the provided
connector. You may supply a NULL connector when using drm bridges, that
handle connectors themselves (see drm_simple_display_pipe_attach_bridge()).
Teardown of a simple display pipe is all handled automatically by the drm
core through calling drm_mode_config_cleanup(). Drivers afterwards need to
release the memory for the structure themselves.
The fb helper functions are useful to provide an fbdev on top of a drm kernel
mode setting driver. They can be used mostly independently from the crtc
helper functions used by many drivers to implement the kernel mode setting
interfaces. Drivers that use one of the shared memory managers, TTM, SHMEM,
DMA, should instead use the corresponding fbdev emulation.
All other functions exported by the fb helper library can be used to
implement the fbdev driver interface by the driver.
It is possible, though perhaps somewhat tricky, to implement race-free
hotplug detection using the fbdev helpers. The drm_fb_helper_prepare()
helper must be called first to initialize the minimum required to make
hotplug detection work. Drivers also need to make sure to properly set up
the drm_mode_config.funcs member. After calling drm_kms_helper_poll_init()
it is safe to enable interrupts and start processing hotplug events. At the
same time, drivers should initialize all modeset objects such as CRTCs,
encoders and connectors. To finish up the fbdev helper initialization, the
drm_fb_helper_init() function is called. To probe for all attached displays
and set up an initial configuration using the detected hardware, drivers
should call drm_fb_helper_initial_config().
If drm_framebuffer_funcs.dirty is set, the
drm_fb_helper_{cfb,sys}_{write,fillrect,copyarea,imageblit} functions will
accumulate changes and schedule drm_fb_helper.dirty_work to run right
away. This worker then calls the dirty() function ensuring that it will
always run in process context since the fb_*() function could be running in
atomic context. If drm_fb_helper_deferred_io() is used as the deferred_io
callback it will also schedule dirty_work with the damage collected from the
mmap page writes.
Note that the scanout surface width/height may be larger than the fbdev
width/height. In case of multiple displays, the scanout surface is sized
according to the largest width/height (so it is large enough for all CRTCs
to scanout). But the fbdev width/height is sized to the minimum width/
height of all the displays. This ensures that fbcon fits on the smallest
of the attached displays. fb_width/fb_height is used by
drm_fb_helper_fill_info() to fill out the fb_info.var structure.
Driver callback to update the framebuffer memory. If set, fbdev
emulation will invoke this callback in regular intervals after
the framebuffer has been written.
This callback is optional.
Returns:
0 on success, or an error code otherwise.
fb_restore
Driver callback to restore internal fbdev state. If set, fbdev
emulation will invoke this callback after restoring the display
mode.
Only for i915. Do not use in new code.
TODO: Fix i915 to not require this callback.
fb_set_suspend
Driver callback to suspend or resume, if set, fbdev emulation will
invoke this callback during suspend and resume. Driver should call
fb_set_suspend() from their implementation. If not set, fbdev
emulation will invoke fb_set_suspend() directly.
Only for i915. Do not use in new code.
TODO: Fix i915 to not require this callback.
Description
Driver callbacks used by the fbdev emulation helper library.
clip rectangle used with deferred_io to accumulate damage to
the screen buffer
damage_lock
spinlock protecting damage_clip
damage_work
worker used to flush the framebuffer
resume_work
worker used during resume if the console lock is already taken
lock
Top-level FBDEV helper lock. This protects all internal data
structures and lists, such as connector_info and crtc_info.
FIXME: fbdev emulation locking is a mess and long term we want to
protect all helper internal state with this lock as well as reduce
core KMS locking as much as possible.
delayed_hotplug
A hotplug was received while fbdev wasn’t in control of the DRM
device, i.e. another KMS master was active. The output configuration
needs to be reprobe when fbdev is in control again.
deferred_setup
If no outputs are connected (disconnected or unknown) the FB helper
code will defer setup until at least one of the outputs shows up.
This field keeps track of the status so that setup can be retried
at every hotplug event until it succeeds eventually.
Protected by lock.
preferred_bpp
Temporary storage for the driver’s preferred BPP setting passed to
FB helper initialization. This needs to be tracked so that deferred
FB helper setup can pass this on.
See also: deferred_setup
fbdefio
Temporary storage for the driver’s FB deferred I/O handler. If the
driver uses the DRM fbdev emulation layer, this is set by the core
to a generic deferred I/O handler if a driver is preferring to use
a shadow buffer.
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 structdrm_fb_helper_funcs with a few
operations.
This helper should be called from fbdev emulation’s drm_client_funcs.restore
callback. It ensures that the user isn’t greeted with a black screen when the
userspace compositor releases the display device.
driver-allocated fbdev helper structure to initialize
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.
A wrapper around unregister_framebuffer, to release the fb_info
framebuffer device. This must be called before releasing all resources for
fb_helper by calling drm_fb_helper_fini().
wrapper around fb_set_suspend that also takes the console lock
Parameters
structdrm_fb_helper*fb_helper
driver-allocated fbdev helper, can be NULL
boolsuspend
whether to suspend or resume
Description
A wrapper around fb_set_suspend() that takes the console lock. If the lock
isn’t available on resume, a worker is tasked with waiting for the lock
to become available. The console lock can be pretty contented on resume
due to all the printk activity.
This function can be called multiple times with the same state since
fb_info.state is checked to see if fbdev is running or not before locking.
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.
Sets up the variable and fixed fbdev metainformation from the given fb helper
instance and the drm framebuffer allocated in drm_fb_helper.fb.
Drivers should call this (or their equivalent setup code) from their
drm_driver.fbdev_probe callback after having allocated the fbdev
backing storage framebuffer.
Scans the CRTCs and connectors and tries to put together an initial setup.
At the moment, this is a cloned configuration across all heads with
a new framebuffer object as the backing store.
Note that this also registers the fbdev and so allows userspace to call into
the driver through the fbdev interfaces.
This function will call down into the drm_driver.fbdev_probe callback
to let the driver allocate and initialize the fbdev info structure and the
drm framebuffer used to back the fbdev. drm_fb_helper_fill_info() is provided
as a helper to setup simple default values for the fbdev info structure.
HANG DEBUGGING:
When you have fbcon support built-in or already loaded, this function will do
a full modeset to setup the fbdev console. Due to locking misdesign in the
VT/fbdev subsystem that entire modeset sequence has to be done while holding
console_lock. Until console_unlock is called no dmesg lines will be sent out
to consoles, not even serial console. This means when your driver crashes,
you will see absolutely nothing else but a system stuck in this function,
with no further output. Any kind of printk() you place within your own driver
or in the drm core modeset code will also never show up.
Standard debug practice is to run the fbcon setup without taking the
console_lock as a hack, to be able to see backtraces and crashes on the
serial line. This can be done by setting the fb.lockless_register_fb=1 kernel
cmdline option.
The other option is to just disable fbdev emulation since very likely the
first modeset from userspace will crash in the same way, and is even easier
to debug. This can be done by setting the drm_kms_helper.fbdev_emulation=0
kernel cmdline option.
respond to a hotplug notification by probing all the outputs attached to the fb
Parameters
structdrm_fb_helper*fb_helper
driver-allocated fbdev helper, can be NULL
Description
Scan the connectors attached to the fb_helper and try to put together a
setup after notification of a change in output configuration.
Called at runtime, takes the mode config locks to be able to check/change the
modeset configuration. Must be run from process context (which usually means
either the output polling work or a work item launched from the driver’s
hotplug interrupt).
Note that drivers may call this even before calling
drm_fb_helper_initial_config but only after drm_fb_helper_init. This allows
for a race-free fbcon setup and will make sure that the fbdev emulation will
not miss any hotplug events.
Allocates at least new_size bytes and returns a pointer to the memory
range. After calling this function, previously returned memory blocks
are invalid. It’s best to collect all memory requirements of a format
conversion and call this function once to allocate the range.
Return
A pointer to the allocated memory range, or NULL otherwise.
Releases the memory range references by the format-conversion state.
After this call, all pointers to the memory are invalid. Prefer
drm_format_conv_state_init() for cleaning up and unloading a driver.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of source buffers
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
Description
This function copies parts of a framebuffer to display memory. Destination and
framebuffer formats must match. No conversion takes place. The parameters dst,
dst_pitch and src refer to arrays. Each array must have at least as many entries
as there are planes in fb’s format. Each entry stores the value for the format’s
respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of source buffers
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
boolcached
Source buffer is mapped cached (eg. not write-combined)
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and swaps per-pixel
bytes during the process. Destination and framebuffer formats must match. The
parameters dst, dst_pitch and src refer to arrays. Each array must have at
least as many entries as there are planes in fb’s format. Each entry stores the
value for the format’s respective color plane at the same index. If cached is
false a temporary buffer is used to cache one pixel line at a time to speed up
slow uncached reads.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffers
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. Destination and framebuffer formats must match. The
parameters dst, dst_pitch and src refer to arrays. Each array must have at
least as many entries as there are planes in fb’s format. Each entry stores the
value for the format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for RGB332 devices that don’t support XRGB8888 natively.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffer
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. Destination and framebuffer formats must match. The
parameters dst, dst_pitch and src refer to arrays. Each array must have at
least as many entries as there are planes in fb’s format. Each entry stores the
value for the format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for RGB565 devices that don’t support XRGB8888 natively.
Convert XRGB8888 to RGB565|DRM_FORMAT_BIG_ENDIAN clip buffer
Parameters
structiosys_map*dst
Array of RGB565BE destination buffers
constunsignedint*dst_pitch
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffer
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. Destination and framebuffer formats must match. The
parameters dst, dst_pitch and src refer to arrays. Each array must have at
least as many entries as there are planes in fb’s format. Each entry stores the
value for the format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for RGB565BE devices that don’t support XRGB8888 natively.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffer
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts
the color format during the process. The parameters dst, dst_pitch and
src refer to arrays. Each array must have at least as many entries as
there are planes in fb’s format. Each entry stores the value for the
format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for XRGB1555 devices that don’t support
XRGB8888 natively.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffer
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts
the color format during the process. The parameters dst, dst_pitch and
src refer to arrays. Each array must have at least as many entries as
there are planes in fb’s format. Each entry stores the value for the
format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for ARGB1555 devices that don’t support
XRGB8888 natively. It sets an opaque alpha channel as part of the conversion.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffer
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts
the color format during the process. The parameters dst, dst_pitch and
src refer to arrays. Each array must have at least as many entries as
there are planes in fb’s format. Each entry stores the value for the
format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for RGBA5551 devices that don’t support
XRGB8888 natively. It sets an opaque alpha channel as part of the conversion.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffers
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. Destination and framebuffer formats must match. The
parameters dst, dst_pitch and src refer to arrays. Each array must have at
least as many entries as there are planes in fb’s format. Each entry stores the
value for the format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for RGB888 devices that don’t natively
support XRGB8888.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffers
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. Destination and framebuffer formats must match. The
parameters dst, dst_pitch and src refer to arrays. Each array must have at
least as many entries as there are planes in fb’s format. Each entry stores the
value for the format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for BGR888 devices that don’t natively
support XRGB8888.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffer
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. The parameters dst, dst_pitch and src refer
to arrays. Each array must have at least as many entries as there are planes in
fb’s format. Each entry stores the value for the format’s respective color plane
at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for ARGB8888 devices that don’t support XRGB8888
natively. It sets an opaque alpha channel as part of the conversion.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffer
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. The parameters dst, dst_pitch and src refer
to arrays. Each array must have at least as many entries as there are planes in
fb’s format. Each entry stores the value for the format’s respective color plane
at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for ABGR8888 devices that don’t support XRGB8888
natively. It sets an opaque alpha channel as part of the conversion.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffer
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. The parameters dst, dst_pitch and src refer
to arrays. Each array must have at least as many entries as there are planes in
fb’s format. Each entry stores the value for the format’s respective color plane
at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for XBGR8888 devices that don’t support XRGB8888
natively.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffer
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. The parameters dst, dst_pitch and src refer
to arrays. Each array must have at least as many entries as there are planes in
fb’s format. Each entry stores the value for the format’s respective color plane
at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for BGRX8888 devices that don’t support XRGB8888
natively.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffers
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. Destination and framebuffer formats must match. The
parameters dst, dst_pitch and src refer to arrays. Each array must have at
least as many entries as there are planes in fb’s format. Each entry stores the
value for the format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for XRGB2101010 devices that don’t support XRGB8888
natively.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffers
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts
the color format during the process. The parameters dst, dst_pitch and
src refer to arrays. Each array must have at least as many entries as
there are planes in fb’s format. Each entry stores the value for the
format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for ARGB2101010 devices that don’t support XRGB8888
natively.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffers
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. Destination and framebuffer formats must match. The
parameters dst, dst_pitch and src refer to arrays. Each array must have at
least as many entries as there are planes in fb’s format. Each entry stores the
value for the format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
DRM doesn’t have native monochrome or grayscale support. Drivers can use this
function for grayscale devices that don’t support XRGB8888 natively.Such
drivers can announce the commonly supported XR24 format to userspace and use
this function to convert to the native format. Monochrome drivers will use the
most significant bit, where 1 means foreground color and 0 background color.
ITU BT.601 is being used for the RGB -> luma (brightness) conversion.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of ARGB8888 source buffer
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts
the color format during the process. The parameters dst, dst_pitch and
src refer to arrays. Each array must have at least as many entries as
there are planes in fb’s format. Each entry stores the value for the
format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner).
Drivers can use this function for ARGB4444 devices that don’t support
ARGB8888 natively.
Array of monochrome destination buffers (0=black, 1=white)
constunsignedint*dst_pitch
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffers
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. Destination and framebuffer formats must match. The
parameters dst, dst_pitch and src refer to arrays. Each array must have at
least as many entries as there are planes in fb’s format. Each entry stores the
value for the format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner). The first pixel (upper left corner of the clip rectangle) will
be converted and copied to the first bit (LSB) in the first byte of the monochrome
destination buffer. If the caller requires that the first pixel in a byte must
be located at an x-coordinate that is a multiple of 8, then the caller must take
care itself of supplying a suitable clip rectangle.
DRM doesn’t have native monochrome support. Drivers can use this function for
monochrome devices that don’t support XRGB8888 natively. Such drivers can
announce the commonly supported XR24 format to userspace and use this function
to convert to the native format.
This function uses drm_fb_xrgb8888_to_gray8() to convert to grayscale and
then the result is converted from grayscale to monochrome.
Array of numbers of bytes between the start of two consecutive scanlines
within dst; can be NULL if scanlines are stored next to each other.
conststructiosys_map*src
Array of XRGB8888 source buffers
conststructdrm_framebuffer*fb
DRM framebuffer
conststructdrm_rect*clip
Clip rectangle area to copy
structdrm_format_conv_state*state
Transform and conversion state
Description
This function copies parts of a framebuffer to display memory and converts the
color format during the process. Destination and framebuffer formats must match. The
parameters dst, dst_pitch and src refer to arrays. Each array must have at
least as many entries as there are planes in fb’s format. Each entry stores the
value for the format’s respective color plane at the same index.
This function does not apply clipping on dst (i.e. the destination is at the
top-left corner). The first pixel (upper left corner of the clip rectangle) will
be converted and copied to the two first bits (LSB) in the first byte of the gray2
destination buffer. If the caller requires that the first pixel in a byte must
be located at an x-coordinate that is a multiple of 8, then the caller must take
care itself of supplying a suitable clip rectangle.
DRM doesn’t have native gray2 support. Drivers can use this function for
gray2 devices that don’t support XRGB8888 natively. Such drivers can
announce the commonly supported XR24 format to userspace and use this function
to convert to the native format.
Provides helper functions for creating a DMA-contiguous framebuffer.
Depending on the platform, the buffers may be physically non-contiguous and
mapped through an IOMMU or a similar mechanism, or allocated from
physically-contiguous memory (using, for instance, CMA or a pool of memory
reserved at early boot). This is handled behind the scenes by the DMA mapping
API.
This function can be used by drivers that use damage clips and have
DMA GEM objects backed by non-coherent memory. Calling this function
in a plane’s .atomic_update ensures that all the data in the backing
memory have been written to RAM.
Generic get_scanout_buffer() implementation, for drivers that uses the
drm_fb_dma_helper. It won’t call vmap in the panic context, so the driver
should make sure the primary plane is vmapped, otherwise the panic screen
won’t get displayed.
This library provides helpers for drivers that don’t subclass
drm_framebuffer and use drm_gem_object for their backing storage.
Drivers without additional needs to validate framebuffers can simply use
drm_gem_fb_create() and everything is wired up automatically. Other drivers
can use all parts independently.
Frees a GEM backed framebuffer with its backing buffer(s) and the structure
itself. Drivers can use this as their drm_framebuffer_funcs->destroy
callback.
This function creates a handle for the GEM object backing the framebuffer.
Drivers can use this as their drm_framebuffer_funcs->create_handle
callback. The GETFB IOCTL calls into this callback.
DRM file that holds the GEM handle(s) backing the framebuffer
conststructdrm_format_info*info
pixel format information
conststructdrm_mode_fb_cmd2*mode_cmd
Metadata from the userspace framebuffer creation request
conststructdrm_framebuffer_funcs*funcs
vtable to be used for the new framebuffer object
Description
This function can be used to set drm_framebuffer_funcs for drivers that need
custom framebuffer callbacks. Use drm_gem_fb_create() if you don’t need to
change drm_framebuffer_funcs. The function does buffer size validation.
The buffer size validation is for a general case, though, so users should
pay attention to the checks being appropriate for them or, at least,
non-conflicting.
DRM file that holds the GEM handle(s) backing the framebuffer
conststructdrm_format_info*info
pixel format information
conststructdrm_mode_fb_cmd2*mode_cmd
Metadata from the userspace framebuffer creation request
Description
This function creates a new framebuffer object described by
drm_mode_fb_cmd2. This description includes handles for the buffer(s)
backing the framebuffer.
If your hardware has special alignment or pitch requirements these should be
checked before calling this function. The function does buffer size
validation. Use drm_gem_fb_create_with_dirty() if you need framebuffer
flushing.
DRM file that holds the GEM handle(s) backing the framebuffer
conststructdrm_format_info*info
pixel format information
conststructdrm_mode_fb_cmd2*mode_cmd
Metadata from the userspace framebuffer creation request
Description
This function creates a new framebuffer object described by
drm_mode_fb_cmd2. This description includes handles for the buffer(s)
backing the framebuffer. drm_atomic_helper_dirtyfb() is used for the dirty
callback giving framebuffer flushing through the atomic machinery. Use
drm_gem_fb_create() if you don’t need the dirty callback.
The function does buffer size validation.
Drivers should also call drm_plane_enable_fb_damage_clips() on all planes
to enable userspace to use damage clips also with the ATOMIC IOCTL.
maps all framebuffer BOs into kernel address space
Parameters
structdrm_framebuffer*fb
the framebuffer
structiosys_map*map
returns the mapping’s address for each BO
structiosys_map*data
returns the data address for each BO, can be NULL
Description
This function maps all buffer objects of the given framebuffer into
kernel address space and stores them in structiosys_map. If the
mapping operation fails for one of the BOs, the function unmaps the
already established mappings automatically.
Callers that want to access a BO’s stored data should pass data.
The argument returns the addresses of the data stored in each BO. This
is different from map if the framebuffer’s offsets field is non-zero.
Both, map and data, must each refer to arrays with at least
fb->format->num_planes elements.
Prepares a framebuffer’s GEM buffer objects for CPU access. This function
must be called before accessing the BO data within the kernel. For imported
BOs, the function calls dma_buf_begin_cpu_access().
Signals the end of CPU access to the given framebuffer’s GEM buffer objects. This
function must be paired with a corresponding call to drm_gem_fb_begin_cpu_access().
For imported BOs, the function calls dma_buf_end_cpu_access().
Helper function for drivers using afbc to fill and validate all the afbc-specific structdrm_afbc_framebuffer members
Parameters
structdrm_device*dev
DRM device
conststructdrm_format_info*info
pixel format information
conststructdrm_mode_fb_cmd2*mode_cmd
Metadata from the userspace framebuffer creation request
structdrm_afbc_framebuffer*afbc_fb
afbc framebuffer
Description
This function can be used by drivers which support afbc to complete
the preparation of structdrm_afbc_framebuffer. It must be called after
allocating the said structand calling drm_gem_fb_init_with_funcs().
It is caller’s responsibility to put afbc_fb->base.obj objects in case
the call is unsuccessful.
Return
Zero on success or a negative error value on failure.
structdrm_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 a chain of bridges:
[ CRTC ---> ] Encoder ---> Bridge A ---> Bridge B
Here, the output of the encoder feeds to bridge A, and that furthers feeds to
bridge B. Bridge chains can be arbitrarily long, and shall be fully linear:
Chaining multiple bridges to the output of a bridge, or the same bridge to
the output of different bridges, is not supported.
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.
Display drivers are responsible for linking encoders with the first bridge
in the chains. This is done by acquiring the appropriate bridge with
devm_drm_of_get_bridge(). Once acquired, the bridge shall be attached to the
encoder with a call to drm_bridge_attach().
Bridges are responsible for linking themselves with the next bridge in the
chain, if any. This is done the same way as for encoders, with the call to
drm_bridge_attach() occurring in the drm_bridge_funcs.attach operation.
Bridges also participate in implementing the drm_connector at the end of
the bridge chain. Display drivers may use the drm_bridge_connector_init()
helper to create the drm_connector, or implement it manually on top of the
connector-related operations exposed by the bridge (see the overview
documentation of bridge operations for more details).
The interaction between the bridges and other frameworks involved in
the probing of the upstream driver and the bridge driver can be
challenging. Indeed, there’s multiple cases that needs to be
considered:
The upstream driver doesn’t use the component framework and isn’t a
MIPI-DSI host. In this case, the bridge driver will probe at some
point and the upstream driver should try to probe again by returning
EPROBE_DEFER as long as the bridge driver hasn’t probed.
The upstream driver doesn’t use the component framework, but is a
MIPI-DSI host. The bridge device uses the MIPI-DCS commands to be
controlled. In this case, the bridge device is a child of the
display device and when it will probe it’s assured that the display
device (and MIPI-DSI host) is present. The upstream driver will be
assured that the bridge driver is connected between the
mipi_dsi_host_ops.attach and mipi_dsi_host_ops.detach operations.
Therefore, it must run mipi_dsi_host_register() in its probe
function, and then run drm_bridge_attach() in its
mipi_dsi_host_ops.attach hook.
The upstream driver uses the component framework and is a MIPI-DSI
host. The bridge device uses the MIPI-DCS commands to be
controlled. This is the same situation than above, and can run
mipi_dsi_host_register() in either its probe or bind hooks.
The upstream driver uses the component framework and is a MIPI-DSI
host. The bridge device uses a separate bus (such as I2C) to be
controlled. In this case, there’s no correlation between the probe
of the bridge and upstream drivers, so care must be taken to avoid
an endless EPROBE_DEFER loop, with each driver waiting for the
other to probe.
The ideal pattern to cover the last item (and all the others in the
MIPI-DSI host driver case) is to split the operations like this:
The MIPI-DSI host driver must run mipi_dsi_host_register() in its
probe hook. It will make sure that the MIPI-DSI host sticks around,
and that the driver’s bind can be called.
In its probe hook, the bridge driver must try to find its MIPI-DSI
host, register as a MIPI-DSI device and attach the MIPI-DSI device
to its host. The bridge driver is now functional.
In its structmipi_dsi_host_ops.attach hook, the MIPI-DSI host can
now add its component. Its bind hook will now be called and since
the bridge driver is attached and registered, we can now look for
and attach it.
At this point, we’re now certain that both the upstream driver and
the bridge driver are functional and we can’t have a deadlock-like
situation when probing.
Bridge drivers expose operations through the drm_bridge_funcs structure.
The DRM internals (atomic and CRTC helpers) use the helpers defined in
drm_bridge.c to call bridge operations. Those operations are divided in
three big categories to support different parts of the bridge usage.
The encoder-related operations support control of the bridges in the
chain, and are roughly counterparts to the drm_encoder_helper_funcs
operations. They are used by the legacy CRTC and the atomic modeset
helpers to perform mode validation, fixup and setting, and enable and
disable the bridge automatically.
The bus format negotiation operations
drm_bridge_funcs.atomic_get_output_bus_fmts and
drm_bridge_funcs.atomic_get_input_bus_fmts allow bridge drivers to
negotiate the formats transmitted between bridges in the chain when
multiple formats are supported. Negotiation for formats is performed
transparently for display drivers by the atomic modeset helpers. Only
atomic versions of those operations exist, bridge drivers that need to
implement them shall thus also implement the atomic version of the
encoder-related operations. This feature is not supported by the legacy
CRTC helpers.
The connector-related operations support implementing a drm_connector
based on a chain of bridges. DRM bridges traditionally create a
drm_connector for bridges meant to be used at the end of the chain. This
puts additional burden on bridge drivers, especially for bridges that may
be used in the middle of a chain or at the end of it. Furthermore, it
requires all operations of the drm_connector to be handled by a single
bridge, which doesn’t always match the hardware architecture.
Bridge drivers shall implement the connector-related operations for all
the features that the bridge hardware support. For instance, if a bridge
supports reading EDID, the drm_bridge_funcs.get_edid shall be
implemented. This however doesn’t mean that the DDC lines are wired to the
bridge on a particular platform, as they could also be connected to an I2C
controller of the SoC. Support for the connector-related operations on the
running platform is reported through the drm_bridge.ops flags. Bridge
drivers shall detect which operations they can support on the platform
(usually this information is provided by ACPI or DT), and set the
drm_bridge.ops flags for all supported operations. A flag shall only be
set if the corresponding drm_bridge_funcs operation is implemented, but
an implemented operation doesn’t necessarily imply that the corresponding
flag will be set. Display drivers shall use the drm_bridge.ops flags to
decide which bridge to delegate a connector operation to. This mechanism
allows providing a single static const drm_bridge_funcs instance in
bridge drivers, improving security by storing function pointers in
read-only memory.
In order to ease transition, bridge drivers may support both the old and
new models by making connector creation optional and implementing the
connected-related bridge operations. Connector creation is then controlled
by the flags argument to the drm_bridge_attach() function. Display drivers
that support the new model and create connectors themselves shall set the
DRM_BRIDGE_ATTACH_NO_CONNECTOR flag, and bridge drivers shall then skip
connector creation. For intermediate bridges in the chain, the flag shall
be passed to the drm_bridge_attach() call for the downstream bridge.
Bridge drivers that implement the new model only shall return an error
from their drm_bridge_funcs.attach handler when the
DRM_BRIDGE_ATTACH_NO_CONNECTOR flag is not set. New display drivers
should use the new model, and convert the bridge drivers they use if
needed, in order to gradually transition to the new model.
The DRM bridge connector helper object provides a DRM connector
implementation that wraps a chain of structdrm_bridge. The connector
operations are fully implemented based on the operations of the bridges in
the chain, and don’t require any intervention from the display controller
driver at runtime.
To use the helper, display controller drivers create a bridge connector with
a call to drm_bridge_connector_init(). This associates the newly created
connector with the chain of bridges passed to the function and registers it
with the DRM device. At that point the connector becomes fully usable, no
further operation is needed.
The DRM bridge connector operations are implemented based on the operations
provided by the bridges in the chain. Each connector operation is delegated
to the bridge closest to the connector (at the end of the chain) that
provides the relevant functionality.
To make use of this helper, all bridges in the chain shall report bridge
operation flags (drm_bridge->ops) and bridge output type
(drm_bridge->type), as well as the DRM_BRIDGE_ATTACH_NO_CONNECTOR attach
flag (none of the bridges shall create a DRM connector directly).
This callback is invoked whenever our bridge is being attached to a
drm_encoder. The flags argument tunes the behaviour of the attach
operation (see DRM_BRIDGE_ATTACH_*).
The attach callback is optional.
RETURNS:
Zero on success, error code on failure.
destroy
This callback is invoked when the bridge is about to be
deallocated.
The destroy callback is optional.
detach
This callback is invoked whenever our bridge is being detached from a
drm_encoder.
The detach callback is optional.
mode_valid
This callback is used to check if a specific mode is valid in this
bridge. This should be implemented if the bridge has some sort of
restriction in the modes it can display. For example, a given bridge
may be responsible to set a clock value. If the clock can not
produce all the values for the available modes then this callback
can be used to restrict the number of modes to only the ones that
can be displayed.
Since this function is both called from the check phase of an atomic
commit, and the mode validation in the probe paths it is not allowed
to look at anything else but the passed-in mode, and validate it
against configuration-invariant hardware constraints. Any further
limits which depend upon the configuration can only be checked in
mode_fixup.
RETURNS:
drm_mode_status Enum
mode_fixup
This callback is used to validate and adjust a mode. The parameter
mode is the display mode that should be fed to the next element in
the display chain, either the final drm_connector or the next
drm_bridge. The parameter adjusted_mode is the input mode the bridge
requires. It can be modified by this callback and does not need to
match mode. See also drm_crtc_state.adjusted_mode for more details.
This is the only hook that allows a bridge to reject a modeset. If
this function passes all other callbacks must succeed for this
configuration.
This function is called in the check phase of atomic modesets, which
can be aborted for any reason (including on userspace’s request to
just check whether a configuration would be possible). Drivers MUST
NOT touch any persistent state (hardware or software) or data
structures except the passed in state parameter.
Also beware that userspace can request its own custom modes, neither
core nor helpers filter modes to the list of probe modes reported by
the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure
that modes are filtered consistently put any bridge constraints and
limits checks into mode_valid.
RETURNS:
True if an acceptable configuration is possible, false if the modeset
operation should be rejected.
This callback should set the given mode on the bridge. It is called
after the mode_set callback for the preceding element in the display
pipeline has been called already. If the bridge is the first element
then this would be drm_encoder_helper_funcs.mode_set. The display
pipe (i.e. clocks and timing signals) is off when this function is
called.
The adjusted_mode parameter is the mode output by the CRTC for the
first bridge in the chain. It can be different from the mode
parameter that contains the desired mode for the connector at the end
of the bridges chain, for instance when the first bridge in the chain
performs scaling. The adjusted mode is mostly useful for the first
bridge in the chain and is likely irrelevant for the other bridges.
The display pipe (i.e. clocks and timing signals) feeding this bridge
will not yet be running when this callback is called. The bridge must
not enable the display link feeding the next bridge in the chain (if
there is one) when this callback is called.
The bridge can assume that the display pipe (i.e. clocks and timing
signals) feeding it is running when this callback is called. This
callback must enable the display link feeding the next bridge in the
chain if there is one.
This callback should enable the bridge. It is called right before
the preceding element in the display pipe is enabled. If the
preceding element is a bridge this means it’s called before that
bridge’s atomic_pre_enable or pre_enable function. If the preceding
element is a drm_encoder it’s called right before the encoder’s
drm_encoder_helper_funcs.atomic_enable hook.
The display pipe (i.e. clocks and timing signals) feeding this bridge
will not yet be running when this callback is called. The bridge must
not enable the display link feeding the next bridge in the chain (if
there is one) when this callback is called.
The atomic_pre_enable callback is optional.
atomic_enable
This callback should enable the bridge. It is called right after
the preceding element in the display pipe is enabled. If the
preceding element is a bridge this means it’s called after that
bridge’s atomic_enable or enable function. If the preceding element
is a drm_encoder it’s called right after the encoder’s
drm_encoder_helper_funcs.atomic_enable hook.
The bridge can assume that the display pipe (i.e. clocks and timing
signals) feeding it is running when this callback is called. This
callback must enable the display link feeding the next bridge in the
chain if there is one.
The atomic_enable callback is optional.
atomic_disable
This callback should disable the bridge. It is called right before
the preceding element in the display pipe is disabled. If the
preceding element is a bridge this means it’s called before that
bridge’s atomic_disable or disable vfunc. If the preceding element
is a drm_encoder it’s called right before the
drm_encoder_helper_funcs.atomic_disable hook.
The bridge can assume that the display pipe (i.e. clocks and timing
signals) feeding it is still running when this callback is called.
The atomic_disable callback is optional.
atomic_post_disable
This callback should disable the bridge. It is called right after the
preceding element in the display pipe is disabled. If the preceding
element is a bridge this means it’s called after that bridge’s
atomic_post_disable or post_disable function. If the preceding
element is a drm_encoder it’s called right after the encoder’s
drm_encoder_helper_funcs.atomic_disable hook.
The bridge must assume that the display pipe (i.e. clocks and timing
signals) feeding it is no longer running when this callback is
called.
The atomic_post_disable callback is optional.
atomic_duplicate_state
Duplicate the current bridge state object (which is guaranteed to be
non-NULL).
The atomic_duplicate_state hook is mandatory if the bridge
implements any of the atomic hooks, and should be left unassigned
otherwise. For bridges that don’t subclass drm_bridge_state, the
drm_atomic_helper_bridge_duplicate_state() helper function shall be
used to implement this hook.
RETURNS:
A valid drm_bridge_state object or NULL if the allocation fails.
The atomic_destroy_state hook is mandatory if the bridge implements
any of the atomic hooks, and should be left unassigned otherwise.
For bridges that don’t subclass drm_bridge_state, the
drm_atomic_helper_bridge_destroy_state() helper function shall be
used to implement this hook.
atomic_get_output_bus_fmts
Return the supported bus formats on the output end of a bridge.
The returned array must be allocated with kmalloc() and will be
freed by the caller. If the allocation fails, NULL should be
returned. num_output_fmts must be set to the returned array size.
Formats listed in the returned array should be listed in decreasing
preference order (the core will try all formats until it finds one
that works).
Return the supported bus formats on the input end of a bridge for
a specific output bus format.
The returned array must be allocated with kmalloc() and will be
freed by the caller. If the allocation fails, NULL should be
returned. num_input_fmts must be set to the returned array size.
Formats listed in the returned array should be listed in decreasing
preference order (the core will try all formats until it finds one
that works). When the format is not supported NULL should be
returned and num_input_fmts should be set to 0.
This method is called on all elements of the bridge chain as part of
the bus format negotiation process that happens in
drm_atomic_bridge_chain_select_bus_fmts().
This method is optional. When not implemented, the core will bypass
bus format negotiation on this element of the bridge without
failing, and the previous element in the chain will be passed
MEDIA_BUS_FMT_FIXED as its output bus format.
Bridge drivers that need to support being linked to bridges that are
not supporting bus format negotiation should handle the
output_fmt == MEDIA_BUS_FMT_FIXED case appropriately, by selecting a
sensible default value or extracting this information from somewhere
else (FW property, drm_display_mode, drm_display_info, ...)
Note: Even if input format selection on the first bridge has no
impact on the negotiation process (bus format negotiation stops once
we reach the first element of the chain), drivers are expected to
return accurate input formats as the input format may be used to
configure the CRTC output appropriately.
atomic_check
This method is responsible for checking bridge state correctness.
It can also check the state of the surrounding components in chain
to make sure the whole pipeline can work properly.
RETURNS:
zero if the check passed, a negative error code otherwise.
atomic_reset
Reset the bridge to a predefined state (or retrieve its current
state) and return a drm_bridge_state object matching this state.
This function is called at attach time.
The atomic_reset hook is mandatory if the bridge implements any of
the atomic hooks, and should be left unassigned otherwise. For
bridges that don’t subclass drm_bridge_state, the
drm_atomic_helper_bridge_reset() helper function shall be used to
implement this hook.
Note that the atomic_reset() semantics is not exactly matching the
reset() semantics found on other components (connector, plane, ...).
The reset operation happens when the bridge is attached, not when
drm_mode_config_reset() is called
It’s meant to be used exclusively on bridges that have been
converted to the ATOMIC API
RETURNS:
A valid drm_bridge_state object in case of success, an ERR_PTR()
giving the reason of the failure otherwise.
detect
Check if anything is attached to the bridge output.
This callback is optional, if not implemented the bridge will be
considered as always having a component attached to its output.
Bridges that implement this callback shall set the
DRM_BRIDGE_OP_DETECT flag in their drm_bridge->ops.
RETURNS:
drm_connector_status indicating the bridge output status.
The get_modes callback is mostly intended to support non-probeable
displays such as many fixed panels. Bridges that support reading
EDID shall leave get_modes unimplemented and implement the
drm_bridge_funcs->edid_read callback instead.
This callback is optional. Bridges that implement it shall set the
DRM_BRIDGE_OP_MODES flag in their drm_bridge->ops.
The connector parameter shall be used for the sole purpose of
filling modes, and shall not be stored internally by bridge drivers
for future usage.
The edid_read callback is the preferred way of reporting mode
information for a display connected to the bridge output. Bridges
that support reading EDID shall implement this callback and leave
the get_modes callback unimplemented.
The caller of this operation shall first verify the output
connection status and refrain from reading EDID from a disconnected
output.
This callback is optional. Bridges that implement it shall set the
DRM_BRIDGE_OP_EDID flag in their drm_bridge->ops.
The connector parameter shall be used for the sole purpose of EDID
retrieval, and shall not be stored internally by bridge drivers for
future usage.
RETURNS:
An edid structure newly allocated with drm_edid_alloc() or returned
from drm_edid_read() family of functions on success, or NULL
otherwise. The caller is responsible for freeing the returned edid
structure with drm_edid_free().
hpd_notify
Notify the bridge of hot plug detection.
This callback is optional, it may be implemented by bridges that
need to be notified of display connection or disconnection for
internal reasons. One use case is to reset the internal state of CEC
controllers for HDMI bridges.
hpd_enable
Enable hot plug detection. From now on the bridge shall call
drm_bridge_hpd_notify() each time a change is detected in the output
connection status, until hot plug detection gets disabled with
hpd_disable.
This callback is optional and shall only be implemented by bridges
that support hot-plug notification without polling. Bridges that
implement it shall also implement the hpd_disable callback and set
the DRM_BRIDGE_OP_HPD flag in their drm_bridge->ops.
hpd_disable
Disable hot plug detection. Once this function returns the bridge
shall not call drm_bridge_hpd_notify() when a change in the output
connection status occurs.
This callback is optional and shall only be implemented by bridges
that support hot-plug notification without polling. Bridges that
implement it shall also implement the hpd_enable callback and set
the DRM_BRIDGE_OP_HPD flag in their drm_bridge->ops.
hdmi_tmds_char_rate_valid
Check whether a particular TMDS character rate is supported by the
driver.
This callback is optional and should only be implemented by the
bridges that take part in the HDMI connector implementation. Bridges
that implement it shall set the DRM_BRIDGE_OP_HDMI flag in their
drm_bridge->ops.
Tells what additional settings for the pixel data on the bus
this bridge requires (like pixel signal polarity). See also
drm_display_info->bus_flags.
setup_time_ps
Defines the time in picoseconds the input data lines must be
stable before the clock edge.
hold_time_ps
Defines the time in picoseconds taken for the bridge to sample the
input signal after the clock edge.
dual_link
True if the bus operates in dual-link mode. The exact meaning is
dependent on the bus type. For LVDS buses, this indicates that even-
and odd-numbered pixels are received on separate links.
The bridge can detect displays connected to
its output. Bridges that set this flag shall implement the
drm_bridge_funcs->detect callback.
DRM_BRIDGE_OP_EDID
The bridge can retrieve the EDID of the display
connected to its output. Bridges that set this flag shall implement
the drm_bridge_funcs->edid_read callback.
DRM_BRIDGE_OP_HPD
The bridge can detect hot-plug and hot-unplug
without requiring polling. Bridges that set this flag shall
implement the drm_bridge_funcs->hpd_enable and
drm_bridge_funcs->hpd_disable callbacks if they support enabling
and disabling hot-plug detection dynamically.
DRM_BRIDGE_OP_MODES
The bridge can retrieve the modes supported
by the display at its output. This does not include reading EDID
which is separately covered by DRM_BRIDGE_OP_EDID. Bridges that set
this flag shall implement the drm_bridge_funcs->get_modes callback.
Note: currently there can be at most one bridge in a chain that sets
this bit. This is to simplify corresponding glue code in connector
drivers. Also it is not possible to have a bridge in the chain that
sets DRM_BRIDGE_OP_DP_AUDIO if there is a bridge that sets this
flag.
Note: currently there can be at most one bridge in a chain that sets
this bit. This is to simplify corresponding glue code in connector
drivers. Also it is not possible to have a bridge in the chain that
sets DRM_BRIDGE_OP_HDMI_AUDIO if there is a bridge that sets this
flag.
Type of the connection at the bridge output
(DRM_MODE_CONNECTOR_*). For bridges at the end of this chain this
identifies the type of connected display.
interlace_allowed
Indicate that the bridge can handle interlaced
modes.
ycbcr_420_allowed
Indicate that the bridge can handle YCbCr 420
output.
pre_enable_prev_first
The bridge requires that the prev
bridge pre_enable function is called before its pre_enable,
and conversely for post_disable. This is most frequently a
requirement for DSI devices which need the host to be initialised
before the peripheral.
support_hdcp
Indicate that the bridge supports HDCP.
ddc
Associated I2C adapter for DDC access, if any.
vendor
Vendor of the product to be used for the SPD InfoFrame
generation. This is required if DRM_BRIDGE_OP_HDMI is set.
product
Name of the product to be used for the SPD InfoFrame
generation. This is required if DRM_BRIDGE_OP_HDMI is set.
supported_formats
Bitmask of hdmi_colorspace listing supported
output formats. This is only relevant if DRM_BRIDGE_OP_HDMI is set.
max_bpc
Maximum bits per char the HDMI bridge supports. Allowed
values are 8, 10 and 12. This is only relevant if
DRM_BRIDGE_OP_HDMI is set.
hdmi_cec_dev
device to be used as a containing device for CEC
functions.
hdmi_audio_dev
device to be used as a parent for the HDMI Codec if
either of DRM_BRIDGE_OP_HDMI_AUDIO or DRM_BRIDGE_OP_DP_AUDIO is set.
hdmi_audio_max_i2s_playback_channels
maximum number of playback
I2S channels for the DRM_BRIDGE_OP_HDMI_AUDIO or
DRM_BRIDGE_OP_DP_AUDIO.
hdmi_audio_i2s_formats
supported I2S formats, optional. The
default is to allow all formats supported by the corresponding I2S
bus driver. This is only used for bridges setting
DRM_BRIDGE_OP_HDMI_AUDIO or DRM_BRIDGE_OP_DP_AUDIO.
hdmi_audio_spdif_playback
set if this bridge has S/PDIF playback
port for DRM_BRIDGE_OP_HDMI_AUDIO or DRM_BRIDGE_OP_DP_AUDIO.
hdmi_audio_dai_port
sound DAI port for either of
DRM_BRIDGE_OP_HDMI_AUDIO and DRM_BRIDGE_OP_DP_AUDIO, -1 if it is
not used.
hdmi_cec_adapter_name
the name of the adapter to register
hdmi_cec_available_las
number of logical addresses, CEC_MAX_LOG_ADDRS if unset
Private data passed to the Hot plug detection callback
hpd_cb.
next_bridge
Pointer to the following bridge, automatically put
when this bridge is freed (i.e. at destroy time). This is for
drivers needing to store a pointer to the next bridge in the
chain, and ensures any code still holding a reference to this
bridge after its removal cannot use-after-free the next
bridge. Any other bridge pointers stored by the driver must be
put in the .destroy callback by driver code.
The reference count of the returned bridge is initialized to 1. This
reference will be automatically dropped via devm (by calling
drm_bridge_put()) when dev is removed.
Pointer to index that will be passed to the matching drm_bridge_exit()
Description
This function marks and protects the beginning of a section that should not
be entered after the bridge has been unplugged. The section end is marked
with drm_bridge_exit(). Calls to this function can be nested.
Return
True if it is OK to enter the section, false otherwise.
This tells the bridge has been physically unplugged and no operations on
device resources must be done anymore. Entry-points can use
drm_bridge_enter() and drm_bridge_exit() to protect device resources in
a race free manner.
Remove the given bridge from the global list of registered bridges, so
it won’t be found by users via of_drm_find_and_get_bridge(), and add it
to the lingering bridge list, to keep track of it until its allocated
memory is eventually freed.
Called by a kms driver to link the bridge to an encoder’s chain. The previous
argument specifies the previous bridge in the chain. If NULL, the bridge is
linked directly at the encoder’s output. Otherwise it is linked at the
previous bridge’s output.
If non-NULL the previous bridge must be already attached by a call to this
function.
The bridge to be attached must have been previously added by
drm_bridge_add().
Note that bridges attached to encoders are auto-detached during encoder
cleanup in drm_encoder_cleanup(), so drm_bridge_attach() should generally
not be balanced with a drm_bridge_detach() in driver code.
validate the mode against all bridges in the encoder chain.
Parameters
structdrm_bridge*bridge
bridge control structure
conststructdrm_display_info*info
display info against which the mode shall be validated
conststructdrm_display_mode*mode
desired mode to be validated
Description
Calls drm_bridge_funcs.mode_valid for all the bridges in the encoder
chain, starting from the first bridge to the last. If at least one bridge
does not accept the mode the function returns the error code.
Note
the bridge passed should be the one closest to the encoder.
Return
MODE_OK on success, drm_mode_status Enum error code on failure
If a bridge sets pre_enable_prev_first, then the post_disable for that
bridge will be called before the previous one to reverse the pre_enable
calling direction.
Example
Bridge A ---> Bridge B ---> Bridge C ---> Bridge D ---> Bridge E
With pre_enable_prev_first flag enable in Bridge B, D, E then the resulting
post_disable order would be,
Bridge B, Bridge A, Bridge E, Bridge D, Bridge C.
Note
the bridge passed should be the one closest to the encoder
If a bridge sets pre_enable_prev_first, then the pre_enable for the
prev bridge will be called before pre_enable of this bridge.
Example
Bridge A ---> Bridge B ---> Bridge C ---> Bridge D ---> Bridge E
With pre_enable_prev_first flag enable in Bridge B, D, E then the resulting
pre_enable order would be,
Bridge C, Bridge D, Bridge E, Bridge A, Bridge B.
Note
the bridge passed should be the one closest to the encoder
check if anything is attached to the bridge output
Parameters
structdrm_bridge*bridge
bridge control structure
structdrm_connector*connector
attached connector
Description
If the bridge supports output detection, as reported by the
DRM_BRIDGE_OP_DETECT bridge ops flag, call drm_bridge_funcs.detect for the
bridge and return the connection status. Otherwise return
connector_status_unknown.
Return
The detection status on success, or connector_status_unknown if the bridge
doesn’t support output detection.
fill all modes currently valid for the sink into the connector
Parameters
structdrm_bridge*bridge
bridge control structure
structdrm_connector*connector
the connector to fill with modes
Description
If the bridge supports output modes retrieval, as reported by the
DRM_BRIDGE_OP_MODES bridge ops flag, call drm_bridge_funcs.get_modes to
fill the connector with all valid modes and return the number of modes
added. Otherwise return 0.
If the bridge supports output EDID retrieval, as reported by the
DRM_BRIDGE_OP_EDID bridge ops flag, call drm_bridge_funcs.edid_read to get
the EDID and return it. Otherwise return NULL.
data to be passed to the hot-plug detection callback
Description
Call drm_bridge_funcs.hpd_enable if implemented and register the given cb
and data as hot plug notification callback. From now on the cb will be
called with data when an output status change is detected by the bridge,
until hot plug notification gets disabled with drm_bridge_hpd_disable().
Hot plug detection is supported only if the DRM_BRIDGE_OP_HPD flag is set in
bridge->ops. This function shall not be called when the flag is not set.
Only one hot plug detection callback can be registered at a time, it is an
error to call this function when hot plug detection is already enabled for
the bridge.
Call drm_bridge_funcs.hpd_disable if implemented and unregister the hot
plug detection callback previously registered with drm_bridge_hpd_enable().
Once this function returns the callback will not be called by the bridge
when an output status change occurs.
Hot plug detection is supported only if the DRM_BRIDGE_OP_HPD flag is set in
bridge->ops. This function shall not be called when the flag is not set.
Bridge drivers shall call this function to report hot plug events when they
detect a change in the output status, when hot plug detection has been
enabled by drm_bridge_hpd_enable().
This function shall be called in a context that can sleep.
The bridge returned by this function is not refcounted. This is
dangerous because the bridge might be deallocated even before the caller
has a chance to use it. To use this function you have to do one of:
get a reference with drm_bridge_get() as soon as possible to
minimize the race window, and then drm_bridge_put() when no longer
using the pointer
not call drm_bridge_get() or drm_bridge_put() at all, which used to
be the correct practice before dynamic bridge lifetime was introduced
DSI host interfaces are expected to be implemented as bridges rather than
encoders, however there are a few aspects of their operation that need to
be defined in order to provide a consistent interface.
A DSI host should keep the PHY powered down until the pre_enable operation is
called. All lanes are in an undefined idle state up to this point, and it
must not be assumed that it is LP-11.
pre_enable should initialise the PHY, set the data lanes to LP-11, and the
clock lane to either LP-11 or HS depending on the mode_flag
MIPI_DSI_CLOCK_NON_CONTINUOUS.
Ordinarily the downstream bridge DSI peripheral pre_enable will have been
called before the DSI host. If the DSI peripheral requires LP-11 and/or
the clock lane to be in HS mode prior to pre_enable, then it can set the
pre_enable_prev_first flag to request the pre_enable (and
post_disable) order to be altered to enable the DSI host first.
Either the CRTC being enabled, or the DSI host enable operation should switch
the host to actively transmitting video on the data lanes.
The reverse also applies. The DSI host disable operation or stopping the CRTC
should stop transmitting video, and the data lanes should return to the LP-11
state. The DSI host post_disable operation should disable the PHY.
If the pre_enable_prev_first flag is set, then the DSI peripheral’s
bridge post_disable will be called before the DSI host’s post_disable.
Whilst it is valid to call host_transfer prior to pre_enable or after
post_disable, the exact state of the lanes is undefined at this point. The
DSI host should initialise the interface, transmit the data, and then disable
the interface again.
Ultra Low Power State (ULPS) is not explicitly supported by DRM. If
implemented, it therefore needs to be handled entirely within the DSI Host
driver.
Allocate, initialise and register a drm_bridge_connector with the drm
device. The connector is associated with a chain of bridges that starts at
the encoder. All bridges in the chain shall report bridge operation flags
(drm_bridge->ops) and bridge output type (drm_bridge->type), and none of
them may create a DRM connector directly.
Returns a pointer to the new connector on success, or a negative error
pointer otherwise.
For drivers converting from directly using drm_panel: The expected
usage pattern is that during either encoder module probe or DSI
host attach, a drm_panel will be looked up through
drm_of_find_panel_or_bridge(). drm_panel_bridge_add() is used to
wrap that panel in the new bridge, and the result can then be
passed to drm_bridge_attach(). The drm_panel_prepare() and related
functions can be dropped from the encoder driver (they’re now
called by the KMS helpers before calling into the encoder), along
with connector creation. When done with the bridge (after
drm_mode_config_cleanup() if the bridge has already been attached), then
drm_panel_bridge_remove() to free it.
The connector type is set to panel->connector_type, which must be set to a
known type. Calling this function with a panel whose connector type is
DRM_MODE_CONNECTOR_Unknown will return ERR_PTR(-EINVAL).
This is just like drm_panel_bridge_add(), but forces the connector type to
connector_type instead of infering it from the panel.
This function is deprecated and should not be used in new drivers. Use
drm_panel_bridge_add() instead, and fix panel drivers as necessary if they
don’t report a connector type.
This is just like devm_drm_panel_bridge_add(), but forces the connector type
to connector_type instead of infering it from the panel.
This function is deprecated and should not be used in new drivers. Use
devm_drm_panel_bridge_add() instead, and fix panel drivers as necessary if
they don’t report a connector type.
Given a DT node’s port and endpoint number, finds the connected node
and returns the associated bridge if any, or creates and returns a
drm panel bridge instance if a panel is connected.
Returns a pointer to the bridge if successful, or an error pointer
otherwise.
Given a DT node’s port and endpoint number, finds the connected node
and returns the associated bridge if any, or creates and returns a
drm panel bridge instance if a panel is connected.
Returns a drmm managed pointer to the bridge if successful, or an error
pointer otherwise.
The DRM panel helpers allow drivers to register panel objects with a
central registry and provide functions to retrieve those panels in display
drivers.
struct drm_panel_funcs {
int (*prepare)(struct drm_panel *panel);
int (*enable)(struct drm_panel *panel);
int (*disable)(struct drm_panel *panel);
int (*unprepare)(struct drm_panel *panel);
int (*get_modes)(struct drm_panel *panel, struct drm_connector *connector);
enum drm_panel_orientation (*get_orientation)(struct drm_panel *panel);
int (*get_timings)(struct drm_panel *panel, unsigned int num_timings, struct display_timing *timings);
void (*debugfs_init)(struct drm_panel *panel, struct dentry *root);
};
Members
prepare
Turn on panel and perform set up.
This function is optional.
enable
Enable panel (turn on back light, etc.).
This function is optional.
disable
Disable panel (turn off back light, etc.).
This function is optional.
unprepare
Turn off panel.
This function is optional.
get_modes
Add modes to the connector that the panel is attached to
and returns the number of modes added.
This function is mandatory.
get_orientation
Return the panel orientation set by device tree or EDID.
This function is optional.
get_timings
Copy display timings into the provided array and return
the number of display timings available.
This function is optional.
debugfs_init
Allows panels to create panels-specific debugfs files.
Description
The .prepare() function is typically called before the display controller
starts to transmit video data. Panel drivers can use this to turn the panel
on and wait for it to become ready. If additional configuration is required
(via a control bus such as I2C, SPI or DSI for example) this is a good time
to do that.
After the display controller has started transmitting video data, it’s safe
to call the .enable() function. This will typically enable the backlight to
make the image on screen visible. Some panels require a certain amount of
time or frames before the image is displayed. This function is responsible
for taking this into account before enabling the backlight to avoid visual
glitches.
Before stopping video transmission from the display controller it can be
necessary to turn off the panel to avoid visual glitches. This is done in
the .disable() function. Analogously to .enable() this typically involves
turning off the backlight and waiting for some time to make sure no image
is visible on the panel. It is then safe for the display controller to
cease transmission of video data.
To save power when no video data is transmitted, a driver can power down
the panel. This is the job of the .unprepare() function.
Backlight device, used to turn on backlight after the call
to enable(), and to turn off backlight before the call to
disable().
backlight is set by drm_panel_of_backlight() or
drm_panel_dp_aux_backlight() and drivers shall not assign it.
funcs
Operations that can be performed on the panel.
connector_type
Type of the panel as a DRM_MODE_CONNECTOR_* value. This is used to
initialise the drm_connector corresponding to the panel with the
correct connector type.
list
Panel entry in registry.
followers
A list of structdrm_panel_follower dependent on this panel.
follower_lock
Lock for followers list.
prepare_prev_first
The previous controller should be prepared first, before the prepare
for the panel is called. This is largely required for DSI panels
where the DSI host controller should be initialised to LP-11 before
the panel is powered up.
prepared
If true then the panel has been prepared.
enabled
If true then the panel has been enabled.
container
Pointer to the private driver structembedding this
struct drm_panel.
the connector type (DRM_MODE_CONNECTOR_*) corresponding to
the panel interface
Description
The reference count of the returned panel is initialized to 1. This
reference will be automatically dropped via devm (by calling
drm_panel_put()) when dev is removed.
Return
Pointer to container structure embedding the panel, ERR_PTR on failure.
Add a panel to the global registry so that it can be looked
up by display drivers. The panel to be added must have been
allocated by devm_drm_panel_alloc().
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. This function cannot fail (as it is
called from the pre_enable call chain). There will always be a call to
drm_panel_disable() afterwards.
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().
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. This function cannot fail (as it is called from the
enable call chain). There will always be a call to drm_panel_disable()
afterwards.
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.
look up the orientation of the panel through the “rotation” binding from a device tree node
Parameters
conststructdevice_node*np
device tree node of the panel
enumdrm_panel_orientation*orientation
orientation enumto be filled in
Description
Looks up the rotation of a panel in the device tree. The orientation of the
panel is expressed as a property name “rotation” in the device tree. The
rotation in the device tree is counter clockwise.
Return
0 when a valid rotation value (0, 90, 180, or 270) is read or the
rotation property doesn’t exist. Return a negative error code on failure.
A panel follower is called right after preparing/enabling the panel and right
before unpreparing/disabling the panel. It’s primary intention is to power on
an associated touchscreen, though it could be used for any similar devices.
Multiple devices are allowed the follow the same panel.
If a follower is added to a panel that’s already been prepared/enabled, the
follower’s prepared/enabled callback is called right away.
The “panel” property of the follower points to the panel to be followed.
Return
0 or an error code. Note that -ENODEV means that we detected that
follower_dev is not actually following a panel. The caller may
choose to ignore this return value if following a panel is optional.
Undo drm_panel_add_follower(). This includes calling the follower’s
unpreparing/disabling function if we’re removed from a panel that’s currently
prepared/enabled.
A typical implementation for a panel driver supporting device tree
will call this function at probe time. Backlight will then be handled
transparently without requiring any intervention from the driver.
drm_panel_of_backlight() must be called after the call to drm_panel_init().
This function checks for platform specific (e.g. DMI based) quirks
providing info on panel_orientation for systems where this cannot be
probed from the hard-/firm-ware. To avoid false-positive this function
takes the panel resolution as argument and checks that against the
resolution expected by the quirk-table entry.
Note this function is also used outside of the drm-subsys, by for example
the efifb code. Because of this this function gets compiled into its own
kernel-module when built as a module.
Return
A DRM_MODE_PANEL_ORIENTATION_* value if there is a quirk for this system,
or DRM_MODE_PANEL_ORIENTATION_UNKNOWN if there is no quirk.
This function checks for platform specific (e.g. DMI based) quirks
providing info on the minimum backlight brightness for systems where this
cannot be probed correctly from the hard-/firm-ware and other sources.
Return
a drm_panel_backlight_quirk struct if a quirk was found, otherwise an
error pointer.
This helper library provides an easy way for drivers to leverage the atomic
framework to implement panel self refresh (SR) support. Drivers are
responsible for initializing and cleaning up the SR helpers on load/unload
(see drm_self_refresh_helper_init/drm_self_refresh_helper_cleanup).
The connector is responsible for setting
drm_connector_state.self_refresh_aware to true at runtime if it is SR-aware
(meaning it knows how to initiate self refresh on the panel).
Once a crtc has enabled SR using drm_self_refresh_helper_init, the
helpers will monitor activity and call back into the driver to enable/disable
SR as appropriate. The best way to think about this is that it’s a DPMS
on/off request with drm_crtc_state.self_refresh_active set in crtc state
that tells you to disable/enable SR on the panel instead of power-cycling it.
During SR, drivers may choose to fully disable their crtc/encoder/bridge
hardware (in which case no driver changes are necessary), or they can inspect
drm_crtc_state.self_refresh_active if they want to enter low power mode
without full disable (in case full disable/enable is too slow).
SR will be deactivated if there are any atomic updates affecting the
pipe that is in SR mode. If a crtc is driving multiple connectors, all
connectors must be SR aware and all will enter/exit SR mode at the same time.
If the crtc and connector are SR aware, but the panel connected does not
support it (or is otherwise unable to enter SR), the driver should fail
atomic_check when drm_crtc_state.self_refresh_active is true.
the amount of time in ms that this commit took to complete
unsignedintnew_self_refresh_mask
bitmask of crtc’s that have self_refresh_active in
new state
Description
Called after drm_mode_config_funcs.atomic_commit_tail, this function will
update the average entry/exit self refresh times on self refresh transitions.
These averages will be used when calculating how long to delay before
entering self refresh mode after activity.
Called at the end of atomic check. This function checks the state for flags
incompatible with self refresh exit and changes them. This is a bit
disingenuous since userspace is expecting one thing and we’re giving it
another. However in order to keep self refresh entirely hidden from
userspace, this is required.
At the end, we queue up the self refresh entry work so we can enter PSR after
the desired delay.
Provides a default connector state check handler for HDMI connectors.
Checks that a desired connector update is valid, and updates various
fields of derived state.
The HDMI connector state to generate the infoframe from
Description
This function is meant for HDMI connector drivers to write their
infoframes. It will typically be used in a
drm_connector_helper_funcs.atomic_enable implementation.
This function is meant for HDMI connector drivers to update their
audio infoframe. It will typically be used in one of the ALSA hooks
(most likely prepare).
This function is meant for HDMI connector drivers to stop sending their
audio infoframe. It will typically be used in one of the ALSA hooks
(most likely shutdown).
HDMI Connector implementation of the force callback
Parameters
structdrm_connector*connector
A pointer to the HDMI connector
Description
This function implements the .force() callback for the HDMI connectors. It
can either be used directly as the callback or should be called from within
the .force() callback implementation to maintain the HDMI-specific
connector’s data.
drm_device for which HDCP revocation check is requested
u8*ksvs
List of KSVs (HDCP receiver IDs)
u32ksv_count
KSV count passed in through ksvs
Description
This function reads the HDCP System renewability Message(SRM Table)
from userspace as a firmware and parses it for the revoked HDCP
KSVs(Receiver IDs) detected by DCP LLC. Once the revoked KSVs are known,
revoked state of the KSVs in the list passed in by display drivers are
decided and response is sent.
SRM should be presented in the name of “display_hdcp_srm.bin”.
is HDCP Content Type property needed for connector
Description
This is used to add support for content protection on select connectors.
Content Protection is intentionally vague to allow for different underlying
technologies, however it is most implemented by HDCP.
When hdcp_content_type is true enumproperty called HDCP Content Type is
created (if it is not already) and attached to the connector.
This property is used for sending the protected content’s stream type
from userspace to kernel on selected connectors. Protected content provider
will decide their type of their content and declare the same to kernel.
When kernel triggered content protection state change like DESIRED->ENABLED
and ENABLED->DESIRED, will use drm_hdcp_update_content_protection() to update
the content protection state of a connector.
Updates the content protection state of a connector
Parameters
structdrm_connector*connector
drm_connector on which content protection state needs an update
u64val
New state of the content protection property
Description
This function can be used by display drivers, to update the kernel triggered
content protection state changes of a drm_connector such as DESIRED->ENABLED
and ENABLED->DESIRED. No uevent for DESIRED->UNDESIRED or ENABLED->UNDESIRED,
as userspace is triggering such state change and kernel performs it without
fail.This function update the new state of the property into the connector’s
state and generate an uevent to notify the userspace.
These functions contain some common logic and helpers at various abstraction
levels to deal with Display Port sink devices and related things like DP aux
channel transfers, EDID reading over DP aux channels, decoding certain DPCD
blocks, ...
The DisplayPort AUX channel is an abstraction to allow generic, driver-
independent access to AUX functionality. Drivers can take advantage of
this by filling in the fields of the drm_dp_aux structure.
Transactions are described using a hardware-independent drm_dp_aux_msg
structure, which is passed into a driver’s .transfer() implementation.
Both native and I2C-over-AUX transactions are supported.
DP secondaray data packet data blocks
VSC SDP Payload for PSR
db[0]: Stereo Interface
db[1]: 0 - PSR State; 1 - Update RFB; 2 - CRC Valid
db[2]: CRC value bits 7:0 of the R or Cr component
db[3]: CRC value bits 15:8 of the R or Cr component
db[4]: CRC value bits 7:0 of the G or Y component
db[5]: CRC value bits 15:8 of the G or Y component
db[6]: CRC value bits 7:0 of the B or Cb component
db[7]: CRC value bits 15:8 of the B or Cb component
db[8] - db[31]: Reserved
VSC SDP Payload for Pixel Encoding/Colorimetry Format
db[0] - db[15]: Reserved
db[16]: Pixel Encoding and Colorimetry Formats
db[17]: Dynamic Range and Component Bit Depth
db[18]: Content Type
db[19] - db[31]: Reserved
sRGB (IEC 61966-2-1) or
ITU-R BT.601 colorimetry format
DP_COLORIMETRY_RGB_WIDE_FIXED
RGB wide gamut fixed point colorimetry format
DP_COLORIMETRY_BT709_YCC
ITU-R BT.709 colorimetry format
DP_COLORIMETRY_RGB_WIDE_FLOAT
RGB wide gamut floating point
(scRGB (IEC 61966-2-2)) colorimetry format
DP_COLORIMETRY_XVYCC_601
xvYCC601 colorimetry format
DP_COLORIMETRY_OPRGB
OpRGB colorimetry format
DP_COLORIMETRY_XVYCC_709
xvYCC709 colorimetry format
DP_COLORIMETRY_DCI_P3_RGB
DCI-P3 (SMPTE RP 431-2) colorimetry format
DP_COLORIMETRY_SYCC_601
sYCC601 colorimetry format
DP_COLORIMETRY_RGB_CUSTOM
RGB Custom Color Profile colorimetry format
DP_COLORIMETRY_OPYCC_601
opYCC601 colorimetry format
DP_COLORIMETRY_BT2020_RGB
ITU-R BT.2020 R’ G’ B’ colorimetry format
DP_COLORIMETRY_BT2020_CYCC
ITU-R BT.2020 Y’c C’bc C’rc colorimetry format
DP_COLORIMETRY_BT2020_YCC
ITU-R BT.2020 Y’ C’b C’r colorimetry format
Description
This enumis used to indicate DP VSC SDP Colorimetry formats.
It is based on DP 1.4 spec [Table 2-117: VSC SDP Payload for DB16 through
DB18] and a name of enummember follows enumdrm_colorimetry definition.
This enumis used to indicate DP VSC SDP Content Types.
It is based on DP 1.4 spec [Table 2-117: VSC SDP Payload for DB16 through
DB18]
CTA-861-G defines content types and expected processing by a sink device
CTA-861-G defines content types and expected processing by a sink device
Description
This structure represents a DP VSC SDP of drm
It is based on DP 1.4 spec [Table 2-116: VSC SDP Header Bytes] and
[Table 2-117: VSC SDP Payload for DB16 through DB18]
struct drm_dp_as_sdp {
unsigned char sdp_type;
unsigned char revision;
unsigned char length;
int vtotal;
int target_rr;
int duration_incr_ms;
int duration_decr_ms;
bool target_rr_divider;
enum operation_mode mode;
};
Members
sdp_type
Secondary-data packet type
revision
Revision Number
length
Number of valid data bytes
vtotal
Minimum Vertical Vtotal
target_rr
Target Refresh
duration_incr_ms
Successive frame duration increase
duration_decr_ms
Successive frame duration decrease
target_rr_divider
Target refresh rate divider
mode
Adaptive Sync Operation Mode
Description
This structure represents a DP AS SDP of drm
It is based on DP 2.1 spec [Table 2-126: Adaptive-Sync SDP Header Bytes] and
[Table 2-127: Adaptive-Sync SDP Payload for DB0 through DB8]
Note that currently this function will return false for panels which support various DPCD
backlight features but which require the brightness be set through PWM, and don’t support setting
the brightness level via the DPCD.
Return
True if edp_dpcd indicates that VESA backlight controls are supported, false
otherwise
user-visible name of this AUX channel and the
I2C-over-AUX adapter.
It’s also used to specify the name of the I2C adapter. If set
to NULL, dev_name() of dev will be used.
ddc
I2C adapter that can be used for I2C-over-AUX
communication
dev
pointer to structdevice that is the parent for this
AUX channel.
drm_dev
pointer to the drm_device that owns this AUX channel.
Beware, this may be NULL before drm_dp_aux_register() has been
called.
It should be set to the drm_device that will be using this AUX
channel as early as possible. For many graphics drivers this should
happen before drm_dp_aux_init(), however it’s perfectly fine to set
this field later so long as it’s assigned before calling
drm_dp_aux_register().
crtc
backpointer to the crtc that is currently using this
AUX channel
hw_mutex
internal mutex used for locking transfers.
Note that if the underlying hardware is shared among multiple
channels, the driver needs to do additional locking to
prevent concurrent access.
crc_work
worker that captures CRCs for each frame
crc_count
counter of captured frame CRCs
transfer
transfers a message representing a single AUX
transaction.
This is a hardware-specific implementation of how
transactions are executed that the drivers must provide.
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 will propagate these errors, 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.
The transfer() function must only modify the reply field of
the drm_dp_aux_msg structure. The retry logic and i2c
helpers assume this is the case.
Also note that this callback can be called no matter the
state dev is in and also no matter what state the panel is
in. It’s expected:
If the dev providing the AUX bus is currently unpowered then
it will power itself up for the transfer.
If we’re on eDP (using a drm_panel) and the panel is not in a
state where it can respond (it’s not powered or it’s in a
low power state) then this function may return an error, but
not crash. It’s up to the caller of this code to make sure that
the panel is powered on if getting an error back is not OK. If a
drm_panel driver is initiating a DP AUX transfer it may power
itself up however it wants. All other code should ensure that
the pre_enable() bridge chain (which eventually calls the
drm_panel prepare function) has powered the panel.
wait_hpd_asserted
wait for HPD to be asserted
This is mainly useful for eDP panels drivers to wait for an eDP
panel to finish powering on. It is optional for DP AUX controllers
to implement this function. It is required for DP AUX endpoints
(panel drivers) to call this function after powering up but before
doing AUX transfers unless the DP AUX endpoint driver knows that
we’re not using the AUX controller’s HPD. One example of the panel
driver not needing to call this is if HPD is hooked up to a GPIO
that the panel driver can read directly.
If a DP AUX controller does not implement this function then it
may still support eDP panels that use the AUX controller’s built-in
HPD signal by implementing a long wait for HPD in the transfer()
callback, though this is deprecated.
This function will efficiently wait for the HPD signal to be
asserted. The wait_us parameter that is passed in says that we
know that the HPD signal is expected to be asserted within wait_us
microseconds. This function could wait for longer than wait_us if
the logic in the DP controller has a long debouncing time. The
important thing is that if this function returns success that the
DP controller is ready to send AUX transactions.
This function returns 0 if HPD was asserted or -ETIMEDOUT if time
expired and HPD wasn’t asserted. This function should not print
timeout errors to the log.
The semantics of this function are designed to match the
readx_poll_timeout() function. That means a wait_us of 0 means
to wait forever. Like readx_poll_timeout(), this function may sleep.
NOTE: this function specifically reports the state of the HPD pin
that’s associated with the DP AUX channel. This is different from
the HPD concept in much of the rest of DRM which is more about
physical presence of a display. For eDP, for instance, a display is
assumed always present even if the HPD pin is deasserted.
i2c_nack_count
Counts I2C NACKs, used for DP validation.
i2c_defer_count
Counts I2C DEFERs, used for DP validation.
cec
structcontaining fields used for CEC-Tunneling-over-AUX.
is_remote
Is this AUX CH actually using sideband messaging.
powered_down
If true then the remote endpoint is powered down.
no_zero_sized
If the hw can’t use zero sized transfers (NVIDIA)
dpcd_probe_disabled
If probing before a DPCD access is disabled.
Description
An AUX channel can also be used to transport I2C messages to a sink. A
typical application of that is to access an EDID that’s present in the sink
device. The transfer() function can also be used to execute such
transactions. The drm_dp_aux_register() function registers an I2C adapter
that can be passed to drm_probe_ddc(). Upon removal, drivers should call
drm_dp_aux_unregister() to remove the I2C adapter. The I2C adapter uses long
transfers by default; if a partial response is received, the adapter will
drop down to the size given by the partial response for this transaction
only.
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. In most of the cases you should be using
drm_dp_dpcd_read_byte() instead.
Returns zero (0) 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.
Returns zero (0) 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.
Returns the number of bytes transferred (1) on success, or a negative
error code on failure. In most of the cases you should be using
drm_dp_dpcd_write_byte() instead.
The device requires main link attributes Mvid and Nvid to be limited
to 16 bits. So will give a constant value (0x8000) for compatability.
DP_DPCD_QUIRK_NO_PSR
The device does not support PSR even if reports that it supports or
driver still need to implement proper handling for such device.
DP_DPCD_QUIRK_NO_SINK_COUNT
The device does not set SINK_COUNT to a non-zero value.
The driver should ignore SINK_COUNT during detection. Note that
drm_dp_read_sink_count_cap() automatically checks for this quirk.
DP_DPCD_QUIRK_DSC_WITHOUT_VIRTUAL_DPCD
The device supports MST DSC despite not supporting Virtual DPCD.
The DSC caps can be read from the physical aux instead.
DP_DPCD_QUIRK_CAN_DO_MAX_LINK_RATE_3_24_GBPS
The device supports a link rate of 3.24 Gbps (multiplier 0xc) despite
the DP_MAX_LINK_RATE register reporting a lower max multiplier.
DP_DPCD_QUIRK_HBLANK_EXPANSION_REQUIRES_DSC
The device applies HBLANK expansion for some modes, but this
requires enabling DSC.
DP_DPCD_QUIRK_DSC_THROUGHPUT_BPP_LIMIT
The device doesn’t support DSC decompression at the maximum DSC
pixel throughput and compressed bpp it indicates via its DPCD DSC
capabilities. The compressed bpp must be limited above a device
specific DSC pixel throughput.
Description
Display Port sink and branch devices in the wild have a variety of bugs, try
to collect them here. The quirks are shared, but it’s up to the drivers to
implement workarounds for them.
Given the dp_phy, get a user friendly name of the DP PHY, either “DPRX” or
“LTTPR <N>”, or “<INVALID DP PHY>” on errors. The returned string is always
non-NULL and valid.
This function checks if the sink needs any extended wake time, if it does
it grants this request. Post this setup the source device can keep trying
the Aux transaction till the granted wake timeout.
If this function is not called all Aux transactions are expected to take
a default of 1ms before they throw an error.
probe a given DPCD address with a 1-byte read access
Parameters
structdrm_dp_aux*aux
DisplayPort AUX channel (SST)
unsignedintoffset
address of the register to probe
Description
Probe the provided DPCD address by reading 1 byte from it. The function can
be used to trigger some side-effect the read access has, like waking up the
sink, without the need for the read-out value.
Returns 0 if the read access suceeded, or a negative error code on failure.
DisplayPort AUX channel; for convenience it’s OK to pass NULL here
and the function will be a no-op.
boolpowered
true if powered; false if not
Description
If the endpoint device on the DP AUX bus is known to be powered down
then this function can be called to make future transfers fail immediately
instead of needing to time out.
If this function is never called then a device defaults to being powered.
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.
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.
Fetch the AUX DPCD registers for the DPRX or an LTTPR PHY link status. The
layout of the returned link_status matches the DPCD register layout of the
DPRX PHY link status.
Returns 0 if the information was read successfully or a negative error code
on failure.
Try waiting for the sink to finish updating its payload table by polling for
the ACT handled bit of DP_PAYLOAD_TABLE_UPDATE_STATUS for up to timeout_ms
milliseconds, defaulting to 3000 ms if 0.
Return
0 if the ACT was handled in time, negative error code on failure.
port type to be checked. Can be:
DP_DS_PORT_TYPE_DP, DP_DS_PORT_TYPE_VGA, DP_DS_PORT_TYPE_DVI,
DP_DS_PORT_TYPE_HDMI, DP_DS_PORT_TYPE_NON_EDID,
DP_DS_PORT_TYPE_DP_DUALMODE or DP_DS_PORT_TYPE_WIRELESS.
Description
Caveat: Only works with DPCD 1.1+ port caps.
Return
whether the downstream facing port matches the type.
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. For drivers which are
grandparents to their AUX adapters (e.g. the AUX adapter is parented by a
drm_connector), you must still call drm_dp_aux_register() once the connector
has been registered to allow userspace access to the auxiliary DP channel.
Likewise, for such drivers you should also assign drm_dp_aux.drm_dev as
early as possible so that the drm_device that corresponds to the AUX adapter
may be mentioned in debugging output from the DRM DP helpers.
For devices which use a separate platform device for their AUX adapters, this
may be called as early as required by the driver.
For devices where the AUX channel is a device that exists independently of
the drm_device that uses it, such as SoCs and bridge devices, it is
recommended to call drm_dp_aux_register() after a drm_device has been
assigned to drm_dp_aux.drm_dev, and likewise to call
drm_dp_aux_unregister() once the drm_device should no longer be associated
with the AUX channel (e.g. on bridge detach).
Drivers which need to use the aux channel before either of the two points
mentioned above need to call drm_dp_aux_init() in order to use the AUX
channel before registration.
Returns 0 on success or a negative error code on failure.
Get the mask of supported slice counts from the sink’s DSC DPCD register.
Return
Mask of slice counts supported by the DSC sink:
- > 0: bit#0,1,3,5..,23 set if the sink supports 1,2,4,6..,24 slices
- 0: if the sink doesn’t support any slices
Get the max slice count supported by the DSC sink.
Parameters
constu8dsc_dpcd[DP_DSC_RECEIVER_CAP_SIZE]
DSC capabilities from DPCD
boolis_edp
true if its eDP, false for DP
Description
Read the slice capabilities DPCD register from DSC sink to get
the maximum slice count supported. This is used to populate
the DSC parameters in the structdrm_dsc_config by the driver.
Driver creates an infoframe using these parameters to populate
structdrm_dsc_pps_infoframe. These are sent to the sink using DSC
infoframe using the helper function drm_dsc_pps_infoframe_pack()
Return
Maximum slice count supported by DSC sink or 0 its invalid
Read the DSC DPCD register to parse the line buffer depth in bits which is
number of bits of precision within the decoder line buffer supported by
the DSC sink. This is used to populate the DSC parameters in the
structdrm_dsc_config by the driver.
Driver creates an infoframe using these parameters to populate
structdrm_dsc_pps_infoframe. These are sent to the sink using DSC
infoframe using the helper function drm_dsc_pps_infoframe_pack()
Return
Line buffer depth supported by DSC panel or 0 its invalid
Get all the input bits per component values supported by the DSC sink.
Parameters
constu8dsc_dpcd[DP_DSC_RECEIVER_CAP_SIZE]
DSC capabilities from DPCD
u8dsc_bpc[3]
An array to be filled by this helper with supported
input bpcs.
Description
Read the DSC DPCD from the sink device to parse the supported bits per
component values. This is used to populate the DSC parameters
in the structdrm_dsc_config by the driver.
Driver creates an infoframe using these parameters to populate
structdrm_dsc_pps_infoframe. These are sent to the sink using DSC
infoframe using the helper function drm_dsc_pps_infoframe_pack()
Get a DSC sink’s maximum pixel throughput per slice
Parameters
constu8dsc_dpcd[DP_DSC_RECEIVER_CAP_SIZE]
DSC sink’s capabilities from DPCD
intpeak_pixel_rate
Cumulative peak pixel rate in kHz
boolis_rgb_yuv444
The mode is either RGB or YUV444
Description
Return the DSC sink device’s maximum pixel throughput per slice, based on
the device’s dsc_dpcd capabilities, the peak_pixel_rate of the transferred
stream(s) and whether the output format is_rgb_yuv444 or yuv422/yuv420.
Note that peak_pixel_rate is the total pixel rate transferred to the same
DSC/display sink. For instance to calculate a tile’s slice count of an MST
multi-tiled display sink (not considering here the required
rounding/alignment of slice count):
Return the branch device’s maximum overall DSC pixel throughput, based on
the device’s DPCD DSC branch capabilities, and whether the output
format is_rgb_yuv444 or yuv422/yuv420.
Return
0: The maximum overall throughput capability is not indicated by
the device separately and it must be determined from the per-slice
max throughput (see drm_dp_dsc_branch_slice_max_throughput())
and the maximum slice count supported by the device.
> 0: The maximum overall DSC pixel throughput supported by the branch
Get the number of detected LTTPRs from the LTTPR common capabilities info.
Return
-ERANGE if more than supported number (8) of LTTPRs are detected
-EINVAL if the DP_PHY_REPEATER_CNT register contains an invalid value
otherwise the number of detected LTTPRs
maximum frl bw to be configured between PCON and HDMI sink
u8frl_mode
FRL Training mode, it can be either Concurrent or Sequential.
In Concurrent Mode, the FRL link bring up can be done along with
DP Link training. In Sequential mode, the FRL link bring up is done prior to
the DP Link training.
Description
Returns 0 if success, else returns negative error code.
FRL training type, can be Extended, or Normal.
In Normal FRL training, the PCON tries each frl bw from the max_frl_mask
starting from min, and stops when link training is successful. In Extended
FRL training, all frl bw selected in the mask are trained by the PCON.
Description
Returns 0 if success, else returns negative error code.
pointer to store bitmask of the trained bw configuration.
Valid only if the MODE returned is FRL. For Normal Link training mode
only 1 of the bits will be set, but in case of Extended mode, more than
one bits can be set.
Description
Returns the link mode : TMDS or FRL on success, else returns negative error
code.
Sets the brightness level of an eDP panel’s backlight. Note that the panel’s backlight must
already have been enabled by the driver by calling drm_edp_backlight_enable().
The initial backlight level to set via AUX, if there is one
Description
This function handles enabling DPCD backlight controls on a panel over DPCD, while additionally
restoring any important backlight state such as the given backlight level, the brightness byte
count, backlight frequency, etc.
Note that certain panels do not support being enabled or disabled via DPCD, but instead require
that the driver handle enabling/disabling the panel through implementation-specific means using
the EDP_BL_PWR GPIO. For such panels, drm_edp_backlight_info.aux_enable will be set to false,
this function becomes a no-op, and the driver is expected to handle powering the panel on using
the EDP_BL_PWR GPIO.
This function handles disabling DPCD backlight controls on a panel over AUX.
Note that certain panels do not support being enabled or disabled via DPCD, but instead require
that the driver handle enabling/disabling the panel through implementation-specific means using
the EDP_BL_PWR GPIO. For such panels, drm_edp_backlight_info.aux_enable will be set to false,
this function becomes a no-op, and the driver is expected to handle powering the panel off using
the EDP_BL_PWR GPIO.
Return
0 on success or no-op, negative error code on failure.
Where to store the probed brightness level, if any
u8*current_mode
Where to store the currently set backlight control mode
boolneed_luminance
Tells us if a we want to manipulate backlight using luminance values
Description
Initializes a drm_edp_backlight_infostructby probing aux for it’s backlight capabilities,
along with also probing the current and maximum supported brightness levels.
If driver_pwm_freq_hz is non-zero, this will be used as the backlight frequency. Otherwise, the
default frequency from the panel is used.
Use this function to create and handle backlight if your panel
supports backlight control over DP AUX channel using DPCD
registers as per VESA’s standard backlight control interface.
When the panel is enabled backlight will be enabled after a
successful call to drm_panel_funcs.enable()
A typical implementation for a panel driver supporting backlight
control over DP AUX will call this function at probe time.
Backlight will then be handled transparently without requiring
any intervention from the driver.
pixel count of the active period in one scanline of the stream
intdsc_slice_count
number of slices for DSC or ‘0’ for non-DSC
intbpp_x16
bits per pixel in .4 binary fixed point
unsignedlongflags
DRM_DP_OVERHEAD_x flags
Description
Calculate the BW allocation overhead of a DP link stream, depending
on the link’s
- lane_count
- SST/MST mode (flags / DRM_DP_OVERHEAD_MST)
- symbol size (flags / DRM_DP_OVERHEAD_UHBR)
- FEC mode (flags / DRM_DP_OVERHEAD_FEC)
- SSC/REF_CLK mode (flags / DRM_DP_OVERHEAD_SSC_REF_CLK)
as well as the stream’s
- hactive timing
- bpp_x16 color depth
- compression mode (dsc_slice_count != 0)
Note that this overhead doesn’t account for the 8b/10b, 128b/132b
channel coding efficiency, for that see
drm_dp_link_bw_channel_coding_efficiency().
Returns the overhead as 100% + overhead% in 1ppm units.
Return the channel coding efficiency of the given DP link type, which is
either 8b/10b or 128b/132b (aka UHBR). The corresponding overhead includes
the 8b -> 10b, 128b -> 132b pixel data to link symbol conversion overhead
and for 128b/132b any link or PHY level control symbol insertion overhead
(LLCP, FEC, PHY sync, see DP Standard v2.1 3.5.2.18). For 8b/10b the
corresponding FEC overhead is BW allocation specific, included in the value
returned by drm_dp_bw_overhead().
Returns the efficiency in the 100%/coding-overhead% ratio in
1ppm units.
Given a link rate and lanes, get the data bandwidth.
Data bandwidth is the actual payload rate, which depends on the data
bandwidth efficiency and the link rate.
Note that protocol layers above the DPRX link level considered here can
further limit the maximum data rate. Such layers are the MST topology (with
limits on the link between the source and first branch device as well as on
the whole MST path until the DPRX link) and (Thunderbolt) DP tunnels -
which in turn can encapsulate an MST link with its own limit - with each
SST or MST encapsulated tunnel sharing the BW of a tunnel group.
A new connector was registered with associated CEC adapter name and
CEC adapter parent device. After registering the name and parent
drm_dp_cec_set_edid() is called to check if the connector supports
CEC and to register a CEC adapter if that is the case.
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.
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.
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.
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.
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.
Type1 adaptors do not support any register writes.
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.
The refcounting schemes for structdrm_dp_mst_branch and structdrm_dp_mst_port are somewhat unusual. Both ports and branch devices have
two different kinds of refcounts: topology refcounts, and malloc refcounts.
Topology refcounts are not exposed to drivers, and are handled internally
by the DP MST helpers. The helpers use them in order to prevent the
in-memory topology state from being changed in the middle of critical
operations like changing the internal state of payload allocations. This
means each branch and port will be considered to be connected to the rest
of the topology until its topology refcount reaches zero. Additionally,
for ports this means that their associated structdrm_connector will stay
registered with userspace until the port’s refcount reaches 0.
Malloc references are used to keep a structdrm_dp_mst_port or structdrm_dp_mst_branch allocated even after all of its topology references have
been dropped, so that the driver or MST helpers can safely access each
branch’s last known state before it was disconnected from the topology.
When the malloc refcount of a port or branch reaches 0, the memory
allocation containing the structdrm_dp_mst_branch or structdrm_dp_mst_port respectively will be freed.
For structdrm_dp_mst_branch, malloc refcounts are not currently exposed
to drivers. As of writing this documentation, there are no drivers that
have a usecase for accessing structdrm_dp_mst_branch outside of the MST
helpers. Exposing this API to drivers in a race-free manner would take more
tweaking of the refcounting scheme, however patches are welcome provided
there is a legitimate driver usecase for this.
Let’s take a look at why the relationship between topology and malloc
refcounts is designed the way it is.
An example of topology and malloc refs in a DP MST topology with two
active payloads. Topology refcount increments are indicated by solid
lines, and malloc refcount increments are indicated by dashed lines.
Each starts from the branch which incremented the refcount, and ends at
the branch to which the refcount belongs to, i.e. the arrow points the
same way as the C pointers used to reference a structure.¶
As you can see in the above figure, every branch increments the topology
refcount of its children, and increments the malloc refcount of its
parent. Additionally, every payload increments the malloc refcount of its
assigned port by 1.
So, what would happen if MSTB #3 from the above figure was unplugged from
the system, but the driver hadn’t yet removed payload #2 from port #3? The
topology would start to look like the figure below.
Ports and branch devices which have been released from memory are
colored grey, and references which have been removed are colored red.¶
Whenever a port or branch device’s topology refcount reaches zero, it will
decrement the topology refcounts of all its children, the malloc refcount
of its parent, and finally its own malloc refcount. For MSTB #4 and port
#4, this means they both have been disconnected from the topology and freed
from memory. But, because payload #2 is still holding a reference to port
#3, port #3 is removed from the topology but its structdrm_dp_mst_port
is still accessible from memory. This also means port #3 has not yet
decremented the malloc refcount of MSTB #3, so its structdrm_dp_mst_branch will also stay allocated in memory until port #3’s
malloc refcount reaches 0.
This relationship is necessary because in order to release payload #2, we
need to be able to figure out the last relative of port #3 that’s still
connected to the topology. In this case, we would travel up the topology as
shown below.
And finally, remove payload #2 by communicating with port #2 through
sideband transactions.
A history of each topology
reference/dereference. See CONFIG_DRM_DEBUG_DP_MST_TOPOLOGY_REFS.
destroy_next
linked-list entry used by
drm_dp_delayed_destroy_work()
rad
Relative Address of the MST branch.
For drm_dp_mst_topology_mgr.mst_primary, it’s rad[8] are all 0,
unset and unused. For MST branches connected after mst_primary,
in each element of rad[] the nibbles are ordered by the most
signifcant 4 bits first and the least significant 4 bits second.
if a link address message has been sent to this device yet.
guid
guid for DP 1.2 branch device. port under this branch can be
identified by port #.
Description
This structure represents an MST branch device, there is one
primary branch device at the root, along with any other branches connected
to downstream port of parent branches.
The time slot that this payload starts on. Because payload start slots
can’t be determined ahead of time, the contents of this value are UNDEFINED at atomic
check time. This shouldn’t usually matter, as the start slot should never be relevant for
atomic state computations.
Since this value is determined at commit time instead of check time, this value is
protected by the MST helpers ensuring that async commits operating on the given topology
never run in parallel. In the event that a driver does need to read this value (e.g. to
inform hardware of the starting timeslot for a payload), the driver may either:
If neither of the two above solutions suffice (e.g. the driver needs to read the start
slot in the middle of an atomic commit without waiting for some reason), then drivers
should cache this value themselves after changing payloads.
vcpi
The Virtual Channel Payload Identifier
time_slots
The number of timeslots allocated to this payload from the source DP Tx to
the immediate downstream DP Rx
pbn
The payload bandwidth for this payload
delete
Whether or not we intend to delete this payload during this atomic commit
dsc_enabled
Whether or not this payload has DSC enabled
payload_allocation_status
The allocation status of this payload
next
The list node for this payload
Description
The primary atomic state structure for a given MST payload. Stores information like current
bandwidth allocation, intended action for this payload, etc.
If this manager is enabled for an MST capable port. False
if no MST sink/branch devices is connected.
payload_id_table_cleared
Whether or not we’ve cleared the payload
ID table for mst_primary. Protected by lock.
reset_rx_state
The down request’s reply and up request message
receiver state must be reset, after the topology manager got
removed. Protected by lock.
payload_count
The number of currently active payloads in hardware. This value is only
intended to be used internally by MST helpers for payload tracking, and is only safe to
read/write from the atomic commit (not check) context.
next_start_slot
The starting timeslot to use for new VC payloads. This value is used
internally by MST helpers for payload tracking, and is only safe to read/write from the
atomic commit (not check) context.
mst_primary
Pointer to the primary/first branch device.
dpcd
Cache of DPCD for primary port.
sink_count
Sink count from DEVICE_SERVICE_IRQ_VECTOR_ESI0.
funcs
Atomic helper callbacks
qlock
protects tx_msg_downq and drm_dp_sideband_msg_tx.state
tx_msg_downq
List of pending down requests
tx_waitq
Wait to queue stall for the tx worker.
work
Probe work.
tx_work
Sideband transmit worker. This can nest within the main
work worker for each transaction work launches.
destroy_port_list
List of to be destroyed connectors.
destroy_branch_device_list
List of to be destroyed branch
devices.
delayed_destroy_lock
Protects destroy_port_list and
destroy_branch_device_list.
delayed_destroy_wq
Workqueue used for delayed_destroy_work items.
A dedicated WQ makes it possible to drain any requeued work items
on it.
delayed_destroy_work
Work item to destroy MST port and branch
devices, needed to avoid locking inversion.
up_req_list
List of pending up requests from the topology that
need to be processed, in chronological order.
up_req_lock
Protects up_req_list
up_req_work
Work item to process up requests received from the
topology. Needed to avoid blocking hotplug handling and sideband
transmissions.
This structrepresents the toplevel displayport MST topology manager.
There should be one instance of this for every MST capable DP connector
on the GPU.
This iterates over all DRM DP MST topology managers in an atomic update,
tracking both old and new state. This is useful in places where the state
delta needs to be considered, for example in atomic check functions.
This iterates over all DRM DP MST topology managers in an atomic update,
tracking only the old state. This is useful in disable functions, where we
need the old state the hardware is still in.
This iterates over all DRM DP MST topology managers in an atomic update,
tracking only the new state. This is useful in enable functions, where we
need the new state the hardware should be in when the atomic commit
operation has completed.
Because port could potentially be freed at any time by the DP MST helpers
if drm_dp_mst_port.malloc_kref reaches 0, including during a call to this
function, drivers that which to make use of structdrm_dp_mst_port should
ensure that they grab at least one main malloc reference to their MST ports
in drm_dp_mst_topology_cbs.add_connector. This callback is called before
there is any chance for drm_dp_mst_port.malloc_kref to reach 0.
Helper to register the remote aux device for this MST port. Drivers should
call this from their mst connector’s late_register hook to enable MST aux
devices.
Helper to unregister the remote aux device for this MST port, registered by
drm_dp_mst_connector_late_register(). Drivers should call this from their mst
connector’s early_unregister hook.
Determines the starting time slot for the given payload, and programs the VCPI for this payload
into the DPCD of DPRX. After calling this, the driver should generate ACT and payload packets.
Removes a payload along the virtual channel if it was successfully allocated.
After calling this, the driver should set HW to generate ACT and then switch to new
payload allocation state.
Updates the starting time slots of all other payloads which would have been shifted towards
the start of the payload ID table as a result of removing a payload. Driver should call this
function whenever it removes a payload in its HW. It’s independent to the result of payload
allocation/deallocation at branch devices along the virtual channel.
If payload was successfully assigned a starting time slot by drm_dp_add_payload_part1(), this
function will send the sideband messages to finish allocating this payload.
Calculate the total bandwidth of a MultiStream Transport link. The returned
value is in units of PBNs/(timeslots/1 MTP). This value can be used to
convert the number of PBNs required for a given stream to the number of
timeslots this stream requires in each MTP.
Returns the BW / timeslot value in 20.12 fixed point format.
Queue a work to probe the MST topology. Driver’s should call this only to
sync the topology’s HW->SW state after the MST link’s parameters have
changed in a way the state could’ve become out-of-sync. This is the case
for instance when the link rate between the source and first downstream
branch device has switched between UHBR and non-UHBR rates. Except of those
cases - for instance when a sink gets plugged/unplugged to a port - the SW
state will get updated automatically via MST UP message notifications.
whether or not to perform topology reprobing synchronously
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.
During system resume (where it is assumed that the driver will be calling
drm_atomic_helper_resume()) this function should be called beforehand with
sync set to true. In contexts like runtime resume where the driver is not
expected to be calling drm_atomic_helper_resume(), this function should be
called with sync set to false in order to avoid deadlocking.
Return
-1 if the MST topology was removed while we were suspended, 0
otherwise.
4 bytes used to ack events starting 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 HPD IRQ,
along with the value of the DEVICE_SERVICE_IRQ_VECTOR_ESI0. The
topology manager will process the sideband messages received
as indicated in the DEVICE_SERVICE_IRQ_VECTOR_ESI0 and set the
corresponding flags that Driver has to ack the DP receiver later.
Note that driver shall also call
drm_dp_mst_hpd_irq_send_new_request() if the ‘handled’ is set
after calling this function, to try to kick off a new request in
the queue if the previous message transaction is completed.
This should be called from the driver when mst irq event is handled
and acked. Note that new down request should only be sent when
previous message transaction is completed. Source is not supposed to generate
interleaved message transactions.
Allocates time slots to port, replacing any previous time slot allocations it may
have had. Any atomic drivers which support MST must call this function in
their drm_encoder_helper_funcs.atomic_check() callback unconditionally to
change the current time slot allocation for the new state, and ensure the MST
atomic state is added whenever the state of payloads in the topology changes.
Allocations set by this function are not checked against the bandwidth
restraints of mgr until the driver calls drm_dp_mst_atomic_check().
Additionally, it is OK to call this function multiple times on the same
port as needed. It is not OK however, to call this function and
drm_dp_atomic_release_time_slots() in the same atomic check phase.
Releases any time slots that have been allocated to a port in the atomic
state. Any atomic drivers which support MST must call this function
unconditionally in their drm_connector_helper_funcs.atomic_check() callback.
This helper will check whether time slots would be released by the new state and
respond accordingly, along with ensuring the MST state is always added to the
atomic state whenever a new state would modify the state of payloads on the
topology.
It is OK to call this even if port has been removed from the system.
Additionally, it is OK to call this function multiple times on the same
port as needed. It is not OK however, to call this function and
drm_dp_atomic_find_time_slots() on the same port in a single atomic check
phase.
Wait for all pending commits on MST topologies, prepare new MST state for commit
Parameters
structdrm_atomic_state*state
global atomic state
Description
Goes through any MST topologies in this atomic state, and waits for any pending commits which
touched CRTCs that were/are on an MST topology to be programmed to hardware and flipped to before
returning. This is to prevent multiple non-blocking commits affecting an MST topology from racing
with eachother by forcing them to be executed sequentially in situations where the only resources
the modeset objects in these commits share are an MST topology.
This function also prepares the new MST state for commit by performing some state preparation
which can’t be done until this point, such as reading back the final VC start slots (which are
determined at commit-time) from the previous state.
Since MST uses fake drm_encoder structs, the generic atomic modesetting code isn’t able to
serialize non-blocking commits happening on the real DP connector of an MST topology switching
into/away from MST mode - as the CRTC on the real DP connector and the CRTCs on the connector’s
MST topology will never share the same drm_encoder.
This function takes care of this serialization issue, by checking a root MST connector’s atomic
state to determine if it is about to have a modeset - and then pulling in the MST topology state
if so, along with adding any relevant CRTCs to drm_dp_mst_topology_state.pending_crtc_mask.
Tries waiting for the MST hub to finish updating it’s payload table by
polling for the ACT handled bit for up to 3 seconds (yes-some hubs really
take that long).
Return
0 if the ACT was handled in time, negative error code on failure.
The function returns true if port is downstream of parent. If parent is
NULL - denoting the root port - the function returns true if port is in
mgr’s topology.
Whenever there is a change in mst topology
DSC configuration would have to be recalculated
therefore we need to trigger modeset on all affected
CRTCs in that topology
Newly recalculated bw required for link with DSC enabled
boolenable
Boolean flag to enable or disable DSC on the port
Description
This function enables DSC on the given Port
by recalculating its vcpi from pbn provided
and sets dsc_enable flag to keep track of which
ports have DSC enabled
Checks the given MST manager’s topology state for an atomic update to ensure
that it’s valid. This includes checking whether there’s enough bandwidth to
support the new timeslot allocations in the atomic update.
The non-root port where a BW limit check failed
with all the ports downstream of failing_port passing
the BW limit check.
The returned port pointer is valid until at least
one payload downstream of it exists.
NULL if the BW limit check failed at the root port
with all the ports downstream of the root port passing
the BW limit check.
-EINVAL, if the new state is invalid, because the root port has
too many payloads.
Return
0 if the new state is valid
-ENOSPC, if the new state is invalid, because of BW limitation
Checks the given topology state for an atomic update to ensure that it’s
valid, calling drm_dp_mst_atomic_check_mgr() for all MST manager in the
atomic state. This includes checking whether there’s enough bandwidth to
support the new timeslot allocations in the atomic update.
Any atomic drivers supporting DP MST must make sure to call this after
checking the rest of their state in their
drm_mode_config_funcs.atomic_check() callback.
MST topology manager, also the private object in this case
Description
This function wraps drm_atomic_get_priv_obj_state() passing in the MST atomic
state vtable so that the private object state returned is that of a MST
topology object.
get old MST topology state in atomic state, if any
Parameters
structdrm_atomic_state*state
global atomic state
structdrm_dp_mst_topology_mgr*mgr
MST topology manager, also the private object in this case
Description
This function wraps drm_atomic_get_old_private_obj_state() passing in the MST atomic
state vtable so that the private object state returned is that of a MST
topology object.
Return
The old MST topology state, or NULL if there’s no topology state for this MST mgr
in the global atomic state
get new MST topology state in atomic state, if any
Parameters
structdrm_atomic_state*state
global atomic state
structdrm_dp_mst_topology_mgr*mgr
MST topology manager, also the private object in this case
Description
This function wraps drm_atomic_get_new_private_obj_state() passing in the MST atomic
state vtable so that the private object state returned is that of a MST
topology object.
Return
The new MST topology state, or NULL if there’s no topology state for this MST mgr
in the global atomic state
Attempts to grab a topology reference to mstb, if it hasn’t yet been
removed from the topology (e.g. drm_dp_mst_branch.topology_kref has
reached 0). Holding a topology reference implies that a malloc reference
will be held to mstb as long as the user holds the topology reference.
Care should be taken to ensure that the user has at least one malloc
reference to mstb. If you already have a topology reference to mstb, you
should use drm_dp_mst_topology_get_mstb() instead.
Increments drm_dp_mst_branch.topology_refcount without checking whether or
not it’s already reached 0. This is only valid to use in scenarios where
you are already guaranteed to have at least one active topology reference
to mstb. Otherwise, drm_dp_mst_topology_try_get_mstb() must be used.
Attempts to grab a topology reference to port, if it hasn’t yet been
removed from the topology (e.g. drm_dp_mst_port.topology_kref has reached
0). Holding a topology reference implies that a malloc reference will be
held to port as long as the user holds the topology reference.
Care should be taken to ensure that the user has at least one malloc
reference to port. If you already have a topology reference to port, you
should use drm_dp_mst_topology_get_port() instead.
Increments drm_dp_mst_port.topology_refcount without checking whether or
not it’s already reached 0. This is only valid to use in scenarios where
you are already guaranteed to have at least one active topology reference
to port. Otherwise, drm_dp_mst_topology_try_get_port() must be used.
This library provides helpers for MIPI Display Bus Interface (DBI)
compatible display controllers.
Many controllers for tiny lcd displays are MIPI compliant and can use this
library. If a controller uses registers 0x2A and 0x2B to set the area to
update and uses register 0x2C to write to frame memory, it is most likely
MIPI compliant.
Only MIPI Type 1 displays are supported since a full frame memory is needed.
There are 3 MIPI DBI implementation types:
Motorola 6800 type parallel bus
Intel 8080 type parallel bus
SPI type with 3 options:
9-bit with the Data/Command signal as the ninth bit
Same as above except it’s sent as 16 bits
8-bit with the Data/Command signal as a separate D/CX pin
Currently mipi_dbi only supports Type C options 1 and 3 with
mipi_dbi_spi_init().
Necessary for drivers with private data since devm_drm_dev_alloc()
can’t allocate structures that embed a structure which then again
embeds drm_device.
This macro initializes structdrm_simple_display_pipe_funcs with default
values for MIPI-DBI-based devices. The only callback that depends on the
hardware is enable, for which the driver has to provide an implementation.
MIPI-based drivers are encouraged to use this macro for initialization.
This function validates a given display mode against the MIPI DBI’s hardware
display. Drivers can use this as their drm_simple_display_pipe_funcs->mode_valid
callback.
Drivers which don’t use mipi_dbi_pipe_update() because they have custom
framebuffer flushing, can’t use this function since they both use the same
flushing code.
This function disables backlight if present, if not the display memory is
blanked. The regulator is disabled if in use. Drivers can use this as their
drm_simple_display_pipe_funcs->disable callback.
MIPI DBI device initialization with custom formats
Parameters
structmipi_dbi_dev*dbidev
MIPI DBI device structure to initialize
conststructdrm_simple_display_pipe_funcs*funcs
Display pipe functions
constuint32_t*formats
Array of supported formats (DRM_FORMAT_*).
unsignedintformat_count
Number of elements in formats
conststructdrm_display_mode*mode
Display mode
unsignedintrotation
Initial rotation in degrees Counter Clock Wise
size_ttx_buf_size
Allocate a transmit buffer of this size.
Description
This function sets up a drm_simple_display_pipe with a drm_connector that
has one fixed drm_display_mode which is rotated according to rotation.
This mode is used to set the mode config min/max width/height properties.
Use mipi_dbi_dev_init() if you want native RGB565 and emulated XRGB8888 format.
Note
Some of the helper functions expects RGB565 to be the default format and the
transmit buffer sized to fit that.
This function checks the Power Mode register (if readable) to see if
display output is turned on. This can be used to see if the bootloader
has already turned on the display avoiding flicker when the pipeline is
enabled.
Return
true if the display can be verified to be on, false otherwise.
This function enables the regulator if used and if the display is off, it
does a hardware and software reset. If mipi_dbi_display_is_on() determines
that the display is on, no reset is performed.
Return
Zero if the controller was reset, 1 if the display was already on, or a
negative error code.
Many controllers have a max speed of 10MHz, but can be pushed way beyond
that. Increase reliability by running pixel data at max speed and the rest
at 10MHz, preventing transfer glitches from messing up the init settings.
If dc is set, a Type C Option 3 interface is assumed, if not
Type C Option 1.
If the command is MIPI_DCS_WRITE_MEMORY_START and the pixel format is RGB565, endianness has
to be taken into account. The MIPI DBI serial interface is big endian and framebuffers are
assumed stored in memory as little endian (DRM_FORMAT_BIG_ENDIAN is not supported).
This is how endianness is handled:
Option 1 (D/C as a bit): The buffer is sent on the wire byte by byte so the 16-bit buffer is
byteswapped before transfer.
Option 3 (D/C as a gpio): If the SPI controller supports 16 bits per word the buffer can be
sent as-is. If not the caller is responsible for swapping the bytes
before calling mipi_dbi_command_buf() and the buffer is sent 8 bpw.
This handling is optimised for DRM_FORMAT_RGB565 framebuffers.
If the interface is Option 1 and the SPI controller doesn’t support 9 bits per word,
the buffer is sent as 9x 8-bit words, padded with MIPI DCS no-op commands if necessary.
This SPI transfer helper breaks up the transfer of buf into chunks which
the SPI controller driver can handle. The SPI bus must be locked when
calling this.
This function creates a ‘command’ debugfs file for sending commands to the
controller or getting the read command values.
Drivers can use this as their drm_driver->debugfs_init callback.
DSI packets transmitted by .transfer() are passed in as mipi_dsi_msg
structures. This structure contains information about the type of packet
being transmitted as well as the transmit and receive buffers. When an
error is encountered during transmission, this function will return a
negative error code. On success it shall return the number of bytes
transmitted for write packets or the number of bytes received for read
packets.
Note that typically DSI packet transmission is atomic, so the .transfer()
function will seldomly return anything other than the number of bytes
contained in the transmit buffer on success.
Also note that those callbacks can be called no matter the state the
host is in. Drivers that need the underlying device to be powered to
perform these operations will first need to make sure it’s been
properly enabled.
struct mipi_dsi_multi_context {
struct mipi_dsi_device *dsi;
int accum_err;
};
Members
dsi
Pointer to the MIPI DSI device
accum_err
Storage for the accumulated error over the multiple calls
Init to 0. If a function encounters an error then the error code
will be stored here. If you call a function and this points to a
non-zero value then the function will be a noop. This allows calling
a function many times in a row and just checking the error at the
end to see if any of them failed.
MIPI DSI function to pass context and arguments into
_ctx
Context for multiple DSI transactions
_dsi1
First DSI interface to act as recipient of the MIPI DSI command
_dsi2
Second DSI interface to act as recipient of the MIPI DSI command
...
Arguments to pass to MIPI DSI function or macro
Description
This macro will send the specified MIPI DSI command twice, once per each of
the two interfaces supplied. This is useful for reducing duplication of code
in panel drivers which use two parallel serial interfaces.
WARNING: This macro reuses the _func argument and the optional trailing
arguments twice each, which may cause unintended side effects. For example,
adding the postfix increment ++ operator to one of the arguments to be
passed to _func will cause the variable to be incremented twice instead of
once and the variable will be its original value + 1 when sent to _dsi2.
transmit data using a generic write packet to two dsi interfaces, one after the other
Parameters
_ctx
Context for multiple DSI transactions
_dsi1
First DSI interface to act as recipient of packet
_dsi2
Second DSI interface to act as recipient of packet
_seq...
buffer containing the payload
Description
This macro will send the specified generic packet twice, once per each of
the two interfaces supplied. This is useful for reducing duplication of code
in panel drivers which use two parallel serial interfaces.
Note that if an error occurs while transmitting the packet to the first DSI
interface, the packet will not be sent to the second DSI interface.
This macro will print errors for you and error handling is optimized for
callers that call this multiple times in a row.
transmit a DCS command with payload to two dsi interfaces, one after the other
Parameters
_ctx
Context for multiple DSI transactions
_dsi1
First DSI interface to act as recipient of packet
_dsi2
Second DSI interface to act as recipient of packet
_cmd
Command
_seq...
buffer containing the payload
Description
This macro will send the specified DCS command with payload twice, once per
each of the two interfaces supplied. This is useful for reducing duplication
of code in panel drivers which use two parallel serial interfaces.
Note that if an error occurs while transmitting the payload to the first DSI
interface, the payload will not be sent to the second DSI interface.
This macro will print errors for you and error handling is optimized for
callers that call this multiple times in a row.
Get the required MEDIA_BUS_FMT_* based input pixel format for a given DSI output pixel format
Parameters
enummipi_dsi_pixel_formatdsi_format
pixel format that a DSI host needs to output
Description
Various DSI hosts can use this function during their
drm_bridge_funcs.atomic_get_input_bus_fmts operation to ascertain
the MEDIA_BUS_FMT_* pixel format required as input.
Return
a 32-bit MEDIA_BUS_FMT_* value on success or 0 in case of failure.
VESA specification for DP 1.4 adds a new feature called Display Stream
Compression (DSC) used to compress the pixel bits before sending it on
DP/eDP/MIPI DSI interface. DSC is required to be enabled so that the existing
display interfaces can support high resolutions at higher frames rates uisng
the maximum available link capacity of these interfaces.
These functions contain some common logic and helpers to deal with VESA
Display Stream Compression standard required for DSC on Display Port/eDP or
MIPI display interfaces.
PPS0[3:0] - dsc_version_minor: Contains Minor version of DSC
PPS0[7:4] - dsc_version_major: Contains major version of DSC
pps_identifier
PPS1[7:0] - Application specific identifier that can be
used to differentiate between different PPS tables.
pps_reserved
PPS2[7:0]- RESERVED Byte
pps_3
PPS3[3:0] - linebuf_depth: Contains linebuffer bit depth used to
generate the bitstream. (0x0 - 16 bits for DSC 1.2, 0x8 - 8 bits,
0xA - 10 bits, 0xB - 11 bits, 0xC - 12 bits, 0xD - 13 bits,
0xE - 14 bits for DSC1.2, 0xF - 14 bits for DSC 1.2.
PPS3[7:4] - bits_per_component: Bits per component for the original
pixels of the encoded picture.
0x0 = 16bpc (allowed only when dsc_version_minor = 0x2)
0x8 = 8bpc, 0xA = 10bpc, 0xC = 12bpc, 0xE = 14bpc (also
allowed only when dsc_minor_version = 0x2)
pps_4
PPS4[1:0] -These are the most significant 2 bits of
compressed BPP bits_per_pixel[9:0] syntax element.
PPS4[2] - vbr_enable: 0 = VBR disabled, 1 = VBR enabled
PPS4[3] - simple_422: Indicates if decoder drops samples to
reconstruct the 4:2:2 picture.
PPS4[4] - Convert_rgb: Indicates if DSC color space conversion is
active.
PPS4[5] - blobk_pred_enable: Indicates if BP is used to code any
groups in picture
PPS4[7:6] - Reseved bits
bits_per_pixel_low
PPS5[7:0] - This indicates the lower significant 8 bits of
the compressed BPP bits_per_pixel[9:0] element.
pic_height
PPS6[7:0], PPS7[7:0] -pic_height: Specifies the number of pixel rows
within the raster.
pic_width
PPS8[7:0], PPS9[7:0] - pic_width: Number of pixel columns within
the raster.
slice_height
PPS10[7:0], PPS11[7:0] - Slice height in units of pixels.
slice_width
PPS12[7:0], PPS13[7:0] - Slice width in terms of pixels.
chunk_size
PPS14[7:0], PPS15[7:0] - Size in units of bytes of the chunks
that are used for slice multiplexing.
initial_xmit_delay_high
PPS16[1:0] - Most Significant two bits of initial transmission delay.
It specifies the number of pixel times that the encoder waits before
transmitting data from its rate buffer.
PPS16[7:2] - Reserved
initial_xmit_delay_low
PPS17[7:0] - Least significant 8 bits of initial transmission delay.
initial_dec_delay
PPS18[7:0], PPS19[7:0] - Initial decoding delay which is the number
of pixel times that the decoder accumulates data in its rate buffer
before starting to decode and output pixels.
pps20_reserved
PPS20[7:0] - Reserved
initial_scale_value
PPS21[5:0] - Initial rcXformScale factor used at beginning
of a slice.
PPS21[7:6] - Reserved
scale_increment_interval
PPS22[7:0], PPS23[7:0] - Number of group times between incrementing
the rcXformScale factor at end of a slice.
scale_decrement_interval_high
PPS24[3:0] - Higher 4 bits indicating number of group times between
decrementing the rcXformScale factor at beginning of a slice.
PPS24[7:4] - Reserved
scale_decrement_interval_low
PPS25[7:0] - Lower 8 bits of scale decrement interval
pps26_reserved
PPS26[7:0]
first_line_bpg_offset
PPS27[4:0] - Number of additional bits that are allocated
for each group on first line of a slice.
PPS27[7:5] - Reserved
nfl_bpg_offset
PPS28[7:0], PPS29[7:0] - Number of bits including frac bits
deallocated for each group for groups after the first line of slice.
slice_bpg_offset
PPS30, PPS31[7:0] - Number of bits that are deallocated for each
group to enforce the slice constraint.
initial_offset
PPS32,33[7:0] - Initial value for rcXformOffset
final_offset
PPS34,35[7:0] - Maximum end-of-slice value for rcXformOffset
flatness_min_qp
PPS36[4:0] - Minimum QP at which flatness is signaled and
flatness QP adjustment is made.
PPS36[7:5] - Reserved
flatness_max_qp
PPS37[4:0] - Max QP at which flatness is signalled and
the flatness adjustment is made.
PPS37[7:5] - Reserved
rc_model_size
PPS38,39[7:0] - Number of bits within RC Model.
rc_edge_factor
PPS40[3:0] - Ratio of current activity vs, previous
activity to determine presence of edge.
PPS40[7:4] - Reserved
rc_quant_incr_limit0
PPS41[4:0] - QP threshold used in short term RC
PPS41[7:5] - Reserved
rc_quant_incr_limit1
PPS42[4:0] - QP threshold used in short term RC
PPS42[7:5] - Reserved
rc_tgt_offset
PPS43[3:0] - Lower end of the variability range around the target
bits per group that is allowed by short term RC.
PPS43[7:4]- Upper end of the variability range around the target
bits per group that i allowed by short term rc.
rc_buf_thresh
PPS44[7:0] - PPS57[7:0] - Specifies the thresholds in RC model for
the 15 ranges defined by 14 thresholds.
rc_range_parameters
PPS58[7:0] - PPS87[7:0]
Parameters that correspond to each of the 15 ranges.
native_422_420
PPS88[0] - 0 = Native 4:2:2 not used
1 = Native 4:2:2 used
PPS88[1] - 0 = Native 4:2:0 not use
1 = Native 4:2:0 used
PPS88[7:2] - Reserved 6 bits
second_line_bpg_offset
PPS89[4:0] - Additional bits/group budget for the
second line of a slice in Native 4:2:0 mode.
Set to 0 if DSC minor version is 1 or native420 is 0.
PPS89[7:5] - Reserved
nsl_bpg_offset
PPS90[7:0], PPS91[7:0] - Number of bits that are deallocated
for each group that is not in the second line of a slice.
second_line_offset_adj
PPS92[7:0], PPS93[7:0] - Used as offset adjustment for the second
line in Native 4:2:0 mode.
pps_long_94_reserved
PPS 94, 95, 96, 97 - Reserved
pps_long_98_reserved
PPS 98, 99, 100, 101 - Reserved
pps_long_102_reserved
PPS 102, 103, 104, 105 - Reserved
pps_long_106_reserved
PPS 106, 107, 108, 109 - reserved
pps_long_110_reserved
PPS 110, 111, 112, 113 - reserved
pps_long_114_reserved
PPS 114 - 117 - reserved
pps_long_118_reserved
PPS 118 - 121 - reserved
pps_long_122_reserved
PPS 122- 125 - reserved
pps_short_126_reserved
PPS 126, 127 - reserved
Description
The VESA DSC standard defines picture parameter set (PPS) which display
stream compression encoders must communicate to decoders.
The PPS is encapsulated in 128 bytes (PPS 0 through PPS 127). The fields in
this structure are as per Table 4.1 in Vesa DSC specification v1.1/v1.2.
The PPS fields that span over more than a byte should be stored in Big Endian
format.
This structure represents the DSC PPS infoframe required to send the Picture
Parameter Set metadata required before enabling VESA Display Stream
Compression. This is based on the DP Secondary Data Packet structure and
comprises of SDP Header as defined structdp_sdp_header in drm_dp_helper.h
and PPS payload defined in structdrm_dsc_picture_parameter_set.
Initializes the PPS Header for DisplayPort as per the DP 1.4 spec.
Parameters
structdp_sdp_header*pps_header
Secondary data packet header for DSC Picture
Parameter Set as defined in structdp_sdp_header
Description
DP 1.4 spec defines the secondary data packet for sending the
picture parameter infoframes from the source to the sink.
This function populates the SDP header defined in
structdp_sdp_header.
DSC source device sends a picture parameter set (PPS) containing the
information required by the sink to decode the compressed frame. Driver
populates the DSC PPS structusing the DSC configuration parameters in
the order expected by the DSC Display Sink device. For the DSC, the sink
device expects the PPS payload in big endian format for fields
that span more than 1 byte.
Set parameters and limits for RC model in accordance with the DSC 1.1 or 1.2 specification and DSC C Model Required bits_per_pixel and bits_per_component to be set before calling this function.
Write rate control parameters to the dsc configuration defined in structdrm_dsc_config in accordance with the DSC 1.2 specification. Some configuration fields must be present beforehand.
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 structdrm_connector_helper_funcs for the details.
This function re-enables the output polling work, after it has been
temporarily disabled using drm_kms_helper_poll_disable(), for example over
suspend/resume.
Drivers can call this helper from their device resume implementation. It is
not an error to call this even when output polling isn’t enabled.
If device polling was never initialized before, this call will trigger a
warning and return.
Note that calls to enable and disable polling must be strictly ordered, which
is automatically the case when they’re only call from suspend/resume
callbacks.
This function reschedules the output polling work, after polling for a
connector has been enabled.
Drivers must call this helper after enabling polling for a connector by
setting DRM_CONNECTOR_POLL_CONNECT / DRM_CONNECTOR_POLL_DISCONNECT flags
in drm_connector::polled. Note that after disabling polling by clearing these
flags for a connector will stop the output polling work automatically if
the polling is disabled for all other connectors as well.
acquire_ctx, or NULL to let this function handle locking.
boolforce
Whether destructive probe operations should be performed.
Description
This function calls the detect callbacks of the connector.
This function returns drm_connector_status, or
if ctx is set, it might also return -EDEADLK.
Based on the helper callbacks implemented by connector in struct
drm_connector_helper_funcs try to detect all valid modes. Modes will first
be added to the connector’s probed_modes list, then culled (based on validity
and the maxX, maxY parameters) and put into the normal modes list.
Intended to be used as a generic implementation of the
drm_connector_funcs.fill_modes() vfunc for drivers that use the CRTC helpers
for output mode filtering and detection.
The basic procedure is as follows
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.
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_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
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()).
This function fires off the uevent for userspace and also calls the
client hotplug 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.
Determine if current task is an output poll worker. This can be used
to select distinct code paths for output polling versus other contexts.
One use case is to avoid a deadlock between the output poll worker and
the autosuspend worker wherein the latter waits for polling to finish
upon calling drm_kms_helper_poll_disable(), while the former waits for
runtime suspend to finish upon calling pm_runtime_get_sync() in a
connector ->detect hook.
Drivers can call this helper from their device suspend implementation. It is
not an error to call this even when output polling isn’t enabled or already
disabled. Polling is re-enabled by calling drm_kms_helper_poll_enable().
If however, the polling was never initialized, this call will trigger a
warning and return.
Note that calls to enable and disable polling must be strictly ordered, which
is automatically the case when they’re only call from suspend/resume
callbacks.
This function initializes 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.
This function initializes and then also enables output polling support for
dev similar to drm_kms_helper_poll_init(). Polling will automatically be
cleaned up when the DRM device goes away.
Drivers can use this helper function to run a detect cycle on a connector
which has the DRM_CONNECTOR_POLL_HPD flag set in its polled member.
This helper function is useful for drivers which can track hotplug
interrupts for a single connector. Drivers that want to send a
hotplug event for all connectors or can’t track hotplug interrupts
per connector need to use drm_helper_hpd_irq_event().
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.
Return
A boolean indicating whether the connector status changed or not
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 can use
drm_connector_helper_hpd_irq_event(). Alternatively, they 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.
Return
A boolean indicating whether the connector status changed or not
This function duplicates a display modes for a connector. Drivers for hardware
that only supports a single fixed mode can use this function in their connector’s
get_modes helper.
Read the EDID using drm_edid_read() (which requires that connector->ddc is
set), and update the connector using the EDID.
This can be used as the “default” connector helper .get_modes() hook if the
driver does not need any special processing. This is sets the example what
custom .get_modes() hooks should do regarding EDID read and connector update.
Perform screen-destructive operations, if necessary
Description
Detects the connector status by reading the EDID using drm_probe_ddc(),
which requires connector->ddc to be set. Returns connector_status_connected
on success or connector_status_disconnected on failure.
Add modes from the override/firmware EDID, if available. Only to be used from
drm_helper_probe_single_connector_modes() as a fallback for when DDC probe
failed during drm_get_edid() and caused the override/firmware EDID to be
skipped.
Return
The number of modes added or 0 if we couldn’t find any.
Allocate a new drm_edid container. Do not calculate edid size from edid, pass
the actual size that has been allocated for the data. There is no validation
of the raw EDID data against the size, but at least the EDID base block must
fit in the buffer.
Read EDID data using given EDID block read function
Parameters
structdrm_connector*connector
Connector to use
read_block_fnread_block
EDID block read function
void*context
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_edid_read() or drm_edid_read_ddc() instead of abusing
this function.
The EDID may be overridden using debugfs override_edid or firmware EDID
(drm_edid_load_firmware() and drm.edid_firmware parameter), in this priority
order. Having either of them bypasses actual EDID reads.
The EDID may be overridden using debugfs override_edid or firmware EDID
(drm_edid_load_firmware() and drm.edid_firmware parameter), in this priority
order. Having either of them bypasses actual EDID reads.
The EDID may be overridden using debugfs override_edid or firmware EDID
(drm_edid_load_firmware() and drm.edid_firmware parameter), in this priority
order. Having either of them bypasses actual EDID reads.
This function uses the first block of the EDID of a panel and (assuming
that the EDID is valid) extracts the ID out of it. The ID is a 32-bit value
(16 bits of manufacturer ID and 16 bits of per-manufacturer ID) that’s
supposed to be different for each different modem of panel.
Return
A 32-bit ID that should be different for each make/model of panel.
See the functions drm_edid_encode_panel_id() and
drm_edid_decode_panel_id() for some details on the structure of this
ID. Return 0 if the EDID size is less than a base block.
This function returns the drm_edid containing the first block of the EDID of
a panel.
This function is intended to be used during early probing on devices where
more than one panel might be present. Because of its intended use it must
assume that the EDID of the panel is correct, at least as far as the base
block is concerned (in other words, we don’t process any overrides here).
it’s expected that this function and drm_do_get_edid() will both
be read the EDID, but there is no caching between them. Since we’re only
reading the first block, hopefully this extra overhead won’t be too big.
WARNING: Only use this function when the connector is unknown. For example,
during the early probe of panel. The EDID read from the function is temporary
and should be replaced by the full EDID returned from other drm_edid_read.
Return
Pointer to allocated EDID base block, or NULL on any failure.
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.
Wrapper around drm_edid_read_ddc() 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.
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.
This function creates a new blob modeset object and assigns its id to the
connector’s edid property.
Since we also parse tile information from EDID’s displayID block, we also
set the connector’s tile property here. See drm_connector_set_tile_property()
for more details.
Add the specified modes to the connector’s mode list. Also fills out the
drm_display_info structure and ELD in connector with any information which
can be derived from the edid.
fill an HDMI infoframe with data from a DRM display mode
Parameters
structhdmi_vendor_infoframe*frame
HDMI vendor infoframe
conststructdrm_connector*connector
the connector
conststructdrm_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.
pointer to an eld memory structure with mnl and sad_count set
Description
This is a helper for determining the payload size of the baseline block, in
bytes, for e.g. setting the Baseline_ELD_Len field in the ELD header block.
The returned value does not include the vendor block. It’s vendor specific,
and comprises of the remaining bytes in the ELD memory buffer after
drm_eld_size() bytes of header and baseline block.
The returned value is guaranteed to be a multiple of 4.
Status and Control Data Channel (SCDC) is a mechanism introduced by the
HDMI 2.0 specification. It is a point-to-point protocol that allows the
HDMI source and HDMI sink to exchange data. The same I2C interface that
is used to access EDID serves as the transport mechanism for SCDC.
Note: The SCDC status is going to be lost when the display is
disconnected. This can happen physically when the user disconnects
the cable, but also when a display is switched on (such as waking up
a TV).
This is further complicated by the fact that, upon a disconnection /
reconnection, KMS won’t change the mode on its own. This means that
one can’t just rely on setting the SCDC status on enable, but also
has to track the connector status changes using interrupts and
restore the SCDC status. The typical solution for this is to trigger an
empty modeset in drm_connector_helper_funcs.detect_ctx(), like what vc4 does
in vc4_hdmi_reset_link().
Strictly speaking this is not a DRM helper library but generally usable
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.
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.
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.
check a HDMI AVI infoframe, and write it to binary buffer
Parameters
structhdmi_avi_infoframe*frame
HDMI AVI infoframe
void*buffer
destination buffer
size_tsize
size of buffer
Description
Validates that the infoframe is consistent and updates derived fields
(eg. length) based on other fields, after which it packs the information
contained in the frame structure into a binary representation that
can be written into the corresponding controller registers. This function
also computes the checksum as required by section 5.3.5 of the HDMI 1.4
specification.
Returns the number of bytes packed into the binary buffer or a negative
error code on failure.
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.
check a HDMI SPD infoframe, and write it to binary buffer
Parameters
structhdmi_spd_infoframe*frame
HDMI SPD infoframe
void*buffer
destination buffer
size_tsize
size of buffer
Description
Validates that the infoframe is consistent and updates derived fields
(eg. length) based on other fields, after which it packs the information
contained in the frame structure into a binary representation that
can be written into the corresponding controller registers. This function
also computes the checksum as required by section 5.3.5 of the HDMI 1.4
specification.
Returns the number of bytes packed into the binary buffer or a negative
error code on failure.
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.
check a HDMI Audio infoframe, and write it to binary buffer
Parameters
structhdmi_audio_infoframe*frame
HDMI Audio infoframe
void*buffer
destination buffer
size_tsize
size of buffer
Description
Validates that the infoframe is consistent and updates derived fields
(eg. length) based on other fields, after which it packs the information
contained in the frame structure into a binary representation that
can be written into the corresponding controller registers. This function
also computes the checksum as required by section 5.3.5 of the HDMI 1.4
specification.
Returns the number of bytes packed into the binary buffer or a negative
error code on failure.
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.
check a HDMI Vendor infoframe, and write it to binary buffer
Parameters
structhdmi_vendor_infoframe*frame
HDMI Vendor infoframe
void*buffer
destination buffer
size_tsize
size of buffer
Description
Validates that the infoframe is consistent and updates derived fields
(eg. length) based on other fields, after which it packs the information
contained in the frame structure into a binary representation that
can be written into the corresponding controller registers. This function
also computes the checksum as required by section 5.3.5 of the HDMI 1.4
specification.
Returns the number of bytes packed into the binary buffer or a negative
error code on failure.
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.
check a HDMI DRM infoframe, and write it to binary buffer
Parameters
structhdmi_drm_infoframe*frame
HDMI DRM infoframe
void*buffer
destination buffer
size_tsize
size of buffer
Description
Validates that the infoframe is consistent and updates derived fields
(eg. length) based on other fields, after which it packs the information
contained in the frame structure into a binary representation that
can be written into the corresponding controller registers. This function
also computes the checksum as required by section 5.3.5 of the HDMI 1.4
specification.
Returns the number of bytes packed into the binary buffer or a negative
error code on failure.
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.
check a HDMI infoframe, and write it to binary buffer
Parameters
unionhdmi_infoframe*frame
HDMI infoframe
void*buffer
destination buffer
size_tsize
size of buffer
Description
Validates that the infoframe is consistent and updates derived fields
(eg. length) based on other fields, after which it packs the information
contained in the frame structure into a binary representation that
can be written into the corresponding controller registers. This function
also computes the checksum as required by section 5.3.5 of the HDMI 1.4
specification.
Returns the number of bytes packed into the binary buffer or a negative
error code on failure.
unpack binary buffer of CTA-861-G DRM infoframe DataBytes to a HDMI DRM infoframe
Parameters
structhdmi_drm_infoframe*frame
HDMI DRM infoframe
constvoid*buffer
source buffer
size_tsize
size of buffer
Description
Unpacks CTA-861-G DRM infoframe DataBytes contained in the binary buffer
into a structured frame of the HDMI Dynamic Range and Mastering (DRM)
infoframe.
Returns 0 on success or a negative error code on failure.
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.
Clip rectangle dst by rectangle clip. Clip rectangle src by
the corresponding amounts, retaining the vertical and horizontal scaling
factors from src to dst.
Return
true if rectangle dst is still visible after being clipped,
false otherwise.
Calculate the horizontal scaling factor as
(src width) / (dst width).
If the scale is below 1 << 16, round down. If the scale is above
1 << 16, round up. This will calculate the scale with the most
pessimistic limit calculation.
Return
The horizontal scaling factor, or errno of out of limits.
Calculate the vertical scaling factor as
(src height) / (dst height).
If the scale is below 1 << 16, round down. If the scale is above
1 << 16, round up. This will calculate the scale with the most
pessimistic limit calculation.
Return
The vertical scaling factor, or errno of out of limits.
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
Utility 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_commit() can be called in atomic context.
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.
Some userspace presumes that the first connected connector is the main
display, where it’s supposed to display e.g. the login screen. For
laptops, this should be the main panel. Use this function to sort all
(eDP/LVDS/DSI) panels to the front of the connector list, instead of
painstakingly trying to initialize them in the right order.
Initialize a CRTC object with a default helper-provided primary plane and no
cursor plane.
Note that we make some assumptions about hardware limitations that may not be
true for all hardware:
Primary plane cannot be repositioned.
Primary plane cannot be scaled.
Primary plane must cover the entire CRTC.
Subpixel positioning is not supported.
The primary plane must always be on if the CRTC is enabled.
This is purely a backwards compatibility helper for old drivers. Drivers
should instead implement their own primary plane. Atomic drivers must do so.
Drivers with the above hardware restriction can look into using structdrm_simple_display_pipe, which encapsulates the above limitations into a nice
interface.
This helper function takes care of suspending the modeset side. It disables
output polling if initialized, suspends fbdev if used and finally calls
drm_atomic_helper_suspend().
If suspending fails, fbdev and polling is re-enabled.
This helper function takes care of resuming the modeset side. It calls
drm_atomic_helper_resume(), resumes fbdev if used and enables output polling
if initiaized.
Generic probe function for a component based master
Parameters
structdevice*dev
master device containing the OF node
int(*compare_of)(structdevice*,void*)
compare function used for matching components
conststructcomponent_master_ops*m_ops
component master ops to be used
Description
Parse the platform device OF node and bind all the components associated
with the master. Interface ports are added before the encoders in order to
satisfy their .bind requirements
Given a DT node’s port and endpoint number, find the connected node and
return either the associated structdrm_panel or drm_bridge device. Either
panel or bridge must not be NULL.
This function is deprecated and should not be used in new drivers. Use
devm_drm_of_get_bridge() instead.
Returns zero if successful, or one of the standard error codes if it fails.
An LVDS dual-link connection is made of two links, with even pixels
transitting on one link, and odd pixels on the other link. This function
returns, for two ports of an LVDS dual-link source, which port shall transmit
the even and odd pixels, based on the requirements of the connected sink.
The pixel order is determined from the dual-lvds-even-pixels and
dual-lvds-odd-pixels properties in the sink’s DT port nodes. If those
properties are not present, or if their usage is not valid, this function
returns -EINVAL.
If either port is not connected, this function returns -EPIPE.
port1 and port2 are typically DT sibling nodes, but may have different
parents when, for instance, two separate LVDS encoders carry the even and odd
pixels.
Return
DRM_LVDS_DUAL_LINK_EVEN_ODD_PIXELS - port1 carries even pixels and port2
carries odd pixels
DRM_LVDS_DUAL_LINK_ODD_EVEN_PIXELS - port1 carries odd pixels and port2
carries even pixels
-EINVAL - port1 and port2 are not connected to a dual-link LVDS sink, or
the sink configuration is invalid
An LVDS dual-link connection is made of two links, with even pixels
transitting on one link, and odd pixels on the other link. This function
returns, for two ports of an LVDS dual-link sink, which port shall transmit
the even and odd pixels, based on the requirements of the sink.
The pixel order is determined from the dual-lvds-even-pixels and
dual-lvds-odd-pixels properties in the sink’s DT port nodes. If those
properties are not present, or if their usage is not valid, this function
returns -EINVAL.
If either port is not connected, this function returns -EPIPE.
port1 and port2 are typically DT sibling nodes, but may have different
parents when, for instance, two separate LVDS decoders receive the even and
odd pixels.
Return
DRM_LVDS_DUAL_LINK_EVEN_ODD_PIXELS - port1 receives even pixels and port2
receives odd pixels
DRM_LVDS_DUAL_LINK_ODD_EVEN_PIXELS - port1 receives odd pixels and port2
receives even pixels
Gets parent DSI bus for a DSI device controlled through a bus other
than MIPI-DCS (SPI, I2C, etc.) using the Device Tree.
This function assumes that the device’s port**0** is the DSI input.
Returns pointer to mipi_dsi_host if successful, -EINVAL if the
request is unsupported, -EPROBE_DEFER if the DSI host is found but
not available, or -ENODEV otherwise.
This helper library contains helpers to implement primary plane support on
top of the normal CRTC configuration interface.
Since the legacy drm_mode_config_funcs.set_config interface ties the primary
plane together with the CRTC state this does not allow userspace to disable
the primary plane itself. The default primary plane only expose XRBG8888 and
ARGB8888 as valid pixel formats for the attached framebuffer.
Drivers are highly recommended to implement proper support for primary
planes, and newly merged drivers must not rely upon these transitional
helpers.
The plane helpers share the function table structures with other helpers,
specifically also the atomic helpers. See structdrm_plane_helper_funcs for
the details.
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.
The CRTC modeset helper library provides a default set_config implementation
in drm_crtc_helper_set_config(). Plus a few other convenience functions using
the same callbacks which drivers can use to e.g. restore the modeset
configuration on resume with drm_helper_resume_force_mode().
Note that this helper library doesn’t track the current power state of CRTCs
and encoders. It can call callbacks like drm_encoder_helper_funcs.dpms even
though the hardware is already in the desired state. This deficiency has been
fixed in the atomic helpers.
The driver callbacks are mostly compatible with the atomic modeset helpers,
except for the handling of the primary plane: Atomic helpers require that the
primary plane is implemented as a real standalone plane and not directly tied
to the CRTC state. For easier transition this library provides functions to
implement the old semantics required by the CRTC helpers using the new plane
and atomic helper callbacks.
Drivers are strongly urged to convert to the atomic helpers (by way of first
converting to the plane helpers). New drivers must not use these functions
but need to implement the atomic interface instead, potentially using the
atomic helpers for that.
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.
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.
This function walks through the entire mode setting configuration of dev. It
will remove any CRTC links of unused encoders and encoder links of
disconnected connectors. Then it will disable all unused encoders and CRTCs
either by calling their disable callback if available or by calling their
dpms callback with DRM_MODE_DPMS_OFF.
NOTE
This function is part of the legacy modeset helper library and will cause
major confusion with atomic drivers. This is because atomic helpers guarantee
to never call ->disable() hooks on a disabled function, or ->enable() hooks
on an enabled functions. drm_helper_disable_unused_functions() on the other
hand throws such guarantees into the wind and calls disable hooks
unconditionally on unused functions.
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.
Provides a default CRTC-state check handler for CRTCs that only have
one primary plane attached to it. This is often the case for the CRTC
of simple framebuffers.
It first tries to locate the best encoder for each connector by calling the
connector drm_connector_helper_funcs.best_encoder helper operation.
After locating the appropriate encoders, the helper function will call the
mode_fixup encoder and CRTC helper operations to adjust the requested mode,
or reject it completely in which case an error will be returned to the
application. If the new configuration after mode adjustment is identical to
the current configuration the helper function will return without performing
any other operation.
If the adjusted mode differs from the current mode, or if the
->mode_set_base() helper operation is not provided, the helper function
performs a full mode set sequence by calling the ->prepare(), ->mode_set()
and ->commit() CRTC and encoder helper operations, in that order.
Alternatively it can also use the dpms and disable helper operations. For
details see structdrm_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.
This is the main helper function provided by the CRTC helper framework for
implementing the DPMS connector attribute. It computes the new desired DPMS
state for all encoders and CRTCs in the output mesh and calls the
drm_crtc_helper_funcs.dpms and drm_encoder_helper_funcs.dpms callbacks
provided by the driver.
This function is deprecated. New drivers must implement atomic modeset
support, where DPMS is handled in the DRM core.
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.
This class allows non KMS drivers, from e.g. drivers/platform/x86 to
register a privacy-screen device, which the KMS drivers can then use
to implement the standard privacy-screen properties, see
Standard Connector Properties.
Called to request a change of the privacy-screen
state. The privacy-screen class code contains a check to avoid this
getting called when the hw_state reports the state is locked.
It is the driver’s responsibility to update sw_state and hw_state.
This is always called with the drm_privacy_screen’s lock held.
get_hw_state
Called to request that the driver gets the current
privacy-screen state from the hardware and then updates sw_state and
hw_state accordingly. This will be called by the core just before
the privacy-screen is registered in sysfs.
Description
Defines the operations which the privacy-screen class code may call.
These functions should be implemented by the privacy-screen driver.
Release a privacy-screen provider reference gotten through
drm_privacy_screen_get(). May be called with a NULL or ERR_PTR,
in which case it is a no-op.
Set the sw-state of a privacy screen. If the privacy-screen is not
in a locked hw-state, then the actual and hw-state of the privacy-screen
will be immediately updated to the new value. If the privacy-screen is
in a locked hw-state, then the new sw-state will be remembered as the
requested state to put the privacy-screen in when it becomes unlocked.
Register a notifier with the privacy-screen to be notified of changes made
to the privacy-screen state from outside of the privacy-screen class.
E.g. the state may be changed by the hardware itself in response to a
hotkey press.
The notifier is called with no locks held. The new hw_state and sw_state
can be retrieved using the drm_privacy_screen_get_state() function.
A pointer to the drm_privacy_screen’s structis passed as the void*data
argument of the notifier_block’s notifier_call.
The notifier will NOT be called when changes are made through
drm_privacy_screen_set_sw_state(). It is only called for external changes.
A privacy-screen provider driver can call this functions upon external
changes to the privacy-screen state. E.g. the state may be changed by the
hardware itself in response to a hotkey press.
This function must be called without holding the privacy-screen lock.
the driver must update sw_state and hw_state to reflect the new state before
calling this function.
The expected behavior from the driver upon receiving an external state
change event is: 1. Take the lock; 2. Update sw_state and hw_state;
3. Release the lock. 4. Call drm_privacy_screen_call_notifier_chain().
