Skip to content

Commit d1aa2a2

Browse files
Harry Wentlandemersion
Harry Wentland
authored and
emersion
committed
drm/amd/display: Add AMD color pipeline doc
Add kernel doc for AMD color pipeline. Signed-off-by: Alex Hung <alex.hung@amd.com> Signed-off-by: Harry Wentland <harry.wentland@amd.com> Reviewed-by: Daniel Stone <daniels@collabora.com> Reviewed-by: Melissa Wen <mwen@igalia.com> Signed-off-by: Simon Ser <contact@emersion.fr> Link: https://patch.msgid.link/20251115000237.3561250-48-alex.hung@amd.com
1 parent 0de2b1a commit d1aa2a2

1 file changed

Lines changed: 102 additions & 20 deletions

File tree

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

Lines changed: 102 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,32 @@
3333
/**
3434
* DOC: overview
3535
*
36+
* We have three types of color management in the AMD display driver.
37+
* 1. the legacy &drm_crtc DEGAMMA, CTM, and GAMMA properties
38+
* 2. AMD driver private color management on &drm_plane and &drm_crtc
39+
* 3. AMD plane color pipeline
40+
*
41+
* The CRTC properties are the original color management. When they were
42+
* implemented per-plane color management was not a thing yet. Because
43+
* of that we could get away with plumbing the DEGAMMA and CTM
44+
* properties to pre-blending HW functions. This is incompatible with
45+
* per-plane color management, such as via the AMD private properties or
46+
* the new drm_plane color pipeline. The only compatible CRTC property
47+
* with per-plane color management is the GAMMA property as it is
48+
* applied post-blending.
49+
*
50+
* The AMD driver private color management properties are only exposed
51+
* when the kernel is built explicitly with -DAMD_PRIVATE_COLOR. They
52+
* are temporary building blocks on the path to full-fledged &drm_plane
53+
* and &drm_crtc color pipelines and lay the driver's groundwork for the
54+
* color pipelines.
55+
*
56+
* The AMD plane color pipeline describes AMD's &drm_colorops via the
57+
* &drm_plane's COLOR_PIPELINE property.
58+
*
59+
* drm_crtc Properties
60+
* -------------------
61+
*
3662
* The DC interface to HW gives us the following color management blocks
3763
* per pipe (surface):
3864
*
@@ -43,33 +69,89 @@
4369
* - Surface regamma LUT (normalized)
4470
* - Output CSC (normalized)
4571
*
46-
* But these aren't a direct mapping to DRM color properties. The current DRM
47-
* interface exposes CRTC degamma, CRTC CTM and CRTC regamma while our hardware
48-
* is essentially giving:
72+
* But these aren't a direct mapping to DRM color properties. The
73+
* current DRM interface exposes CRTC degamma, CRTC CTM and CRTC regamma
74+
* while our hardware is essentially giving:
4975
*
5076
* Plane CTM -> Plane degamma -> Plane CTM -> Plane regamma -> Plane CTM
5177
*
52-
* The input gamma LUT block isn't really applicable here since it operates
53-
* on the actual input data itself rather than the HW fp representation. The
54-
* input and output CSC blocks are technically available to use as part of
55-
* the DC interface but are typically used internally by DC for conversions
56-
* between color spaces. These could be blended together with user
57-
* adjustments in the future but for now these should remain untouched.
78+
* The input gamma LUT block isn't really applicable here since it
79+
* operates on the actual input data itself rather than the HW fp
80+
* representation. The input and output CSC blocks are technically
81+
* available to use as part of the DC interface but are typically used
82+
* internally by DC for conversions between color spaces. These could be
83+
* blended together with user adjustments in the future but for now
84+
* these should remain untouched.
85+
*
86+
* The pipe blending also happens after these blocks so we don't
87+
* actually support any CRTC props with correct blending with multiple
88+
* planes - but we can still support CRTC color management properties in
89+
* DM in most single plane cases correctly with clever management of the
90+
* DC interface in DM.
91+
*
92+
* As per DRM documentation, blocks should be in hardware bypass when
93+
* their respective property is set to NULL. A linear DGM/RGM LUT should
94+
* also considered as putting the respective block into bypass mode.
95+
*
96+
* This means that the following configuration is assumed to be the
97+
* default:
98+
*
99+
* Plane DGM Bypass -> Plane CTM Bypass -> Plane RGM Bypass -> ... CRTC
100+
* DGM Bypass -> CRTC CTM Bypass -> CRTC RGM Bypass
101+
*
102+
* AMD Private Color Management on drm_plane
103+
* -----------------------------------------
104+
*
105+
* The AMD private color management properties on a &drm_plane are:
106+
*
107+
* - AMD_PLANE_DEGAMMA_LUT
108+
* - AMD_PLANE_DEGAMMA_LUT_SIZE
109+
* - AMD_PLANE_DEGAMMA_TF
110+
* - AMD_PLANE_HDR_MULT
111+
* - AMD_PLANE_CTM
112+
* - AMD_PLANE_SHAPER_LUT
113+
* - AMD_PLANE_SHAPER_LUT_SIZE
114+
* - AMD_PLANE_SHAPER_TF
115+
* - AMD_PLANE_LUT3D
116+
* - AMD_PLANE_LUT3D_SIZE
117+
* - AMD_PLANE_BLEND_LUT
118+
* - AMD_PLANE_BLEND_LUT_SIZE
119+
* - AMD_PLANE_BLEND_TF
120+
*
121+
* The AMD private color management property on a &drm_crtc is:
122+
*
123+
* - AMD_CRTC_REGAMMA_TF
124+
*
125+
* Use of these properties is discouraged.
126+
*
127+
* AMD plane color pipeline
128+
* ------------------------
129+
*
130+
* The AMD &drm_plane color pipeline is advertised for DCN generations
131+
* 3.0 and newer. It exposes these elements in this order:
132+
*
133+
* 1. 1D curve colorop
134+
* 2. Multiplier
135+
* 3. 3x4 CTM
136+
* 4. 1D curve colorop
137+
* 5. 1D LUT
138+
* 6. 3D LUT
139+
* 7. 1D curve colorop
140+
* 8. 1D LUT
141+
*
142+
* The multiplier (#2) is a simple multiplier that is applied to all
143+
* channels.
144+
*
145+
* The 3x4 CTM (#3) is a simple 3x4 matrix.
58146
*
59-
* The pipe blending also happens after these blocks so we don't actually
60-
* support any CRTC props with correct blending with multiple planes - but we
61-
* can still support CRTC color management properties in DM in most single
62-
* plane cases correctly with clever management of the DC interface in DM.
147+
* #1, and #7 are non-linear to linear curves. #4 is a linear to
148+
* non-linear curve. They support sRGB, PQ, and BT.709/BT.2020 EOTFs or
149+
* their inverse.
63150
*
64-
* As per DRM documentation, blocks should be in hardware bypass when their
65-
* respective property is set to NULL. A linear DGM/RGM LUT should also
66-
* considered as putting the respective block into bypass mode.
151+
* The 1D LUTs (#5 and #8) are plain 4096 entry LUTs.
67152
*
68-
* This means that the following
69-
* configuration is assumed to be the default:
153+
* The 3DLUT (#6) is a tetrahedrally interpolated 17 cube LUT.
70154
*
71-
* Plane DGM Bypass -> Plane CTM Bypass -> Plane RGM Bypass -> ...
72-
* CRTC DGM Bypass -> CRTC CTM Bypass -> CRTC RGM Bypass
73155
*/
74156

75157
#define MAX_DRM_LUT_VALUE 0xFFFF

0 commit comments

Comments
 (0)