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@pengutronix.de>
Acked-by: Maíra Canal <mcanal@igalia.com>
Reviewed-by: Christian König <christian.koenig@amd.com>
Signed-off-by: Pierre-Eric Pelloux-Prayer <pierre-eric.pelloux-prayer@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
+ *
+ */
+
 DECLARE_EVENT_CLASS(drm_sched_job,
 	    TP_PROTO(struct drm_sched_job *sched_job, struct drm_sched_entity *entity),
 	    TP_ARGS(sched_job, entity),
-- 
2.43.0

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.stach@pengutronix.de>
> Acked-by: Maíra Canal <mcanal@igalia.com>
> Reviewed-by: Christian König <christian.koenig@amd.com>
> Signed-off-by: Pierre-Eric Pelloux-Prayer
> <pierre-eric.pelloux-prayer@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),

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.stach@pengutronix.de>
>> Acked-by: Maíra Canal <mcanal@igalia.com>
>> Reviewed-by: Christian König <christian.koenig@amd.com>
>> Signed-off-by: Pierre-Eric Pelloux-Prayer
>> <pierre-eric.pelloux-prayer@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),