On 2021-11-30 10:48 a.m., Harry Wentland wrote:

quoted

On 2021-11-30 10:46, Rodrigo Siqueira Jordao wrote:

quoted

On 2021-11-29 7:06 a.m., Jani Nikula wrote:

quoted

On Fri, 26 Nov 2021, Daniel Vetter [off-list ref] wrote:

quoted

On Thu, Nov 25, 2021 at 10:38:25AM -0500, Rodrigo Siqueira
wrote:

quoted

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