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