On Thu, 2025-04-24 at 10:38 +0200, Pierre-Eric Pelloux-Prayer wrote: > 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.st...@pengutronix.de> > Acked-by: Maíra Canal <mca...@igalia.com> > Reviewed-by: Christian König <christian.koe...@amd.com> > Signed-off-by: Pierre-Eric Pelloux-Prayer > <pierre-eric.pelloux-pra...@amd.com> > --- > Documentation/gpu/drm-uapi.rst | 19 > +++++++++++++++++++ > .../gpu/drm/scheduler/gpu_scheduler_trace.h | 19 > +++++++++++++++++++ > 2 files changed, 38 insertions(+) > > diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm- > uapi.rst > index 69f72e71a96e..4863a4deb0ee 100644 > --- a/Documentation/gpu/drm-uapi.rst > +++ b/Documentation/gpu/drm-uapi.rst > @@ -693,3 +693,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 781b20349389..7e840d08ef39 100644 > --- a/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h > +++ b/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h > @@ -32,6 +32,25 @@ > #define TRACE_SYSTEM gpu_scheduler > #define TRACE_INCLUDE_FILE gpu_scheduler_trace > > +/** > + * DOC: uAPI trace events > + * > + * ``drm_sched_job_queue``, ``drm_sched_job_run``, > ``drm_sched_job_add_dep``, > + * ``drm_sched_job_done`` and ``drm_sched_job_unschedulable`` are > considered > + * stable uAPI. > + * > + * Common trace events attributes: > + * > + * * ``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 > + * > + */
For my understanding, why do you use the double apostrophes here? Also, the linking for the docu afair here two requires you to write &struct dma_fence.seqno If I am not mistaken https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#highlights-and-cross-references P. > + > DECLARE_EVENT_CLASS(drm_sched_job, > TP_PROTO(struct drm_sched_job *sched_job, struct > drm_sched_entity *entity), > TP_ARGS(sched_job, entity),
