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

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

[Randy Dunlap]

Add 2 struct member descriptions and convert #define macro constants
comments to kernel-doc 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>
Acked-by: Mikko Perttunen <mperttunen@nvidia.com>
---
v2: add kernel-doc comments for #define constants (thanks, Mikko)
v3: rebase & resend

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 |   16 ++++++++++++++++
 1 file changed, 16 insertions(+)

--- linux-next-20260427.orig/include/uapi/drm/tegra_drm.h
+++ linux-next-20260427/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:
@@ -778,6 +780,9 @@ struct drm_tegra_channel_unmap {
 /* Submission */
 
 /**
+ * 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.
@@ -830,16 +835,27 @@ struct drm_tegra_submit_buf {
 };
 
 /**
+ * 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_GATHER_UPTR		0
+
 /**
+ * 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		1
+
 /**
+ * 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.
  */

Claude review: drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[Claude Code Review Bot]

Overall Series Review

Subject: drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings
Author: Randy Dunlap <rdunlap@infradead.org>
Patches: 1
Reviewed: 2026-04-28T14:00:47.253886

---

This is a single-patch documentation fix that addresses kernel-doc warnings in `include/uapi/drm/tegra_drm.h`. It adds two missing struct member descriptions and converts four `/**` comments on `#define` constants into proper kernel-doc format. The patch is mechanical and low-risk, touching only comments in a UAPI header. It already carries an Ack from the Tegra subsystem maintainer (Mikko Perttunen) and is on its third revision.

**Recommendation:** This patch looks good to apply. One minor nit below, but nothing blocking.

---
Generated by Claude Code Patch Reviewer

Claude review: drm/tegra: tegra_drm.h: fix all uapi kernel-doc warnings

[Claude Code Review Bot]

Patch Review

**Struct member descriptions (lines 307, 325 in patched file):**

The two added descriptions fix the documented warnings for `cmdbuf` and `target` members of `struct drm_tegra_reloc`:

```c
/** @cmdbuf: cmd information */
struct {
```

```c
/** @target: relocate target information */
struct {
```

These are correct and silence the warnings. Minor nit: `"cmd information"` is quite vague — something like `"command buffer location"` would better match the sub-fields (`handle` and `offset` into the command buffer), but this is a stylistic preference and the existing text is adequate.

**Define constant comments (lines 782–861 in patched file):**

The four `#define` comments are converted from bare `/**` blocks (which the kernel-doc parser flags as malformed) to proper `define MACRO - description` form. For example:

```c
/**
 * 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_GATHER_UPTR		0
```

The `\` line-continuation on the first `define` line is used to keep line length manageable, particularly for `DRM_TEGRA_SUBMIT_RELOC_SECTOR_LAYOUT`. This works with the kernel-doc script's line-joining logic, so it should parse correctly. The added short descriptions (`"Select sector layout swizzling..."`, `"Execute Host1x opcodes..."`, `"Wait for syncpoint (absolute)."`, `"Wait for syncpoint (relative)."`) are clear and appropriate.

**No functional code changes.** Only documentation comments are modified. No risk of runtime behavior change since this is a UAPI header and only comment lines are touched.

**Verdict:** Patch is correct and ready to merge. The warnings are real, the fixes are appropriate, and the Tegra maintainer has already acked it.

---
Generated by Claude Code Patch Reviewer