summaryrefslogtreecommitdiff
path: root/include/drm
diff options
context:
space:
mode:
authorDaniel Vetter <daniel.vetter@ffwll.ch>2018-07-09 11:40:15 +0300
committerDaniel Vetter <daniel.vetter@ffwll.ch>2018-07-13 19:40:28 +0300
commit620eec75f35ce470cb59410b2ed91ad750b867a2 (patch)
treee14f334a7b23689664390d8c7ed8dfa8a4082572 /include/drm
parent7f9e7ec92be93e73ef552e6185a3ada72a90e1a9 (diff)
downloadlinux-620eec75f35ce470cb59410b2ed91ad750b867a2.tar.xz
drm/doc: use inline kerneldoc style for drm_crtc_state
Lots of added text here since I think the various control flow bits are worth explaining a bit better. v2: Fix conflict with Boris' no_vblank addition. Reviewed-by: Sean Paul <seanpaul@chromium.org> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Link: https://patchwork.freedesktop.org/patch/msgid/20180709084016.23750-15-daniel.vetter@ffwll.ch
Diffstat (limited to 'include/drm')
-rw-r--r--include/drm/drm_crtc.h110
1 files changed, 86 insertions, 24 deletions
diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index 7fe06ad6e5f0..92e7fc7f05a4 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -77,21 +77,6 @@ struct drm_plane_helper_funcs;
/**
* struct drm_crtc_state - mutable CRTC state
- * @crtc: backpointer to the CRTC
- * @enable: whether the CRTC should be enabled, gates all other state
- * @active: whether the CRTC is actively displaying (used for DPMS)
- * @planes_changed: planes on this crtc are updated
- * @mode_changed: @mode or @enable has been changed
- * @active_changed: @active has been toggled.
- * @connectors_changed: connectors to this crtc have been updated
- * @zpos_changed: zpos values of planes on this crtc have been updated
- * @color_mgmt_changed: color management properties have changed (degamma or
- * gamma LUT or CSC matrix)
- * @plane_mask: bitmask of (1 << drm_plane_index(plane)) of attached planes
- * @connector_mask: bitmask of (1 << drm_connector_index(connector)) of attached connectors
- * @encoder_mask: bitmask of (1 << drm_encoder_index(encoder)) of attached encoders
- * @mode_blob: &drm_property_blob for @mode
- * @state: backpointer to global drm_atomic_state
*
* Note that the distinction between @enable and @active is rather subtile:
* Flipping @active while @enable is set without changing anything else may
@@ -102,21 +87,86 @@ struct drm_plane_helper_funcs;
*
* 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()
+ * describing what has changed in a commit. See also:
+ * drm_atomic_crtc_needs_modeset()
+ *
+ * WARNING: Transitional helpers (like drm_helper_crtc_mode_set() or
+ * drm_helper_crtc_mode_set_base()) do not maintain many of the derived control
+ * state like @plane_mask so drivers not converted over to atomic helpers should
+ * not rely on these being accurate!
*/
struct drm_crtc_state {
+ /** @crtc: backpointer to the CRTC */
struct drm_crtc *crtc;
+ /**
+ * @enable: Whether the CRTC should be enabled, gates all other state.
+ * This controls reservations of shared resources. Actual hardware state
+ * is controlled by @active.
+ */
bool enable;
+
+ /**
+ * @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.
+ */
bool active;
- /* computed state bits used by helpers and drivers */
+ /**
+ * @planes_changed: Planes on this crtc are updated. Used by the atomic
+ * helpers and drivers to steer the atomic commit control flow.
+ */
bool planes_changed : 1;
+
+ /**
+ * @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.
+ */
bool mode_changed : 1;
+
+ /**
+ * @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().
+ */
bool active_changed : 1;
+
+ /**
+ * @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
+ */
bool connectors_changed : 1;
+ /**
+ * @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.
+ */
bool zpos_changed : 1;
+ /**
+ * @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.
+ */
bool color_mgmt_changed : 1;
/**
@@ -142,14 +192,22 @@ struct drm_crtc_state {
*/
bool no_vblank : 1;
- /* attached planes bitmask:
- * WARNING: transitional helpers do not maintain plane_mask so
- * drivers not converted over to atomic helpers should not rely
- * on plane_mask being accurate!
+ /**
+ * @plane_mask: Bitmask of drm_plane_mask(plane) of planes attached to
+ * this CRTC.
*/
u32 plane_mask;
+ /**
+ * @connector_mask: Bitmask of drm_connector_mask(connector) of
+ * connectors attached to this CRTC.
+ */
u32 connector_mask;
+
+ /**
+ * @encoder_mask: Bitmask of drm_encoder_mask(encoder) of encoders
+ * attached to this CRTC.
+ */
u32 encoder_mask;
/**
@@ -159,7 +217,7 @@ struct drm_crtc_state {
* 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
+ * 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
@@ -184,7 +242,10 @@ struct drm_crtc_state {
*/
struct drm_display_mode mode;
- /* blob property to expose current mode to atomic userspace */
+ /**
+ * @mode_blob: &drm_property_blob for @mode, for exposing the mode to
+ * atomic userspace.
+ */
struct drm_property_blob *mode_blob;
/**
@@ -288,6 +349,7 @@ struct drm_crtc_state {
*/
struct drm_crtc_commit *commit;
+ /** @state: backpointer to global drm_atomic_state */
struct drm_atomic_state *state;
};