Hi,
Le 14/05/2025 à 14:53, Philipp Stanner a écrit :
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?
To get similar formatting to function arguments and make the output a bit nicer
to read.
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
Indeed, thanks. I fixed this.
Pierre-Eric
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),
