#include <drm_crtc.h>
Public Attributes | |
| struct drm_crtc * | crtc |
| bool | enable |
| bool | active |
| bool | planes_changed: 1 |
| bool | mode_changed: 1 |
| bool | active_changed: 1 |
| bool | connectors_changed: 1 |
| bool | zpos_changed: 1 |
| bool | color_mgmt_changed: 1 |
| bool | no_vblank |
| u32 | plane_mask |
| u32 | connector_mask |
| u32 | encoder_mask |
| struct drm_display_mode | adjusted_mode |
| struct drm_display_mode | mode |
| struct drm_property_blob * | mode_blob |
| struct drm_property_blob * | degamma_lut |
| struct drm_property_blob * | ctm |
| struct drm_property_blob * | gamma_lut |
| u64 | background_color |
| u32 | target_vblank |
| bool | async_flip |
| bool | vrr_enabled |
| bool | self_refresh_active |
| enum drm_scaling_filter | scaling_filter |
| u8 | sharpness_strength |
| struct drm_pending_vblank_event * | event |
| struct drm_crtc_commit * | commit |
| struct drm_atomic_commit * | state |
Detailed Description
struct drm_crtc_state - mutable CRTC state
Note that the distinction between @enable and @active is rather subtle: Flipping @active while @enable is set without changing anything else may never return in a failure from the &drm_mode_config_funcs.atomic_check callback. Userspace assumes that a DPMS On will always succeed. In other words: @enable controls resource assignment, @active controls the actual hardware state.
The three booleans active_changed, connectors_changed and mode_changed are intended to indicate whether a full modeset is needed, rather than strictly describing what has changed in a commit. See also: drm_atomic_crtc_needs_modeset()
Member Data Documentation
◆ active
| bool drm_crtc_state::active |
@active: Whether the CRTC is actively displaying (used for DPMS). Implies that @enable is set. The driver must not release any shared resources if @active is set to false but @enable still true, because userspace expects that a DPMS ON always succeeds.
Hence drivers must not consult @active in their various &drm_mode_config_funcs.atomic_check callback to reject an atomic commit. They can consult it to aid in the computation of derived hardware state, since even in the DPMS OFF state the display hardware should be as much powered down as when the CRTC is completely disabled through setting @enable to false.
◆ active_changed
| bool drm_crtc_state::active_changed |
@active_changed: @active has been toggled. Used by the atomic helpers and drivers to steer the atomic commit control flow. See also drm_atomic_crtc_needs_modeset().
◆ adjusted_mode
| struct drm_display_mode drm_crtc_state::adjusted_mode |
@adjusted_mode:
Internal display timings which can be used by the driver to handle differences between the mode requested by userspace in @mode and what is actually programmed into the hardware.
For drivers using &drm_bridge, this stores hardware display timings used between the CRTC and the first bridge. For other drivers, the meaning of the adjusted_mode field is purely driver implementation defined information, and will usually be used to store the hardware display timings used between the CRTC and encoder blocks.
◆ async_flip
| bool drm_crtc_state::async_flip |
@async_flip:
This is set when DRM_MODE_PAGE_FLIP_ASYNC is set in the legacy PAGE_FLIP IOCTL. It's not wired up for the atomic IOCTL itself yet.
◆ background_color
| u64 drm_crtc_state::background_color |
@background_color:
RGB value representing the CRTC's background color. The background color (aka "canvas color") of a CRTC is the color that will be used for pixels not covered by a plane, or covered by transparent pixels of a plane. The value here should be built using DRM_ARGB64_PREP*() helpers, while the individual color components can be extracted with desired precision via the DRM_ARGB64_GET*() macros.
◆ color_mgmt_changed
| bool drm_crtc_state::color_mgmt_changed |
@color_mgmt_changed: Color management properties have changed (@gamma_lut, @degamma_lut or @ctm). Used by the atomic helpers and drivers to steer the atomic commit control flow.
◆ commit
| struct drm_crtc_commit* drm_crtc_state::commit |
@commit:
This tracks how the commit for this update proceeds through the various phases. This is never cleared, except when we destroy the state, so that subsequent commits can synchronize with previous ones.
◆ connector_mask
| u32 drm_crtc_state::connector_mask |
@connector_mask: Bitmask of drm_connector_mask(connector) of connectors attached to this CRTC.
◆ connectors_changed
| bool drm_crtc_state::connectors_changed |
@connectors_changed: Connectors to this crtc have been updated, either in their state or routing. Used by the atomic helpers and drivers to steer the atomic commit control flow. See also drm_atomic_crtc_needs_modeset().
Drivers are supposed to set this as-needed from their own atomic check code, e.g. from &drm_encoder_helper_funcs.atomic_check
◆ crtc
| struct drm_crtc* drm_crtc_state::crtc |
@crtc: backpointer to the CRTC
◆ ctm
| struct drm_property_blob* drm_crtc_state::ctm |
@ctm:
Color transformation matrix. See drm_crtc_enable_color_mgmt(). The blob (if not NULL) is a &struct drm_color_ctm.
◆ degamma_lut
| struct drm_property_blob* drm_crtc_state::degamma_lut |
@degamma_lut:
Lookup table for converting framebuffer pixel data before apply the color conversion matrix @ctm. See drm_crtc_enable_color_mgmt(). The blob (if not NULL) is an array of &struct drm_color_lut.
◆ enable
| bool drm_crtc_state::enable |
@enable: Whether the CRTC should be enabled, gates all other state. This controls reservations of shared resources. Actual hardware state is controlled by @active.
◆ encoder_mask
| u32 drm_crtc_state::encoder_mask |
@encoder_mask: Bitmask of drm_encoder_mask(encoder) of encoders attached to this CRTC.
◆ event
| struct drm_pending_vblank_event* drm_crtc_state::event |
@event:
Optional pointer to a DRM event to signal upon completion of the state update. The driver must send out the event when the atomic commit operation completes. There are two cases:
- The event is for a CRTC which is being disabled through this atomic commit. In that case the event can be send out any time after the hardware has stopped scanning out the current framebuffers. It should contain the timestamp and counter for the last vblank before the display pipeline was shut off. The simplest way to achieve that is calling drm_crtc_send_vblank_event() somewhen after drm_crtc_vblank_off() has been called.
- For a CRTC which is enabled at the end of the commit (even when it undergoes an full modeset) the vblank timestamp and counter must be for the vblank right before the first frame that scans out the new set of buffers. Again the event can only be sent out after the hardware has stopped scanning out the old buffers.
- Events for disabled CRTCs are not allowed, and drivers can ignore that case.
For very simple hardware without VBLANK interrupt, enabling &struct drm_crtc_state.no_vblank makes DRM's atomic commit helpers send a fake VBLANK event at the end of the display update after all hardware changes have been applied. See drm_atomic_helper_fake_vblank().
For more complex hardware this can be handled by the drm_crtc_send_vblank_event() function, which the driver should call on the provided event upon completion of the atomic commit. Note that if the driver supports vblank signalling and timestamping the vblank counters and timestamps must agree with the ones returned from page flip events. With the current vblank helper infrastructure this can be achieved by holding a vblank reference while the page flip is pending, acquired through drm_crtc_vblank_get() and released with drm_crtc_vblank_put(). Drivers are free to implement their own vblank counter and timestamp tracking though, e.g. if they have accurate timestamp registers in hardware.
For hardware which supports some means to synchronize vblank interrupt delivery with committing display state there's also drm_crtc_arm_vblank_event(). See the documentation of that function for a detailed discussion of the constraints it needs to be used safely.
If the device can't notify of flip completion in a race-free way at all, then the event should be armed just after the page flip is committed. In the worst case the driver will send the event to userspace one frame too late. This doesn't allow for a real atomic update, but it should avoid tearing.
◆ gamma_lut
| struct drm_property_blob* drm_crtc_state::gamma_lut |
@gamma_lut:
Lookup table for converting pixel data after the color conversion matrix @ctm. See drm_crtc_enable_color_mgmt(). The blob (if not NULL) is an array of &struct drm_color_lut.
Note that for mostly historical reasons stemming from Xorg heritage, this is also used to store the color map (also sometimes color lut, CLUT or color palette) for indexed formats like DRM_FORMAT_C8.
◆ mode
| struct drm_display_mode drm_crtc_state::mode |
@mode:
Display timings requested by userspace. The driver should try to match the refresh rate as close as possible (but note that it's undefined what exactly is close enough, e.g. some of the HDMI modes only differ in less than 1% of the refresh rate). The active width and height as observed by userspace for positioning planes must match exactly.
For external connectors where the sink isn't fixed (like with a built-in panel), this mode here should match the physical mode on the wire to the last details (i.e. including sync polarities and everything).
◆ mode_blob
| struct drm_property_blob* drm_crtc_state::mode_blob |
@mode_blob: &drm_property_blob for @mode, for exposing the mode to atomic userspace.
◆ mode_changed
| bool drm_crtc_state::mode_changed |
@mode_changed: @mode or @enable has been changed. Used by the atomic helpers and drivers to steer the atomic commit control flow. See also drm_atomic_crtc_needs_modeset().
Drivers are supposed to set this for any CRTC state changes that require a full modeset. They can also reset it to false if e.g. a @mode change can be done without a full modeset by only changing scaler settings.
◆ no_vblank
| bool drm_crtc_state::no_vblank |
@no_vblank:
Reflects the ability of a CRTC to send VBLANK events. This state usually depends on the pipeline configuration. If set to true, DRM atomic helpers will send out a fake VBLANK event during display updates after all hardware changes have been committed. This is implemented in drm_atomic_helper_fake_vblank().
One usage is for drivers and/or hardware without support for VBLANK interrupts. Such drivers typically do not initialize vblanking (i.e., call drm_vblank_init() with the number of CRTCs). For CRTCs without initialized vblanking, this field is set to true in drm_atomic_helper_check_modeset(), and a fake VBLANK event will be send out on each update of the display pipeline by drm_atomic_helper_fake_vblank().
Another usage is CRTCs feeding a writeback connector operating in oneshot mode. In this case the fake VBLANK event is only generated when a job is queued to the writeback connector, and we want the core to fake VBLANK events when this part of the pipeline hasn't changed but others had or when the CRTC and connectors are being disabled.
__drm_atomic_helper_crtc_duplicate_state() will not reset the value from the current state, the CRTC driver is then responsible for updating this field when needed.
Note that the combination of &drm_crtc_state.event == NULL and &drm_crtc_state.no_blank == true is valid and usually used when the writeback connector attached to the CRTC has a new job queued. In this case the driver will send the VBLANK event on its own when the writeback job is complete.
◆ plane_mask
| u32 drm_crtc_state::plane_mask |
@plane_mask: Bitmask of drm_plane_mask(plane) of planes attached to this CRTC.
◆ planes_changed
| bool drm_crtc_state::planes_changed |
@planes_changed: Planes on this crtc are updated. Used by the atomic helpers and drivers to steer the atomic commit control flow.
◆ scaling_filter
| enum drm_scaling_filter drm_crtc_state::scaling_filter |
@scaling_filter:
Scaling filter to be applied
◆ self_refresh_active
| bool drm_crtc_state::self_refresh_active |
@self_refresh_active:
Used by the self refresh helpers to denote when a self refresh transition is occurring. This will be set on enable/disable callbacks when self refresh is being enabled or disabled. In some cases, it may not be desirable to fully shut off the crtc during self refresh. CRTC's can inspect this flag and determine the best course of action.
◆ sharpness_strength
| u8 drm_crtc_state::sharpness_strength |
@sharpness_strength:
Used by the user to set the sharpness intensity. The value ranges from 0-255. Default value is 0 which disable the sharpness feature. Any value greater than 0 enables sharpening with the specified strength.
◆ state
| struct drm_atomic_commit* drm_crtc_state::state |
@state: backpointer to global drm_atomic_commit
◆ target_vblank
| u32 drm_crtc_state::target_vblank |
@target_vblank:
Target vertical blank period when a page flip should take effect.
◆ vrr_enabled
| bool drm_crtc_state::vrr_enabled |
@vrr_enabled:
Indicates if variable refresh rate should be enabled for the CRTC. Support for the requested vrr state will depend on driver and hardware capabiltiy - lacking support is not treated as failure.
◆ zpos_changed
| bool drm_crtc_state::zpos_changed |
@zpos_changed: zpos values of planes on this crtc have been updated. Used by the atomic helpers and drivers to steer the atomic commit control flow.
The documentation for this struct was generated from the following file:
- XenevaOS/BaseHdr/drm/drm_crtc.h
