1======================
2AMDgpu Display Manager
3======================
4
5.. contents:: Table of Contents
6    :depth: 3
7
8.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
9   :doc: overview
10
11.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
12   :internal:
13
14Lifecycle
15=========
16
17.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
18   :doc: DM Lifecycle
19
20.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
21   :functions: dm_hw_init dm_hw_fini
22
23Interrupts
24==========
25
26.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c
27   :doc: overview
28
29.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c
30   :internal:
31
32.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
33   :functions: register_hpd_handlers dm_crtc_high_irq dm_pflip_high_irq
34
35Atomic Implementation
36=====================
37
38.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
39   :doc: atomic
40
41.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
42   :functions: amdgpu_dm_atomic_check amdgpu_dm_atomic_commit_tail
43
44Color Management Properties
45===========================
46
47.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c
48   :doc: overview
49
50.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c
51   :internal:
52
53
54DC Color Capabilities between DCN generations
55---------------------------------------------
56
57DRM/KMS framework defines three CRTC color correction properties: degamma,
58color transformation matrix (CTM) and gamma, and two properties for degamma and
59gamma LUT sizes. AMD DC programs some of the color correction features
60pre-blending but DRM/KMS has not per-plane color correction properties.
61
62In general, the DRM CRTC color properties are programmed to DC, as follows:
63CRTC gamma after blending, and CRTC degamma pre-blending. Although CTM is
64programmed after blending, it is mapped to DPP hw blocks (pre-blending). Other
65color caps available in the hw is not currently exposed by DRM interface and
66are bypassed.
67
68.. kernel-doc:: drivers/gpu/drm/amd/display/dc/dc.h
69   :doc: color-management-caps
70
71.. kernel-doc:: drivers/gpu/drm/amd/display/dc/dc.h
72   :internal:
73
74The color pipeline has undergone major changes between DCN hardware
75generations. What's possible to do before and after blending depends on
76hardware capabilities, as illustrated below by the DCN 2.0 and DCN 3.0 families
77schemas.
78
79**DCN 2.0 family color caps and mapping**
80
81.. kernel-figure:: dcn2_cm_drm_current.svg
82
83**DCN 3.0 family color caps and mapping**
84
85.. kernel-figure:: dcn3_cm_drm_current.svg
86
87Blend Mode Properties
88=====================
89
90Pixel blend mode is a DRM plane composition property of :c:type:`drm_plane` used to
91describes how pixels from a foreground plane (fg) are composited with the
92background plane (bg). Here, we present main concepts of DRM blend mode to help
93to understand how this property is mapped to AMD DC interface. See more about
94this DRM property and the alpha blending equations in :ref:`DRM Plane
95Composition Properties <plane_composition_properties>`.
96
97Basically, a blend mode sets the alpha blending equation for plane
98composition that fits the mode in which the alpha channel affects the state of
99pixel color values and, therefore, the resulted pixel color. For
100example, consider the following elements of the alpha blending equation:
101
102- *fg.rgb*: Each of the RGB component values from the foreground's pixel.
103- *fg.alpha*: Alpha component value from the foreground's pixel.
104- *bg.rgb*: Each of the RGB component values from the background.
105- *plane_alpha*: Plane alpha value set by the **plane "alpha" property**, see
106  more in :ref:`DRM Plane Composition Properties <plane_composition_properties>`.
107
108in the basic alpha blending equation::
109
110   out.rgb = alpha * fg.rgb + (1 - alpha) * bg.rgb
111
112the alpha channel value of each pixel in a plane is ignored and only the plane
113alpha affects the resulted pixel color values.
114
115DRM has three blend mode to define the blend formula in the plane composition:
116
117* **None**: Blend formula that ignores the pixel alpha.
118
119* **Pre-multiplied**: Blend formula that assumes the pixel color values in a
120  plane was already pre-multiplied by its own alpha channel before storage.
121
122* **Coverage**: Blend formula that assumes the pixel color values were not
123  pre-multiplied with the alpha channel values.
124
125and pre-multiplied is the default pixel blend mode, that means, when no blend
126mode property is created or defined, DRM considers the plane's pixels has
127pre-multiplied color values. On IGT GPU tools, the kms_plane_alpha_blend test
128provides a set of subtests to verify plane alpha and blend mode properties.
129
130The DRM blend mode and its elements are then mapped by AMDGPU display manager
131(DM) to program the blending configuration of the Multiple Pipe/Plane Combined
132(MPC), as follows:
133
134.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
135   :doc: mpc-overview
136
137.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
138   :functions: mpcc_blnd_cfg
139
140Therefore, the blending configuration for a single MPCC instance on the MPC
141tree is defined by :c:type:`mpcc_blnd_cfg`, where
142:c:type:`pre_multiplied_alpha` is the alpha pre-multiplied mode flag used to
143set :c:type:`MPCC_ALPHA_MULTIPLIED_MODE`. It controls whether alpha is
144multiplied (true/false), being only true for DRM pre-multiplied blend mode.
145:c:type:`mpcc_alpha_blend_mode` defines the alpha blend mode regarding pixel
146alpha and plane alpha values. It sets one of the three modes for
147:c:type:`MPCC_ALPHA_BLND_MODE`, as described below.
148
149.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
150   :functions: mpcc_alpha_blend_mode
151
152DM then maps the elements of `enum mpcc_alpha_blend_mode` to those in the DRM
153blend formula, as follows:
154
155* *MPC pixel alpha* matches *DRM fg.alpha* as the alpha component value
156  from the plane's pixel
157* *MPC global alpha* matches *DRM plane_alpha* when the pixel alpha should
158  be ignored and, therefore, pixel values are not pre-multiplied
159* *MPC global gain* assumes *MPC global alpha* value when both *DRM
160  fg.alpha* and *DRM plane_alpha* participate in the blend equation
161
162In short, *fg.alpha* is ignored by selecting
163:c:type:`MPCC_ALPHA_BLEND_MODE_GLOBAL_ALPHA`. On the other hand, (plane_alpha *
164fg.alpha) component becomes available by selecting
165:c:type:`MPCC_ALPHA_BLEND_MODE_PER_PIXEL_ALPHA_COMBINED_GLOBAL_GAIN`. And the
166:c:type:`MPCC_ALPHA_MULTIPLIED_MODE` defines if the pixel color values are
167pre-multiplied by alpha or not.
168
169Blend configuration flow
170------------------------
171
172The alpha blending equation is configured from DRM to DC interface by the
173following path:
174
1751. When updating a :c:type:`drm_plane_state <drm_plane_state>`, DM calls
176   :c:type:`fill_blending_from_plane_state()` that maps
177   :c:type:`drm_plane_state <drm_plane_state>` attributes to
178   :c:type:`dc_plane_info <dc_plane_info>` struct to be handled in the
179   OS-agnostic component (DC).
180
1812. On DC interface, :c:type:`struct mpcc_blnd_cfg <mpcc_blnd_cfg>` programs the
182   MPCC blend configuration considering the :c:type:`dc_plane_info
183   <dc_plane_info>` input from DPP.
184