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.