[PATCH v2 0/6] Expand display core documentation

[PATCH v2 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 in this series and what
kind of content you want to see for the next series.

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  |   47 +
 .../gpu/amdgpu/display/config_example.svg     |  414 ++++++
 Documentation/gpu/amdgpu/display/dc-debug.rst |   77 ++
 .../gpu/amdgpu/display/dc-glossary.rst        |  243 ++++
 .../amdgpu/display/dc_pipeline_overview.svg   | 1125 +++++++++++++++++
 .../gpu/amdgpu/display/dcn-overview.rst       |  168 +++
 .../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, 2653 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 v2 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 v2 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 v2 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 v2 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 v2 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 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  |  47 ++++
 .../gpu/amdgpu/display/dc-glossary.rst        | 243 ++++++++++++++++++
 Documentation/gpu/amdgpu/display/index.rst    |   1 +
 Documentation/gpu/amdgpu/index.rst            |   7 +
 4 files changed, 298 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..e635851025e7
--- /dev/null
+++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst
@@ -0,0 +1,47 @@
+===============
+AMDGPU Glossary
+===============
+
+Here you can find some generic acronyms used in the amdgpu driver. Notice that
+we have a dedicated glossary for Display Core.
+
+.. glossary::
+
+    CPLIB
+      Content Protection Library
+
+    DFS
+      Digital Frequency Synthesizer
+
+    ECP
+      Enhanced Content Protection
+
+    EOP
+      End Of Pipe/Pipeline
+
+    HQD
+      Hardware Queue Descriptor
+
+    KCQ
+      Kernel Compute Queue
+
+    KGQ
+      Kernel Graphics Queue
+
+    KIQ
+      Kernel Interface Queue
+
+    MQD
+      Memory Queue Descriptor
+
+    PPLib
+      PowerPlay Library - PowerPlay is the power management component.
+
+    SMU
+      System Management Unit
+
+    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..547c0bfbb3e2
--- /dev/null
+++ b/Documentation/gpu/amdgpu/display/dc-glossary.rst
@@ -0,0 +1,243 @@
+===========
+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 amdgpu
+glossary; 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
+
+    GMC
+      Graphic Memory Controller
+
+    GSL
+      Global Swap Lock
+
+    iGPU
+      integrated GPU
+
+    IH
+      Interrupt Handler
+
+    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 v2 6/6] Documentation/gpu: Add amdgpu and dc glossary

[Daniel Vetter]

On Thu, Dec 02, 2021 at 11:01:32AM -0500, Rodrigo Siqueira wrote:
> 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 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  |  47 ++++
>  .../gpu/amdgpu/display/dc-glossary.rst        | 243 ++++++++++++++++++
>  Documentation/gpu/amdgpu/display/index.rst    |   1 +
>  Documentation/gpu/amdgpu/index.rst            |   7 +
>  4 files changed, 298 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..e635851025e7
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst
> @@ -0,0 +1,47 @@
> +===============
> +AMDGPU Glossary
> +===============
> +
> +Here you can find some generic acronyms used in the amdgpu driver. Notice that
> +we have a dedicated glossary for Display Core.

Maybe add a link to that here so it's easier to find? sphinx autogenerates
header targets so pretty easy (if the heading is unique at least).
-Daniel

> +
> +.. glossary::
> +
> +    CPLIB
> +      Content Protection Library
> +
> +    DFS
> +      Digital Frequency Synthesizer
> +
> +    ECP
> +      Enhanced Content Protection
> +
> +    EOP
> +      End Of Pipe/Pipeline
> +
> +    HQD
> +      Hardware Queue Descriptor
> +
> +    KCQ
> +      Kernel Compute Queue
> +
> +    KGQ
> +      Kernel Graphics Queue
> +
> +    KIQ
> +      Kernel Interface Queue
> +
> +    MQD
> +      Memory Queue Descriptor
> +
> +    PPLib
> +      PowerPlay Library - PowerPlay is the power management component.
> +
> +    SMU
> +      System Management Unit
> +
> +    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..547c0bfbb3e2
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu/display/dc-glossary.rst
> @@ -0,0 +1,243 @@
> +===========
> +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 amdgpu
> +glossary; 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
> +
> +    GMC
> +      Graphic Memory Controller
> +
> +    GSL
> +      Global Swap Lock
> +
> +    iGPU
> +      integrated GPU
> +
> +    IH
> +      Interrupt Handler
> +
> +    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
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

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

[Yann Dirson]

> On Thu, Dec 02, 2021 at 11:01:32AM -0500, Rodrigo Siqueira wrote:
> > 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 V1:
> >  - Yann: Divide glossary based on driver context.
> >  - Alex: Make terms more consistent and update CPLIB
> >  - Add new acronyms to the glossary

If you're rerolling, it could be a good time to include the additional
(and detailed) entries from Alex's answer to "Looking for clarifications
around gfx/kcq/kiq".  Finding a way to fit the other details not
fitting directly in the glossary will likely take more rounds, though,
so we can wait for the first round to be merged before dealing with them.



> > 
> > Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> > ---
> >  Documentation/gpu/amdgpu/amdgpu-glossary.rst  |  47 ++++
> >  .../gpu/amdgpu/display/dc-glossary.rst        | 243
> >  ++++++++++++++++++
> >  Documentation/gpu/amdgpu/display/index.rst    |   1 +
> >  Documentation/gpu/amdgpu/index.rst            |   7 +
> >  4 files changed, 298 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..e635851025e7
> > --- /dev/null
> > +++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst
> > @@ -0,0 +1,47 @@
> > +===============
> > +AMDGPU Glossary
> > +===============
> > +
> > +Here you can find some generic acronyms used in the amdgpu driver.
> > Notice that
> > +we have a dedicated glossary for Display Core.
> 
> Maybe add a link to that here so it's easier to find? sphinx
> autogenerates
> header targets so pretty easy (if the heading is unique at least).
> -Daniel
> 
> > +
> > +.. glossary::
> > +
> > +    CPLIB
> > +      Content Protection Library
> > +
> > +    DFS
> > +      Digital Frequency Synthesizer
> > +
> > +    ECP
> > +      Enhanced Content Protection
> > +
> > +    EOP
> > +      End Of Pipe/Pipeline
> > +
> > +    HQD
> > +      Hardware Queue Descriptor
> > +
> > +    KCQ
> > +      Kernel Compute Queue
> > +
> > +    KGQ
> > +      Kernel Graphics Queue
> > +
> > +    KIQ
> > +      Kernel Interface Queue
> > +
> > +    MQD
> > +      Memory Queue Descriptor
> > +
> > +    PPLib
> > +      PowerPlay Library - PowerPlay is the power management
> > component.
> > +
> > +    SMU
> > +      System Management Unit
> > +
> > +    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..547c0bfbb3e2
> > --- /dev/null
> > +++ b/Documentation/gpu/amdgpu/display/dc-glossary.rst
> > @@ -0,0 +1,243 @@
> > +===========
> > +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 amdgpu
> > +glossary; 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
> > +
> > +    GMC
> > +      Graphic Memory Controller
> > +
> > +    GSL
> > +      Global Swap Lock
> > +
> > +    iGPU
> > +      integrated GPU
> > +
> > +    IH
> > +      Interrupt Handler
> > +
> > +    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
> > 
> 
> --
> Daniel Vetter
> Software Engineer, Intel Corporation
> http://blog.ffwll.ch
> 

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

[Rodrigo Siqueira Jordao]

On 2021-12-07 2:49 p.m., Yann Dirson wrote:
> 
>> On Thu, Dec 02, 2021 at 11:01:32AM -0500, Rodrigo Siqueira wrote:
>>> 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 V1:
>>>   - Yann: Divide glossary based on driver context.
>>>   - Alex: Make terms more consistent and update CPLIB
>>>   - Add new acronyms to the glossary
> 
> If you're rerolling, it could be a good time to include the additional
> (and detailed) entries from Alex's answer to "Looking for clarifications
> around gfx/kcq/kiq".  Finding a way to fit the other details not
> fitting directly in the glossary will likely take more rounds, though,
> so we can wait for the first round to be merged before dealing with them.

Hi Yann,

I will send another version to address Daniel's comment, and I'll also 
expand the amdgpu acronyms glossary based on your mail thread with Alex. 
However, I don't want to add more details about that discussion in this 
series because I don't want to lose focus in this patchset since my main 
goal is to start to expand display documentation.

By the way, I think you could consider writing a kernel-doc based on 
your discussion with Alex. This way, you can try to consolidate what you 
discover and get reviews in the content.

Thanks
Siqueira

> 
> 
>>>
>>> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
>>> ---
>>>   Documentation/gpu/amdgpu/amdgpu-glossary.rst  |  47 ++++
>>>   .../gpu/amdgpu/display/dc-glossary.rst        | 243
>>>   ++++++++++++++++++
>>>   Documentation/gpu/amdgpu/display/index.rst    |   1 +
>>>   Documentation/gpu/amdgpu/index.rst            |   7 +
>>>   4 files changed, 298 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..e635851025e7
>>> --- /dev/null
>>> +++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst
>>> @@ -0,0 +1,47 @@
>>> +===============
>>> +AMDGPU Glossary
>>> +===============
>>> +
>>> +Here you can find some generic acronyms used in the amdgpu driver.
>>> Notice that
>>> +we have a dedicated glossary for Display Core.
>>
>> Maybe add a link to that here so it's easier to find? sphinx
>> autogenerates
>> header targets so pretty easy (if the heading is unique at least).
>> -Daniel
>>
>>> +
>>> +.. glossary::
>>> +
>>> +    CPLIB
>>> +      Content Protection Library
>>> +
>>> +    DFS
>>> +      Digital Frequency Synthesizer
>>> +
>>> +    ECP
>>> +      Enhanced Content Protection
>>> +
>>> +    EOP
>>> +      End Of Pipe/Pipeline
>>> +
>>> +    HQD
>>> +      Hardware Queue Descriptor
>>> +
>>> +    KCQ
>>> +      Kernel Compute Queue
>>> +
>>> +    KGQ
>>> +      Kernel Graphics Queue
>>> +
>>> +    KIQ
>>> +      Kernel Interface Queue
>>> +
>>> +    MQD
>>> +      Memory Queue Descriptor
>>> +
>>> +    PPLib
>>> +      PowerPlay Library - PowerPlay is the power management
>>> component.
>>> +
>>> +    SMU
>>> +      System Management Unit
>>> +
>>> +    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..547c0bfbb3e2
>>> --- /dev/null
>>> +++ b/Documentation/gpu/amdgpu/display/dc-glossary.rst
>>> @@ -0,0 +1,243 @@
>>> +===========
>>> +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 amdgpu
>>> +glossary; 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
>>> +
>>> +    GMC
>>> +      Graphic Memory Controller
>>> +
>>> +    GSL
>>> +      Global Swap Lock
>>> +
>>> +    iGPU
>>> +      integrated GPU
>>> +
>>> +    IH
>>> +      Interrupt Handler
>>> +
>>> +    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
>>>
>>
>> --
>> Daniel Vetter
>> Software Engineer, Intel Corporation
>> http://blog.ffwll.ch/>>>

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

[Yann Dirson]

Hi Rodrigo,

> On 2021-12-07 2:49 p.m., Yann Dirson wrote:
> > 
> >> On Thu, Dec 02, 2021 at 11:01:32AM -0500, Rodrigo Siqueira wrote:
> >>> 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 V1:
> >>>   - Yann: Divide glossary based on driver context.
> >>>   - Alex: Make terms more consistent and update CPLIB
> >>>   - Add new acronyms to the glossary
> > 
> > If you're rerolling, it could be a good time to include the
> > additional
> > (and detailed) entries from Alex's answer to "Looking for
> > clarifications
> > around gfx/kcq/kiq".  Finding a way to fit the other details not
> > fitting directly in the glossary will likely take more rounds,
> > though,
> > so we can wait for the first round to be merged before dealing with
> > them.
> 
> Hi Yann,
> 
> I will send another version to address Daniel's comment, and I'll
> also
> expand the amdgpu acronyms glossary based on your mail thread with
> Alex.
> However, I don't want to add more details about that discussion in
> this
> series because I don't want to lose focus in this patchset since my
> main
> goal is to start to expand display documentation.

fair enough


> By the way, I think you could consider writing a kernel-doc based on
> your discussion with Alex. This way, you can try to consolidate what
> you
> discover and get reviews in the content.

that's the idea, though I'm not sure I have enough material to start with
yet :)

> 
> Thanks
> Siqueira
> 
> > 
> > 
> >>>
> >>> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> >>> ---
> >>>   Documentation/gpu/amdgpu/amdgpu-glossary.rst  |  47 ++++
> >>>   .../gpu/amdgpu/display/dc-glossary.rst        | 243
> >>>   ++++++++++++++++++
> >>>   Documentation/gpu/amdgpu/display/index.rst    |   1 +
> >>>   Documentation/gpu/amdgpu/index.rst            |   7 +
> >>>   4 files changed, 298 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..e635851025e7
> >>> --- /dev/null
> >>> +++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst
> >>> @@ -0,0 +1,47 @@
> >>> +===============
> >>> +AMDGPU Glossary
> >>> +===============
> >>> +
> >>> +Here you can find some generic acronyms used in the amdgpu
> >>> driver.
> >>> Notice that
> >>> +we have a dedicated glossary for Display Core.
> >>
> >> Maybe add a link to that here so it's easier to find? sphinx
> >> autogenerates
> >> header targets so pretty easy (if the heading is unique at least).
> >> -Daniel
> >>
> >>> +
> >>> +.. glossary::
> >>> +
> >>> +    CPLIB
> >>> +      Content Protection Library
> >>> +
> >>> +    DFS
> >>> +      Digital Frequency Synthesizer
> >>> +
> >>> +    ECP
> >>> +      Enhanced Content Protection
> >>> +
> >>> +    EOP
> >>> +      End Of Pipe/Pipeline
> >>> +
> >>> +    HQD
> >>> +      Hardware Queue Descriptor
> >>> +
> >>> +    KCQ
> >>> +      Kernel Compute Queue
> >>> +
> >>> +    KGQ
> >>> +      Kernel Graphics Queue
> >>> +
> >>> +    KIQ
> >>> +      Kernel Interface Queue
> >>> +
> >>> +    MQD
> >>> +      Memory Queue Descriptor
> >>> +
> >>> +    PPLib
> >>> +      PowerPlay Library - PowerPlay is the power management
> >>> component.
> >>> +
> >>> +    SMU
> >>> +      System Management Unit
> >>> +
> >>> +    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..547c0bfbb3e2
> >>> --- /dev/null
> >>> +++ b/Documentation/gpu/amdgpu/display/dc-glossary.rst
> >>> @@ -0,0 +1,243 @@
> >>> +===========
> >>> +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 amdgpu
> >>> +glossary; 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
> >>> +
> >>> +    GMC
> >>> +      Graphic Memory Controller
> >>> +
> >>> +    GSL
> >>> +      Global Swap Lock
> >>> +
> >>> +    iGPU
> >>> +      integrated GPU
> >>> +
> >>> +    IH
> >>> +      Interrupt Handler
> >>> +
> >>> +    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
> >>>
> >>
> >> --
> >> Daniel Vetter
> >> Software Engineer, Intel Corporation
> >> http://blog.ffwll.ch/>>>
> 
> 

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

[Rodrigo Siqueira Jordao]

On 2021-12-08 11:16 a.m., Yann Dirson wrote:
> Hi Rodrigo,
> 
>> On 2021-12-07 2:49 p.m., Yann Dirson wrote:
>>>
>>>> On Thu, Dec 02, 2021 at 11:01:32AM -0500, Rodrigo Siqueira wrote:
>>>>> 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 V1:
>>>>>    - Yann: Divide glossary based on driver context.
>>>>>    - Alex: Make terms more consistent and update CPLIB
>>>>>    - Add new acronyms to the glossary
>>>
>>> If you're rerolling, it could be a good time to include the
>>> additional
>>> (and detailed) entries from Alex's answer to "Looking for
>>> clarifications
>>> around gfx/kcq/kiq".  Finding a way to fit the other details not
>>> fitting directly in the glossary will likely take more rounds,
>>> though,
>>> so we can wait for the first round to be merged before dealing with
>>> them.
>>
>> Hi Yann,
>>
>> I will send another version to address Daniel's comment, and I'll
>> also
>> expand the amdgpu acronyms glossary based on your mail thread with
>> Alex.
>> However, I don't want to add more details about that discussion in
>> this
>> series because I don't want to lose focus in this patchset since my
>> main
>> goal is to start to expand display documentation.
> 
> fair enough
> 
> 
>> By the way, I think you could consider writing a kernel-doc based on
>> your discussion with Alex. This way, you can try to consolidate what
>> you
>> discover and get reviews in the content.
> 
> that's the idea, though I'm not sure I have enough material to start with
> yet :)

As you know, right now, we have zero documentation about that, which 
means that if you add something, it is an excellent improvement in the 
current status :)

>>
>> Thanks
>> Siqueira
>>
>>>
>>>
>>>>>
>>>>> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
>>>>> ---
>>>>>    Documentation/gpu/amdgpu/amdgpu-glossary.rst  |  47 ++++
>>>>>    .../gpu/amdgpu/display/dc-glossary.rst        | 243
>>>>>    ++++++++++++++++++
>>>>>    Documentation/gpu/amdgpu/display/index.rst    |   1 +
>>>>>    Documentation/gpu/amdgpu/index.rst            |   7 +
>>>>>    4 files changed, 298 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..e635851025e7
>>>>> --- /dev/null
>>>>> +++ b/Documentation/gpu/amdgpu/amdgpu-glossary.rst
>>>>> @@ -0,0 +1,47 @@
>>>>> +===============
>>>>> +AMDGPU Glossary
>>>>> +===============
>>>>> +
>>>>> +Here you can find some generic acronyms used in the amdgpu
>>>>> driver.
>>>>> Notice that
>>>>> +we have a dedicated glossary for Display Core.
>>>>
>>>> Maybe add a link to that here so it's easier to find? sphinx
>>>> autogenerates
>>>> header targets so pretty easy (if the heading is unique at least).
>>>> -Daniel
>>>>
>>>>> +
>>>>> +.. glossary::
>>>>> +
>>>>> +    CPLIB
>>>>> +      Content Protection Library
>>>>> +
>>>>> +    DFS
>>>>> +      Digital Frequency Synthesizer
>>>>> +
>>>>> +    ECP
>>>>> +      Enhanced Content Protection
>>>>> +
>>>>> +    EOP
>>>>> +      End Of Pipe/Pipeline
>>>>> +
>>>>> +    HQD
>>>>> +      Hardware Queue Descriptor
>>>>> +
>>>>> +    KCQ
>>>>> +      Kernel Compute Queue
>>>>> +
>>>>> +    KGQ
>>>>> +      Kernel Graphics Queue
>>>>> +
>>>>> +    KIQ
>>>>> +      Kernel Interface Queue
>>>>> +
>>>>> +    MQD
>>>>> +      Memory Queue Descriptor
>>>>> +
>>>>> +    PPLib
>>>>> +      PowerPlay Library - PowerPlay is the power management
>>>>> component.
>>>>> +
>>>>> +    SMU
>>>>> +      System Management Unit
>>>>> +
>>>>> +    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..547c0bfbb3e2
>>>>> --- /dev/null
>>>>> +++ b/Documentation/gpu/amdgpu/display/dc-glossary.rst
>>>>> @@ -0,0 +1,243 @@
>>>>> +===========
>>>>> +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 amdgpu
>>>>> +glossary; 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
>>>>> +
>>>>> +    GMC
>>>>> +      Graphic Memory Controller
>>>>> +
>>>>> +    GSL
>>>>> +      Global Swap Lock
>>>>> +
>>>>> +    iGPU
>>>>> +      integrated GPU
>>>>> +
>>>>> +    IH
>>>>> +      Interrupt Handler
>>>>> +
>>>>> +    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
>>>>>
>>>>
>>>> --
>>>> Daniel Vetter
>>>> Software Engineer, Intel Corporation
>>>> http://blog.ffwll.ch/>>>
>>