[PATCH v4 0/6] Expand display core documentation

[PATCH v4 0/6] Expand display core documentation

[Rodrigo Siqueira]

Display Core (DC) is one of the components under amdgpu, and it has
multiple features directly related to the KMS API. Unfortunately, we
don't have enough documentation about DC in the upstream, which makes
the life of some external contributors a little bit more challenging.
For these reasons, this patchset reworks part of the DC documentation
and introduces a new set of details on how the display core works on DCN
IP. Another improvement that this documentation effort tries to bring is
making explicit some of our hardware-specific details to guide
user-space developers better.

In my view, it is easier to review this series if you apply it in your
local kernel and build the HTML version (make htmldocs). I'm suggesting
this approach because I added a few SVG diagrams that will be easier to
see in the HTML version. If you cannot build the documentation, try to
open the SVG images while reviewing the content. In summary, in this
series, you will find:

1. Patch 1: Re-arrange of display core documentation. This is
   preparation work for the other patches, but it is also a way to expand
   this documentation.
2. Patch 2 to 4: Document some common debug options related to display.
3. Patch 5: This patch provides an overview of how our display core next
   works and a brief explanation of each component.
4. Patch 6: We use a lot of acronyms in our driver; for this reason, we
   exposed a glossary with common terms used by display core.

Please let us know what you think we can improve this series and what
kind of content you want to see for the next series.

Changes since V3:
 - Add new acronyms to amdgpu glossary
 - Add link between dc and amdgpu glossary
Changes since V2:
 - Add a comment about MMHUBBUB
Changes since V1:
 - Group amdgpu documentation together.
 - Create index pages.
 - Mirror display folder in the documentation.
 - Divide glossary based on driver context.
 - Make terms more consistent and update CPLIB
 - Add new acronyms to the glossary

Thanks
Siqueira

Rodrigo Siqueira (6):
  Documentation/gpu: Reorganize DC documentation
  Documentation/gpu: Document amdgpu_dm_visual_confirm debugfs entry
  Documentation/gpu: Document pipe split visual confirmation
  Documentation/gpu: How to collect DTN log
  Documentation/gpu: Add basic overview of DC pipeline
  Documentation/gpu: Add amdgpu and dc glossary

 Documentation/gpu/amdgpu-dc.rst               |   74 --
 Documentation/gpu/amdgpu/amdgpu-glossary.rst  |   87 ++
 .../gpu/amdgpu/display/config_example.svg     |  414 ++++++
 Documentation/gpu/amdgpu/display/dc-debug.rst |   77 ++
 .../gpu/amdgpu/display/dc-glossary.rst        |  237 ++++
 .../amdgpu/display/dc_pipeline_overview.svg   | 1125 +++++++++++++++++
 .../gpu/amdgpu/display/dcn-overview.rst       |  171 +++
 .../gpu/amdgpu/display/display-manager.rst    |   42 +
 .../gpu/amdgpu/display/global_sync_vblank.svg |  485 +++++++
 Documentation/gpu/amdgpu/display/index.rst    |   29 +
 .../gpu/{amdgpu.rst => amdgpu/index.rst}      |   25 +-
 Documentation/gpu/drivers.rst                 |    3 +-
 12 files changed, 2690 insertions(+), 79 deletions(-)
 delete mode 100644 Documentation/gpu/amdgpu-dc.rst
 create mode 100644 Documentation/gpu/amdgpu/amdgpu-glossary.rst
 create mode 100644 Documentation/gpu/amdgpu/display/config_example.svg
 create mode 100644 Documentation/gpu/amdgpu/display/dc-debug.rst
 create mode 100644 Documentation/gpu/amdgpu/display/dc-glossary.rst
 create mode 100644 Documentation/gpu/amdgpu/display/dc_pipeline_overview.svg
 create mode 100644 Documentation/gpu/amdgpu/display/dcn-overview.rst
 create mode 100644 Documentation/gpu/amdgpu/display/display-manager.rst
 create mode 100644 Documentation/gpu/amdgpu/display/global_sync_vblank.svg
 create mode 100644 Documentation/gpu/amdgpu/display/index.rst
 rename Documentation/gpu/{amdgpu.rst => amdgpu/index.rst} (95%)

-- 
2.25.1

[PATCH v4 1/6] Documentation/gpu: Reorganize DC documentation

[Rodrigo Siqueira]

Display core documentation is not well organized, and it is hard to find
information due to the lack of sections. This commit reorganizes the
documentation layout, and it is preparation work for future changes.

Changes since V1:
- Christian: Group amdgpu documentation together.
- Daniel: Drop redundant amdgpu prefix.
- Jani: Create index pages.
- Yann: Mirror display folder in the documentation.

Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
 Documentation/gpu/amdgpu-dc.rst               | 74 -------------------
 Documentation/gpu/amdgpu/display/dc-debug.rst |  4 +
 .../gpu/amdgpu/display/display-manager.rst    | 42 +++++++++++
 Documentation/gpu/amdgpu/display/index.rst    | 29 ++++++++
 .../gpu/{amdgpu.rst => amdgpu/index.rst}      | 18 ++++-
 Documentation/gpu/drivers.rst                 |  3 +-
 6 files changed, 91 insertions(+), 79 deletions(-)
 delete mode 100644 Documentation/gpu/amdgpu-dc.rst
 create mode 100644 Documentation/gpu/amdgpu/display/dc-debug.rst
 create mode 100644 Documentation/gpu/amdgpu/display/display-manager.rst
 create mode 100644 Documentation/gpu/amdgpu/display/index.rst
 rename Documentation/gpu/{amdgpu.rst => amdgpu/index.rst} (96%)

diff --git a/Documentation/gpu/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc.rst
deleted file mode 100644
index f7ff7e1309de..000000000000
--- a/Documentation/gpu/amdgpu-dc.rst
+++ /dev/null
@@ -1,74 +0,0 @@
-===================================
-drm/amd/display - Display Core (DC)
-===================================
-
-*placeholder - general description of supported platforms, what dc is, etc.*
-
-Because it is partially shared with other operating systems, the Display Core
-Driver is divided in two pieces.
-
-1. **Display Core (DC)** contains the OS-agnostic components. Things like
-   hardware programming and resource management are handled here.
-2. **Display Manager (DM)** contains the OS-dependent components. Hooks to the
-   amdgpu base driver and DRM are implemented here.
-
-It doesn't help that the entire package is frequently referred to as DC. But
-with the context in mind, it should be clear.
-
-When CONFIG_DRM_AMD_DC is enabled, DC will be initialized by default for
-supported ASICs. To force disable, set `amdgpu.dc=0` on kernel command line.
-Likewise, to force enable on unsupported ASICs, set `amdgpu.dc=1`.
-
-To determine if DC is loaded, search dmesg for the following entry:
-
-``Display Core initialized with <version number here>``
-
-AMDgpu Display Manager
-======================
-
-.. 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
-
-Display Core
-============
-
-**WIP**
-
-FreeSync Video
---------------
-
-.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
-   :doc: FreeSync Video
diff --git a/Documentation/gpu/amdgpu/display/dc-debug.rst b/Documentation/gpu/amdgpu/display/dc-debug.rst
new file mode 100644
index 000000000000..bbb8c3fc8eee
--- /dev/null
+++ b/Documentation/gpu/amdgpu/display/dc-debug.rst
@@ -0,0 +1,4 @@
+Display Core Debug tools
+========================
+
+TODO
diff --git a/Documentation/gpu/amdgpu/display/display-manager.rst b/Documentation/gpu/amdgpu/display/display-manager.rst
new file mode 100644
index 000000000000..7ce31f89d9a0
--- /dev/null
+++ b/Documentation/gpu/amdgpu/display/display-manager.rst
@@ -0,0 +1,42 @@
+======================
+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
diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst
new file mode 100644
index 000000000000..a443866332ac
--- /dev/null
+++ b/Documentation/gpu/amdgpu/display/index.rst
@@ -0,0 +1,29 @@
+===================================
+drm/amd/display - Display Core (DC)
+===================================
+
+*placeholder - general description of supported platforms, what dc is, etc.*
+
+Because it is partially shared with other operating systems, the Display Core
+Driver is divided in two pieces.
+
+1. **Display Core (DC)** contains the OS-agnostic components. Things like
+   hardware programming and resource management are handled here.
+2. **Display Manager (DM)** contains the OS-dependent components. Hooks to the
+   amdgpu base driver and DRM are implemented here.
+
+It doesn't help that the entire package is frequently referred to as DC. But
+with the context in mind, it should be clear.
+
+When CONFIG_DRM_AMD_DC is enabled, DC will be initialized by default for
+supported ASICs. To force disable, set `amdgpu.dc=0` on kernel command line.
+Likewise, to force enable on unsupported ASICs, set `amdgpu.dc=1`.
+
+To determine if DC is loaded, search dmesg for the following entry:
+
+.. toctree::
+
+   display-manager.rst
+   dc-debug.rst
+
+``Display Core initialized with <version number here>``
diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu/index.rst
similarity index 96%
rename from Documentation/gpu/amdgpu.rst
rename to Documentation/gpu/amdgpu/index.rst
index 8ba72e898099..5c8cbf514097 100644
--- a/Documentation/gpu/amdgpu.rst
+++ b/Documentation/gpu/amdgpu/index.rst
@@ -1,6 +1,6 @@
-=========================
+==========================
  drm/amdgpu AMDgpu driver
-=========================
+==========================
 
 The drm/amdgpu driver supports all AMD Radeon GPUs based on the Graphics Core
 Next (GCN) architecture.
@@ -71,7 +71,7 @@ Interrupt Handling
    :internal:
 
 IP Blocks
-------------------
+---------
 
 .. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h
    :doc: IP Blocks
@@ -79,6 +79,18 @@ IP Blocks
 .. kernel-doc:: drivers/gpu/drm/amd/include/amd_shared.h
    :identifiers: amd_ip_block_type amd_ip_funcs
 
+Display Core
+============
+
+This section covers Display core.
+
+.. toctree::
+
+  display/index
+
+.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c
+   :doc: overview
+
 AMDGPU XGMI Support
 ===================
 
diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst
index b4a0ed3ca961..3a52f48215a3 100644
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -4,8 +4,7 @@ GPU Driver Documentation
 
 .. toctree::
 
-   amdgpu
-   amdgpu-dc
+   amdgpu/index
    i915
    mcde
    meson
-- 
2.25.1

[PATCH v4 2/6] Documentation/gpu: Document amdgpu_dm_visual_confirm debugfs entry

[Rodrigo Siqueira]

Display core provides a feature that makes it easy for users to debug
Multiple planes by enabling a visual notification at the bottom of each
plane. This commit introduces how to use such a feature.

Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
 Documentation/gpu/amdgpu/display/dc-debug.rst | 34 ++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/Documentation/gpu/amdgpu/display/dc-debug.rst b/Documentation/gpu/amdgpu/display/dc-debug.rst
index bbb8c3fc8eee..532cbbd64863 100644
--- a/Documentation/gpu/amdgpu/display/dc-debug.rst
+++ b/Documentation/gpu/amdgpu/display/dc-debug.rst
@@ -1,4 +1,36 @@
+========================
 Display Core Debug tools
 ========================
 
-TODO
+DC Debugfs
+==========
+
+Multiple Planes Debug
+---------------------
+
+If you want to enable or debug multiple planes in a specific user-space
+application, you can leverage a debug feature named visual confirm. For
+enabling it, you will need::
+
+  echo 1 > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm
+
+You need to reload your GUI to see the visual confirmation. When the plane
+configuration changes or a full update occurs there will be a colored bar at
+the bottom of each hardware plane being drawn on the screen.
+
+* The color indicates the format - For example, red is AR24 and green is NV12
+* The height of the bar indicates the index of the plane
+* Pipe split can be observed if there are two bars with a difference in height
+  covering the same plane
+
+Consider the video playback case in which a video is played in a specific
+plane, and the desktop is drawn in another plane. The video plane should
+feature one or two green bars at the bottom of the video depending on pipe
+split configuration.
+
+* There should **not** be any visual corruption
+* There should **not** be any underflow or screen flashes
+* There should **not** be any black screens
+* There should **not** be any cursor corruption
+* Multiple plane **may** be briefly disabled during window transitions or
+  resizing but should come back after the action has finished
-- 
2.25.1

[PATCH v4 3/6] Documentation/gpu: Document pipe split visual confirmation

[Rodrigo Siqueira]

Display core provides a feature that makes it easy for users to debug
Pipe Split. This commit introduces how to use such a debug option.

Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
 Documentation/gpu/amdgpu/display/dc-debug.rst | 28 +++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/Documentation/gpu/amdgpu/display/dc-debug.rst b/Documentation/gpu/amdgpu/display/dc-debug.rst
index 532cbbd64863..6dbd21f7f59e 100644
--- a/Documentation/gpu/amdgpu/display/dc-debug.rst
+++ b/Documentation/gpu/amdgpu/display/dc-debug.rst
@@ -2,8 +2,18 @@
 Display Core Debug tools
 ========================
 
-DC Debugfs
-==========
+DC Visual Confirmation
+======================
+
+Display core provides a feature named visual confirmation, which is a set of
+bars added at the scanout time by the driver to convey some specific
+information. In general, you can enable this debug option by using::
+
+  echo <N> > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm
+
+Where `N` is an integer number for some specific scenarios that the developer
+wants to enable, you will see some of these debug cases in the following
+subsection.
 
 Multiple Planes Debug
 ---------------------
@@ -34,3 +44,17 @@ split configuration.
 * There should **not** be any cursor corruption
 * Multiple plane **may** be briefly disabled during window transitions or
   resizing but should come back after the action has finished
+
+Pipe Split Debug
+----------------
+
+Sometimes we need to debug if DCN is splitting pipes correctly, and visual
+confirmation is also handy for this case. Similar to the MPO case, you can use
+the below command to enable visual confirmation::
+
+  echo 1 > /sys/kernel/debug/dri/0/amdgpu_dm_visual_confirm
+
+In this case, if you have a pipe split, you will see one small red bar at the
+bottom of the display covering the entire display width and another bar
+covering the second pipe. In other words, you will see a bit high bar in the
+second pipe.
-- 
2.25.1

[PATCH v4 4/6] Documentation/gpu: How to collect DTN log

[Rodrigo Siqueira]

Introduce how to collect DTN log from debugfs.

Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
 Documentation/gpu/amdgpu/display/dc-debug.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/gpu/amdgpu/display/dc-debug.rst b/Documentation/gpu/amdgpu/display/dc-debug.rst
index 6dbd21f7f59e..40c55a618918 100644
--- a/Documentation/gpu/amdgpu/display/dc-debug.rst
+++ b/Documentation/gpu/amdgpu/display/dc-debug.rst
@@ -58,3 +58,20 @@ In this case, if you have a pipe split, you will see one small red bar at the
 bottom of the display covering the entire display width and another bar
 covering the second pipe. In other words, you will see a bit high bar in the
 second pipe.
+
+DTN Debug
+=========
+
+DC (DCN) provides an extensive log that dumps multiple details from our
+hardware configuration. Via debugfs, you can capture those status values by
+using Display Test Next (DTN) log, which can be captured via debugfs by using::
+
+  cat /sys/kernel/debug/dri/0/amdgpu_dm_dtn_log
+
+Since this log is updated accordingly with DCN status, you can also follow the
+change in real-time by using something like::
+
+  sudo watch -d cat /sys/kernel/debug/dri/0/amdgpu_dm_dtn_log
+
+When reporting a bug related to DC, consider attaching this log before and
+after you reproduce the bug.
-- 
2.25.1

[PATCH v4 6/6] Documentation/gpu: Add amdgpu and dc glossary

[Rodrigo Siqueira]

In the DC driver, we have multiple acronyms that are not obvious most of
the time; the same idea is valid for amdgpu. This commit introduces a DC
and amdgpu glossary in order to make it easier to navigate through our
driver.

Changes since V3:
 - Yann: Add new acronyms to amdgpu glossary
 - Daniel: Add link between dc and amdgpu glossary

Changes since V2:
 - Add MMHUB

Changes since V1:
 - Yann: Divide glossary based on driver context.
 - Alex: Make terms more consistent and update CPLIB
 - Add new acronyms to the glossary

Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
 Documentation/gpu/amdgpu/amdgpu-glossary.rst  |  87 +++++++
 .../gpu/amdgpu/display/dc-glossary.rst        | 237 ++++++++++++++++++
 Documentation/gpu/amdgpu/display/index.rst    |   1 +
 Documentation/gpu/amdgpu/index.rst            |   7 +
 4 files changed, 332 insertions(+)
 create mode 100644 Documentation/gpu/amdgpu/amdgpu-glossary.rst
 create mode 100644 Documentation/gpu/amdgpu/display/dc-glossary.rst

diff --git a/Documentation/gpu/amdgpu/amdgpu-glossary.rst b/Documentation/gpu/amdgpu/amdgpu-glossary.rst
new file mode 100644
index 000000000000..859dcec6c6f9
--- /dev/null
+++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst
@@ -0,0 +1,87 @@
+===============
+AMDGPU Glossary
+===============
+
+Here you can find some generic acronyms used in the amdgpu driver. Notice that
+we have a dedicated glossary for Display Core at
+'Documentation/gpu/amdgpu/display/dc-glossary.rst'.
+
+.. glossary::
+
+    CP
+      Command Processor
+
+    CPLIB
+      Content Protection Library
+
+    DFS
+      Digital Frequency Synthesizer
+
+    ECP
+      Enhanced Content Protection
+
+    EOP
+      End Of Pipe/Pipeline
+
+    GC
+      Graphics and Compute
+
+    GMC
+      Graphic Memory Controller
+
+    IH
+      Interrupt Handler
+
+    HQD
+      Hardware Queue Descriptor
+
+    IB
+      Indirect Buffer
+
+    IP
+        Intellectual Property blocks
+
+    KCQ
+      Kernel Compute Queue
+
+    KGQ
+      Kernel Graphics Queue
+
+    KIQ
+      Kernel Interface Queue
+
+    MEC
+      MicroEngine Compute
+
+    MES
+      MicroEngine Scheduler
+
+    MMHUB
+      Multi-Media HUB
+
+    MQD
+      Memory Queue Descriptor
+
+    PPLib
+      PowerPlay Library - PowerPlay is the power management component.
+
+    PSP
+        Platform Security Processor
+
+    RCL
+      RunList Controller
+
+    SDMA
+      System DMA
+
+    SMU
+      System Management Unit
+
+    SS
+      Spread Spectrum
+
+    VCE
+      Video Compression Engine
+
+    VCN
+      Video Codec Next
diff --git a/Documentation/gpu/amdgpu/display/dc-glossary.rst b/Documentation/gpu/amdgpu/display/dc-glossary.rst
new file mode 100644
index 000000000000..116f5f0942fd
--- /dev/null
+++ b/Documentation/gpu/amdgpu/display/dc-glossary.rst
@@ -0,0 +1,237 @@
+===========
+DC Glossary
+===========
+
+On this page, we try to keep track of acronyms related to the display
+component. If you do not find what you are looking for, look at the
+'Documentation/gpu/amdgpu/amdgpu-glossary.rst'; if you cannot find it anywhere,
+consider asking in the amdgfx and update this page.
+
+.. glossary::
+
+    ABM
+      Adaptive Backlight Modulation
+
+    APU
+      Accelerated Processing Unit
+
+    ASIC
+      Application-Specific Integrated Circuit
+
+    ASSR
+      Alternate Scrambler Seed Reset
+
+    AZ
+      Azalia (HD audio DMA engine)
+
+    BPC
+      Bits Per Colour/Component
+
+    BPP
+      Bits Per Pixel
+
+    Clocks
+      * PCLK: Pixel Clock
+      * SYMCLK: Symbol Clock
+      * SOCCLK: GPU Engine Clock
+      * DISPCLK: Display Clock
+      * DPPCLK: DPP Clock
+      * DCFCLK: Display Controller Fabric Clock
+      * REFCLK: Real Time Reference Clock
+      * PPLL: Pixel PLL
+      * FCLK: Fabric Clock
+      * MCLK: Memory Clock
+
+    CRC
+      Cyclic Redundancy Check
+
+    CRTC
+      Cathode Ray Tube Controller - commonly called "Controller" - Generates
+      raw stream of pixels, clocked at pixel clock
+
+    CVT
+      Coordinated Video Timings
+
+    DAL
+      Display Abstraction layer
+
+    DC (Software)
+      Display Core
+
+    DC (Hardware)
+      Display Controller
+
+    DCC
+      Delta Colour Compression
+
+    DCE
+      Display Controller Engine
+
+    DCHUB
+      Display Controller HUB
+
+    ARB
+      Arbiter
+
+    VTG
+      Vertical Timing Generator
+
+    DCN
+      Display Core Next
+
+    DCCG
+      Display Clock Generator block
+
+    DDC
+      Display Data Channel
+
+    DIO
+      Display IO
+
+    DPP
+      Display Pipes and Planes
+
+    DSC
+      Display Stream Compression (Reduce the amount of bits to represent pixel
+      count while at the same pixel clock)
+
+    dGPU
+      discrete GPU
+
+    DMIF
+      Display Memory Interface
+
+    DML
+      Display Mode Library
+
+    DMCU
+      Display Micro-Controller Unit
+
+    DMCUB
+      Display Micro-Controller Unit, version B
+
+    DPCD
+      DisplayPort Configuration Data
+
+    DPM(S)
+      Display Power Management (Signaling)
+
+    DRR
+      Dynamic Refresh Rate
+
+    DWB
+      Display Writeback
+
+    FB
+      Frame Buffer
+
+    FBC
+      Frame Buffer Compression
+
+    FEC
+      Forward Error Correction
+
+    FRL
+      Fixed Rate Link
+
+    GCO
+      Graphical Controller Object
+
+    GSL
+      Global Swap Lock
+
+    iGPU
+      integrated GPU
+
+    ISR
+      Interrupt Service Request
+
+    ISV
+      Independent Software Vendor
+
+    KMD
+      Kernel Mode Driver
+
+    LB
+      Line Buffer
+
+    LFC
+      Low Framerate Compensation
+
+    LTTPR
+      Link Training Tunable Phy Repeater
+
+    LUT
+      Lookup Table
+
+    MALL
+      Memory Access at Last Level
+
+    MC
+      Memory Controller
+
+    MPC
+      Multiple pipes and plane combine
+
+    MPO
+      Multi Plane Overlay
+
+    MST
+      Multi Stream Transport
+
+    NBP State
+      Northbridge Power State
+
+    NBIO
+      North Bridge Input/Output
+
+    ODM
+      Output Data Mapping
+
+    OPM
+      Output Protection Manager
+
+    OPP
+      Output Plane Processor
+
+    OPTC
+      Output Pipe Timing Combiner
+
+    OTG
+      Output Timing Generator
+
+    PCON
+      Power Controller
+
+    PGFSM
+      Power Gate Finite State Machine
+
+    PSR
+      Panel Self Refresh
+
+    SCL
+      Scaler
+
+    SDP
+      Scalable Data Port
+
+    SLS
+      Single Large Surface
+
+    SST
+      Single Stream Transport
+
+    TMDS
+      Transition-Minimized Differential Signaling
+
+    TMZ
+      Trusted Memory Zone
+
+    TTU
+      Time to Underflow
+
+    VRR
+      Variable Refresh Rate
+
+    UVD
+      Unified Video Decoder
diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst
index fe2ecad8df81..e23c752ee5f5 100644
--- a/Documentation/gpu/amdgpu/display/index.rst
+++ b/Documentation/gpu/amdgpu/display/index.rst
@@ -26,3 +26,4 @@ table of content:
    display-manager.rst
    dc-debug.rst
    dcn-overview.rst
+   dc-glossary.rst
diff --git a/Documentation/gpu/amdgpu/index.rst b/Documentation/gpu/amdgpu/index.rst
index 5c8cbf514097..ff38c360b04e 100644
--- a/Documentation/gpu/amdgpu/index.rst
+++ b/Documentation/gpu/amdgpu/index.rst
@@ -334,3 +334,10 @@ smartshift_bias
 
 .. kernel-doc:: drivers/gpu/drm/amd/pm/amdgpu_pm.c
    :doc: smartshift_bias
+
+AMDGPU Glossary
+===============
+
+.. toctree::
+
+   amdgpu-glossary.rst
-- 
2.25.1

Re: [PATCH v4 0/6] Expand display core documentation

[Harry Wentland]

Thanks for this. It's really good to see this.

Reviewed-by: Harry Wentland <harry.wentland@amd.com>

Harry

On 2021-12-09 09:20, Rodrigo Siqueira wrote:
> Display Core (DC) is one of the components under amdgpu, and it has
> multiple features directly related to the KMS API. Unfortunately, we
> don't have enough documentation about DC in the upstream, which makes
> the life of some external contributors a little bit more challenging.
> For these reasons, this patchset reworks part of the DC documentation
> and introduces a new set of details on how the display core works on DCN
> IP. Another improvement that this documentation effort tries to bring is
> making explicit some of our hardware-specific details to guide
> user-space developers better.
> 
> In my view, it is easier to review this series if you apply it in your
> local kernel and build the HTML version (make htmldocs). I'm suggesting
> this approach because I added a few SVG diagrams that will be easier to
> see in the HTML version. If you cannot build the documentation, try to
> open the SVG images while reviewing the content. In summary, in this
> series, you will find:
> 
> 1. Patch 1: Re-arrange of display core documentation. This is
>    preparation work for the other patches, but it is also a way to expand
>    this documentation.
> 2. Patch 2 to 4: Document some common debug options related to display.
> 3. Patch 5: This patch provides an overview of how our display core next
>    works and a brief explanation of each component.
> 4. Patch 6: We use a lot of acronyms in our driver; for this reason, we
>    exposed a glossary with common terms used by display core.
> 
> Please let us know what you think we can improve this series and what
> kind of content you want to see for the next series.
> 
> Changes since V3:
>  - Add new acronyms to amdgpu glossary
>  - Add link between dc and amdgpu glossary
> Changes since V2:
>  - Add a comment about MMHUBBUB
> Changes since V1:
>  - Group amdgpu documentation together.
>  - Create index pages.
>  - Mirror display folder in the documentation.
>  - Divide glossary based on driver context.
>  - Make terms more consistent and update CPLIB
>  - Add new acronyms to the glossary
> 
> Thanks
> Siqueira
> 
> Rodrigo Siqueira (6):
>   Documentation/gpu: Reorganize DC documentation
>   Documentation/gpu: Document amdgpu_dm_visual_confirm debugfs entry
>   Documentation/gpu: Document pipe split visual confirmation
>   Documentation/gpu: How to collect DTN log
>   Documentation/gpu: Add basic overview of DC pipeline
>   Documentation/gpu: Add amdgpu and dc glossary
> 
>  Documentation/gpu/amdgpu-dc.rst               |   74 --
>  Documentation/gpu/amdgpu/amdgpu-glossary.rst  |   87 ++
>  .../gpu/amdgpu/display/config_example.svg     |  414 ++++++
>  Documentation/gpu/amdgpu/display/dc-debug.rst |   77 ++
>  .../gpu/amdgpu/display/dc-glossary.rst        |  237 ++++
>  .../amdgpu/display/dc_pipeline_overview.svg   | 1125 +++++++++++++++++
>  .../gpu/amdgpu/display/dcn-overview.rst       |  171 +++
>  .../gpu/amdgpu/display/display-manager.rst    |   42 +
>  .../gpu/amdgpu/display/global_sync_vblank.svg |  485 +++++++
>  Documentation/gpu/amdgpu/display/index.rst    |   29 +
>  .../gpu/{amdgpu.rst => amdgpu/index.rst}      |   25 +-
>  Documentation/gpu/drivers.rst                 |    3 +-
>  12 files changed, 2690 insertions(+), 79 deletions(-)
>  delete mode 100644 Documentation/gpu/amdgpu-dc.rst
>  create mode 100644 Documentation/gpu/amdgpu/amdgpu-glossary.rst
>  create mode 100644 Documentation/gpu/amdgpu/display/config_example.svg
>  create mode 100644 Documentation/gpu/amdgpu/display/dc-debug.rst
>  create mode 100644 Documentation/gpu/amdgpu/display/dc-glossary.rst
>  create mode 100644 Documentation/gpu/amdgpu/display/dc_pipeline_overview.svg
>  create mode 100644 Documentation/gpu/amdgpu/display/dcn-overview.rst
>  create mode 100644 Documentation/gpu/amdgpu/display/display-manager.rst
>  create mode 100644 Documentation/gpu/amdgpu/display/global_sync_vblank.svg
>  create mode 100644 Documentation/gpu/amdgpu/display/index.rst
>  rename Documentation/gpu/{amdgpu.rst => amdgpu/index.rst} (95%)
> 

Re: [PATCH v4 0/6] Expand display core documentation

[Yann Dirson]

> Thanks for this. It's really good to see this.
> 
> Reviewed-by: Harry Wentland <harry.wentland@amd.com>

Hearfully seconded, let's get this rolling :)

Reviewed-by: Yann Dirson <ydirson@free.fr>

> 
> Harry
> 
> On 2021-12-09 09:20, Rodrigo Siqueira wrote:
> > Display Core (DC) is one of the components under amdgpu, and it has
> > multiple features directly related to the KMS API. Unfortunately,
> > we
> > don't have enough documentation about DC in the upstream, which
> > makes
> > the life of some external contributors a little bit more
> > challenging.
> > For these reasons, this patchset reworks part of the DC
> > documentation
> > and introduces a new set of details on how the display core works
> > on DCN
> > IP. Another improvement that this documentation effort tries to
> > bring is
> > making explicit some of our hardware-specific details to guide
> > user-space developers better.
> > 
> > In my view, it is easier to review this series if you apply it in
> > your
> > local kernel and build the HTML version (make htmldocs). I'm
> > suggesting
> > this approach because I added a few SVG diagrams that will be
> > easier to
> > see in the HTML version. If you cannot build the documentation, try
> > to
> > open the SVG images while reviewing the content. In summary, in
> > this
> > series, you will find:
> > 
> > 1. Patch 1: Re-arrange of display core documentation. This is
> >    preparation work for the other patches, but it is also a way to
> >    expand
> >    this documentation.
> > 2. Patch 2 to 4: Document some common debug options related to
> > display.
> > 3. Patch 5: This patch provides an overview of how our display core
> > next
> >    works and a brief explanation of each component.
> > 4. Patch 6: We use a lot of acronyms in our driver; for this
> > reason, we
> >    exposed a glossary with common terms used by display core.
> > 
> > Please let us know what you think we can improve this series and
> > what
> > kind of content you want to see for the next series.
> > 
> > Changes since V3:
> >  - Add new acronyms to amdgpu glossary
> >  - Add link between dc and amdgpu glossary
> > Changes since V2:
> >  - Add a comment about MMHUBBUB
> > Changes since V1:
> >  - Group amdgpu documentation together.
> >  - Create index pages.
> >  - Mirror display folder in the documentation.
> >  - Divide glossary based on driver context.
> >  - Make terms more consistent and update CPLIB
> >  - Add new acronyms to the glossary
> > 
> > Thanks
> > Siqueira
> > 
> > Rodrigo Siqueira (6):
> >   Documentation/gpu: Reorganize DC documentation
> >   Documentation/gpu: Document amdgpu_dm_visual_confirm debugfs
> >   entry
> >   Documentation/gpu: Document pipe split visual confirmation
> >   Documentation/gpu: How to collect DTN log
> >   Documentation/gpu: Add basic overview of DC pipeline
> >   Documentation/gpu: Add amdgpu and dc glossary
> > 
> >  Documentation/gpu/amdgpu-dc.rst               |   74 --
> >  Documentation/gpu/amdgpu/amdgpu-glossary.rst  |   87 ++
> >  .../gpu/amdgpu/display/config_example.svg     |  414 ++++++
> >  Documentation/gpu/amdgpu/display/dc-debug.rst |   77 ++
> >  .../gpu/amdgpu/display/dc-glossary.rst        |  237 ++++
> >  .../amdgpu/display/dc_pipeline_overview.svg   | 1125
> >  +++++++++++++++++
> >  .../gpu/amdgpu/display/dcn-overview.rst       |  171 +++
> >  .../gpu/amdgpu/display/display-manager.rst    |   42 +
> >  .../gpu/amdgpu/display/global_sync_vblank.svg |  485 +++++++
> >  Documentation/gpu/amdgpu/display/index.rst    |   29 +
> >  .../gpu/{amdgpu.rst => amdgpu/index.rst}      |   25 +-
> >  Documentation/gpu/drivers.rst                 |    3 +-
> >  12 files changed, 2690 insertions(+), 79 deletions(-)
> >  delete mode 100644 Documentation/gpu/amdgpu-dc.rst
> >  create mode 100644 Documentation/gpu/amdgpu/amdgpu-glossary.rst
> >  create mode 100644
> >  Documentation/gpu/amdgpu/display/config_example.svg
> >  create mode 100644 Documentation/gpu/amdgpu/display/dc-debug.rst
> >  create mode 100644
> >  Documentation/gpu/amdgpu/display/dc-glossary.rst
> >  create mode 100644
> >  Documentation/gpu/amdgpu/display/dc_pipeline_overview.svg
> >  create mode 100644
> >  Documentation/gpu/amdgpu/display/dcn-overview.rst
> >  create mode 100644
> >  Documentation/gpu/amdgpu/display/display-manager.rst
> >  create mode 100644
> >  Documentation/gpu/amdgpu/display/global_sync_vblank.svg
> >  create mode 100644 Documentation/gpu/amdgpu/display/index.rst
> >  rename Documentation/gpu/{amdgpu.rst => amdgpu/index.rst} (95%)
> > 
> 
> 

Re: [PATCH v4 0/6] Expand display core documentation

[Rodrigo Siqueira Jordao]

On 2021-12-09 4:04 p.m., Yann Dirson wrote:
> 
>> Thanks for this. It's really good to see this.
>>
>> Reviewed-by: Harry Wentland <harry.wentland@amd.com>
> 
> Hearfully seconded, let's get this rolling :)
> 
> Reviewed-by: Yann Dirson <ydirson@free.fr>

Series applied to amd-staging-drm-next

Thanks a lot!

>>
>> Harry
>>
>> On 2021-12-09 09:20, Rodrigo Siqueira wrote:
>>> Display Core (DC) is one of the components under amdgpu, and it has
>>> multiple features directly related to the KMS API. Unfortunately,
>>> we
>>> don't have enough documentation about DC in the upstream, which
>>> makes
>>> the life of some external contributors a little bit more
>>> challenging.
>>> For these reasons, this patchset reworks part of the DC
>>> documentation
>>> and introduces a new set of details on how the display core works
>>> on DCN
>>> IP. Another improvement that this documentation effort tries to
>>> bring is
>>> making explicit some of our hardware-specific details to guide
>>> user-space developers better.
>>>
>>> In my view, it is easier to review this series if you apply it in
>>> your
>>> local kernel and build the HTML version (make htmldocs). I'm
>>> suggesting
>>> this approach because I added a few SVG diagrams that will be
>>> easier to
>>> see in the HTML version. If you cannot build the documentation, try
>>> to
>>> open the SVG images while reviewing the content. In summary, in
>>> this
>>> series, you will find:
>>>
>>> 1. Patch 1: Re-arrange of display core documentation. This is
>>>     preparation work for the other patches, but it is also a way to
>>>     expand
>>>     this documentation.
>>> 2. Patch 2 to 4: Document some common debug options related to
>>> display.
>>> 3. Patch 5: This patch provides an overview of how our display core
>>> next
>>>     works and a brief explanation of each component.
>>> 4. Patch 6: We use a lot of acronyms in our driver; for this
>>> reason, we
>>>     exposed a glossary with common terms used by display core.
>>>
>>> Please let us know what you think we can improve this series and
>>> what
>>> kind of content you want to see for the next series.
>>>
>>> Changes since V3:
>>>   - Add new acronyms to amdgpu glossary
>>>   - Add link between dc and amdgpu glossary
>>> Changes since V2:
>>>   - Add a comment about MMHUBBUB
>>> Changes since V1:
>>>   - Group amdgpu documentation together.
>>>   - Create index pages.
>>>   - Mirror display folder in the documentation.
>>>   - Divide glossary based on driver context.
>>>   - Make terms more consistent and update CPLIB
>>>   - Add new acronyms to the glossary
>>>
>>> Thanks
>>> Siqueira
>>>
>>> Rodrigo Siqueira (6):
>>>    Documentation/gpu: Reorganize DC documentation
>>>    Documentation/gpu: Document amdgpu_dm_visual_confirm debugfs
>>>    entry
>>>    Documentation/gpu: Document pipe split visual confirmation
>>>    Documentation/gpu: How to collect DTN log
>>>    Documentation/gpu: Add basic overview of DC pipeline
>>>    Documentation/gpu: Add amdgpu and dc glossary
>>>
>>>   Documentation/gpu/amdgpu-dc.rst               |   74 --
>>>   Documentation/gpu/amdgpu/amdgpu-glossary.rst  |   87 ++
>>>   .../gpu/amdgpu/display/config_example.svg     |  414 ++++++
>>>   Documentation/gpu/amdgpu/display/dc-debug.rst |   77 ++
>>>   .../gpu/amdgpu/display/dc-glossary.rst        |  237 ++++
>>>   .../amdgpu/display/dc_pipeline_overview.svg   | 1125
>>>   +++++++++++++++++
>>>   .../gpu/amdgpu/display/dcn-overview.rst       |  171 +++
>>>   .../gpu/amdgpu/display/display-manager.rst    |   42 +
>>>   .../gpu/amdgpu/display/global_sync_vblank.svg |  485 +++++++
>>>   Documentation/gpu/amdgpu/display/index.rst    |   29 +
>>>   .../gpu/{amdgpu.rst => amdgpu/index.rst}      |   25 +-
>>>   Documentation/gpu/drivers.rst                 |    3 +-
>>>   12 files changed, 2690 insertions(+), 79 deletions(-)
>>>   delete mode 100644 Documentation/gpu/amdgpu-dc.rst
>>>   create mode 100644 Documentation/gpu/amdgpu/amdgpu-glossary.rst
>>>   create mode 100644
>>>   Documentation/gpu/amdgpu/display/config_example.svg
>>>   create mode 100644 Documentation/gpu/amdgpu/display/dc-debug.rst
>>>   create mode 100644
>>>   Documentation/gpu/amdgpu/display/dc-glossary.rst
>>>   create mode 100644
>>>   Documentation/gpu/amdgpu/display/dc_pipeline_overview.svg
>>>   create mode 100644
>>>   Documentation/gpu/amdgpu/display/dcn-overview.rst
>>>   create mode 100644
>>>   Documentation/gpu/amdgpu/display/display-manager.rst
>>>   create mode 100644
>>>   Documentation/gpu/amdgpu/display/global_sync_vblank.svg
>>>   create mode 100644 Documentation/gpu/amdgpu/display/index.rst
>>>   rename Documentation/gpu/{amdgpu.rst => amdgpu/index.rst} (95%)
>>>
>>
>>