Re: [PATCH v3 1/5] drm/amdgpu: Expand kernel-doc in amdgpu_ring

["Timur Kristóf" <timur.kristof@gmail.com>]

On 10/20/25 21:38, Rodrigo Siqueira wrote:
> Expand the kernel-doc about amdgpu_ring and add some tiny improvements.
> 
> Cc: Alex Deucher <alexander.deucher@amd.com>
> Cc: Christian König <christian.koenig@amd.com>
> Cc: Timur Kristóf <timur.kristof@gmail.com>
> Signed-off-by: Rodrigo Siqueira <siqueira@igalia.com>
> ---
>   drivers/gpu/drm/amd/amdgpu/amdgpu_ring.c | 15 ++++++++++++---
>   drivers/gpu/drm/amd/amdgpu/amdgpu_ring.h |  2 ++
>   2 files changed, 14 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.c
> index 5ec5c3ff22bb..29de8dbe2917 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.c
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.c
> @@ -75,8 +75,16 @@ unsigned int amdgpu_ring_max_ibs(enum amdgpu_ring_type type)
>    * @ring: amdgpu_ring structure holding ring information
>    * @ndw: number of dwords to allocate in the ring buffer
>    *
> - * Allocate @ndw dwords in the ring buffer (all asics).
> - * Returns 0 on success, error on failure.
> + * Allocate @ndw dwords in the ring buffer (it works in all ASICs). When
> + * inspecting the code, you may encounter places where this function is invoked
> + * like this: amdgpu_ring_alloc(ring, X + Y + Z), where X, Y, and Z are integer
> + * numbers. The idea of using each integer addition instead of the final result
> + * is to explicitly indicate each block of operation that will be inserted into
> + * the ring.

To clarify this further, I recommend using the term "packet" instead of 
"block of operation".

> + *
> + * Returns:
> + * 0 on success, otherwise -ENOMEM if it tries to allocate more than the
> + * maximum dword allowed for one submission.
>    */
>   int amdgpu_ring_alloc(struct amdgpu_ring *ring, unsigned int ndw)
>   {
> @@ -122,7 +130,8 @@ static void amdgpu_ring_alloc_reemit(struct amdgpu_ring *ring, unsigned int ndw)
>   		ring->funcs->begin_use(ring);
>   }
>   
> -/** amdgpu_ring_insert_nop - insert NOP packets
> +/**
> + * amdgpu_ring_insert_nop - insert NOP packets
>    *
>    * @ring: amdgpu_ring structure holding ring information
>    * @count: the number of NOP packets to insert
> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.h b/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.h
> index 87b962df5460..e83589619a92 100644
> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.h
> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.h
> @@ -62,6 +62,8 @@ enum amdgpu_ring_priority_level {
>   #define AMDGPU_FENCE_FLAG_64BIT         (1 << 0)
>   #define AMDGPU_FENCE_FLAG_INT           (1 << 1)
>   #define AMDGPU_FENCE_FLAG_TC_WB_ONLY    (1 << 2)
> +
> +/* Ensure the execution in case of preemption or reset */
>   #define AMDGPU_FENCE_FLAG_EXEC          (1 << 3)
>   
>   #define to_amdgpu_ring(s) container_of((s), struct amdgpu_ring, sched)