[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
> 

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

[Lin, Shuicheng]

Thanks Matt for the review.

Hi drm misc maintainers,
Could you please help me merge it?
Thanks in advance for your support.

Shuicheng

On Fri, May 1, 2026 3:40 PM Matthew Brost wrote:
> 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
> >

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

[Matthew Brost]

On Wed, May 06, 2026 at 07:17:51PM -0600, Lin, Shuicheng wrote:
> Thanks Matt for the review.
> 
> Hi drm misc maintainers,
> Could you please help me merge it?
> Thanks in advance for your support.
> 

Pushed to drm-misc-next.

Matt

> Shuicheng
> 
> On Fri, May 1, 2026 3:40 PM Matthew Brost wrote:
> > 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
> > >