Commit 1780e94a authored by Pierre-Eric Pelloux-Prayer's avatar Pierre-Eric Pelloux-Prayer Committed by Philipp Stanner
Browse files

drm/doc: Document some tracepoints as uAPI 



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: default avatarLucas Stach <l.stach@pengutronix.de>
Acked-by: default avatarMaíra Canal <mcanal@igalia.com>
Reviewed-by: default avatarChristian König <christian.koenig@amd.com>
Signed-off-by: default avatarPierre-Eric Pelloux-Prayer <pierre-eric.pelloux-prayer@amd.com>
Signed-off-by: default avatarPhilipp Stanner <phasta@kernel.org>
Link: https://lore.kernel.org/r/20250526125505.2360-10-pierre-eric.pelloux-prayer@amd.com
parent 4f7fa5fa

Documentation/gpu/drm-uapi.rst

+19 −0
Original line number Diff line number Diff line
@@ -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

drivers/gpu/drm/scheduler/gpu_scheduler_trace.h

+22 −0
Original line number Diff line number Diff line
@@ -32,6 +32,28 @@ 
#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 &struct dma_fence.context and the &struct dma_fence.seqno of

 *   &struct drm_sched_fence.finished

 *

 * All the events depends on drm_sched_job_arm() having been called already for

 * the job because they use &struct drm_sched_job.sched or

 * &struct drm_sched_job.s_fence.

 */



DECLARE_EVENT_CLASS(drm_sched_job,

	    TP_PROTO(struct drm_sched_job *sched_job, struct drm_sched_entity *entity),

	    TP_ARGS(sched_job, entity),