Skip to contentSkip to conversation

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

PATCH Superseded Shuicheng Lin 1 participant 1 message May 1

Subsystems (3)

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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

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.

---
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(-)
include/drm/drm_gpusvm.h +1 -6
index 2578ac92a8d4..96eaf0328b4d 100644
@@ -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;
Signature · 1 line
2.43.0