diff mbox series

[v2,30/39] docs: gpu: i915.rst: gt: add more kernel-doc markups

Message ID d7d1f6d6516eb3a82041af1d5f40c2f550de40db.1657699522.git.mchehab@kernel.org (mailing list archive)
State New, archived
Headers show
Series drm/i915: fix kernel-doc issues | expand

Commit Message

Mauro Carvalho Chehab July 13, 2022, 8:12 a.m. UTC 
There are several documented GT kAPI that aren't currently part
of the docs. Add them, as this allows identifying issues with
badly-formatted tags.

Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/

 Documentation/gpu/i915.rst | 43 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

Comments

Rodrigo Vivi Aug. 9, 2022, 10:01 a.m. UTC | #1 
On Wed, Jul 13, 2022 at 09:12:18AM +0100, Mauro Carvalho Chehab wrote:
> There are several documented GT kAPI that aren't currently part
> of the docs. Add them, as this allows identifying issues with
> badly-formatted tags.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> ---
> 
> To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/
> 
>  Documentation/gpu/i915.rst | 43 +++++++++++++++++++++++++++++++++++++-
>  1 file changed, 42 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 2ad7941a79f2..afd8c0e3c689 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -149,7 +149,6 @@ Misc display functions
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
>  
> -
>  Plane Configuration
>  -------------------
>  
> @@ -308,6 +307,48 @@ Multicast/Replicated (MCR) Registers
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c
>     :internal:
>  
> +GT engine
> +---------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_types.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_cs.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_pm.c
> +
> +GT context
> +----------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h

why does the context deserves a separated section and the
many others below no?

> +
> +Graphics Translation Tables
> +---------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
> +
> +Other GT functionality
> +----------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.h

Why aren't these gtt ones in the above block? why only
having the global gtt there?

> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_migrate.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_mocs.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rc6.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_reset.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps_types.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_sseu.c
> +
>  Memory Management and Command Submission
>  ========================================
>  
> -- 
> 2.36.1
>
Mauro Carvalho Chehab Sept. 6, 2022, 7:35 p.m. UTC | #2 
On Tue, 9 Aug 2022 06:01:53 -0400
Rodrigo Vivi <rodrigo.vivi@intel.com> wrote:

> On Wed, Jul 13, 2022 at 09:12:18AM +0100, Mauro Carvalho Chehab wrote:
> > There are several documented GT kAPI that aren't currently part
> > of the docs. Add them, as this allows identifying issues with
> > badly-formatted tags.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> > ---
> > 
> > To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
> > See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/
> > 
> >  Documentation/gpu/i915.rst | 43 +++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 42 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> > index 2ad7941a79f2..afd8c0e3c689 100644
> > --- a/Documentation/gpu/i915.rst
> > +++ b/Documentation/gpu/i915.rst
> > @@ -149,7 +149,6 @@ Misc display functions
> >  
> >  .. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
> >  
> > -
> >  Plane Configuration
> >  -------------------
> >  
> > @@ -308,6 +307,48 @@ Multicast/Replicated (MCR) Registers
> >  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c
> >     :internal:
> >  
> > +GT engine
> > +---------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_types.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_cs.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_pm.c
> > +
> > +GT context
> > +----------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h  
> 
> why does the context deserves a separated section and the
> many others below no?

Good question. The patches adding stuff to i915.rst are the
hardest ones to produce, in the sense that it is not easy to have
a common criteria about when creating or not a new section.

I tried to follow the same as other things for the same type, but
it is hard to classify.

The main point is that they should be somewhere there, in order to start
producing errors when building the docs. Reorganizing those markups should
be easily done once all files with kernel-docs gets added there.

Anyway, I'll keep this under:

	Other GT functionality

Section. We can shift things later on as needed.

> > +
> > +Graphics Translation Tables
> > +---------------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
> > +
> > +Other GT functionality
> > +----------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.h  
> 
> Why aren't these gtt ones in the above block? why only
> having the global gtt there?

Makes sense. I'll place GTT together with GGTT.

> 
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_migrate.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_mocs.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rc6.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_reset.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps_types.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_sseu.c
> > +
> >  Memory Management and Command Submission
> >  ========================================
> >  
> > -- 
> > 2.36.1
> >
diff mbox series

Patch

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 2ad7941a79f2..afd8c0e3c689 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -149,7 +149,6 @@  Misc display functions
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
 
-
 Plane Configuration
 -------------------
 
@@ -308,6 +307,48 @@  Multicast/Replicated (MCR) Registers
 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c
    :internal:
 
+GT engine
+---------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_types.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_cs.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_pm.c
+
+GT context
+----------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h
+
+Graphics Translation Tables
+---------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
+
+Other GT functionality
+----------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_migrate.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_mocs.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rc6.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_reset.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps_types.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_sseu.c
+
 Memory Management and Command Submission
 ========================================