DC Programming Model

DC service와 Display Manager의 경계

DCN overview와 DCN block 문서가 hardware component와 상호작용을 설명했다면, 이 문서는 display code architecture에 초점을 맞춥니다. DC code는 여러 operating system이 공유하므로 서로 다른 OS API를 DCN/DCE hardware configuration에 연결하는 abstraction과 operation을 제공합니다.

====================
DC Programming Model
====================

In the :ref:`Display Core Next (DCN) <dcn_overview>` and :ref:`DCN Block
<dcn_blocks>` pages, you learned about the hardware components and how they
interact with each other. On this page, the focus is shifted to the display
code architecture. Hence, it is reasonable to remind the reader that the code
in DC is shared with other OSes; for this reason, DC provides a set of
abstractions and operations to connect different APIs with the hardware
configuration. See DC as a service available for a Display Manager (amdgpu_dm)
to access and configure DCN/DCE hardware (DCE is also part of DC, but for
simplicity's sake, this documentation only examines DCN).

.. note::
   For this page, we will use the term GPU to refers to dGPU and APU.

DC policy, resource 안정성과 DML

범위와 해법이 명확한 문제는 hardware에 구현되는 경우가 많고, 여러 해결 방법이 있어 상황별 판단이 필요한 문제는 DC level의 policy로 구현됩니다. Resource management, power optimization과 image quality는 DC core의 policy이며, hardware가 제공하는 기능은 DC configuration을 통해 활성화합니다.

DCN에는 HUBP, DPP, MPC 같은 block instance가 여러 개 있습니다. DC의 resource policy는 state A에서 B로 바뀔 때 hardware shuffle을 최소화하려 합니다. 같은 driver object 집합이 기존 hardware resource를 계속 사용하면 transition이 단순해집니다. `pipe_ctx`에 resource를 추가하거나 제거하는 것은 보통 문제가 아니지만, resource를 한 `pipe_ctx`에서 다른 `pipe_ctx`로 옮기는 일은 피해야 합니다.

Image를 표시하는 기본 configuration 자체는 비교적 단순하지만, 가장 낮은 power footprint를 얻는 configuration은 DCN/DCE version, display 수와 mode 등 변수가 너무 많아 간단한 analytic formula로 결정하기 어렵습니다. AMDGPU는 여러 configuration을 시도하고 지원 가능성을 검증하는 Display Mode Library(DML)에 이 복잡한 결정을 맡깁니다.

따라서 DC는 다양한 display scenario를 hardware capability에 맞추고 지속 가능한 policy를 선택하는 계층입니다. 이 관점을 가지면 AMDGPU display code에서 policy와 low-level programming이 섞여 보이는 복잡성을 더 정확히 탐색할 수 있습니다.

Overview
========

From the display hardware perspective, it is plausible to expect that if a
problem is well-defined, it will probably be implemented at the hardware level.
On the other hand, when there are multiple ways of achieving something without
a very well-defined scope, the solution is usually implemented as a policy at
the DC level. In other words, some policies are defined in the DC core
(resource management, power optimization, image quality, etc.), and the others
implemented in hardware are enabled via DC configuration.

In terms of hardware management, DCN has multiple instances of the same block
(e.g., HUBP, DPP, MPC, etc), and during the driver execution, it might be
necessary to use some of these instances. The core has policies in place for
handling those instances. Regarding resource management, the DC objective is
quite simple: minimize the hardware shuffle when the driver performs some
actions. When the state changes from A to B, the transition is considered
easier to maneuver if the hardware resource is still used for the same set of
driver objects. Usually, adding and removing a resource to a `pipe_ctx` (more
details below) is not a problem; however, moving a resource from one `pipe_ctx`
to another should be avoided.

Another area of influence for DC is power optimization, which has a myriad of
arrangement possibilities. In some way, just displaying an image via DCN should
be relatively straightforward; however, showing it with the best power
footprint is more desirable, but it has many associated challenges.
Unfortunately, there is no straight-forward analytic way to determine if a
configuration is the best one for the context due to the enormous variety of
variables related to this problem (e.g., many different DCN/DCE hardware
versions, different displays configurations, etc.) for this reason DC
implements a dedicated library for trying some configuration and verify if it
is possible to support it or not. This type of policy is extremely complex to
create and maintain, and amdgpu driver relies on Display Mode Library (DML) to
generate the best decisions.

In summary, DC must deal with the complexity of handling multiple scenarios and
determine policies to manage them. All of the above information is conveyed to
give the reader some idea about the complexity of driving a display from the
driver's perspective. This page hopes to allow the reader to better navigate
over the amdgpu display code.

Display driver software layer

`dc-components.svg`는 DC software layer를 일반 display path와 DMUB microcontroller path로 나눕니다. 가장 위에는 `dc/dc.h`가 제공하는 high-level Display Core API가 있고, Core와 Link를 지나 hardware sequencer와 block-level API로 내려갑니다.

Display Driver Architecture Overview
====================================

The diagram below provides an overview of the display driver architecture;
notice it illustrates the software layers adopted by DC:

.. kernel-figure:: dc-components.svg

The first layer of the diagram is the high-level DC API represented by the
`dc.h` file; below it are two big blocks represented by Core and Link. Next is
the hardware configuration block; the main file describing it is
the`hw_sequencer.h`, where the implementation of the callbacks can be found in
the hardware sequencer folder. Almost at the end, you can see the block level
API (`dc/inc/hw`), which represents each DCN low-level block, such as HUBP,
DPP, MPC, OPTC, etc. Notice on the left side of the diagram that we have a
different set of layers representing the interaction with the DMUB
microcontroller.

GPU·board·stream을 잇는 기본 object

`dc-arch-overview.svg`의 box 이름은 driver data structure와 architecture boundary를 나타냅니다. 중심 object인 `dc`는 GPU마다 하나씩 초기화됩니다. GPU 한 개에는 `dc` instance 하나, GPU 두 개에는 두 instance가 있으므로 각 `amdgpu` instance 안에서 Singleton과 비슷하게 동작합니다.

Connector는 DCN SoC block의 일부가 아니라 platform 또는 board가 정의합니다. `dc_link`는 단순히 사용자가 조작하는 외부 physical connector만 뜻하지 않습니다. 역사적으로 붙은 이름이며 eDP처럼 내부 연결이거나 output이 다른 device를 거치는 경우도 포함합니다.

Basic Objects
-------------

The below diagram outlines the basic display objects. In particular, pay
attention to the names in the boxes since they represent a data structure in
the driver:

.. kernel-figure:: dc-arch-overview.svg

Let's start with the central block in the image, `dc`. The `dc` struct is
initialized per GPU; for example, one GPU has one `dc` instance, two GPUs have
two `dc` instances, and so forth. In other words we have one 'dc' per 'amdgpu'
instance. In some ways, this object behaves like the `Singleton` pattern.

After the `dc` block in the diagram, you can see the `dc_link` component, which
is a low-level abstraction for the connector. One interesting aspect of the
image is that connectors are not part of the DCN block; they are defined by the
platform/board and not by the SoC. The `dc_link` struct is the high-level data
container with information such as connected sinks, connection status, signal
types, etc. After `dc_link`, there is the `dc_sink`, which is the object that
represents the connected display.

.. note::
   For historical reasons, we used the name `dc_link`, which gives the
   wrong impression that this abstraction only deals with physical connections
   that the developer can easily manipulate. However, this also covers
   connections like eDP or cases where the output is connected to other devices.

There are two structs that are not represented in the diagram since they were
elaborated in the DCN overview page  (check the DCN block diagram :ref:`Display
Core Next (DCN) <dcn_overview>`); still, it is worth bringing back for this
overview which is `dc_stream` and `dc_state`. The `dc_stream` stores many
properties associated with the data transmission, but most importantly, it
represents the data flow from the connector to the display. Next we have
`dc_state`, which represents the logic state within the hardware at the moment;
`dc_state` is composed of `dc_stream` and `dc_plane`. The `dc_stream` is the DC
version of `drm_crtc` and represents the post-blending pipeline.

Speaking of the `dc_plane` data structure (first part of the diagram), you can
think about it as an abstraction similar to `drm_plane` that represents the
pre-blending portion of the pipeline. This image was probably processed by GFX
and is ready to be composited under a `dc_stream`. Normally, the driver may
have one or more `dc_plane` connected to the same `dc_stream`, which defines a
composition at the DC level.

Software 생성부터 plane update까지

`dc_create()`는 `dc` data structure에 대한 constructor 역할을 하며 기본 software initialization과 다른 API를 사용할 준비를 합니다. 이 단계는 hardware configuration을 전혀 건드리지 않습니다. 반면 `dc_hardware_init()`은 unknown state일 수 있는 hardware를 valid state로 만들며 hardware-specific callback을 호출하는 최초의 hardware access 지점입니다.

Link 정보는 SoC definition이 아니라 board configuration에 달려 있으므로 `dc_get_link_at_index`로 device의 `dc_link`를 열거해야 합니다. 각 link가 준비되면 `dc_link_detect()`로 display 연결 여부를 확인합니다.

Basic Operations
----------------

Now that we have covered the basic objects, it is time to examine some of the
basic hardware/software operations. Let's start with the `dc_create()`
function, which directly works with the `dc` data struct; this function behaves
like a constructor responsible for the basic software initialization and
preparing for enabling other parts of the API. It is important to highlight
that this operation does not touch any hardware configuration; it is only a
software initialization.

Next, we have the `dc_hardware_init()`, which also relies on the `dc` data
struct. Its main function is to put the hardware in a valid state. It is worth
highlighting that the hardware might initialize in an unknown state, and it is
a requirement to put it in a valid state; this function has multiple callbacks
for the hardware-specific initialization, whereas `dc_hardware_init` does the
hardware initialization and is the first point where we touch hardware.

The `dc_get_link_at_index` is an operation that depends on the `dc_link` data
structure. This function retrieves and enumerates all the `dc_links` available
on the device; this is required since this information is not part of the SoC
definition but depends on the board configuration. As soon as the `dc_link` is
initialized, it is useful to figure out if any of them are already connected to
the display by using the `dc_link_detect()` function. After the driver figures
out if any display is connected to the device, the challenging phase starts:
configuring the monitor to show something. Nonetheless, dealing with the ideal
configuration is not a DC task since this is the Display Manager (`amdgpu_dm`)
responsibility which in turn is responsible for dealing with the atomic
commits. The only interface DC provides to the configuration phase is the
function `dc_validate_with_context` that receives the configuration information
and, based on that, validates whether the hardware can support it or not. It is
important to add that even if the display supports some specific configuration,
it does not mean the DCN hardware can support it.

After the DM and DC agree upon the configuration, the stream configuration
phase starts. This task activates one or more `dc_stream` at this phase, and in
the best-case scenario, you might be able to turn the display on with a black
screen (it does not show anything yet since it does not have any plane
associated with it). The final step would be to call the
`dc_update_planes_and_stream,` which will add or remove planes.