Documentation/gpu/amdgpu/display/display-manager.rst

   1 ======================
   2 AMDgpu 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
  14 Lifecycle
  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
  23 Interrupts
  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
  35 Atomic 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
  44 Color 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
  54 DC Color Capabilities between DCN generations
  55 ---------------------------------------------
  56
  57 DRM/KMS framework defines three CRTC color correction properties: degamma,
  58 color transformation matrix (CTM) and gamma, and two properties for degamma and
  59 gamma LUT sizes. AMD DC programs some of the color correction features
  60 pre-blending but DRM/KMS has not per-plane color correction properties.
  61
  62 In general, the DRM CRTC color properties are programmed to DC, as follows:
  63 CRTC gamma after blending, and CRTC degamma pre-blending. Although CTM is
  64 programmed after blending, it is mapped to DPP hw blocks (pre-blending). Other
  65 color caps available in the hw is not currently exposed by DRM interface and
  66 are 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
  74 The color pipeline has undergone major changes between DCN hardware
  75 generations. What's possible to do before and after blending depends on
  76 hardware capabilities, as illustrated below by the DCN 2.0 and DCN 3.0 families
  77 schemas.
  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
  87 Blend Mode Properties
  88 =====================
  89
  90 Pixel blend mode is a DRM plane composition property of :c:type:`drm_plane` used to
  91 describes how pixels from a foreground plane (fg) are composited with the
  92 background plane (bg). Here, we present main concepts of DRM blend mode to help
  93 to understand how this property is mapped to AMD DC interface. See more about
  94 this DRM property and the alpha blending equations in :ref:`DRM Plane
  95 Composition Properties <plane_composition_properties>`.
  96
  97 Basically, a blend mode sets the alpha blending equation for plane
  98 composition that fits the mode in which the alpha channel affects the state of
  99 pixel color values and, therefore, the resulted pixel color. For
 100 example, 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
 108 in the basic alpha blending equation::
 109
 110    out.rgb = alpha * fg.rgb + (1 - alpha) * bg.rgb
 111
 112 the alpha channel value of each pixel in a plane is ignored and only the plane
 113 alpha affects the resulted pixel color values.
 114
 115 DRM 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
 125 and pre-multiplied is the default pixel blend mode, that means, when no blend
 126 mode property is created or defined, DRM considers the plane's pixels has
 127 pre-multiplied color values. On IGT GPU tools, the kms_plane_alpha_blend test
 128 provides a set of subtests to verify plane alpha and blend mode properties.
 129
 130 The 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    :identifiers: mpcc_blnd_cfg
 136
 137 Therefore, the blending configuration for a single MPCC instance on the MPC
 138 tree is defined by :c:type:`mpcc_blnd_cfg`, where
 139 :c:type:`pre_multiplied_alpha` is the alpha pre-multiplied mode flag used to
 140 set :c:type:`MPCC_ALPHA_MULTIPLIED_MODE`. It controls whether alpha is
 141 multiplied (true/false), being only true for DRM pre-multiplied blend mode.
 142 :c:type:`mpcc_alpha_blend_mode` defines the alpha blend mode regarding pixel
 143 alpha and plane alpha values. It sets one of the three modes for
 144 :c:type:`MPCC_ALPHA_BLND_MODE`, as described below.
 145
 146 .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
 147    :identifiers: mpcc_alpha_blend_mode
 148
 149 DM then maps the elements of `enum mpcc_alpha_blend_mode` to those in the DRM
 150 blend formula, as follows:
 151
 152 * *MPC pixel alpha* matches *DRM fg.alpha* as the alpha component value
 153   from the plane's pixel
 154 * *MPC global alpha* matches *DRM plane_alpha* when the pixel alpha should
 155   be ignored and, therefore, pixel values are not pre-multiplied
 156 * *MPC global gain* assumes *MPC global alpha* value when both *DRM
 157   fg.alpha* and *DRM plane_alpha* participate in the blend equation
 158
 159 In short, *fg.alpha* is ignored by selecting
 160 :c:type:`MPCC_ALPHA_BLEND_MODE_GLOBAL_ALPHA`. On the other hand, (plane_alpha *
 161 fg.alpha) component becomes available by selecting
 162 :c:type:`MPCC_ALPHA_BLEND_MODE_PER_PIXEL_ALPHA_COMBINED_GLOBAL_GAIN`. And the
 163 :c:type:`MPCC_ALPHA_MULTIPLIED_MODE` defines if the pixel color values are
 164 pre-multiplied by alpha or not.
 165
 166 Blend configuration flow
 167 ------------------------
 168
 169 The alpha blending equation is configured from DRM to DC interface by the
 170 following path:
 171
 172 1. When updating a :c:type:`drm_plane_state <drm_plane_state>`, DM calls
 173    :c:type:`amdgpu_dm_plane_fill_blending_from_plane_state()` that maps
 174    :c:type:`drm_plane_state <drm_plane_state>` attributes to
 175    :c:type:`dc_plane_info <dc_plane_info>` struct to be handled in the
 176    OS-agnostic component (DC).
 177
 178 2. On DC interface, :c:type:`struct mpcc_blnd_cfg <mpcc_blnd_cfg>` programs the
 179    MPCC blend configuration considering the :c:type:`dc_plane_info
 180    <dc_plane_info>` input from DPP.