linux-kernel - Re: [Intel-gfx] [PATCH v2 35/39] docs: gpu: i915.rst: add the remaining kernel-doc markup files

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20220906214323.3d3a0db4@maurocar-mobl2>
Date:   Tue, 6 Sep 2022 21:43:30 +0200
From:   Mauro Carvalho Chehab <mauro.chehab@...ux.intel.com>
To:     Rodrigo Vivi <rodrigo.vivi@...el.com>
Cc:     Mauro Carvalho Chehab <mchehab@...nel.org>,
        linux-doc@...r.kernel.org, David Airlie <airlied@...ux.ie>,
        intel-gfx@...ts.freedesktop.org, Jonathan Corbet <corbet@....net>,
        linux-kernel@...r.kernel.org, dri-devel@...ts.freedesktop.org,
        Maxime Ripard <mripard@...nel.org>,
        Thomas Zimmermann <tzimmermann@...e.de>
Subject: Re: [Intel-gfx] [PATCH v2 35/39] docs: gpu: i915.rst: add the
 remaining kernel-doc markup files

On Tue, 9 Aug 2022 06:20:57 -0400
Rodrigo Vivi <rodrigo.vivi@...el.com> wrote:

> On Wed, Jul 13, 2022 at 09:12:23AM +0100, Mauro Carvalho Chehab wrote:
> > There are other files with kernel-doc markups:
> > 
> > 	$ git grep -l "/\*\*" $(git ls-files|grep drivers/gpu/drm/i915/) >kernel-doc-files
> > 	$ for i in $(cat kernel-doc-files); do if [ "$(git grep $i Documentation/)" == "" ]; then echo "$i"; fi; done >aaa
> > 
> > Add them to i915.rst as well.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@...nel.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 | 87 ++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 87 insertions(+)
> > 
> > diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> > index 974754586be8..6bb50edc6d79 100644
> > --- a/Documentation/gpu/i915.rst
> > +++ b/Documentation/gpu/i915.rst
> > @@ -13,6 +13,11 @@ Core Driver Infrastructure
> >  This section covers core driver infrastructure used by both the display
> >  and the GEM parts of the driver.
> >  
> > +Core driver
> > +-----------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_driver.c
> > +
> >  Runtime Power Management
> >  ------------------------
> >  
> > @@ -29,6 +34,10 @@ Runtime Power Management
> >  
> >  .. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
> >  
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_wakeref.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_active.h  
> 
> not sure if this belongs to this group...
> 
> > +
> >  Interrupt Handling
> >  ------------------
> >  
> > @@ -44,6 +53,28 @@ Interrupt Handling
> >  .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
> >     :functions: intel_runtime_pm_enable_interrupts
> >  
> > +Error handling
> > +--------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_gpu_error.c  
> 
> not sure if this gt hang stuff deserves a separated section
> alone and if the name is the best one....
> 
> > +
> > +Memory Handling
> > +---------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_mm.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_memory_region.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_memcpy.c
> > +
> >  Intel GVT-g Guest Support(vGPU)  
> 
>                             ^ missing space
> 
> >  -------------------------------
> >  
> > @@ -109,6 +140,54 @@ Workarounds
> >  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
> >     :doc: Hardware workarounds
> >  
> > +32-bits compatible ioctl Logic
> > +------------------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_ioc32.c
> > +
> > +Scatterlist handling
> > +--------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.c
> > +
> > +i915 request
> > +------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_request.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_request.c
> > +
> > +Ancillary routines  
> 
> maybe simply have an "Others" section and put everything
> that has only one item like the gpu hang one?

OK!

> 
> > +------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_device_info.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_params.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_sw_fence_work.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_syncmap.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_pcode.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_reg_defs.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.h
> > +
> > +
> > +PXP  
> 
> Protected Xe Path (PXP)
> 
> 
> > +---
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_irq.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_tee.c
> > +
> >  Display Hardware Handling
> >  =========================
> >  
> > @@ -618,6 +697,12 @@ Protected Objects
> >  Table Manager (TTM)
> >  -------------------
> >  
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_region_ttm.c
> > +
> >  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.c
> >  
> >  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.h
> > @@ -627,6 +712,8 @@ Table Manager (TTM)
> >  Graphics Execution Manager (GEM)
> >  --------------------------------
> >  
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c
> > +
> >  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_create.c
> >  
> >  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_domain.c  
> 
> in many cases I see only the .h or only the .c... why is that?
> wouldn't be better already put both in all the cases?

No. Adding kernel-doc files that doesn't contain any markups
will produce warnings.

We're working hard upstream to have a zero-warnings policy for
documentation.

Regards,
Mauro