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

[Daniel Vetter <daniel@ffwll.ch>]

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