[PATCH v3] drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[PATCH v3] drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[Shuicheng Lin]

The kernel-doc block above struct drm_gpusvm_pages duplicates the
descriptions of the bit-flags that live in struct drm_gpusvm_pages_flags
using dotted notation (@flags.migrate_devmem, @flags.unmapped, ...).
That dotted notation is intended for nested anonymous structs/unions that
the parser flattens into the parent's parameter list.  Here, however,
flags is of a named external type, so the parser does not flatten its
members and the dotted entries do not match any member of
drm_gpusvm_pages.  They also duplicate the canonical descriptions already
present in the kernel-doc of struct drm_gpusvm_pages_flags itself.

Drop the five @flags.* lines and replace them with a single @flags entry
that cross-references the type via kernel-doc's "&struct ..." syntax.
This eliminates the redundancy and removes warnings emitted by the new
parameterdescs check in scripts/kernel-doc:

  Excess struct member 'flags.migrate_devmem' description in
   'drm_gpusvm_pages'
  Excess struct member 'flags.unmapped' description in 'drm_gpusvm_pages'
  Excess struct member 'flags.partial_unmap' description in
   'drm_gpusvm_pages'
  Excess struct member 'flags.has_devmem_pages' description in
   'drm_gpusvm_pages'
  Excess struct member 'flags.has_dma_mapping' description in
   'drm_gpusvm_pages'

No functional change.

Assisted-by: Claude:claude-opus-4.6
Cc: Matthew Auld <matthew.auld@intel.com>
Signed-off-by: Shuicheng Lin <shuicheng.lin@intel.com>
---
v2: change base to drm-misc.
v3: correct the assisted-by tag.

The failure is reported by the new kernel-doc check in: https://patchwork.freedesktop.org/series/164948/
---
 include/drm/drm_gpusvm.h | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/include/drm/drm_gpusvm.h b/include/drm/drm_gpusvm.h
index cd94bb2ee6ee..8a4d7134a9a7 100644
--- a/include/drm/drm_gpusvm.h
+++ b/include/drm/drm_gpusvm.h
@@ -140,12 +140,7 @@ struct drm_gpusvm_pages_flags {
  * @state: DMA IOVA state for mapping.
  * @state_offset: DMA IOVA offset for mapping.
  * @notifier_seq: Notifier sequence number of the range's pages
- * @flags: Flags for range
- * @flags.migrate_devmem: Flag indicating whether the range can be migrated to device memory
- * @flags.unmapped: Flag indicating if the range has been unmapped
- * @flags.partial_unmap: Flag indicating if the range has been partially unmapped
- * @flags.has_devmem_pages: Flag indicating if the range has devmem pages
- * @flags.has_dma_mapping: Flag indicating if the range has a DMA mapping
+ * @flags: Flags for the range; see &struct drm_gpusvm_pages_flags
  */
 struct drm_gpusvm_pages {
 	struct drm_pagemap_addr *dma_addr;
-- 
2.43.0

Re: [PATCH v3] drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[Matthew Brost]

On Fri, May 01, 2026 at 05:59:56PM +0000, Shuicheng Lin wrote:
> The kernel-doc block above struct drm_gpusvm_pages duplicates the
> descriptions of the bit-flags that live in struct drm_gpusvm_pages_flags
> using dotted notation (@flags.migrate_devmem, @flags.unmapped, ...).
> That dotted notation is intended for nested anonymous structs/unions that
> the parser flattens into the parent's parameter list.  Here, however,
> flags is of a named external type, so the parser does not flatten its
> members and the dotted entries do not match any member of
> drm_gpusvm_pages.  They also duplicate the canonical descriptions already
> present in the kernel-doc of struct drm_gpusvm_pages_flags itself.
> 
> Drop the five @flags.* lines and replace them with a single @flags entry
> that cross-references the type via kernel-doc's "&struct ..." syntax.
> This eliminates the redundancy and removes warnings emitted by the new
> parameterdescs check in scripts/kernel-doc:
> 
>   Excess struct member 'flags.migrate_devmem' description in
>    'drm_gpusvm_pages'
>   Excess struct member 'flags.unmapped' description in 'drm_gpusvm_pages'
>   Excess struct member 'flags.partial_unmap' description in
>    'drm_gpusvm_pages'
>   Excess struct member 'flags.has_devmem_pages' description in
>    'drm_gpusvm_pages'
>   Excess struct member 'flags.has_dma_mapping' description in
>    'drm_gpusvm_pages'
> 
> No functional change.
> 
> Assisted-by: Claude:claude-opus-4.6
> Cc: Matthew Auld <matthew.auld@intel.com>
> Signed-off-by: Shuicheng Lin <shuicheng.lin@intel.com>

Reviewed-by: Matthew Brost <matthew.brost@intel.com>

> ---
> v2: change base to drm-misc.
> v3: correct the assisted-by tag.
> 
> The failure is reported by the new kernel-doc check in: https://patchwork.freedesktop.org/series/164948/
> ---
>  include/drm/drm_gpusvm.h | 7 +------
>  1 file changed, 1 insertion(+), 6 deletions(-)
> 
> diff --git a/include/drm/drm_gpusvm.h b/include/drm/drm_gpusvm.h
> index cd94bb2ee6ee..8a4d7134a9a7 100644
> --- a/include/drm/drm_gpusvm.h
> +++ b/include/drm/drm_gpusvm.h
> @@ -140,12 +140,7 @@ struct drm_gpusvm_pages_flags {
>   * @state: DMA IOVA state for mapping.
>   * @state_offset: DMA IOVA offset for mapping.
>   * @notifier_seq: Notifier sequence number of the range's pages
> - * @flags: Flags for range
> - * @flags.migrate_devmem: Flag indicating whether the range can be migrated to device memory
> - * @flags.unmapped: Flag indicating if the range has been unmapped
> - * @flags.partial_unmap: Flag indicating if the range has been partially unmapped
> - * @flags.has_devmem_pages: Flag indicating if the range has devmem pages
> - * @flags.has_dma_mapping: Flag indicating if the range has a DMA mapping
> + * @flags: Flags for the range; see &struct drm_gpusvm_pages_flags
>   */
>  struct drm_gpusvm_pages {
>  	struct drm_pagemap_addr *dma_addr;
> -- 
> 2.43.0
> 

Claude review: drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[Claude Code Review Bot]

Overall Series Review

Subject: drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages
Author: Shuicheng Lin <shuicheng.lin@intel.com>
Patches: 2
Reviewed: 2026-05-05T09:11:20.649692

---

This is a single, straightforward kernel-doc cleanup patch. The analysis in the commit message is correct: `struct drm_gpusvm_pages` has a `flags` member of the named type `struct drm_gpusvm_pages_flags`, so the `@flags.*` dotted kernel-doc notation does not apply (that notation is only for anonymous nested structs/unions). The canonical descriptions already exist in the kernel-doc block for `struct drm_gpusvm_pages_flags` itself (lines 109-116 in drm-next), making the dotted entries in `struct drm_gpusvm_pages` redundant and triggering warnings from the kernel-doc checker.

The fix is minimal and correct: replace five `@flags.*` lines with a single `@flags` line that cross-references the type via `&struct drm_gpusvm_pages_flags`.

**Verdict: Looks good.** No issues found.

---
Generated by Claude Code Patch Reviewer

Claude review: drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[Claude Code Review Bot]

Patch Review

**Correctness:** The change is correct. Comparing with the kernel tree, `drm_gpusvm_notifier` (line 96-106) uses an anonymous `struct { u32 removed : 1; } flags;` where dotted `@flags.removed` notation *is* appropriate. But `drm_gpusvm_pages` (line 147-152) uses the named type `struct drm_gpusvm_pages_flags flags;`, which the kernel-doc parser does not flatten — so the `@flags.*` entries are indeed excess members that trigger warnings.

**The replacement line:**
```
 * @flags: Flags for the range; see &struct drm_gpusvm_pages_flags
```
This correctly uses kernel-doc's `&struct` cross-reference syntax and provides a pointer to the canonical documentation.

**Minor observations:**

1. The patch context lines include `@state` and `@state_offset` fields that don't exist in the current drm-next tree, confirming this targets drm-misc (as stated in the v2 changelog). This is fine — the patch will apply cleanly on its intended base.

2. The commit message is well-written: it explains the root cause (named vs anonymous struct semantics in kernel-doc), quotes the specific warnings, and states "No functional change."

3. The `Assisted-by: Claude:claude-opus-4.6` tag — v3 of this patch specifically corrects this tag formatting, which is a reasonable thing to fix.

**Reviewed-by worthy:** Yes, this is a clean, correct documentation fix. No concerns.

---
Generated by Claude Code Patch Reviewer

[PATCH v2] drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[Shuicheng Lin]

The kernel-doc block above struct drm_gpusvm_pages duplicates the
descriptions of the bit-flags that live in struct drm_gpusvm_pages_flags
using dotted notation (@flags.migrate_devmem, @flags.unmapped, ...).
That dotted notation is intended for nested anonymous structs/unions that
the parser flattens into the parent's parameter list.  Here, however,
flags is of a named external type, so the parser does not flatten its
members and the dotted entries do not match any member of
drm_gpusvm_pages.  They also duplicate the canonical descriptions already
present in the kernel-doc of struct drm_gpusvm_pages_flags itself.

Drop the five @flags.* lines and replace them with a single @flags entry
that cross-references the type via kernel-doc's "&struct ..." syntax.
This eliminates the redundancy and removes warnings emitted by the new
parameterdescs check in scripts/kernel-doc:

  Excess struct member 'flags.migrate_devmem' description in
   'drm_gpusvm_pages'
  Excess struct member 'flags.unmapped' description in 'drm_gpusvm_pages'
  Excess struct member 'flags.partial_unmap' description in
   'drm_gpusvm_pages'
  Excess struct member 'flags.has_devmem_pages' description in
   'drm_gpusvm_pages'
  Excess struct member 'flags.has_dma_mapping' description in
   'drm_gpusvm_pages'

No functional change.

v2: change base to drm-misc.

Assisted-by: GitHub Copilot <copilot@github.com>
Cc: Matthew Auld <matthew.auld@intel.com>
Signed-off-by: Shuicheng Lin <shuicheng.lin@intel.com>
---                                                                             
The failure is reported by the new kernel-doc check in: https://patchwork.freedesktop.org/series/164948/
---
 include/drm/drm_gpusvm.h | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/include/drm/drm_gpusvm.h b/include/drm/drm_gpusvm.h
index cd94bb2ee6ee..8a4d7134a9a7 100644
--- a/include/drm/drm_gpusvm.h
+++ b/include/drm/drm_gpusvm.h
@@ -140,12 +140,7 @@ struct drm_gpusvm_pages_flags {
  * @state: DMA IOVA state for mapping.
  * @state_offset: DMA IOVA offset for mapping.
  * @notifier_seq: Notifier sequence number of the range's pages
- * @flags: Flags for range
- * @flags.migrate_devmem: Flag indicating whether the range can be migrated to device memory
- * @flags.unmapped: Flag indicating if the range has been unmapped
- * @flags.partial_unmap: Flag indicating if the range has been partially unmapped
- * @flags.has_devmem_pages: Flag indicating if the range has devmem pages
- * @flags.has_dma_mapping: Flag indicating if the range has a DMA mapping
+ * @flags: Flags for the range; see &struct drm_gpusvm_pages_flags
  */
 struct drm_gpusvm_pages {
 	struct drm_pagemap_addr *dma_addr;
-- 
2.43.0

Claude review: drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[Claude Code Review Bot]

Patch Review

**Correctness: Good.** The distinction between anonymous structs (where dotted notation is valid) and named struct types (where it isn't) is correctly identified. Compare with `struct drm_gpusvm_notifier` in the same file (line ~96 in the current tree), which uses `@flags.removed` — and that one is correct because `flags` there is an anonymous `struct { u32 removed : 1; }`, not a named type.

**The replacement line is well-formed:**
```
- * @flags: Flags for range
- * @flags.migrate_devmem: Flag indicating whether the range can be migrated to device memory
- * @flags.unmapped: Flag indicating if the range has been unmapped
- * @flags.partial_unmap: Flag indicating if the range has been partially unmapped
- * @flags.has_devmem_pages: Flag indicating if the range has devmem pages
- * @flags.has_dma_mapping: Flag indicating if the range has a DMA mapping
+ * @flags: Flags for the range; see &struct drm_gpusvm_pages_flags
```

The `&struct drm_gpusvm_pages_flags` syntax is standard kernel-doc cross-referencing and will produce a hyperlink in the generated documentation.

**One very minor nit:** The wording changed from "Flags for range" to "Flags for the range" (added "the"). Fine, slightly better English.

**No issues found.** 

Reviewed-by worthy.

---
Generated by Claude Code Patch Reviewer

Claude review: drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[Claude Code Review Bot]

Overall Series Review

Subject: drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages
Author: Shuicheng Lin <shuicheng.lin@intel.com>
Patches: 1
Reviewed: 2026-05-05T09:12:49.244063

---

This is a single trivial kernel-doc fix for `struct drm_gpusvm_pages` in `include/drm/drm_gpusvm.h`. The change is correct and well-motivated. The existing kernel-doc uses `@flags.*` dotted notation (e.g., `@flags.migrate_devmem`) to document sub-fields of the `flags` member, but that notation only works for **anonymous** embedded structs that kernel-doc flattens into the parent. Here, `flags` is of the named type `struct drm_gpusvm_pages_flags`, which already has its own kernel-doc block — so the dotted entries are redundant, don't match any flattened member, and generate "Excess struct member" warnings from `scripts/kernel-doc`.

The fix correctly drops the five `@flags.*` lines and replaces them with a single `@flags` entry using the `&struct drm_gpusvm_pages_flags` cross-reference. No functional change.

The commit message is clear and thorough, including the exact warnings being fixed and a link to the failing CI series. No concerns with the patch itself.

**Minor process note:** The patch lists `Assisted-by: GitHub Copilot` and Cc's `copilot@github.com`. While this is a trivial doc change, some subsystem maintainers have policies about AI-attribution tags — worth checking if drm-misc has any stance on this. The `Assisted-by:` tag is not an officially recognized kernel tag (unlike `Co-developed-by:` or `Suggested-by:`).

**Verdict:** Looks good. Trivial and correct fix.

---

---
Generated by Claude Code Patch Reviewer

[PATCH] drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[Shuicheng Lin]

The kernel-doc block above struct drm_gpusvm_pages duplicates the
descriptions of the bit-flags that live in struct drm_gpusvm_pages_flags
using dotted notation (@flags.migrate_devmem, @flags.unmapped, ...).
That dotted notation is intended for nested anonymous structs/unions that
the parser flattens into the parent's parameter list.  Here, however,
flags is of a named external type, so the parser does not flatten its
members and the dotted entries do not match any member of
drm_gpusvm_pages.  They also duplicate the canonical descriptions already
present in the kernel-doc of struct drm_gpusvm_pages_flags itself.

Drop the five @flags.* lines and replace them with a single @flags entry
that cross-references the type via kernel-doc's "&struct ..." syntax.
This eliminates the redundancy and removes warnings emitted by the new
parameterdescs check in scripts/kernel-doc:

  Excess struct member 'flags.migrate_devmem' description in
   'drm_gpusvm_pages'
  Excess struct member 'flags.unmapped' description in 'drm_gpusvm_pages'
  Excess struct member 'flags.partial_unmap' description in
   'drm_gpusvm_pages'
  Excess struct member 'flags.has_devmem_pages' description in
   'drm_gpusvm_pages'
  Excess struct member 'flags.has_dma_mapping' description in
   'drm_gpusvm_pages'

No functional change.

Cc: Matthew Auld <matthew.auld@intel.com>
Signed-off-by: Shuicheng Lin <shuicheng.lin@intel.com>
---
The failure is reported by the new kernel-doc check in: https://patchwork.freedesktop.org/series/164948/
---
 include/drm/drm_gpusvm.h | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/include/drm/drm_gpusvm.h b/include/drm/drm_gpusvm.h
index 2578ac92a8d4..96eaf0328b4d 100644
--- a/include/drm/drm_gpusvm.h
+++ b/include/drm/drm_gpusvm.h
@@ -137,12 +137,7 @@ struct drm_gpusvm_pages_flags {
  * @dpagemap: The struct drm_pagemap of the device pages we're dma-mapping.
  *            Note this is assuming only one drm_pagemap per range is allowed.
  * @notifier_seq: Notifier sequence number of the range's pages
- * @flags: Flags for range
- * @flags.migrate_devmem: Flag indicating whether the range can be migrated to device memory
- * @flags.unmapped: Flag indicating if the range has been unmapped
- * @flags.partial_unmap: Flag indicating if the range has been partially unmapped
- * @flags.has_devmem_pages: Flag indicating if the range has devmem pages
- * @flags.has_dma_mapping: Flag indicating if the range has a DMA mapping
+ * @flags: Flags for the range; see &struct drm_gpusvm_pages_flags
  */
 struct drm_gpusvm_pages {
 	struct drm_pagemap_addr *dma_addr;
-- 
2.43.0

Claude review: drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[Claude Code Review Bot]

Patch Review

**Correctness:** The change is correct. Looking at the kernel tree, `struct drm_gpusvm_pages_flags` already has its own complete kernel-doc block (lines 108–117 in the header) documenting all five bit-flags (`@migrate_devmem`, `@unmapped`, `@partial_unmap`, `@has_devmem_pages`, `@has_dma_mapping`) plus `@__flags`. The dotted `@flags.*` entries in `struct drm_gpusvm_pages` were purely redundant.

**Replacement text is appropriate:** The new line:
```
 * @flags: Flags for the range; see &struct drm_gpusvm_pages_flags
```
uses the standard kernel-doc cross-reference syntax (`&struct ...`), which will produce a proper hyperlink in generated documentation. This is the idiomatic way to handle named sub-struct types.

**Minor nit (non-blocking):** The original `@flags` description said "Flags for range" and the replacement says "Flags for the range". This is fine — actually slightly more grammatical. However, the canonical doc in `struct drm_gpusvm_pages_flags` itself uses "pages" terminology (e.g., "Flag indicating if the pages has been unmapped"), while this says "range". Both are arguably correct since `drm_gpusvm_pages` is embedded in `drm_gpusvm_range`, but "Flags for the pages" would be more consistent with the naming of both the containing struct (`drm_gpusvm_pages`) and the flags struct (`drm_gpusvm_pages_flags`). This is purely cosmetic and not worth blocking on.

**No other concerns.** The diff is minimal, touches only documentation, and introduces no functional change.

Reviewed-by worthy as-is.

---
Generated by Claude Code Patch Reviewer

Claude review: drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages

[Claude Code Review Bot]

Overall Series Review

Subject: drm/gpusvm: Drop redundant @flags.* kernel-doc on struct drm_gpusvm_pages
Author: Shuicheng Lin <shuicheng.lin@intel.com>
Patches: 1
Reviewed: 2026-05-05T09:13:58.409097

---

This is a single, straightforward kernel-doc cleanup patch. The problem is well-described: `struct drm_gpusvm_pages` uses `@flags.*` dotted notation in its kernel-doc comment to describe the members of the named sub-struct `drm_gpusvm_pages_flags`. Since `flags` is a named external type (not an anonymous inline struct), the kernel-doc parser does not flatten its members, producing "Excess struct member" warnings. The fix correctly removes the redundant dotted entries and replaces them with a cross-reference to the type.

The patch is correct, well-motivated, and the commit message is exemplary — it explains the parser semantics, quotes the exact warnings being fixed, and notes "No functional change."

**Verdict: Patch looks good.**

---
Generated by Claude Code Patch Reviewer