drm/amd/display: Add AMD color pipeline doc (d1aa2a26) · Commits · git / linux-net

drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c

+102 −20

Original line number	Diff line number	Diff line
		@@ -33,6 +33,32 @@
		/**
		* DOC: overview
		*
		* We have three types of color management in the AMD display driver.
		* 1. the legacy &drm_crtc DEGAMMA, CTM, and GAMMA properties
		* 2. AMD driver private color management on &drm_plane and &drm_crtc
		* 3. AMD plane color pipeline
		*
		* The CRTC properties are the original color management. When they were
		* implemented per-plane color management was not a thing yet. Because
		* of that we could get away with plumbing the DEGAMMA and CTM
		* properties to pre-blending HW functions. This is incompatible with
		* per-plane color management, such as via the AMD private properties or
		* the new drm_plane color pipeline. The only compatible CRTC property
		* with per-plane color management is the GAMMA property as it is
		* applied post-blending.
		*
		* The AMD driver private color management properties are only exposed
		* when the kernel is built explicitly with -DAMD_PRIVATE_COLOR. They
		* are temporary building blocks on the path to full-fledged &drm_plane
		* and &drm_crtc color pipelines and lay the driver's groundwork for the
		* color pipelines.
		*
		* The AMD plane color pipeline describes AMD's &drm_colorops via the
		* &drm_plane's COLOR_PIPELINE property.
		*
		* drm_crtc Properties
		* -------------------
		*
		* The DC interface to HW gives us the following color management blocks
		* per pipe (surface):
		*
		@@ -43,33 +69,89 @@
		* - Surface regamma LUT (normalized)
		* - Output CSC (normalized)
		*
		* But these aren't a direct mapping to DRM color properties. The current DRM
		* interface exposes CRTC degamma, CRTC CTM and CRTC regamma while our hardware
		* is essentially giving:
		* But these aren't a direct mapping to DRM color properties. The
		* current DRM interface exposes CRTC degamma, CRTC CTM and CRTC regamma
		* while our hardware is essentially giving:
		*
		* Plane CTM -> Plane degamma -> Plane CTM -> Plane regamma -> Plane CTM
		*
		* The input gamma LUT block isn't really applicable here since it operates
		* on the actual input data itself rather than the HW fp representation. The
		* input and output CSC blocks are technically available to use as part of
		* the DC interface but are typically used internally by DC for conversions
		* between color spaces. These could be blended together with user
		* adjustments in the future but for now these should remain untouched.
		* The input gamma LUT block isn't really applicable here since it
		* operates on the actual input data itself rather than the HW fp
		* representation. The input and output CSC blocks are technically
		* available to use as part of the DC interface but are typically used
		* internally by DC for conversions between color spaces. These could be
		* blended together with user adjustments in the future but for now
		* these should remain untouched.
		*
		* The pipe blending also happens after these blocks so we don't
		* actually support any CRTC props with correct blending with multiple
		* planes - but we can still support CRTC color management properties in
		* DM in most single plane cases correctly with clever management of the
		* DC interface in DM.
		*
		* As per DRM documentation, blocks should be in hardware bypass when
		* their respective property is set to NULL. A linear DGM/RGM LUT should
		* also considered as putting the respective block into bypass mode.
		*
		* This means that the following configuration is assumed to be the
		* default:
		*
		* Plane DGM Bypass -> Plane CTM Bypass -> Plane RGM Bypass -> ... CRTC
		* DGM Bypass -> CRTC CTM Bypass -> CRTC RGM Bypass
		*
		* AMD Private Color Management on drm_plane
		* -----------------------------------------
		*
		* The AMD private color management properties on a &drm_plane are:
		*
		* - AMD_PLANE_DEGAMMA_LUT
		* - AMD_PLANE_DEGAMMA_LUT_SIZE
		* - AMD_PLANE_DEGAMMA_TF
		* - AMD_PLANE_HDR_MULT
		* - AMD_PLANE_CTM
		* - AMD_PLANE_SHAPER_LUT
		* - AMD_PLANE_SHAPER_LUT_SIZE
		* - AMD_PLANE_SHAPER_TF
		* - AMD_PLANE_LUT3D
		* - AMD_PLANE_LUT3D_SIZE
		* - AMD_PLANE_BLEND_LUT
		* - AMD_PLANE_BLEND_LUT_SIZE
		* - AMD_PLANE_BLEND_TF
		*
		* The AMD private color management property on a &drm_crtc is:
		*
		* - AMD_CRTC_REGAMMA_TF
		*
		* Use of these properties is discouraged.
		*
		* AMD plane color pipeline
		* ------------------------
		*
		* The AMD &drm_plane color pipeline is advertised for DCN generations
		* 3.0 and newer. It exposes these elements in this order:
		*
		* 1. 1D curve colorop
		* 2. Multiplier
		* 3. 3x4 CTM
		* 4. 1D curve colorop
		* 5. 1D LUT
		* 6. 3D LUT
		* 7. 1D curve colorop
		* 8. 1D LUT
		*
		* The multiplier (#2) is a simple multiplier that is applied to all
		* channels.
		*
		* The 3x4 CTM (#3) is a simple 3x4 matrix.
		*
		* The pipe blending also happens after these blocks so we don't actually
		* support any CRTC props with correct blending with multiple planes - but we
		* can still support CRTC color management properties in DM in most single
		* plane cases correctly with clever management of the DC interface in DM.
		* #1, and #7 are non-linear to linear curves. #4 is a linear to
		* non-linear curve. They support sRGB, PQ, and BT.709/BT.2020 EOTFs or
		* their inverse.
		*
		* As per DRM documentation, blocks should be in hardware bypass when their
		* respective property is set to NULL. A linear DGM/RGM LUT should also
		* considered as putting the respective block into bypass mode.
		* The 1D LUTs (#5 and #8) are plain 4096 entry LUTs.
		*
		* This means that the following
		* configuration is assumed to be the default:
		* The 3DLUT (#6) is a tetrahedrally interpolated 17 cube LUT.
		*
		* Plane DGM Bypass -> Plane CTM Bypass -> Plane RGM Bypass -> ...
		* CRTC DGM Bypass -> CRTC CTM Bypass -> CRTC RGM Bypass
		*/

		#define MAX_DRM_LUT_VALUE 0xFFFF