Skip to content

Commit 200a6b3

Browse files
rddunlapmripard
rddunlap
authored and
mripard
committed
drm/gpuvm: fix all kernel-doc warnings in include/drm/drm_gpuvm.h
Update kernel-doc comments in <drm/drm_gpuvm.h> to correct all kernel-doc warnings: drm_gpuvm.h:148: warning: Excess struct member 'addr' description in 'drm_gpuva' drm_gpuvm.h:148: warning: Excess struct member 'offset' description in 'drm_gpuva' drm_gpuvm.h:148: warning: Excess struct member 'obj' description in 'drm_gpuva' drm_gpuvm.h:148: warning: Excess struct member 'entry' description in 'drm_gpuva' drm_gpuvm.h:148: warning: Excess struct member '__subtree_last' description in 'drm_gpuva' drm_gpuvm.h:192: warning: No description found for return value of 'drm_gpuva_invalidated' drm_gpuvm.h:331: warning: Excess struct member 'tree' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'list' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'list' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'local_list' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'lock' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'list' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'local_list' description in 'drm_gpuvm' drm_gpuvm.h:331: warning: Excess struct member 'lock' description in 'drm_gpuvm' drm_gpuvm.h:352: warning: No description found for return value of 'drm_gpuvm_get' drm_gpuvm.h:545: warning: Excess struct member 'fn' description in 'drm_gpuvm_exec' drm_gpuvm.h:545: warning: Excess struct member 'priv' description in 'drm_gpuvm_exec' drm_gpuvm.h:597: warning: missing initial short description on line: * drm_gpuvm_exec_resv_add_fence() drm_gpuvm.h:616: warning: missing initial short description on line: * drm_gpuvm_exec_validate() drm_gpuvm.h:623: warning: No description found for return value of 'drm_gpuvm_exec_validate' drm_gpuvm.h:698: warning: Excess struct member 'gpuva' description in 'drm_gpuvm_bo' drm_gpuvm.h:698: warning: Excess struct member 'entry' description in 'drm_gpuvm_bo' drm_gpuvm.h:698: warning: Excess struct member 'gem' description in 'drm_gpuvm_bo' drm_gpuvm.h:698: warning: Excess struct member 'evict' description in 'drm_gpuvm_bo' drm_gpuvm.h:726: warning: No description found for return value of 'drm_gpuvm_bo_get' drm_gpuvm.h:738: warning: missing initial short description on line: * drm_gpuvm_bo_gem_evict() drm_gpuvm.h:740: warning: missing initial short description on line: * drm_gpuvm_bo_gem_evict() drm_gpuvm.h:698: warning: Excess struct member 'evict' description in 'drm_gpuvm_bo' drm_gpuvm.h:844: warning: Excess struct member 'addr' description in 'drm_gpuva_op_map' drm_gpuvm.h:844: warning: Excess struct member 'range' description in 'drm_gpuva_op_map' drm_gpuvm.h:844: warning: Excess struct member 'offset' description in 'drm_gpuva_op_map' drm_gpuvm.h:844: warning: Excess struct member 'obj' description in 'drm_gpuva_op_map' Signed-off-by: Randy Dunlap <rdunlap@infradead.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: Daniel Vetter <daniel@ffwll.ch> Cc: dri-devel@lists.freedesktop.org Cc: Jonathan Corbet <corbet@lwn.net> Cc: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Maxime Ripard <mripard@kernel.org> Link: https://patchwork.freedesktop.org/patch/msgid/20231231054856.31786-1-rdunlap@infradead.org
1 parent f40e61e commit 200a6b3

1 file changed

Lines changed: 45 additions & 35 deletions

File tree

‎include/drm/drm_gpuvm.h‎

Lines changed: 45 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ struct drm_gpuva {
9292
*/
9393
struct {
9494
/**
95-
* @addr: the start address
95+
* @va.addr: the start address
9696
*/
9797
u64 addr;
9898

@@ -107,17 +107,17 @@ struct drm_gpuva {
107107
*/
108108
struct {
109109
/**
110-
* @offset: the offset within the &drm_gem_object
110+
* @gem.offset: the offset within the &drm_gem_object
111111
*/
112112
u64 offset;
113113

114114
/**
115-
* @obj: the mapped &drm_gem_object
115+
* @gem.obj: the mapped &drm_gem_object
116116
*/
117117
struct drm_gem_object *obj;
118118

119119
/**
120-
* @entry: the &list_head to attach this object to a &drm_gpuvm_bo
120+
* @gem.entry: the &list_head to attach this object to a &drm_gpuvm_bo
121121
*/
122122
struct list_head entry;
123123
} gem;
@@ -127,12 +127,12 @@ struct drm_gpuva {
127127
*/
128128
struct {
129129
/**
130-
* @rb: the rb-tree node
130+
* @rb.node: the rb-tree node
131131
*/
132132
struct rb_node node;
133133

134134
/**
135-
* @entry: The &list_head to additionally connect &drm_gpuvas
135+
* @rb.entry: The &list_head to additionally connect &drm_gpuvas
136136
* in the same order they appear in the interval tree. This is
137137
* useful to keep iterating &drm_gpuvas from a start node found
138138
* through the rb-tree while doing modifications on the rb-tree
@@ -141,7 +141,7 @@ struct drm_gpuva {
141141
struct list_head entry;
142142

143143
/**
144-
* @__subtree_last: needed by the interval tree, holding last-in-subtree
144+
* @rb.__subtree_last: needed by the interval tree, holding last-in-subtree
145145
*/
146146
u64 __subtree_last;
147147
} rb;
@@ -187,6 +187,8 @@ static inline void drm_gpuva_invalidate(struct drm_gpuva *va, bool invalidate)
187187
* drm_gpuva_invalidated() - indicates whether the backing BO of this &drm_gpuva
188188
* is invalidated
189189
* @va: the &drm_gpuva to check
190+
*
191+
* Returns: %true if the GPU VA is invalidated, %false otherwise
190192
*/
191193
static inline bool drm_gpuva_invalidated(struct drm_gpuva *va)
192194
{
@@ -252,12 +254,12 @@ struct drm_gpuvm {
252254
*/
253255
struct {
254256
/**
255-
* @tree: the rb-tree to track GPU VA mappings
257+
* @rb.tree: the rb-tree to track GPU VA mappings
256258
*/
257259
struct rb_root_cached tree;
258260

259261
/**
260-
* @list: the &list_head to track GPU VA mappings
262+
* @rb.list: the &list_head to track GPU VA mappings
261263
*/
262264
struct list_head list;
263265
} rb;
@@ -290,19 +292,19 @@ struct drm_gpuvm {
290292
*/
291293
struct {
292294
/**
293-
* @list: &list_head storing &drm_gpuvm_bos serving as
295+
* @extobj.list: &list_head storing &drm_gpuvm_bos serving as
294296
* external object
295297
*/
296298
struct list_head list;
297299

298300
/**
299-
* @local_list: pointer to the local list temporarily storing
300-
* entries from the external object list
301+
* @extobj.local_list: pointer to the local list temporarily
302+
* storing entries from the external object list
301303
*/
302304
struct list_head *local_list;
303305

304306
/**
305-
* @lock: spinlock to protect the extobj list
307+
* @extobj.lock: spinlock to protect the extobj list
306308
*/
307309
spinlock_t lock;
308310
} extobj;
@@ -312,19 +314,19 @@ struct drm_gpuvm {
312314
*/
313315
struct {
314316
/**
315-
* @list: &list_head storing &drm_gpuvm_bos currently being
316-
* evicted
317+
* @evict.list: &list_head storing &drm_gpuvm_bos currently
318+
* being evicted
317319
*/
318320
struct list_head list;
319321

320322
/**
321-
* @local_list: pointer to the local list temporarily storing
322-
* entries from the evicted object list
323+
* @evict.local_list: pointer to the local list temporarily
324+
* storing entries from the evicted object list
323325
*/
324326
struct list_head *local_list;
325327

326328
/**
327-
* @lock: spinlock to protect the evict list
329+
* @evict.lock: spinlock to protect the evict list
328330
*/
329331
spinlock_t lock;
330332
} evict;
@@ -344,6 +346,8 @@ void drm_gpuvm_init(struct drm_gpuvm *gpuvm, const char *name,
344346
*
345347
* This function acquires an additional reference to @gpuvm. It is illegal to
346348
* call this without already holding a reference. No locks required.
349+
*
350+
* Returns: the &struct drm_gpuvm pointer
347351
*/
348352
static inline struct drm_gpuvm *
349353
drm_gpuvm_get(struct drm_gpuvm *gpuvm)
@@ -533,12 +537,13 @@ struct drm_gpuvm_exec {
533537
*/
534538
struct {
535539
/**
536-
* @fn: The driver callback to lock additional &drm_gem_objects.
540+
* @extra.fn: The driver callback to lock additional
541+
* &drm_gem_objects.
537542
*/
538543
int (*fn)(struct drm_gpuvm_exec *vm_exec);
539544

540545
/**
541-
* @priv: driver private data for the @fn callback
546+
* @extra.priv: driver private data for the @fn callback
542547
*/
543548
void *priv;
544549
} extra;
@@ -589,7 +594,7 @@ void drm_gpuvm_resv_add_fence(struct drm_gpuvm *gpuvm,
589594
enum dma_resv_usage extobj_usage);
590595

591596
/**
592-
* drm_gpuvm_exec_resv_add_fence()
597+
* drm_gpuvm_exec_resv_add_fence() - add fence to private and all extobj
593598
* @vm_exec: the &drm_gpuvm_exec wrapper
594599
* @fence: fence to add
595600
* @private_usage: private dma-resv usage
@@ -608,10 +613,12 @@ drm_gpuvm_exec_resv_add_fence(struct drm_gpuvm_exec *vm_exec,
608613
}
609614

610615
/**
611-
* drm_gpuvm_exec_validate()
616+
* drm_gpuvm_exec_validate() - validate all BOs marked as evicted
612617
* @vm_exec: the &drm_gpuvm_exec wrapper
613618
*
614619
* See drm_gpuvm_validate().
620+
*
621+
* Returns: 0 on success, negative error code on failure.
615622
*/
616623
static inline int
617624
drm_gpuvm_exec_validate(struct drm_gpuvm_exec *vm_exec)
@@ -664,33 +671,33 @@ struct drm_gpuvm_bo {
664671
*/
665672
struct {
666673
/**
667-
* @gpuva: The list of linked &drm_gpuvas.
674+
* @list.gpuva: The list of linked &drm_gpuvas.
668675
*
669676
* It is safe to access entries from this list as long as the
670677
* GEM's gpuva lock is held. See also struct drm_gem_object.
671678
*/
672679
struct list_head gpuva;
673680

674681
/**
675-
* @entry: Structure containing all &list_heads serving as
682+
* @list.entry: Structure containing all &list_heads serving as
676683
* entry.
677684
*/
678685
struct {
679686
/**
680-
* @gem: List entry to attach to the &drm_gem_objects
681-
* gpuva list.
687+
* @list.entry.gem: List entry to attach to the
688+
* &drm_gem_objects gpuva list.
682689
*/
683690
struct list_head gem;
684691

685692
/**
686-
* @evict: List entry to attach to the &drm_gpuvms
687-
* extobj list.
693+
* @list.entry.evict: List entry to attach to the
694+
* &drm_gpuvms extobj list.
688695
*/
689696
struct list_head extobj;
690697

691698
/**
692-
* @evict: List entry to attach to the &drm_gpuvms evict
693-
* list.
699+
* @list.entry.evict: List entry to attach to the
700+
* &drm_gpuvms evict list.
694701
*/
695702
struct list_head evict;
696703
} entry;
@@ -713,6 +720,8 @@ drm_gpuvm_bo_obtain_prealloc(struct drm_gpuvm_bo *vm_bo);
713720
*
714721
* This function acquires an additional reference to @vm_bo. It is illegal to
715722
* call this without already holding a reference. No locks required.
723+
*
724+
* Returns: the &struct vm_bo pointer
716725
*/
717726
static inline struct drm_gpuvm_bo *
718727
drm_gpuvm_bo_get(struct drm_gpuvm_bo *vm_bo)
@@ -730,7 +739,8 @@ drm_gpuvm_bo_find(struct drm_gpuvm *gpuvm,
730739
void drm_gpuvm_bo_evict(struct drm_gpuvm_bo *vm_bo, bool evict);
731740

732741
/**
733-
* drm_gpuvm_bo_gem_evict()
742+
* drm_gpuvm_bo_gem_evict() - add/remove all &drm_gpuvm_bo's in the list
743+
* to/from the &drm_gpuvms evicted list
734744
* @obj: the &drm_gem_object
735745
* @evict: indicates whether @obj is evicted
736746
*
@@ -817,12 +827,12 @@ struct drm_gpuva_op_map {
817827
*/
818828
struct {
819829
/**
820-
* @addr: the base address of the new mapping
830+
* @va.addr: the base address of the new mapping
821831
*/
822832
u64 addr;
823833

824834
/**
825-
* @range: the range of the new mapping
835+
* @va.range: the range of the new mapping
826836
*/
827837
u64 range;
828838
} va;
@@ -832,12 +842,12 @@ struct drm_gpuva_op_map {
832842
*/
833843
struct {
834844
/**
835-
* @offset: the offset within the &drm_gem_object
845+
* @gem.offset: the offset within the &drm_gem_object
836846
*/
837847
u64 offset;
838848

839849
/**
840-
* @obj: the &drm_gem_object to map
850+
* @gem.obj: the &drm_gem_object to map
841851
*/
842852
struct drm_gem_object *obj;
843853
} gem;

0 commit comments

Comments
 (0)