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

[Jani Nikula <jani.nikula@linux.intel.com>]

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