On 11/01/2025 06:28, Randy Dunlap wrote:
> Use the correct format for all kernel-doc comments.
> Use structname.membername for named structs.
> Don't precede function names in kernel-doc with '@' sign.
> Use the correct function parameter names in kernel-doc comments.
>
> This fixes around 80 kernel-doc warnings.
>
> Signed-off-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> Cc: Boris Brezillon <boris.brezillon@xxxxxxxxxxxxx>
> Cc: Steven Price <steven.price@xxxxxxx>
> Cc: Liviu Dudau <liviu.dudau@xxxxxxx>
> Cc: Maarten Lankhorst <maarten.lankhorst@xxxxxxxxxxxxxxx>
> Cc: Maxime Ripard <mripard@xxxxxxxxxx>
> Cc: Thomas Zimmermann <tzimmermann@xxxxxxx>
> Cc: David Airlie <airlied@xxxxxxxxx>
> Cc: Simona Vetter <simona@xxxxxxxx>
Thanks for doing this - it's been on my TODO list to take a look at
this, and I know we've got more issues in other files.
Reviewed-by: Steven Price <steven.price@xxxxxxx>
I'll push this to drm-misc-next.
> ---
> drivers/gpu/drm/panthor/panthor_mmu.c | 71 ++++++++++++------------
> 1 file changed, 37 insertions(+), 34 deletions(-)
>
> --- linux-next-20250108.orig/drivers/gpu/drm/panthor/panthor_mmu.c
> +++ linux-next-20250108/drivers/gpu/drm/panthor/panthor_mmu.c
> @@ -53,26 +53,27 @@ struct panthor_mmu {
> /** @irq: The MMU irq. */
> struct panthor_irq irq;
>
> - /** @as: Address space related fields.
> + /**
> + * @as: Address space related fields.
> *
> * The GPU has a limited number of address spaces (AS) slots, forcing
> * us to re-assign them to re-assign slots on-demand.
> */
> struct {
> - /** @slots_lock: Lock protecting access to all other AS fields. */
> + /** @as.slots_lock: Lock protecting access to all other AS fields. */
> struct mutex slots_lock;
>
> - /** @alloc_mask: Bitmask encoding the allocated slots. */
> + /** @as.alloc_mask: Bitmask encoding the allocated slots. */
> unsigned long alloc_mask;
>
> - /** @faulty_mask: Bitmask encoding the faulty slots. */
> + /** @as.faulty_mask: Bitmask encoding the faulty slots. */
> unsigned long faulty_mask;
>
> - /** @slots: VMs currently bound to the AS slots. */
> + /** @as.slots: VMs currently bound to the AS slots. */
> struct panthor_as_slot slots[MAX_AS_SLOTS];
>
> /**
> - * @lru_list: List of least recently used VMs.
> + * @as.lru_list: List of least recently used VMs.
> *
> * We use this list to pick a VM to evict when all slots are
> * used.
> @@ -87,16 +88,16 @@ struct panthor_mmu {
>
> /** @vm: VMs management fields */
> struct {
> - /** @lock: Lock protecting access to list. */
> + /** @vm.lock: Lock protecting access to list. */
> struct mutex lock;
>
> - /** @list: List containing all VMs. */
> + /** @vm.list: List containing all VMs. */
> struct list_head list;
>
> - /** @reset_in_progress: True if a reset is in progress. */
> + /** @vm.reset_in_progress: True if a reset is in progress. */
> bool reset_in_progress;
>
> - /** @wq: Workqueue used for the VM_BIND queues. */
> + /** @vm.wq: Workqueue used for the VM_BIND queues. */
> struct workqueue_struct *wq;
> } vm;
> };
> @@ -143,14 +144,14 @@ struct panthor_vma {
> struct panthor_vm_op_ctx {
> /** @rsvd_page_tables: Pages reserved for the MMU page table update. */
> struct {
> - /** @count: Number of pages reserved. */
> + /** @rsvd_page_tables.count: Number of pages reserved. */
> u32 count;
>
> - /** @ptr: Point to the first unused page in the @pages table. */
> + /** @rsvd_page_tables.ptr: Point to the first unused page in the @pages table. */
> u32 ptr;
>
> /**
> - * @page: Array of pages that can be used for an MMU page table update.
> + * @rsvd_page_tables.pages: Array of pages that can be used for an MMU page table update.
> *
> * After an VM operation, there might be free pages left in this array.
> * They should be returned to the pt_cache as part of the op_ctx cleanup.
> @@ -172,10 +173,10 @@ struct panthor_vm_op_ctx {
>
> /** @va: Virtual range targeted by the VM operation. */
> struct {
> - /** @addr: Start address. */
> + /** @va.addr: Start address. */
> u64 addr;
>
> - /** @range: Range size. */
> + /** @va.range: Range size. */
> u64 range;
> } va;
>
> @@ -195,14 +196,14 @@ struct panthor_vm_op_ctx {
>
> /** @map: Fields specific to a map operation. */
> struct {
> - /** @vm_bo: Buffer object to map. */
> + /** @map.vm_bo: Buffer object to map. */
> struct drm_gpuvm_bo *vm_bo;
>
> - /** @bo_offset: Offset in the buffer object. */
> + /** @map.bo_offset: Offset in the buffer object. */
> u64 bo_offset;
>
> /**
> - * @sgt: sg-table pointing to pages backing the GEM object.
> + * @map.sgt: sg-table pointing to pages backing the GEM object.
> *
> * This is gathered at job creation time, such that we don't have
> * to allocate in ::run_job().
> @@ -210,7 +211,7 @@ struct panthor_vm_op_ctx {
> struct sg_table *sgt;
>
> /**
> - * @new_vma: The new VMA object that will be inserted to the VA tree.
> + * @map.new_vma: The new VMA object that will be inserted to the VA tree.
> */
> struct panthor_vma *new_vma;
> } map;
> @@ -304,27 +305,27 @@ struct panthor_vm {
>
> /** @kernel_auto_va: Automatic VA-range for kernel BOs. */
> struct {
> - /** @start: Start of the automatic VA-range for kernel BOs. */
> + /** @kernel_auto_va.start: Start of the automatic VA-range for kernel BOs. */
> u64 start;
>
> - /** @size: Size of the automatic VA-range for kernel BOs. */
> + /** @kernel_auto_va.size: Size of the automatic VA-range for kernel BOs. */
> u64 end;
> } kernel_auto_va;
>
> /** @as: Address space related fields. */
> struct {
> /**
> - * @id: ID of the address space this VM is bound to.
> + * @as.id: ID of the address space this VM is bound to.
> *
> * A value of -1 means the VM is inactive/not bound.
> */
> int id;
>
> - /** @active_cnt: Number of active users of this VM. */
> + /** @as.active_cnt: Number of active users of this VM. */
> refcount_t active_cnt;
>
> /**
> - * @lru_node: Used to instead the VM in the panthor_mmu::as::lru_list.
> + * @as.lru_node: Used to instead the VM in the panthor_mmu::as::lru_list.
> *
> * Active VMs should not be inserted in the LRU list.
> */
> @@ -336,13 +337,13 @@ struct panthor_vm {
> */
> struct {
> /**
> - * @pool: The heap pool attached to this VM.
> + * @heaps.pool: The heap pool attached to this VM.
> *
> * Will stay NULL until someone creates a heap context on this VM.
> */
> struct panthor_heap_pool *pool;
>
> - /** @lock: Lock used to protect access to @pool. */
> + /** @heaps.lock: Lock used to protect access to @pool. */
> struct mutex lock;
> } heaps;
>
> @@ -408,7 +409,7 @@ struct panthor_vm_bind_job {
> struct panthor_vm_op_ctx ctx;
> };
>
> -/**
> +/*
> * @pt_cache: Cache used to allocate MMU page tables.
> *
> * The pre-allocation pattern forces us to over-allocate to plan for
> @@ -478,7 +479,7 @@ static void *alloc_pt(void *cookie, size
> }
>
> /**
> - * @free_pt() - Custom page table free function
> + * free_pt() - Custom page table free function
> * @cookie: Cookie passed at page table allocation time.
> * @data: Page table to free.
> * @size: Size of the page table. This size should be fixed,
> @@ -697,7 +698,7 @@ static void panthor_vm_release_as_locked
>
> /**
> * panthor_vm_active() - Flag a VM as active
> - * @VM: VM to flag as active.
> + * @vm: VM to flag as active.
> *
> * Assigns an address space to a VM so it can be used by the GPU/MCU.
> *
> @@ -801,7 +802,7 @@ out_dev_exit:
>
> /**
> * panthor_vm_idle() - Flag a VM idle
> - * @VM: VM to flag as idle.
> + * @vm: VM to flag as idle.
> *
> * When we know the GPU is done with the VM (no more jobs to process),
> * we can relinquish the AS slot attached to this VM, if any.
> @@ -1017,7 +1018,7 @@ static int flags_to_prot(u32 flags)
>
> /**
> * panthor_vm_alloc_va() - Allocate a region in the auto-va space
> - * @VM: VM to allocate a region on.
> + * @vm: VM to allocate a region on.
> * @va: start of the VA range. Can be PANTHOR_VM_KERNEL_AUTO_VA if the user
> * wants the VA to be automatically allocated from the auto-VA range.
> * @size: size of the VA range.
> @@ -1063,7 +1064,7 @@ panthor_vm_alloc_va(struct panthor_vm *v
>
> /**
> * panthor_vm_free_va() - Free a region allocated with panthor_vm_alloc_va()
> - * @VM: VM to free the region on.
> + * @vm: VM to free the region on.
> * @va_node: Memory node representing the region to free.
> */
> void panthor_vm_free_va(struct panthor_vm *vm, struct drm_mm_node *va_node)
> @@ -1492,9 +1493,9 @@ panthor_vm_create_check_args(const struc
>
> /**
> * panthor_vm_pool_create_vm() - Create a VM
> + * @ptdev: The panthor device
> * @pool: The VM to create this VM on.
> - * @kernel_va_start: Start of the region reserved for kernel objects.
> - * @kernel_va_range: Size of the region reserved for kernel objects.
> + * @args: VM creation args.
> *
> * Return: a positive VM ID on success, a negative error code otherwise.
> */
> @@ -1558,6 +1559,8 @@ static void panthor_vm_destroy(struct pa
> *
> * The VM resources are freed when the last reference on the VM object is
> * dropped.
> + *
> + * Return: %0 for success, negative errno value for failure
> */
> int panthor_vm_pool_destroy_vm(struct panthor_vm_pool *pool, u32 handle)
> {
