Display Core Next (DCN)

DCN architecture와 block 관계

AMD Display Core Next(DCN)를 이해하려면 먼저 hardware pipeline의 큰 구조를 봐야 합니다. `dc_pipeline_overview.svg`는 공통 개념도이며, 실제 block 수와 연결은 ASIC마다 달라집니다. 따라서 이 그림은 고정 wiring diagram이 아니라 DC가 선택할 수 있는 resource와 interface의 기본 모델로 읽어야 합니다.

DCN은 userspace 요구에 맞춰 block을 사용하거나 생략하고 resource 수를 바꿉니다. 원문 예시의 8k@60Hz와 DSC 구성에서는 4개의 DPP와 2개의 OPP가 필요할 수 있으며, DC는 scenario마다 적합한 구성을 선택해야 합니다.

HUBP는 memory에서 특정 format의 surface를 읽고, `dc_plane` 경로는 이 pixel들을 DPP와 MPC에서 처리해 `dc_stream` 및 `dc_link`를 통해 display로 보낼 수 있는 형태로 바꿉니다.

.. _dcn_overview:

=======================
Display Core Next (DCN)
=======================

To equip our readers with the basic knowledge of how AMD Display Core Next
(DCN) works, we need to start with an overview of the hardware pipeline. Below
you can see a picture that provides a DCN overview, keep in mind that this is a
generic diagram, and we have variations per ASIC.

.. kernel-figure:: dc_pipeline_overview.svg

Based on this diagram, we can pass through each block and briefly describe
them:

* **Display Controller Hub (DCHUB)**: This is the gateway between the Scalable
  Data Port (SDP) and DCN. This component has multiple features, such as memory
  arbitration, rotation, and cursor manipulation.

* **Display Pipe and Plane (DPP)**: This block provides pre-blend pixel
  processing such as color space conversion, linearization of pixel data, tone
  mapping, and gamut mapping.

* **Multiple Pipe/Plane Combined (MPC)**: This component performs blending of
  multiple planes, using global or per-pixel alpha.

* **Output Pixel Processing (OPP)**: Process and format pixels to be sent to
  the display.

* **Output Pipe Timing Combiner (OPTC)**: It generates time output to combine
  streams or divide capabilities. CRC values are generated in this block.

* **Display Output (DIO)**: Codify the output to the display connected to our
  GPU.

* **Display Writeback (DWB)**: It provides the ability to write the output of
  the display pipe back to memory as video frames.

* **Multi-Media HUB (MMHUBBUB)**: Memory controller interface for DMCUB and DWB
  (Note that DWB is not hooked yet).

* **DCN Management Unit (DMU)**: It provides registers with access control and
  interrupts the controller to the SOC host interrupt unit. This block includes
  the Display Micro-Controller Unit - version B (DMCUB), which is handled via
  firmware.

* **DCN Clock Generator Block (DCCG)**: It provides the clocks and resets
  for all of the display controller clock domains.

* **Azalia (AZ)**: Audio engine.

The above diagram is an architecture generalization of DCN, which means that
every ASIC has variations around this base model. Notice that the display
pipeline is connected to the Scalable Data Port (SDP) via DCHUB; you can see
the SDP as the element from our Data Fabric that feeds the display pipe.

Always approach the DCN architecture as something flexible that can be
configured and reconfigured in multiple ways; in other words, each block can be
setup or ignored accordingly with userspace demands. For example, if we
want to drive an 8k@60Hz with a DSC enabled, our DCN may require 4 DPP and 2
OPP. It is DC's responsibility to drive the best configuration for each
specific scenario. Orchestrate all of these components together requires a
sophisticated communication interface which is highlighted in the diagram by
the edges that connect each block; from the chart, each connection between
these blocks represents:

1. Pixel data interface (red): Represents the pixel data flow;
2. Global sync signals (green): It is a set of synchronization signals composed
   by VStartup, VUpdate, and VReady;
3. Config interface: Responsible to configure blocks;
4. Sideband signals: All other signals that do not fit the previous one.

These signals are essential and play an important role in DCN. Nevertheless,
the Global Sync deserves an extra level of detail described in the next
section.

All of these components are represented by a data structure named dc_state.
From DCHUB to MPC, we have a representation called dc_plane; from MPC to OPTC,
we have dc_stream, and the output (DIO) is handled by dc_link. Keep in mind
that HUBP accesses a surface using a specific format read from memory, and our
dc_plane should work to convert all pixels in the plane to something that can
be sent to the display via dc_stream and dc_link.

Front End와 Back End

Display pipeline은 보통 Front End(FE)와 Back End(BE)로 나눕니다. FE는 pixel data를 읽고 변환·합성하는 영역이며, BE는 generic pixel stream을 특정 display가 요구하는 timing과 link stream으로 framing하는 영역입니다.

Link encoder와 PHY는 일대일로 mapping되지만, DCN configuration은 어느 link encoder를 어느 PHY에 연결할지 선택할 수 있습니다. 즉 resource의 수는 고정되어도 사용 pairing은 scenario에 따라 구성됩니다.

Front End and Back End
----------------------

Display pipeline can be broken down into two components that are usually
referred as **Front End (FE)** and **Back End (BE)**, where FE consists of:

* DCHUB (Mainly referring to a subcomponent named HUBP)
* DPP
* MPC

On the other hand, BE consist of

* OPP
* OPTC
* DIO (DP/HDMI stream encoder and link encoder)

OPP and OPTC are two joining blocks between FE and BE. On a side note, this is
a one-to-one mapping of the link encoder to PHY, but we can configure the DCN
to choose which link encoder to connect to which PHY. FE's main responsibility
is to change, blend and compose pixel data, while BE's job is to frame a
generic pixel stream to a specific display's pixel stream.

Pixel data 표현의 변화

VRAM의 data는 Data Fabric(DF)을 통해 native pixel format으로 들어옵니다. 이 format은 DCHUB의 HUBP까지 유지되며, HUBP가 format을 unpack한 뒤 alpha 한 채널과 color 세 채널의 균일한 네 채널 stream으로 DPP에 전달합니다.

DPP의 Converter and Cursor(CNVC)는 표현을 정규화하고 IEEE floating-point와 다른 DCN 전용 floating-point format으로 변환합니다. CNVC는 degamma를 적용해 non-linear space를 linear space로 바꾸므로 뒤의 floating-point color 계산을 단순화할 수 있습니다. 이 floating-point 표현은 DPP부터 OPP까지 유지됩니다.

OPP에 도달하면 color transformation과 blending이 끝났으므로 alpha를 버릴 수 있습니다. Display sink는 integer bit-depth format을 사용하므로 OPP에서 bit-depth reduction과 dithering을 적용하고, 앞에서 제거한 gamma를 regamma로 다시 넣습니다. 최종적으로 DIO는 integer format을 출력합니다.

Data Flow
---------

Initially, data is passed in from VRAM through Data Fabric (DF) in native pixel
formats. Such data format stays through till HUBP in DCHUB, where HUBP unpacks
different pixel formats and outputs them to DPP in uniform streams through 4
channels (1 for alpha + 3 for colors).

The Converter and Cursor (CNVC) in DPP would then normalize the data
representation and convert them to a DCN specific floating-point format (i.e.,
different from the IEEE floating-point format). In the process, CNVC also
applies a degamma function to transform the data from non-linear to linear
space to relax the floating-point calculations following. Data would stay in
this floating-point format from DPP to OPP.

Starting OPP, because color transformation and blending have been completed
(i.e alpha can be dropped), and the end sinks do not require the precision and
dynamic range that floating points provide (i.e. all displays are in integer
depth format), bit-depth reduction/dithering would kick in. In OPP, we would
also apply a regamma function to introduce the gamma removed earlier back.
Eventually, we output data in integer format at DIO.

Hardware pipeline, pipe split과 DTN log

Linux graphics에서 pipeline은 여러 의미로 쓰이므로 DCN driver의 정의를 분명히 해야 합니다. DC core에서 hardware pipeline, pipeline, pipe는 특정 configuration을 위해 배치한 DCN block sequence를 뜻합니다. 각 block은 개별 resource이지만 임의의 pipe 사이를 자유롭게 교차 연결할 수 있는 것은 아니며, 일반 경로는 선형으로 routing됩니다. DSC는 필요에 따라 배정할 수 있는 예외입니다.

Pipe abstraction은 bandwidth 사용을 최적화하기 위해 존재합니다. `pipeline_4k_no_split.svg` 예시는 HUBP(0), DPP(0), MPC(0), OPP(0)를 사용하는 단일 4K pipeline이며 DPPCLK 535.916 MHz, DISPCLK 541.275 MHz, DCFCLK 506 MHz를 표시합니다.

 HUBP:  format  addr_hi  width  height ...
 [ 0]:      8h      81h   3840    2160
 [ 1]:      0h       0h      0       0
 [ 2]:      0h       0h      0       0
 [ 3]:      0h       0h      0       0
 [ 4]:      0h       0h      0       0
 ...
 MPCC:  OPP  DPP ...
 [ 0]:   0h   0h ...

DCN은 같은 display를 여러 pipe로 나눌 수 있습니다. `pipeline_4k_split.svg`에서는 HUBP/DPP/MPC 0번과 5번이 각각 폭 1920을 처리하고 OPP(0) 쪽으로 결합됩니다. DPPCLK는 267.958 MHz로 낮아져 no-split의 절반 수준이지만 DISPCLK 541.275 MHz와 DCFCLK 506 MHz는 그림에서 그대로입니다.

 HUBP:  format  addr_hi  width  height ...
 [ 0]:      8h      81h   1920    2160 ...
 ...
 [ 4]:      0h       0h      0       0 ...
 [ 5]:      8h      81h   1920    2160 ...
 ...
 MPCC:  OPP  DPP ...
 [ 0]:   0h   0h ...
 [ 5]:   0h   5h ...

원문 180-182줄은 두 개의 `1920x2160` 부분을 설명하면서 괄호에 `3440x2160`이라고 적습니다. 그러나 DTN log와 앞의 3840-wide 예시를 기준으로 합계는 `3840x2160`입니다. 한국어 해설은 이 산술 불일치를 바로잡아 읽되, 영어 원문과 줄 좌표는 변경하지 않습니다.

AMD Hardware Pipeline
---------------------

When discussing graphics on Linux, the **pipeline** term can sometimes be
overloaded with multiple meanings, so it is important to define what we mean
when we say **pipeline**. In the DCN driver, we use the term **hardware
pipeline** or **pipeline** or just **pipe** as an abstraction to indicate a
sequence of DCN blocks instantiated to address some specific configuration. DC
core treats DCN blocks as individual resources, meaning we can build a pipeline
by taking resources for all individual hardware blocks to compose one pipeline.
In actuality, we can't connect an arbitrary block from one pipe to a block from
another pipe; they are routed linearly, except for DSC, which can be
arbitrarily assigned as needed. We have this pipeline concept for trying to
optimize bandwidth utilization.

.. kernel-figure:: pipeline_4k_no_split.svg

Additionally, let's take a look at parts of the DTN log (see
'Documentation/gpu/amdgpu/display/dc-debug.rst' for more information) since
this log can help us to see part of this pipeline behavior in real-time::

 HUBP:  format  addr_hi  width  height ...
 [ 0]:      8h      81h   3840    2160
 [ 1]:      0h       0h      0       0
 [ 2]:      0h       0h      0       0
 [ 3]:      0h       0h      0       0
 [ 4]:      0h       0h      0       0
 ...
 MPCC:  OPP  DPP ...
 [ 0]:   0h   0h ...

The first thing to notice from the diagram and DTN log it is the fact that we
have different clock domains for each part of the DCN blocks. In this example,
we have just a single **pipeline** where the data flows from DCHUB to DIO, as
we intuitively expect. Nonetheless, DCN is flexible, as mentioned before, and
we can split this single pipe differently, as described in the below diagram:

.. kernel-figure:: pipeline_4k_split.svg

Now, if we inspect the DTN log again we can see some interesting changes::

 HUBP:  format  addr_hi  width  height ...
 [ 0]:      8h      81h   1920    2160 ...
 ...
 [ 4]:      0h       0h      0       0 ...
 [ 5]:      8h      81h   1920    2160 ...
 ...
 MPCC:  OPP  DPP ...
 [ 0]:   0h   0h ...
 [ 5]:   0h   5h ...

From the above example, we now split the display pipeline into two vertical
parts of 1920x2160 (i.e., 3440x2160), and as a result, we could reduce the
clock frequency in the DPP part. This is not only useful for saving power but
also to better handle the required throughput. The idea to keep in mind here is
that the pipe configuration can vary a lot according to the display
configuration, and it is the DML's responsibility to set up all required
configuration parameters for multiple scenarios supported by our hardware.

Global Sync와 atomic register update

DCN register는 다수가 double-buffered이며 surface address가 대표적입니다. 이 구조 덕분에 새 pipe를 enable 또는 disable하지 않는 page flip과 대부분의 update를 atomic하게 적용할 수 있습니다. 높은 pixel clock 또는 power 절감을 위해 DC가 extra pipe를 미리 reserve하는 scenario도 있습니다.

Atomic update는 global sync signal로 구동됩니다. VSTARTUP, VUPDATE, VREADY는 Display Mode Library(DML)의 `drivers/gpu/drm/amd/display/dc/dml`이 system configuration과 bandwidth 관련 parameter를 바탕으로 계산합니다. 세 signal은 VBlank 안에서 발생하고 VSync와 독립적이며 서로 겹치지 않습니다.

Driver stack과 userspace client가 직접 관심을 갖는 신호는 VUPDATE입니다. Hardware가 atomic하게 program된 register를 latch하는 지점이기 때문입니다. VUPDATE는 VSync와 독립적이지만 atomic commit과 hardware 적용의 관계를 가장 잘 나타내므로 driver는 이를 VSync event 신호로 사용합니다.

Global Sync
-----------

Many DCN registers are double buffered, most importantly the surface address.
This allows us to update DCN hardware atomically for page flips, as well as
for most other updates that don't require enabling or disabling of new pipes.

(Note: There are many scenarios when DC will decide to reserve extra pipes
in order to support outputs that need a very high pixel clock, or for
power saving purposes.)

These atomic register updates are driven by global sync signals in DCN. In
order to understand how atomic updates interact with DCN hardware, and how DCN
signals page flip and vblank events it is helpful to understand how global sync
is programmed.

Global sync consists of three signals, VSTARTUP, VUPDATE, and VREADY. These are
calculated by the Display Mode Library - DML (drivers/gpu/drm/amd/display/dc/dml)
based on a large number of parameters and ensure our hardware is able to feed
the DCN pipeline without underflows or hangs in any given system configuration.
The global sync signals always happen during VBlank, are independent from the
VSync signal, and do not overlap each other.

VUPDATE is the only signal that is of interest to the rest of the driver stack
or userspace clients as it signals the point at which hardware latches to
atomically programmed (i.e. double buffered) registers. Even though it is
independent of the VSync signal we use VUPDATE to signal the VSync event as it
provides the best indication of how atomic commits and hardware interact.

Since DCN hardware is double-buffered the DC driver is able to program the
hardware at any point during the frame.

The below picture illustrates the global sync signals:

.. kernel-figure:: global_sync_vblank.svg

Mailbox 방식 configuration 적용

Global sync를 잘못 program하면 underflow, hang, 잘못된 page flip timing처럼 핵심 DCN 동작에 심각한 결과가 생길 수 있습니다. `config_example.svg`는 VUPDATE 사이에 여러 configuration을 program할 수 있지만 다음 VUPDATE에서 유효해지는 것은 마지막 configuration뿐인 mailbox 동작을 보여 줍니다.

These signals affect core DCN behavior. Programming them incorrectly will lead
to a number of negative consequences, most of them quite catastrophic.

The following picture shows how global sync allows for a mailbox style of
updates, i.e. it allows for multiple re-configurations between VUpdate
events where only the last configuration programmed before the VUpdate signal
becomes effective.

.. kernel-figure:: config_example.svg