[PATCH v5 4/4] drm/doc: document some tracepoints as uAPI

[Lucas Stach]

Hi Pierre-Eric,

Am Montag, dem 01.07.2024 um 14:44 +0200 schrieb Pierre-Eric Pelloux-
Prayer:
> [adding more people to this thread based on the drivers using gpu_scheduler]
> 
> Hi,
> 
> Christian's comment on patch 1/5 will be addressed in v6, but before 
> pushing another version I'd like to know if there's a consensus among 
> the drivers maintainers regarding the changes proposed in this series.
> 
I absolutely agree with the changes done in this series. The pointer
values in the existing tracepoints are close to useless. Being able to
tie events together through a stable representation of the fences is a
very welcome improvement.

Acked-by: Lucas Stach <l.stach at pengutronix.de>

Regards,
Lucas

> Thanks!
> Pierre-Eric
> 
> 
> Le 14/06/2024 à 10:16, Pierre-Eric Pelloux-Prayer a écrit :
> > This commit adds a document section in drm-uapi.rst about tracepoints,
> > and mark the events gpu_scheduler_trace.h as stable uAPI.
> > 
> > The goal is to explicitly state that tools can rely on the fields,
> > formats and semantics of these events.
> > 
> > Signed-off-by: Pierre-Eric Pelloux-Prayer <pierre-eric.pelloux-prayer at amd.com>
> > ---
> >   Documentation/gpu/drm-uapi.rst                | 19 ++++++++++++++++
> >   .../gpu/drm/scheduler/gpu_scheduler_trace.h   | 22 +++++++++++++++++++
> >   2 files changed, 41 insertions(+)
> > 
> > diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> > index 370d820be248..78496793a8f0 100644
> > --- a/Documentation/gpu/drm-uapi.rst
> > +++ b/Documentation/gpu/drm-uapi.rst
> > @@ -570,3 +570,22 @@ dma-buf interoperability
> >   
> >   Please see Documentation/userspace-api/dma-buf-alloc-exchange.rst for
> >   information on how dma-buf is integrated and exposed within DRM.
> > +
> > +
> > +Trace events
> > +============
> > +
> > +See Documentation/trace/tracepoints.rst for the tracepoints documentation.
> > +In the drm subsystem, some events are considered stable uAPI to avoid
> > +breaking tools (eg: gpuvis, umr) relying on them. Stable means that fields
> > +cannot be removed, nor their formatting updated. Adding new fields is
> > +possible, under the normal uAPI requirements.
> > +
> > +Stable uAPI events
> > +------------------
> > +
> > +From ``drivers/gpu/drm/scheduler/gpu_scheduler_trace.h``
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +.. kernel-doc::  drivers/gpu/drm/scheduler/gpu_scheduler_trace.h
> > +   :doc: uAPI trace events
> > \ No newline at end of file
> > diff --git a/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h b/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h
> > index 0abcad26839c..63113803cdd5 100644
> > --- a/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h
> > +++ b/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h
> > @@ -33,6 +33,28 @@
> >   #define TRACE_SYSTEM gpu_scheduler
> >   #define TRACE_INCLUDE_FILE gpu_scheduler_trace
> >   
> > +
> > +/**
> > + * DOC: uAPI trace events
> > + *
> > + * ``drm_sched_job``, ``drm_run_job``, ``drm_sched_process_job``,
> > + * and ``drm_sched_job_wait_dep`` are considered stable uAPI.
> > + *
> > + * Common trace events attributes:
> > + *
> > + * * ``id``    - this is &drm_sched_job->id. It uniquely idenfies a job
> > + *   inside a &struct drm_gpu_scheduler.
> > + *
> > + * * ``dev``   - the dev_name() of the device running the job.
> > + *
> > + * * ``ring``  - the hardware ring running the job. Together with ``dev`` it
> > + *   uniquely identifies where the job is going to be executed.
> > + *
> > + * * ``fence`` - the &dma_fence.context and the &dma_fence.seqno of
> > + *   &drm_sched_fence.finished
> > + *
> > + */
> > +
> >   #ifndef __TRACE_EVENT_GPU_SCHEDULER_PRINT_FN
> >   #define __TRACE_EVENT_GPU_SCHEDULER_PRINT_FN
> >   /* Similar to trace_print_array_seq but for fences. */