Merge branch 'for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/jack/linux-fs

[mirror_ubuntu-bionic-kernel.git] / include / drm / drm_crtc.h

diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index a8176a836e25d2cb6599d45351d4b8068a8f76af..629a5fe075b3f7fc3d915e8204a279af1211dc5e 100644 (file)
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -90,14 +90,7 @@ struct drm_plane_helper_funcs;
  * @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
- * @adjusted_mode: for use by helpers and drivers to compute adjusted mode timings
- * @mode: current mode timings
  * @mode_blob: &drm_property_blob for @mode
- * @degamma_lut: Lookup table for converting framebuffer pixel data
- *     before apply the conversion matrix
- * @ctm: Transformation matrix
- * @gamma_lut: Lookup table for converting pixel data after the
- *     conversion matrix
  * @state: backpointer to global drm_atomic_state
  *
  * Note that the distinction between @enable and @active is rather subtile:
@@ -136,17 +129,62 @@ struct drm_crtc_state {
        u32 connector_mask;
        u32 encoder_mask;
 
-       /* adjusted_mode: for use by helpers and drivers */
+       /**
+        * @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. It is purely driver
+        * implementation defined what exactly this adjusted mode means. Usually
+        * it is used to store the hardware display timings used between the
+        * CRTC and encoder blocks.
+        */
        struct drm_display_mode adjusted_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).
+        */
        struct drm_display_mode mode;
 
        /* blob property to expose current mode to atomic userspace */
        struct drm_property_blob *mode_blob;
 
-       /* blob property to expose color management to userspace */
+       /**
+        * @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.
+        */
        struct drm_property_blob *degamma_lut;
+
+       /**
+        * @ctm:
+        *
+        * Color transformation matrix. See drm_crtc_enable_color_mgmt(). The
+        * blob (if not NULL) is a &struct drm_color_ctm.
+        */
        struct drm_property_blob *ctm;
+
+       /**
+        * @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.
+        */
        struct drm_property_blob *gamma_lut;
 
        /**
@@ -176,7 +214,9 @@ struct drm_crtc_state {
         *    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.
+        *    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
@@ -313,6 +353,12 @@ struct drm_crtc_funcs {
         *
         * This callback is optional.
         *
+        * Atomic drivers who want to support gamma tables should implement the
+        * atomic color management support, enabled by calling
+        * drm_crtc_enable_color_mgmt(), which then supports the legacy gamma
+        * interface through the drm_atomic_helper_legacy_gamma_set()
+        * compatibility implementation.
+        *
         * NOTE:
         *
         * Drivers that support gamma tables and also fbdev emulation through