[PATCH] drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[PATCH] drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[Randy Dunlap]

Add 2 struct member descriptions and demote several comments from
"/**" kernel-doc comments to plain C "/*" comments to eliminate all
kernel-doc warnings:

Warning: include/uapi/drm/tegra_drm.h:353 struct member 'cmdbuf' not
 described in 'drm_tegra_reloc'
Warning: include/uapi/drm/tegra_drm.h:353 struct member 'target' not
 described in 'drm_tegra_reloc'

Warning: include/uapi/drm/tegra_drm.h:780 This comment starts with '/**',
 but isn't a kernel-doc comment.
 * Specify that bit 39 of the patched-in address should be set to switch
Warning: include/uapi/drm/tegra_drm.h:832 This comment starts with '/**',
 but isn't a kernel-doc comment.
 * Execute `words` words of Host1x opcodes specified in the
 `gather_data_ptr`
Warning: include/uapi/drm/tegra_drm.h:837 This comment starts with '/**',
 but isn't a kernel-doc comment.
 * Wait for a syncpoint to reach a value before continuing with further
Warning: include/uapi/drm/tegra_drm.h:842 This comment starts with '/**',
 but isn't a kernel-doc comment.
 * Wait for a syncpoint to reach a value before continuing with further

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Thierry Reding <thierry.reding@gmail.com>
Cc: Mikko Perttunen <mperttunen@nvidia.com>
Cc: linux-tegra@vger.kernel.org
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <mripard@kernel.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: David Airlie <airlied@gmail.com>
Cc: Simona Vetter <simona@ffwll.ch>

 include/uapi/drm/tegra_drm.h |   10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

--- linux-next-20260226.orig/include/uapi/drm/tegra_drm.h
+++ linux-next-20260226/include/uapi/drm/tegra_drm.h
@@ -304,6 +304,7 @@ struct drm_tegra_cmdbuf {
  * struct drm_tegra_reloc - GEM object relocation structure
  */
 struct drm_tegra_reloc {
+	/** @cmdbuf: cmd information */
 	struct {
 		/**
 		 * @cmdbuf.handle:
@@ -321,6 +322,7 @@ struct drm_tegra_reloc {
 		 */
 		__u32 offset;
 	} cmdbuf;
+	/** @target: relocate target information */
 	struct {
 		/**
 		 * @target.handle:
@@ -777,7 +779,7 @@ struct drm_tegra_channel_unmap {
 
 /* Submission */
 
-/**
+/*
  * Specify that bit 39 of the patched-in address should be set to switch
  * swizzling between Tegra and non-Tegra sector layout on systems that store
  * surfaces in system memory in non-Tegra sector layout.
@@ -829,17 +831,17 @@ struct drm_tegra_submit_buf {
 	} reloc;
 };
 
-/**
+/*
  * Execute `words` words of Host1x opcodes specified in the `gather_data_ptr`
  * buffer. Each GATHER_UPTR command uses successive words from the buffer.
  */
 #define DRM_TEGRA_SUBMIT_CMD_GATHER_UPTR		0
-/**
+/*
  * Wait for a syncpoint to reach a value before continuing with further
  * commands.
  */
 #define DRM_TEGRA_SUBMIT_CMD_WAIT_SYNCPT		1
-/**
+/*
  * Wait for a syncpoint to reach a value before continuing with further
  * commands. The threshold is calculated relative to the start of the job.
  */

Re: [PATCH] drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[Mikko Perttunen]

On Friday, February 27, 2026 6:58 AM Randy Dunlap wrote:
> Add 2 struct member descriptions and demote several comments from
> "/**" kernel-doc comments to plain C "/*" comments to eliminate all
> kernel-doc warnings:
> 
> Warning: include/uapi/drm/tegra_drm.h:353 struct member 'cmdbuf' not
>  described in 'drm_tegra_reloc'
> Warning: include/uapi/drm/tegra_drm.h:353 struct member 'target' not
>  described in 'drm_tegra_reloc'
> 
> Warning: include/uapi/drm/tegra_drm.h:780 This comment starts with '/**',
>  but isn't a kernel-doc comment.
>  * Specify that bit 39 of the patched-in address should be set to switch
> Warning: include/uapi/drm/tegra_drm.h:832 This comment starts with '/**',
>  but isn't a kernel-doc comment.
>  * Execute `words` words of Host1x opcodes specified in the
>  `gather_data_ptr`
> Warning: include/uapi/drm/tegra_drm.h:837 This comment starts with '/**',
>  but isn't a kernel-doc comment.
>  * Wait for a syncpoint to reach a value before continuing with further
> Warning: include/uapi/drm/tegra_drm.h:842 This comment starts with '/**',
>  but isn't a kernel-doc comment.
>  * Wait for a syncpoint to reach a value before continuing with further
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: Thierry Reding <thierry.reding@gmail.com>
> Cc: Mikko Perttunen <mperttunen@nvidia.com>
> Cc: linux-tegra@vger.kernel.org
> Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
> Cc: Maxime Ripard <mripard@kernel.org>
> Cc: Thomas Zimmermann <tzimmermann@suse.de>
> Cc: David Airlie <airlied@gmail.com>
> Cc: Simona Vetter <simona@ffwll.ch>
> 
>  include/uapi/drm/tegra_drm.h |   10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
> --- linux-next-20260226.orig/include/uapi/drm/tegra_drm.h
> +++ linux-next-20260226/include/uapi/drm/tegra_drm.h
> @@ -304,6 +304,7 @@ struct drm_tegra_cmdbuf {
>   * struct drm_tegra_reloc - GEM object relocation structure
>   */
>  struct drm_tegra_reloc {
> +	/** @cmdbuf: cmd information */
>  	struct {
>  		/**
>  		 * @cmdbuf.handle:
> @@ -321,6 +322,7 @@ struct drm_tegra_reloc {
>  		 */
>  		__u32 offset;
>  	} cmdbuf;
> +	/** @target: relocate target information */
>  	struct {
>  		/**
>  		 * @target.handle:
> @@ -777,7 +779,7 @@ struct drm_tegra_channel_unmap {
> 
>  /* Submission */
> 
> -/**
> +/*

Looks like kerneldoc has syntax for documenting defines, so it would be better 
to change these to use that rather than demoting to standard comments, I 
think.

For example,

/**
 * define DRM_TEGRA_SUBMIT_RELOC_SECTOR_LAYOUT - \
 *    Select sector layout swizzling for in-memory buffers.
 *
 * Specify that bit 39 of the patched-in address should be set to switch
 * swizzling between Tegra and non-Tegra sector layout on systems that store
 * surfaces in system memory in non-Tegra sector layout.
*/

/**
 * define DRM_TEGRA_SUBMIT_CMD_GATHER_UPTR - \
 *    Execute Host1x opcodes from user pointer.
 *
 * Execute `words` words of Host1x opcodes specified in the `gather_data_ptr`
 * buffer. Each GATHER_UPTR command uses successive words from the buffer.
 */

/**
 * define DRM_TEGRA_SUBMIT_CMD_WAIT_SYNCPT - \
 *    Wait for syncpoint (absolute).
 *
 * Wait for a syncpoint to reach a value before continuing with further
 * commands.
 */

/**
 * define DRM_TEGRA_SUBMIT_CMD_WAIT_SYNCPT_RELATIVE - \
 *    Wait for syncpoint (relative).
 *
 * Wait for a syncpoint to reach a value before continuing with further
 * commands. The threshold is calculated relative to the start of the job.
 */

Otherwise, looks good to me.

Thank you,
Mikko

>   * Specify that bit 39 of the patched-in address should be set to switch
>   * swizzling between Tegra and non-Tegra sector layout on systems that
> store * surfaces in system memory in non-Tegra sector layout.
> @@ -829,17 +831,17 @@ struct drm_tegra_submit_buf {
>  	} reloc;
>  };
> 
> -/**
> +/*
>   * Execute `words` words of Host1x opcodes specified in the
> `gather_data_ptr` * buffer. Each GATHER_UPTR command uses successive words
> from the buffer. */
>  #define DRM_TEGRA_SUBMIT_CMD_GATHER_UPTR		0
> -/**
> +/*
>   * Wait for a syncpoint to reach a value before continuing with further
>   * commands.
>   */
>  #define DRM_TEGRA_SUBMIT_CMD_WAIT_SYNCPT		1
> -/**
> +/*
>   * Wait for a syncpoint to reach a value before continuing with further
>   * commands. The threshold is calculated relative to the start of the job.
>   */