Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Tue, 9 Aug 2022 06:20:57 -0400
From:   Rodrigo Vivi <rodrigo.vivi@intel.com>
To:     Mauro Carvalho Chehab <mchehab@kernel.org>
CC:     Thomas Zimmermann <tzimmermann@suse.de>,
        Jonathan Corbet <corbet@lwn.net>,
        David Airlie <airlied@linux.ie>,
        <dri-devel@lists.freedesktop.org>, <linux-kernel@vger.kernel.org>,
        <linux-doc@vger.kernel.org>, Maxime Ripard <mripard@kernel.org>,
        <intel-gfx@lists.freedesktop.org>
Subject: Re: [Intel-gfx] [PATCH v2 35/39] docs: gpu: i915.rst: add the
 remaining kernel-doc markup files
Message-ID: <YvI1CbsIZIG7FVBP@intel.com>
References: <cover.1657699522.git.mchehab@kernel.org>
 <5630ff7f2d5a99fc78b4fc2fa7e63649d23f226c.1657699522.git.mchehab@kernel.org>
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <5630ff7f2d5a99fc78b4fc2fa7e63649d23f226c.1657699522.git.mchehab@kernel.org>
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?yPtIpBpeaF5FYMCCroE2241OwuS/vLj6PqiGlzNEOXPwZ+f8powIWeDToZRu?=
 =?us-ascii?Q?dmeJS4P2A1Fb0slnMMUlObPkKjLOky33yxdmeqFT37WWD8rjnyAgPM4AmsHG?=
 =?us-ascii?Q?FuDrviPymDyc+S2Qpn9aPfEiLMSTyP9uAqxs7lAd2r3cVkpD0JrP7jZXelUi?=
 =?us-ascii?Q?yP0+GvP6+HK4t10Wbog7xYTIj+O2XHI9OYlYhqS0DQnOiYWKVUfpA8uOHw6h?=
 =?us-ascii?Q?yQ80xxKl/DUcxJcVTtLdAi0m7NUT2gNcllkH0vBggBqFmKUSa+X8RFvFhPRd?=
 =?us-ascii?Q?vWiX2vDmSaLR7wpzA71qB1oXQ+XCesdvBAwtOeFd1ooe/BgbmZGxd4H3UTre?=
 =?us-ascii?Q?/gjFOwMOEX7KK8aRU+WQTUt0Mqm4aktSbrX6kZsWvfLMECk/FLZgHLf3Uzzm?=
 =?us-ascii?Q?SPOyEO4VQQQPaAVdVeNKzvS3bHHYYAY5O/s2U7dXY5g0qk2kS+ueaSAeANvm?=
 =?us-ascii?Q?ecXy4FZbl05f0xNJ/mKA0jO/nJr5bLxu+3AvRHMhlal+eTLxpLvl5kKuI6rf?=
 =?us-ascii?Q?KNLVDXT8ndlQ8Jsfi3lWoLPDJM0B7TJBJo6+/mWFP95CXa/m3RIC82hcjZxm?=
 =?us-ascii?Q?lAwXjGrfDelsv9Rba9fWdev34C1hI8JQ8wIFnQ3UyB+5yXxxIxKA35+xVhiE?=
 =?us-ascii?Q?q/3JrMxs+r8phx8XDrAhlg3IJFViZoqlLab5TYXqvm8Q7CCqj6dDR/Jn0NCt?=
 =?us-ascii?Q?MP5vMS8CQwqTDzaSeC/dyxwlvkMRYA2qt9wksSH0+VcKtGE4ZgR/KqfZ9LmU?=
 =?us-ascii?Q?QIhbxSWHlOhBbzdfJ1ImfBCQb+Dyncz4I0CwQHt3cR7p3oTLsgvP8+j30Y53?=
 =?us-ascii?Q?qlJUq0YtXIejIGI1yvaL66uGO+5DA+aPM5RyGDroz1sLeNd3K+1Rc4j5gb7W?=
 =?us-ascii?Q?wgzqhq+Ru5QtVwv7je81oZMg5QarUJAYiNBm8dGeFDS6cWTLK/7flJkPOSu3?=
 =?us-ascii?Q?ewasSHkCZlDL7xFqCHisLZG1EZz398AJnraOJLklVpAJCkuyuEywR0uNT5r8?=
 =?us-ascii?Q?WbU72ZfN+2CIswR1H+ke9GsWt/uiIbeImtL0TE/9d3LqkZWrZ8WJUkW2bSp6?=
 =?us-ascii?Q?Zp/RjHvTQ7lMOezOjLN8B6reeU0DhJblcVE2PFfTpv5Xy7h2QonPjTQm1MuT?=
 =?us-ascii?Q?LDu+h4UPCmkCHrqpvzRGa9oqWo47Jp69Uix7F5FdHQrY1TZQBrqTWHrsAWXz?=
 =?us-ascii?Q?ys3TytERR41EACWhGFuz0goqAGiG2ujFY/0ZvWAp90+shEArxQfOlFlD1on+?=
 =?us-ascii?Q?kOKy5R4dKxhX7O62I065X+qTz1FHSeaKZHdvn/GBu4i4DQQu0j9b6pM8Ba1x?=
 =?us-ascii?Q?LVkIvBaI4TH4AaFyG8o8hBwfsWQeUQhxgDfBkESod+jYF/X1oyFVhfSI2F11?=
 =?us-ascii?Q?B/FFgv7lyX+BeWQSXeNFP0pjg7TyEa/jfRMskeF7adNSbEMvgH2MMray772L?=
 =?us-ascii?Q?w6P3wXUyVk9sHuVjpkpelsehbWP9hGH6QncXj3wXF04pceT+aJipVqr7eGHC?=
 =?us-ascii?Q?xJKpLMfBQATMOrhpWsFNwaZ76lme4i1PtsX0mKv6hoEdZBnNKlI6XAm/gSsJ?=
 =?us-ascii?Q?rSgHxqs2aav9+i/XddbJ36NjJFle5rhvUFJkBEkSERfSyiROHrmjG9AJC2vk?=
 =?us-ascii?Q?2Q=3D=3D?=
X-MS-Exchange-CrossTenant-Network-Message-Id: bae470aa-735e-4136-5f4e-08da79f0dc8a
X-MS-Exchange-CrossTenant-AuthSource: MN0PR11MB6059.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 09 Aug 2022 10:21:02.8325
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: SdAT3piaBYHUJp37T9fXrQGHRrL4ecyp1XEALDQaZvZQxuPLMKzWKlJYQ+/Qd+QiUguivfcUlPKRFpzbGXSJiw==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: CY4PR1101MB2199
X-OriginatorOrg: intel.com
X-Spam-Status: No, score=-5.0 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,
        DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_MED,
        SPF_HELO_NONE,SPF_NONE,T_SCC_BODY_TEXT_LINE autolearn=ham
        autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

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

> +------------------
> +
> +.. 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?

> -- 
> 2.36.1
>