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

[Yann Dirson <ydirson@free.fr>]

> 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 ?