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

[Harry Wentland]

On 2021-11-30 10:59, Rodrigo Siqueira Jordao wrote:
> 
> 
> 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 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?
> 
> 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.
> 
> Does it make sense?

Makes sense.

Harry

> Thanks
> 
>> Harry
>>
>>> Thanks.
>>>
>>
>