AMDgpu Display Manager

Display Manager의 계층과 핵심 경로

AMDGPU Display Manager(DM)는 Linux DRM/KMS object와 atomic state를 AMD의 OS-agnostic Display Core(DC) interface로 연결하는 계층입니다. 이 RST 문서는 긴 implementation을 복제하지 않고 `amdgpu_dm.c`, `amdgpu_dm.h`, `amdgpu_dm_irq.c`의 kernel-doc overview, internal symbol과 선택된 function 문서를 조합합니다.

Lifecycle 절은 `dm_hw_init`와 `dm_hw_fini`를 직접 지정합니다. 두 function은 DM hardware-facing resource의 시작과 종료 경계를 이루므로 init failure unwind와 suspend/resume 또는 teardown 순서를 함께 봐야 합니다.

Interrupt 절은 `amdgpu_dm_irq.c`의 overview와 internal symbol을 포함하고, `register_hpd_handlers`, `dm_crtc_high_irq`, `dm_pflip_high_irq`를 별도로 문서화합니다. HPD는 connector 상태 변화, CRTC high IRQ는 timing event, pflip high IRQ는 page-flip completion 경로와 연결됩니다.

Atomic Implementation 절은 `amdgpu_dm_atomic_check`와 `amdgpu_dm_atomic_commit_tail`을 지정합니다. 전자는 proposed DRM state가 DC resource와 bandwidth 제약을 만족하는지 검사하고, 후자는 승인된 state를 hardware에 적용하고 event 및 cleanup을 이어가는 핵심 경로입니다.

======================
AMDgpu Display Manager
======================

.. contents:: Table of Contents
    :depth: 3

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
   :doc: overview

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h
   :internal:

Lifecycle
=========

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
   :doc: DM Lifecycle

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
   :functions: dm_hw_init dm_hw_fini

Interrupts
==========

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c
   :doc: overview

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c
   :internal:

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
   :functions: register_hpd_handlers dm_crtc_high_irq dm_pflip_high_irq

Atomic Implementation
=====================

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
   :doc: atomic

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
   :functions: amdgpu_dm_atomic_check amdgpu_dm_atomic_commit_tail

Color Management와 DCN 세대별 mapping

Color Management 절은 `amdgpu_dm_color.c`의 overview와 internal symbol을 포함합니다. DRM/KMS는 CRTC color correction property로 degamma, color transformation matrix(CTM), gamma를 정의하고 degamma LUT와 gamma LUT의 size property도 제공합니다. 그러나 DRM/KMS에는 이 원문 시점에 per-plane color correction property가 없습니다.

일반 mapping에서 CRTC degamma는 blending 전에, CRTC gamma는 blending 뒤에 DC로 program됩니다. CTM은 DRM 관점에서는 blending 뒤 property이지만 현재 AMD DC mapping은 pre-blending DPP hardware block을 사용합니다. Hardware가 가진 다른 color capability 중 DRM interface로 노출되지 않은 기능은 bypass됩니다.

`dc.h`의 `color-management-caps` 문서와 internal symbol은 DC가 세대별 color capability를 표현하는 방식을 설명합니다. Pre-blend와 post-blend에서 가능한 operation은 DCN generation의 hardware block에 따라 크게 달라집니다.

Color Management Properties
===========================

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c
   :doc: overview

.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_color.c
   :internal:


DC Color Capabilities between DCN generations
---------------------------------------------

DRM/KMS framework defines three CRTC color correction properties: degamma,
color transformation matrix (CTM) and gamma, and two properties for degamma and
gamma LUT sizes. AMD DC programs some of the color correction features
pre-blending but DRM/KMS has not per-plane color correction properties.

In general, the DRM CRTC color properties are programmed to DC, as follows:
CRTC gamma after blending, and CRTC degamma pre-blending. Although CTM is
programmed after blending, it is mapped to DPP hw blocks (pre-blending). Other
color caps available in the hw is not currently exposed by DRM interface and
are bypassed.

.. kernel-doc:: drivers/gpu/drm/amd/display/dc/dc.h
   :doc: color-management-caps

.. kernel-doc:: drivers/gpu/drm/amd/display/dc/dc.h
   :internal:

The color pipeline has undergone major changes between DCN hardware
generations. What's possible to do before and after blending depends on
hardware capabilities, as illustrated below by the DCN 2.0 and DCN 3.0 families
schemas.

**DCN 2.0 family color caps and mapping**

.. kernel-figure:: dcn2_cm_drm_current.svg

**DCN 3.0 family color caps and mapping**

.. kernel-figure:: dcn3_cm_drm_current.svg

DRM plane blend mode와 alpha equation

Pixel blend mode는 `drm_plane`의 plane composition property이며 foreground plane(fg)과 background plane(bg)의 pixel을 어떻게 합성할지 정합니다. 정확한 DRM property와 alpha equation은 `DRM Plane Composition Properties <plane_composition_properties>` 참조 절이 기준입니다.

기본 alpha blending equation은 다음과 같습니다.

out.rgb = alpha * fg.rgb + (1 - alpha) * bg.rgb

어떤 alpha 값을 식의 `alpha`에 사용할지는 blend mode가 결정합니다. Pixel alpha를 무시하는 mode에서는 plane alpha만 결과 color에 영향을 줍니다.

IGT GPU tools의 `kms_plane_alpha_blend` test는 plane alpha와 blend mode property를 검증하는 subtest 집합을 제공합니다. Mode mapping을 바꿀 때에는 equation만 확인하지 말고 실제 plane format과 alpha property 조합을 함께 검증해야 합니다.

Blend Mode Properties
=====================

Pixel blend mode is a DRM plane composition property of :c:type:`drm_plane` used to
describes how pixels from a foreground plane (fg) are composited with the
background plane (bg). Here, we present main concepts of DRM blend mode to help
to understand how this property is mapped to AMD DC interface. See more about
this DRM property and the alpha blending equations in :ref:`DRM Plane
Composition Properties <plane_composition_properties>`.

Basically, a blend mode sets the alpha blending equation for plane
composition that fits the mode in which the alpha channel affects the state of
pixel color values and, therefore, the resulted pixel color. For
example, consider the following elements of the alpha blending equation:

- *fg.rgb*: Each of the RGB component values from the foreground's pixel.
- *fg.alpha*: Alpha component value from the foreground's pixel.
- *bg.rgb*: Each of the RGB component values from the background.
- *plane_alpha*: Plane alpha value set by the **plane "alpha" property**, see
  more in :ref:`DRM Plane Composition Properties <plane_composition_properties>`.

in the basic alpha blending equation::

   out.rgb = alpha * fg.rgb + (1 - alpha) * bg.rgb

the alpha channel value of each pixel in a plane is ignored and only the plane
alpha affects the resulted pixel color values.

DRM has three blend mode to define the blend formula in the plane composition:

* **None**: Blend formula that ignores the pixel alpha.

* **Pre-multiplied**: Blend formula that assumes the pixel color values in a
  plane was already pre-multiplied by its own alpha channel before storage.

* **Coverage**: Blend formula that assumes the pixel color values were not
  pre-multiplied with the alpha channel values.

and pre-multiplied is the default pixel blend mode, that means, when no blend
mode property is created or defined, DRM considers the plane's pixels has
pre-multiplied color values. On IGT GPU tools, the kms_plane_alpha_blend test
provides a set of subtests to verify plane alpha and blend mode properties.

DM에서 MPC blend structure로

AMDGPU Display Manager는 DRM blend mode와 alpha 요소를 Multiple Pipe/Plane Combined(MPC)의 blending configuration으로 mapping합니다. `mpc.h`의 kernel-doc는 먼저 `mpcc_blnd_cfg`, 이어서 `mpcc_alpha_blend_mode` identifier를 선택해 문서화합니다.

`pre_multiplied_alpha`는 DRM Pre-multiplied mode에서만 true가 되며 `MPCC_ALPHA_MULTIPLIED_MODE`를 설정합니다. `mpcc_alpha_blend_mode`는 pixel alpha와 global alpha를 식에 넣는 방식을 선택합니다.

The DRM blend mode and its elements are then mapped by AMDGPU display manager
(DM) to program the blending configuration of the Multiple Pipe/Plane Combined
(MPC), as follows:

.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
   :identifiers: mpcc_blnd_cfg

Therefore, the blending configuration for a single MPCC instance on the MPC
tree is defined by :c:type:`mpcc_blnd_cfg`, where
:c:type:`pre_multiplied_alpha` is the alpha pre-multiplied mode flag used to
set :c:type:`MPCC_ALPHA_MULTIPLIED_MODE`. It controls whether alpha is
multiplied (true/false), being only true for DRM pre-multiplied blend mode.
:c:type:`mpcc_alpha_blend_mode` defines the alpha blend mode regarding pixel
alpha and plane alpha values. It sets one of the three modes for
:c:type:`MPCC_ALPHA_BLND_MODE`, as described below.

.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h
   :identifiers: mpcc_alpha_blend_mode

Pixel alpha, global alpha와 global gain

MPC pixel alpha는 DRM의 `fg.alpha`와 같습니다. MPC global alpha는 pixel alpha를 무시하고 pixel value가 pre-multiplied되지 않은 경우 DRM `plane_alpha`에 대응합니다. DRM `fg.alpha`와 `plane_alpha`가 모두 blend equation에 참여하면 MPC global gain이 global alpha 값을 사용합니다.

따라서 blend mode mapping은 alpha source 선택과 RGB premultiplication 여부를 별도로 정해야 합니다. 이 둘을 혼동하면 같은 alpha 값에서도 foreground color contribution이 달라집니다.

DM then maps the elements of `enum mpcc_alpha_blend_mode` to those in the DRM
blend formula, as follows:

* *MPC pixel alpha* matches *DRM fg.alpha* as the alpha component value
  from the plane's pixel
* *MPC global alpha* matches *DRM plane_alpha* when the pixel alpha should
  be ignored and, therefore, pixel values are not pre-multiplied
* *MPC global gain* assumes *MPC global alpha* value when both *DRM
  fg.alpha* and *DRM plane_alpha* participate in the blend equation

In short, *fg.alpha* is ignored by selecting
:c:type:`MPCC_ALPHA_BLEND_MODE_GLOBAL_ALPHA`. On the other hand, (plane_alpha *
fg.alpha) component becomes available by selecting
:c:type:`MPCC_ALPHA_BLEND_MODE_PER_PIXEL_ALPHA_COMBINED_GLOBAL_GAIN`. And the
:c:type:`MPCC_ALPHA_MULTIPLIED_MODE` defines if the pixel color values are
pre-multiplied by alpha or not.

Blend configuration flow

Alpha blending equation은 DRM plane state에서 DM을 거쳐 DC interface의 MPCC configuration으로 전달됩니다. 이 경로에서는 Linux-specific `drm_plane_state`를 OS-agnostic `dc_plane_info`로 바꾸는 경계가 핵심입니다.

Blend configuration flow
------------------------

The alpha blending equation is configured from DRM to DC interface by the
following path:

1. When updating a :c:type:`drm_plane_state <drm_plane_state>`, DM calls
   :c:type:`amdgpu_dm_plane_fill_blending_from_plane_state()` that maps
   :c:type:`drm_plane_state <drm_plane_state>` attributes to
   :c:type:`dc_plane_info <dc_plane_info>` struct to be handled in the
   OS-agnostic component (DC).

2. On DC interface, :c:type:`struct mpcc_blnd_cfg <mpcc_blnd_cfg>` programs the
   MPCC blend configuration considering the :c:type:`dc_plane_info
   <dc_plane_info>` input from DPP.