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

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

Harry

> Thanks.
>