Hi Pierre,
On 6/14/24 05:16, 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.
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 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.
I would write it:
"See Documentation/trace/tracepoints.rst for information about using
Linux Kernel Tracepoints."
+In the drm subsystem, some events are considered stable uAPI to avoid
Super small nit: s/drm/DRM
+breaking tools (eg: gpuvis, umr) relying on them. Stable means that fields
Super small nit:
1. s/eg:/e.g.:
2. s/gpuvis/GPUVis (maybe a URL to it?)
3. Maybe a URL to umr?
+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``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Super small nit: from the rest of the file, I see that a title was never
needed. Do we need it here?
+
+.. 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.
Super small nit again, but I believe we should format function names
with ``foo()``, if I understood kerneldoc documentation correctly.
Apart from all those nits, I completely agree with Lucas, it is great to
see this improvement.
Acked-by: Maíra Canal <mcanal@xxxxxxxxxx>
Best Regards,
- Maíra
+ *
+ * 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. */
