Hi,
On Mon, 2025-08-25 at 17:19 +0200, Christian König wrote:
> On 25.08.25 01:29, Rodrigo Siqueira wrote:
> > Expand the kernel-doc about amdgpu_ring and add some tiny
> > improvements.
> >
> > Cc: Alex Deucher <alexander.deuc...@amd.com>
> > Cc: Christian König <christian.koe...@amd.com>
> > Cc: Timur Kristóf <timur.kris...@gmail.com>
> > Signed-off-by: Rodrigo Siqueira <sique...@igalia.com>
> > ---
> > drivers/gpu/drm/amd/amdgpu/amdgpu_ring.c | 14 +++++++++++---
> > drivers/gpu/drm/amd/amdgpu/amdgpu_ring.h | 2 ++
> > 2 files changed, 13 insertions(+), 3 deletions(-)
> >
> > diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.c
> > b/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.c
> > index 6379bb25bf5c..80dd6f58a53b 100644
> > --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.c
> > +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_ring.c
> > @@ -75,8 +75,15 @@ 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 called
> > + * amdgpu_ring_alloc(ring, X + Y + Z), where X, Y, and Z are
> > integer numbers.
> > + * This indicates the number of dword operations to be inserted
> > into the ring
> > + * per operation.
>
> I think explaining that is overkill, but the remaining comments are
> valid.
>
> With the change above removed that patch is Reviewed-by: Christian
> König <christian.koe...@amd.com>.
>
> Regards,
> Christian.
I respectfully disagree with that.
This stuff may be obvious to you, having worked on it for many years.
But it was super confusing to me when I first looked at it, so I'm glad
to see Siquiera added it here. It may help the next newcomer.
As a side note, in many places it's not fully clear when something is
in bytes vs. dwords so it's also good to emphasize that these represent
dwords of packets.
>
> > + *
> > + * 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 +129,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 7670f5d82b9e..d27dbb3c109f 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)
