[PATCH 0/6] Expand display core documentation

[PATCH 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.

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 DC glossary

 Documentation/gpu/amdgpu-dc.rst               |   74 --
 .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |   77 ++
 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     |   29 +
 .../gpu/amdgpu-dc/amdgpu-dcn-overview.rst     |  168 +++
 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     |   42 +
 .../gpu/amdgpu-dc/config_example.svg          |  414 ++++++
 Documentation/gpu/amdgpu-dc/dc-glossary.rst   |  257 ++++
 .../gpu/amdgpu-dc/dc_pipeline_overview.svg    | 1125 +++++++++++++++++
 .../gpu/amdgpu-dc/global_sync_vblank.svg      |  485 +++++++
 Documentation/gpu/drivers.rst                 |    2 +-
 10 files changed, 2598 insertions(+), 75 deletions(-)
 delete mode 100644 Documentation/gpu/amdgpu-dc.rst
 create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
 create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
 create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dcn-overview.rst
 create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
 create mode 100644 Documentation/gpu/amdgpu-dc/config_example.svg
 create mode 100644 Documentation/gpu/amdgpu-dc/dc-glossary.rst
 create mode 100644 Documentation/gpu/amdgpu-dc/dc_pipeline_overview.svg
 create mode 100644 Documentation/gpu/amdgpu-dc/global_sync_vblank.svg

-- 
2.25.1

[PATCH 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.

Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
 Documentation/gpu/amdgpu-dc.rst               | 74 -------------------
 .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |  4 +
 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     | 29 ++++++++
 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     | 42 +++++++++++
 Documentation/gpu/drivers.rst                 |  2 +-
 5 files changed, 76 insertions(+), 75 deletions(-)
 delete mode 100644 Documentation/gpu/amdgpu-dc.rst
 create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
 create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
 create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst

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-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
new file mode 100644
index 000000000000..bbb8c3fc8eee
--- /dev/null
+++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
@@ -0,0 +1,4 @@
+Display Core Debug tools
+========================
+
+TODO
diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
new file mode 100644
index 000000000000..3685b3b1ad64
--- /dev/null
+++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.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::
+
+   amdgpu-dm.rst
+   amdgpu-dc-debug.rst
+
+``Display Core initialized with <version number here>``
diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dm.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
new file mode 100644
index 000000000000..7ce31f89d9a0
--- /dev/null
+++ b/Documentation/gpu/amdgpu-dc/amdgpu-dm.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/drivers.rst b/Documentation/gpu/drivers.rst
index b4a0ed3ca961..dffe52d837cd 100644
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -5,7 +5,7 @@ GPU Driver Documentation
 .. toctree::
 
    amdgpu
-   amdgpu-dc
+   amdgpu-dc/amdgpu-dc
    i915
    mcde
    meson
-- 
2.25.1

[PATCH 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>
---
 .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         | 34 ++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
index bbb8c3fc8eee..532cbbd64863 100644
--- a/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
+++ b/Documentation/gpu/amdgpu-dc/amdgpu-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 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>
---
 .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         | 28 +++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
index 532cbbd64863..6dbd21f7f59e 100644
--- a/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
+++ b/Documentation/gpu/amdgpu-dc/amdgpu-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 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-dc/amdgpu-dc-debug.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
index 6dbd21f7f59e..40c55a618918 100644
--- a/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
+++ b/Documentation/gpu/amdgpu-dc/amdgpu-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 6/6] Documentation/gpu: Add DC glossary

[Rodrigo Siqueira]

In the DC driver, we have multiple acronyms that are not obvious most of
the time. This commit introduces a DC glossary in order to make it
easier to navigate through our driver.

Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst   |   2 +-
 Documentation/gpu/amdgpu-dc/dc-glossary.rst | 257 ++++++++++++++++++++
 2 files changed, 258 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/gpu/amdgpu-dc/dc-glossary.rst

diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
index 2e45e83d9a2a..15405c43786a 100644
--- a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
+++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
@@ -26,4 +26,4 @@ table of content:
    amdgpu-dcn-overview.rst
    amdgpu-dm.rst
    amdgpu-dc-debug.rst
-
+   dc-glossary.rst
diff --git a/Documentation/gpu/amdgpu-dc/dc-glossary.rst b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
new file mode 100644
index 000000000000..48698fc1799f
--- /dev/null
+++ b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
@@ -0,0 +1,257 @@
+===========
+DC Glossary
+===========
+
+.. 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
+      * CPLIB: Content Protection Library
+
+    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
+
+    DFS
+      Digital Frequency Synthesizer
+
+    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
+
+    ECP
+      Enhanced Content Protection
+
+    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
+
+    PPLib
+      PowerPlay Library
+
+    PSR
+      Panel Self Refresh
+
+    SCL
+      Scaler
+
+    SDP
+      Scalable Data Port
+
+    SMU
+      System Management Unit
+
+    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
+
+    VCE
+      Video Compression Engine
+
+    VCN
+      Video Codec Next
-- 
2.25.1

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

[Christian König]

Just a general comment. Could you name the new subdirectory "amdgpu" 
instead?

DC is just a component of the amdgpu driver and I think it would sooner 
or later make sense to group together the amdgpu documentation in one 
folder.

Regards,
Christian.

Am 25.11.21 um 16:38 schrieb 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.
>
> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> ---
>   Documentation/gpu/amdgpu-dc.rst               | 74 -------------------
>   .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |  4 +
>   Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     | 29 ++++++++
>   Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     | 42 +++++++++++
>   Documentation/gpu/drivers.rst                 |  2 +-
>   5 files changed, 76 insertions(+), 75 deletions(-)
>   delete mode 100644 Documentation/gpu/amdgpu-dc.rst
>   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
>
> 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-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
> new file mode 100644
> index 000000000000..bbb8c3fc8eee
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
> @@ -0,0 +1,4 @@
> +Display Core Debug tools
> +========================
> +
> +TODO
> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> new file mode 100644
> index 000000000000..3685b3b1ad64
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.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::
> +
> +   amdgpu-dm.rst
> +   amdgpu-dc-debug.rst
> +
> +``Display Core initialized with <version number here>``
> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dm.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
> new file mode 100644
> index 000000000000..7ce31f89d9a0
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dm.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/drivers.rst b/Documentation/gpu/drivers.rst
> index b4a0ed3ca961..dffe52d837cd 100644
> --- a/Documentation/gpu/drivers.rst
> +++ b/Documentation/gpu/drivers.rst
> @@ -5,7 +5,7 @@ GPU Driver Documentation
>   .. toctree::
>   
>      amdgpu
> -   amdgpu-dc
> +   amdgpu-dc/amdgpu-dc
>      i915
>      mcde
>      meson

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

[Daniel Vetter]

On Fri, Nov 26, 2021 at 11:35:03AM +0100, Christian König wrote:
> Just a general comment. Could you name the new subdirectory "amdgpu"
> instead?
> 
> DC is just a component of the amdgpu driver and I think it would sooner or
> later make sense to group together the amdgpu documentation in one folder.

Seconded, I think when driver docs get too big for the single file
approach a directory matching the driver name sounds best. Also at that
point maybe just drop the amdgpu prefix in the .rst files, it's kinda
redundant?
-Daniel

> 
> Regards,
> Christian.
> 
> Am 25.11.21 um 16:38 schrieb 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.
> > 
> > Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> > ---
> >   Documentation/gpu/amdgpu-dc.rst               | 74 -------------------
> >   .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |  4 +
> >   Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     | 29 ++++++++
> >   Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     | 42 +++++++++++
> >   Documentation/gpu/drivers.rst                 |  2 +-
> >   5 files changed, 76 insertions(+), 75 deletions(-)
> >   delete mode 100644 Documentation/gpu/amdgpu-dc.rst
> >   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
> >   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> >   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
> > 
> > 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-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
> > new file mode 100644
> > index 000000000000..bbb8c3fc8eee
> > --- /dev/null
> > +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
> > @@ -0,0 +1,4 @@
> > +Display Core Debug tools
> > +========================
> > +
> > +TODO
> > diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > new file mode 100644
> > index 000000000000..3685b3b1ad64
> > --- /dev/null
> > +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.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::
> > +
> > +   amdgpu-dm.rst
> > +   amdgpu-dc-debug.rst
> > +
> > +``Display Core initialized with <version number here>``
> > diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dm.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
> > new file mode 100644
> > index 000000000000..7ce31f89d9a0
> > --- /dev/null
> > +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dm.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/drivers.rst b/Documentation/gpu/drivers.rst
> > index b4a0ed3ca961..dffe52d837cd 100644
> > --- a/Documentation/gpu/drivers.rst
> > +++ b/Documentation/gpu/drivers.rst
> > @@ -5,7 +5,7 @@ GPU Driver Documentation
> >   .. toctree::
> >      amdgpu
> > -   amdgpu-dc
> > +   amdgpu-dc/amdgpu-dc
> >      i915
> >      mcde
> >      meson
> 

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

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

[Daniel Vetter]

On Thu, Nov 25, 2021 at 10:38:25AM -0500, Rodrigo Siqueira wrote:
> 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.
> 
> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> ---
>  Documentation/gpu/amdgpu-dc.rst               | 74 -------------------
>  .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |  4 +
>  Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     | 29 ++++++++
>  Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     | 42 +++++++++++
>  Documentation/gpu/drivers.rst                 |  2 +-
>  5 files changed, 76 insertions(+), 75 deletions(-)
>  delete mode 100644 Documentation/gpu/amdgpu-dc.rst
>  create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>  create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>  create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
> 
> 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-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
> new file mode 100644
> index 000000000000..bbb8c3fc8eee
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
> @@ -0,0 +1,4 @@
> +Display Core Debug tools
> +========================
> +
> +TODO
> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> new file mode 100644
> index 000000000000..3685b3b1ad64
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst

While we bikeshed names, I think it'd would make sense to call this
overview.rst or intro.rst or similar, since it's meant to contain the
overall toctree for everything amdgpu related (maybe there will be more in
the future).
-Daniel

> @@ -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::
> +
> +   amdgpu-dm.rst
> +   amdgpu-dc-debug.rst
> +
> +``Display Core initialized with <version number here>``
> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dm.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
> new file mode 100644
> index 000000000000..7ce31f89d9a0
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dm.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/drivers.rst b/Documentation/gpu/drivers.rst
> index b4a0ed3ca961..dffe52d837cd 100644
> --- a/Documentation/gpu/drivers.rst
> +++ b/Documentation/gpu/drivers.rst
> @@ -5,7 +5,7 @@ GPU Driver Documentation
>  .. toctree::
>  
>     amdgpu
> -   amdgpu-dc
> +   amdgpu-dc/amdgpu-dc
>     i915
>     mcde
>     meson
> -- 
> 2.25.1
> 

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

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

[Jani Nikula]

On Fri, 26 Nov 2021, Daniel Vetter <daniel@ffwll.ch> wrote:
> On Thu, Nov 25, 2021 at 10:38:25AM -0500, Rodrigo Siqueira wrote:
>> 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.
>> 
>> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
>> ---
>>  Documentation/gpu/amdgpu-dc.rst               | 74 -------------------
>>  .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |  4 +
>>  Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     | 29 ++++++++
>>  Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     | 42 +++++++++++
>>  Documentation/gpu/drivers.rst                 |  2 +-
>>  5 files changed, 76 insertions(+), 75 deletions(-)
>>  delete mode 100644 Documentation/gpu/amdgpu-dc.rst
>>  create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>  create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>  create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
>> 
>> 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-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>> new file mode 100644
>> index 000000000000..bbb8c3fc8eee
>> --- /dev/null
>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>> @@ -0,0 +1,4 @@
>> +Display Core Debug tools
>> +========================
>> +
>> +TODO
>> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>> new file mode 100644
>> index 000000000000..3685b3b1ad64
>> --- /dev/null
>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>
> While we bikeshed names, I think it'd would make sense to call this
> overview.rst or intro.rst or similar, since it's meant to contain the
> overall toctree for everything amdgpu related (maybe there will be more in
> the future).

index.rst?


-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH 6/6] Documentation/gpu: Add DC glossary

[Alex Deucher]

On Thu, Nov 25, 2021 at 10:40 AM Rodrigo Siqueira
<Rodrigo.Siqueira@amd.com> wrote:
>
> In the DC driver, we have multiple acronyms that are not obvious most of
> the time. This commit introduces a DC glossary in order to make it
> easier to navigate through our driver.
>
> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> ---
>  Documentation/gpu/amdgpu-dc/amdgpu-dc.rst   |   2 +-
>  Documentation/gpu/amdgpu-dc/dc-glossary.rst | 257 ++++++++++++++++++++
>  2 files changed, 258 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/gpu/amdgpu-dc/dc-glossary.rst
>
> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> index 2e45e83d9a2a..15405c43786a 100644
> --- a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> @@ -26,4 +26,4 @@ table of content:
>     amdgpu-dcn-overview.rst
>     amdgpu-dm.rst
>     amdgpu-dc-debug.rst
> -
> +   dc-glossary.rst
> diff --git a/Documentation/gpu/amdgpu-dc/dc-glossary.rst b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> new file mode 100644
> index 000000000000..48698fc1799f
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> @@ -0,0 +1,257 @@
> +===========
> +DC Glossary
> +===========
> +
> +.. 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
> +      * CPLIB: Content Protection Library

CPLIB is not a clock.  It should be split out as its own item.

> +
> +    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
> +
> +    DFS
> +      Digital Frequency Synthesizer
> +
> +    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

Make Micro Controller vs. Micro-Controller consistent for these.

> +
> +    DPCD
> +      DisplayPort Configuration Data
> +
> +    DPM(S)
> +      Display Power Management (Signaling)
> +
> +    DRR
> +      Dynamic Refresh Rate
> +
> +    DWB
> +      Display writeback
> +
> +    ECP
> +      Enhanced Content Protection
> +
> +    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
> +
> +    PPLib
> +      PowerPlay Library

Maybe say that powerplay is the power management component.

> +
> +    PSR
> +      Panel Self Refresh
> +
> +    SCL
> +      Scaler
> +
> +    SDP
> +      Scalable Data Port
> +
> +    SMU
> +      System Management Unit
> +
> +    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
> +
> +    VCE
> +      Video Compression Engine
> +
> +    VCN
> +      Video Codec Next
> --
> 2.25.1
>

Re: [PATCH 6/6] Documentation/gpu: Add DC glossary

[ydirson]

Hi Rodrigo,

That will really be helpful!

I know drawing the line is a difficult problem (and can even make things
harder when searching), but maybe it would make sense to keep generic
acronyms not specific to amdgpu in a separate list.  I bet a number of
them would be useful in the scope of other drm drivers (e.g. CRTC, DCC,
MST), and some are not restricted to the drm subsystem at all (e.g. FEC,
LUT), but still have value as not necessarily easy to look up.

Maybe "DC glossary" should just be "Glossary", since quite some entries
help to read adm/amdgpu/ too.  Which brings me to the result of my recent
searches as suggested entries:

 KIQ (Kernel Interface Queue), MQD (memory queue descriptor), HQD (hardware
 queue descriptor), EOP (still no clue :)

Maybe some more specific ones just to be spelled out in clear where they
are used ?  KCQ (compute queue?), KGQ (gfx queue?)

More suggestions inlined.

Best regards,
-- 
Yann

> On Thu, Nov 25, 2021 at 10:40 AM Rodrigo Siqueira
> <Rodrigo.Siqueira@amd.com> wrote:
> >
> > In the DC driver, we have multiple acronyms that are not obvious
> > most of
> > the time. This commit introduces a DC glossary in order to make it
> > easier to navigate through our driver.
> >
> > Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> > ---
> >  Documentation/gpu/amdgpu-dc/amdgpu-dc.rst   |   2 +-
> >  Documentation/gpu/amdgpu-dc/dc-glossary.rst | 257
> >  ++++++++++++++++++++
> >  2 files changed, 258 insertions(+), 1 deletion(-)
> >  create mode 100644 Documentation/gpu/amdgpu-dc/dc-glossary.rst
> >
> > diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > index 2e45e83d9a2a..15405c43786a 100644
> > --- a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > @@ -26,4 +26,4 @@ table of content:
> >     amdgpu-dcn-overview.rst
> >     amdgpu-dm.rst
> >     amdgpu-dc-debug.rst
> > -
> > +   dc-glossary.rst
> > diff --git a/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > new file mode 100644
> > index 000000000000..48698fc1799f
> > --- /dev/null
> > +++ b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > @@ -0,0 +1,257 @@
> > +===========
> > +DC Glossary
> > +===========
> > +
> > +.. 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
> > +      * CPLIB: Content Protection Library
> 
> CPLIB is not a clock.  It should be split out as its own item.
> 
> > +
> > +    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

I recall this as the old name for DC, maybe this should be mentioned ?

> > +
> > +    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
> > +
> > +    DFS
> > +      Digital Frequency Synthesizer
> > +
> > +    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
> 
> Make Micro Controller vs. Micro-Controller consistent for these.
> 
> > +
> > +    DPCD
> > +      DisplayPort Configuration Data
> > +
> > +    DPM(S)
> > +      Display Power Management (Signaling)
> > +
> > +    DRR
> > +      Dynamic Refresh Rate
> > +
> > +    DWB
> > +      Display writeback
> > +
> > +    ECP
> > +      Enhanced Content Protection
> > +
> > +    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
> > +
> > +    PPLib
> > +      PowerPlay Library
> 
> Maybe say that powerplay is the power management component.
> 
> > +
> > +    PSR
> > +      Panel Self Refresh
> > +
> > +    SCL
> > +      Scaler
> > +
> > +    SDP
> > +      Scalable Data Port
> > +
> > +    SMU
> > +      System Management Unit
> > +
> > +    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
> > +
> > +    VCE
> > +      Video Compression Engine
> > +
> > +    VCN
> > +      Video Codec Next
> > --
> > 2.25.1
> >
> 

Re: [PATCH 6/6] Documentation/gpu: Add DC glossary

[Christian König]

Am 29.11.21 um 21:48 schrieb ydirson@free.fr:
> Hi Rodrigo,
>
> That will really be helpful!
>
> I know drawing the line is a difficult problem (and can even make things
> harder when searching), but maybe it would make sense to keep generic
> acronyms not specific to amdgpu in a separate list.  I bet a number of
> them would be useful in the scope of other drm drivers (e.g. CRTC, DCC,
> MST), and some are not restricted to the drm subsystem at all (e.g. FEC,
> LUT), but still have value as not necessarily easy to look up.
>
> Maybe "DC glossary" should just be "Glossary", since quite some entries
> help to read adm/amdgpu/ too.  Which brings me to the result of my recent
> searches as suggested entries:
>
>   KIQ (Kernel Interface Queue), MQD (memory queue descriptor), HQD (hardware
>   queue descriptor), EOP (still no clue :)

End Of Pipe/Pipeline :)

This means that calculations are done, all caches are flushed and all 
memory is coherent again.

Usually related to an interrupt send or fence value written.

Christian.

>
> Maybe some more specific ones just to be spelled out in clear where they
> are used ?  KCQ (compute queue?), KGQ (gfx queue?)
>
> More suggestions inlined.
>
> Best regards,

Re: [PATCH 6/6] Documentation/gpu: Add DC glossary

[Alex Deucher]

On Mon, Nov 29, 2021 at 3:48 PM <ydirson@free.fr> wrote:
>
> Hi Rodrigo,
>
> That will really be helpful!
>
> I know drawing the line is a difficult problem (and can even make things
> harder when searching), but maybe it would make sense to keep generic
> acronyms not specific to amdgpu in a separate list.  I bet a number of
> them would be useful in the scope of other drm drivers (e.g. CRTC, DCC,
> MST), and some are not restricted to the drm subsystem at all (e.g. FEC,
> LUT), but still have value as not necessarily easy to look up.
>
> Maybe "DC glossary" should just be "Glossary", since quite some entries
> help to read adm/amdgpu/ too.  Which brings me to the result of my recent
> searches as suggested entries:
>
>  KIQ (Kernel Interface Queue), MQD (memory queue descriptor), HQD (hardware
>  queue descriptor), EOP (still no clue :)
>
> Maybe some more specific ones just to be spelled out in clear where they
> are used ?  KCQ (compute queue?), KGQ (gfx queue?)

Kernel Compute Queue and Kernel Graphics Queue.

Alex

>
> More suggestions inlined.
>
> Best regards,
> --
> Yann
>
> > On Thu, Nov 25, 2021 at 10:40 AM Rodrigo Siqueira
> > <Rodrigo.Siqueira@amd.com> wrote:
> > >
> > > In the DC driver, we have multiple acronyms that are not obvious
> > > most of
> > > the time. This commit introduces a DC glossary in order to make it
> > > easier to navigate through our driver.
> > >
> > > Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> > > ---
> > >  Documentation/gpu/amdgpu-dc/amdgpu-dc.rst   |   2 +-
> > >  Documentation/gpu/amdgpu-dc/dc-glossary.rst | 257
> > >  ++++++++++++++++++++
> > >  2 files changed, 258 insertions(+), 1 deletion(-)
> > >  create mode 100644 Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > >
> > > diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > > b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > > index 2e45e83d9a2a..15405c43786a 100644
> > > --- a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > > +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > > @@ -26,4 +26,4 @@ table of content:
> > >     amdgpu-dcn-overview.rst
> > >     amdgpu-dm.rst
> > >     amdgpu-dc-debug.rst
> > > -
> > > +   dc-glossary.rst
> > > diff --git a/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > > b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > > new file mode 100644
> > > index 000000000000..48698fc1799f
> > > --- /dev/null
> > > +++ b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > > @@ -0,0 +1,257 @@
> > > +===========
> > > +DC Glossary
> > > +===========
> > > +
> > > +.. 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
> > > +      * CPLIB: Content Protection Library
> >
> > CPLIB is not a clock.  It should be split out as its own item.
> >
> > > +
> > > +    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
>
> I recall this as the old name for DC, maybe this should be mentioned ?
>
> > > +
> > > +    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
> > > +
> > > +    DFS
> > > +      Digital Frequency Synthesizer
> > > +
> > > +    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
> >
> > Make Micro Controller vs. Micro-Controller consistent for these.
> >
> > > +
> > > +    DPCD
> > > +      DisplayPort Configuration Data
> > > +
> > > +    DPM(S)
> > > +      Display Power Management (Signaling)
> > > +
> > > +    DRR
> > > +      Dynamic Refresh Rate
> > > +
> > > +    DWB
> > > +      Display writeback
> > > +
> > > +    ECP
> > > +      Enhanced Content Protection
> > > +
> > > +    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
> > > +
> > > +    PPLib
> > > +      PowerPlay Library
> >
> > Maybe say that powerplay is the power management component.
> >
> > > +
> > > +    PSR
> > > +      Panel Self Refresh
> > > +
> > > +    SCL
> > > +      Scaler
> > > +
> > > +    SDP
> > > +      Scalable Data Port
> > > +
> > > +    SMU
> > > +      System Management Unit
> > > +
> > > +    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
> > > +
> > > +    VCE
> > > +      Video Compression Engine
> > > +
> > > +    VCN
> > > +      Video Codec Next
> > > --
> > > 2.25.1
> > >
> >

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

[Rodrigo Siqueira Jordao]

On 2021-11-29 7:06 a.m., Jani Nikula wrote:
> On Fri, 26 Nov 2021, Daniel Vetter <daniel@ffwll.ch> wrote:
>> On Thu, Nov 25, 2021 at 10:38:25AM -0500, Rodrigo Siqueira wrote:
>>> 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.
>>>
>>> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
>>> ---
>>>   Documentation/gpu/amdgpu-dc.rst               | 74 -------------------
>>>   .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |  4 +
>>>   Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     | 29 ++++++++
>>>   Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     | 42 +++++++++++
>>>   Documentation/gpu/drivers.rst                 |  2 +-
>>>   5 files changed, 76 insertions(+), 75 deletions(-)
>>>   delete mode 100644 Documentation/gpu/amdgpu-dc.rst
>>>   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>>   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>>   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
>>>
>>> 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-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>> new file mode 100644
>>> index 000000000000..bbb8c3fc8eee
>>> --- /dev/null
>>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>> @@ -0,0 +1,4 @@
>>> +Display Core Debug tools
>>> +========================
>>> +
>>> +TODO
>>> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>> new file mode 100644
>>> index 000000000000..3685b3b1ad64
>>> --- /dev/null
>>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>
>> While we bikeshed names, I think it'd would make sense to call this
>> overview.rst or intro.rst or similar, since it's meant to contain the
>> overall toctree for everything amdgpu related (maybe there will be more in
>> the future).
> 
> index.rst?
> 
> 

Hi,

Thanks a lot for the suggestions; I will prepare a V2 that addresses all 
your comments.

Ps.: If there is no objection, I'll rename amdgpu-dc to index as Jani 
suggested.

Thanks.

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

[Harry Wentland]

On 2021-11-30 10:46, Rodrigo Siqueira Jordao wrote:
> 
> 
> On 2021-11-29 7:06 a.m., Jani Nikula wrote:
>> On Fri, 26 Nov 2021, Daniel Vetter <daniel@ffwll.ch> wrote:
>>> On Thu, Nov 25, 2021 at 10:38:25AM -0500, Rodrigo Siqueira wrote:
>>>> 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.
>>>>
>>>> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
>>>> ---
>>>>   Documentation/gpu/amdgpu-dc.rst               | 74 -------------------
>>>>   .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |  4 +
>>>>   Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     | 29 ++++++++
>>>>   Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     | 42 +++++++++++
>>>>   Documentation/gpu/drivers.rst                 |  2 +-
>>>>   5 files changed, 76 insertions(+), 75 deletions(-)
>>>>   delete mode 100644 Documentation/gpu/amdgpu-dc.rst
>>>>   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>>>   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>>>   create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
>>>>
>>>> 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-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>>> new file mode 100644
>>>> index 000000000000..bbb8c3fc8eee
>>>> --- /dev/null
>>>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>>> @@ -0,0 +1,4 @@
>>>> +Display Core Debug tools
>>>> +========================
>>>> +
>>>> +TODO
>>>> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>>> new file mode 100644
>>>> index 000000000000..3685b3b1ad64
>>>> --- /dev/null
>>>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>>
>>> While we bikeshed names, I think it'd would make sense to call this
>>> overview.rst or intro.rst or similar, since it's meant to contain the
>>> overall toctree for everything amdgpu related (maybe there will be more in
>>> the future).
>>
>> index.rst?
>>
>>
> 
> Hi,
> 
> Thanks a lot for the suggestions; I will prepare a V2 that addresses all your comments.
> 
> Ps.: If there is no objection, I'll rename amdgpu-dc to index as Jani suggested.
> 

SGTM, you mean amdgpu/index.rst, right?

Harry

> Thanks.
> 

Re: [PATCH 6/6] Documentation/gpu: Add DC glossary

[Rodrigo Siqueira Jordao]

On 2021-11-29 3:48 p.m., ydirson@free.fr wrote:
> Hi Rodrigo,
> 
> That will really be helpful!
> 
> I know drawing the line is a difficult problem (and can even make things
> harder when searching), but maybe it would make sense to keep generic
> acronyms not specific to amdgpu in a separate list.  I bet a number of
> them would be useful in the scope of other drm drivers (e.g. CRTC, DCC,
> MST), and some are not restricted to the drm subsystem at all (e.g. FEC,
> LUT), but still have value as not necessarily easy to look up.
> 
> Maybe "DC glossary" should just be "Glossary", since quite some entries
> help to read adm/amdgpu/ too.  Which brings me to the result of my recent
> searches as suggested entries:
> 
>   KIQ (Kernel Interface Queue), MQD (memory queue descriptor), HQD (hardware
>   queue descriptor), EOP (still no clue :)
> 
> Maybe some more specific ones just to be spelled out in clear where they
> are used ?  KCQ (compute queue?), KGQ (gfx queue?)
> 
> More suggestions inlined.
> 
> Best regards,
> 

Hi all,

I'll address all the highlighted problems in the V2. Thanks a lot for 
all the feedback.

Yann,
For the generic acronyms, how about keeping it in this patch for now? 
After it gets merged, I can prepare a new documentation patch that 
creates a glossary for DRM where I move the generic acronyms to the DRM 
documentation. I prefer this approach to keep the improvement small and 
manageable.

Best Regards
Siqueira

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

[Rodrigo Siqueira Jordao]

On 2021-11-30 10:48 a.m., Harry Wentland wrote:
> On 2021-11-30 10:46, Rodrigo Siqueira Jordao wrote:
>>
>>
>> On 2021-11-29 7:06 a.m., Jani Nikula wrote:
>>> On Fri, 26 Nov 2021, Daniel Vetter <daniel@ffwll.ch> wrote:
>>>> On Thu, Nov 25, 2021 at 10:38:25AM -0500, Rodrigo Siqueira wrote:
>>>>> 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.
>>>>>
>>>>> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
>>>>> ---
>>>>>    Documentation/gpu/amdgpu-dc.rst               | 74 -------------------
>>>>>    .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |  4 +
>>>>>    Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     | 29 ++++++++
>>>>>    Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     | 42 +++++++++++
>>>>>    Documentation/gpu/drivers.rst                 |  2 +-
>>>>>    5 files changed, 76 insertions(+), 75 deletions(-)
>>>>>    delete mode 100644 Documentation/gpu/amdgpu-dc.rst
>>>>>    create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>>>>    create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>>>>    create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
>>>>>
>>>>> 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-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>>>> new file mode 100644
>>>>> index 000000000000..bbb8c3fc8eee
>>>>> --- /dev/null
>>>>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>>>> @@ -0,0 +1,4 @@
>>>>> +Display Core Debug tools
>>>>> +========================
>>>>> +
>>>>> +TODO
>>>>> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>>>> new file mode 100644
>>>>> index 000000000000..3685b3b1ad64
>>>>> --- /dev/null
>>>>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>>>
>>>> While we bikeshed names, I think it'd would make sense to call this
>>>> overview.rst or intro.rst or similar, since it's meant to contain the
>>>> overall toctree for everything amdgpu related (maybe there will be more in
>>>> the future).
>>>
>>> index.rst?
>>>
>>>
>>
>> Hi,
>>
>> Thanks a lot for the suggestions; I will prepare a V2 that addresses all your comments.
>>
>> Ps.: If there is no objection, I'll rename amdgpu-dc to index as Jani suggested.
>>
> 
> SGTM, you mean amdgpu/index.rst, right?

Yeah, but I'm also thinking about this new organization:

1. Create an amdgpu folder.
2. Inside amdgpu folder, I want to create a display folder.
3. Move all display documentation to the display folder and keep other 
amdgpu generic things under amdgpu.
4. Finally, inside the amdgpu folder, I'll create the index.rst for 
amdgpu, and inside the display folder, I will create a similar file.

Does it make sense?
Thanks

> Harry
> 
>> Thanks.
>>
> 

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

[Harry Wentland]

On 2021-11-30 10:59, Rodrigo Siqueira Jordao wrote:
> 
> 
> On 2021-11-30 10:48 a.m., Harry Wentland wrote:
>> On 2021-11-30 10:46, Rodrigo Siqueira Jordao wrote:
>>>
>>>
>>> On 2021-11-29 7:06 a.m., Jani Nikula wrote:
>>>> On Fri, 26 Nov 2021, Daniel Vetter <daniel@ffwll.ch> wrote:
>>>>> On Thu, Nov 25, 2021 at 10:38:25AM -0500, Rodrigo Siqueira wrote:
>>>>>> 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.
>>>>>>
>>>>>> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
>>>>>> ---
>>>>>>    Documentation/gpu/amdgpu-dc.rst               | 74 -------------------
>>>>>>    .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |  4 +
>>>>>>    Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     | 29 ++++++++
>>>>>>    Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     | 42 +++++++++++
>>>>>>    Documentation/gpu/drivers.rst                 |  2 +-
>>>>>>    5 files changed, 76 insertions(+), 75 deletions(-)
>>>>>>    delete mode 100644 Documentation/gpu/amdgpu-dc.rst
>>>>>>    create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>>>>>    create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>>>>>    create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
>>>>>>
>>>>>> 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-dc/amdgpu-dc-debug.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>>>>> new file mode 100644
>>>>>> index 000000000000..bbb8c3fc8eee
>>>>>> --- /dev/null
>>>>>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
>>>>>> @@ -0,0 +1,4 @@
>>>>>> +Display Core Debug tools
>>>>>> +========================
>>>>>> +
>>>>>> +TODO
>>>>>> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>>>>> new file mode 100644
>>>>>> index 000000000000..3685b3b1ad64
>>>>>> --- /dev/null
>>>>>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
>>>>>
>>>>> While we bikeshed names, I think it'd would make sense to call this
>>>>> overview.rst or intro.rst or similar, since it's meant to contain the
>>>>> overall toctree for everything amdgpu related (maybe there will be more in
>>>>> the future).
>>>>
>>>> index.rst?
>>>>
>>>>
>>>
>>> Hi,
>>>
>>> Thanks a lot for the suggestions; I will prepare a V2 that addresses all your comments.
>>>
>>> Ps.: If there is no objection, I'll rename amdgpu-dc to index as Jani suggested.
>>>
>>
>> SGTM, you mean amdgpu/index.rst, right?
> 
> Yeah, but I'm also thinking about this new organization:
> 
> 1. Create an amdgpu folder.
> 2. Inside amdgpu folder, I want to create a display folder.
> 3. Move all display documentation to the display folder and keep other amdgpu generic things under amdgpu.
> 4. Finally, inside the amdgpu folder, I'll create the index.rst for amdgpu, and inside the display folder, I will create a similar file.
> 
> Does it make sense?

Makes sense.

Harry

> Thanks
> 
>> Harry
>>
>>> Thanks.
>>>
>>
> 

Re: [PATCH 6/6] Documentation/gpu: Add DC glossary

[Yann Dirson]

----- Mail original -----
> De: "Rodrigo Siqueira Jordao" <rjordrigo@amd.com>
> À: ydirson@free.fr, "Rodrigo Siqueira" <Rodrigo.Siqueira@amd.com>, "Christian König" <christian.koenig@amd.com>,
> "Alex Deucher" <alexander.deucher@amd.com>
> Cc: "Harry Wentland" <Harry.Wentland@amd.com>, "Linux Doc Mailing List" <linux-doc@vger.kernel.org>, "Mark Yacoub"
> <markyacoub@chromium.org>, "Michel Dänzer" <michel@daenzer.net>, "Bas Nieuwenhuizen" <bas@basnieuwenhuizen.nl>,
> "Roman Li" <roman.li@amd.com>, "amd-gfx list" <amd-gfx@lists.freedesktop.org>, "Roman Gilg" <subdiff@gmail.com>,
> "Marek Olšák" <marek.olsak@amd.com>, "Pekka Paalanen" <ppaalanen@gmail.com>, "Aurabindo Pillai"
> <aurabindo.pillai@amd.com>, "nicholas choi" <nicholas.choi@amd.com>, "Maling list - DRI developers"
> <dri-devel@lists.freedesktop.org>, "Simon Ser" <contact@emersion.fr>, "Alex Deucher" <alexdeucher@gmail.com>, "Sean
> Paul" <seanpaul@chromium.org>, "Qingqing Zhuo" <qingqing.zhuo@amd.com>, "Bhawanpreet Lakha"
> <bhawanpreet.lakha@amd.com>, "Nicholas Kazlauskas" <nicholas.kazlauskas@amd.com>
> Envoyé: Mardi 30 Novembre 2021 16:53:55
> Objet: Re: [PATCH 6/6] Documentation/gpu: Add DC glossary
> 
> 
> 
> On 2021-11-29 3:48 p.m., ydirson@free.fr wrote:
> > Hi Rodrigo,
> > 
> > That will really be helpful!
> > 
> > I know drawing the line is a difficult problem (and can even make
> > things
> > harder when searching), but maybe it would make sense to keep
> > generic
> > acronyms not specific to amdgpu in a separate list.  I bet a number
> > of
> > them would be useful in the scope of other drm drivers (e.g. CRTC,
> > DCC,
> > MST), and some are not restricted to the drm subsystem at all (e.g.
> > FEC,
> > LUT), but still have value as not necessarily easy to look up.
> > 
> > Maybe "DC glossary" should just be "Glossary", since quite some
> > entries
> > help to read adm/amdgpu/ too.  Which brings me to the result of my
> > recent
> > searches as suggested entries:
> > 
> >   KIQ (Kernel Interface Queue), MQD (memory queue descriptor), HQD
> >   (hardware
> >   queue descriptor), EOP (still no clue :)
> > 
> > Maybe some more specific ones just to be spelled out in clear where
> > they
> > are used ?  KCQ (compute queue?), KGQ (gfx queue?)
> > 
> > More suggestions inlined.
> > 
> > Best regards,
> > 
> 
> Hi all,
> 
> I'll address all the highlighted problems in the V2. Thanks a lot for
> all the feedback.
> 
> Yann,
> For the generic acronyms, how about keeping it in this patch for now?
> After it gets merged, I can prepare a new documentation patch that
> creates a glossary for DRM where I move the generic acronyms to the
> DRM
> documentation. I prefer this approach to keep the improvement small
> and
> manageable.

Sure, especially as the Right Solution(tm) is not necessarily obvious :)

One thing I thought about is that a context could be specified together
with terms.  Like "BPP (graphics)", "FEC (CS)", "DMCUB (amdgpu)".  Well,
"CS" may not be a good choice but you get the idea: that would keep all
terms together and keep it easy for the reader.

That way it could be easily be generalized at some point by just moving
it to a generic kernel level - provided the solution suits the doc
community at large.

Best regards,
-- 
Yann

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

[Yann Dirson]

> On 2021-11-30 10:48 a.m., Harry Wentland wrote:
> > On 2021-11-30 10:46, Rodrigo Siqueira Jordao wrote:
> >>
> >>
> >> On 2021-11-29 7:06 a.m., Jani Nikula wrote:
> >>> On Fri, 26 Nov 2021, Daniel Vetter <daniel@ffwll.ch> wrote:
> >>>> On Thu, Nov 25, 2021 at 10:38:25AM -0500, Rodrigo Siqueira
> >>>> wrote:
> >>>>> 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.
> >>>>>
> >>>>> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> >>>>> ---
> >>>>>    Documentation/gpu/amdgpu-dc.rst               | 74
> >>>>>    -------------------
> >>>>>    .../gpu/amdgpu-dc/amdgpu-dc-debug.rst         |  4 +
> >>>>>    Documentation/gpu/amdgpu-dc/amdgpu-dc.rst     | 29 ++++++++
> >>>>>    Documentation/gpu/amdgpu-dc/amdgpu-dm.rst     | 42
> >>>>>    +++++++++++
> >>>>>    Documentation/gpu/drivers.rst                 |  2 +-
> >>>>>    5 files changed, 76 insertions(+), 75 deletions(-)
> >>>>>    delete mode 100644 Documentation/gpu/amdgpu-dc.rst
> >>>>>    create mode 100644
> >>>>>    Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
> >>>>>    create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> >>>>>    create mode 100644 Documentation/gpu/amdgpu-dc/amdgpu-dm.rst
> >>>>>
> >>>>> 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-dc/amdgpu-dc-debug.rst
> >>>>> b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
> >>>>> new file mode 100644
> >>>>> index 000000000000..bbb8c3fc8eee
> >>>>> --- /dev/null
> >>>>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc-debug.rst
> >>>>> @@ -0,0 +1,4 @@
> >>>>> +Display Core Debug tools
> >>>>> +========================
> >>>>> +
> >>>>> +TODO
> >>>>> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> >>>>> b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> >>>>> new file mode 100644
> >>>>> index 000000000000..3685b3b1ad64
> >>>>> --- /dev/null
> >>>>> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> >>>>
> >>>> While we bikeshed names, I think it'd would make sense to call
> >>>> this
> >>>> overview.rst or intro.rst or similar, since it's meant to
> >>>> contain the
> >>>> overall toctree for everything amdgpu related (maybe there will
> >>>> be more in
> >>>> the future).
> >>>
> >>> index.rst?
> >>>
> >>>
> >>
> >> Hi,
> >>
> >> Thanks a lot for the suggestions; I will prepare a V2 that
> >> addresses all your comments.
> >>
> >> Ps.: If there is no objection, I'll rename amdgpu-dc to index as
> >> Jani suggested.
> >>
> > 
> > SGTM, you mean amdgpu/index.rst, right?
> 
> Yeah, but I'm also thinking about this new organization:
> 
> 1. Create an amdgpu folder.
> 2. Inside amdgpu folder, I want to create a display folder.
> 3. Move all display documentation to the display folder and keep
> other
> amdgpu generic things under amdgpu.
> 4. Finally, inside the amdgpu folder, I'll create the index.rst for
> amdgpu, and inside the display folder, I will create a similar file.

Since the source tree has amd/amdgpu/ and amd/display/, wouldn't it
be useful to mirror that layout ?