Hi, Am Donnerstag, dem 14.11.2024 um 11:01 +0100 schrieb Pierre-Eric Pelloux-Prayer: > 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. > > Acked-by: Lucas Stach <l.stach@xxxxxxxxxxxxxx> > Acked-by: Maíra Canal <mcanal@xxxxxxxxxx> > Signed-off-by: Pierre-Eric Pelloux-Prayer <pierre-eric.pelloux-prayer@xxxxxxx> > --- > 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 b75cc9a70d1f..9603ac0f4c09 100644 > --- a/Documentation/gpu/drm-uapi.rst > +++ b/Documentation/gpu/drm-uapi.rst > @@ -583,3 +583,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 information about using > +Linux Kernel Tracepoints. > +In the DRM subsystem, some events are considered stable uAPI to avoid > +breaking tools (e.g.: 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 8340c7c0c6b6..ec230e558961 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. > + * It might be nitpicky, but as we change the format of the tracepoints anyway and are about to declare them a ABI: I don't really like the ring name. Yes, in most hardware implementations today the mechanism to queue jobs is a ring buffer, but there are other mechanisms to schedule jobs (see for example the lima driver). Maybe we could rename this to something a bit more generic like "dev_queue" or something like that? Regards, Lucas > + * * ``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. */
