[PATCH v11 00/10] Improve gpu_scheduler trace events + UAPI

[PATCH v11 00/10] Improve gpu_scheduler trace events + UAPI

[Pierre-Eric Pelloux-Prayer]

Hi,

The initial goal of this series was to improve the drm and amdgpu
trace events to be able to expose more of the inner workings of
the scheduler and drivers to developers via tools.

Then, the series evolved to become focused only on gpu_scheduler.
The changes around vblank events will be part of a different
series, as well as the amdgpu ones.

Moreover Sima suggested to make some trace events stable uAPI,
so tools can rely on them long term.

The first patches extend and cleanup the gpu scheduler events,
then add a documentation entry in drm-uapi.rst.

The last 2 patches are new in v8. One is based on a suggestion
from Tvrtko and gets rid of drm_sched_job::id. The other is a
cleanup of amdgpu trace events to use the fence=%llu:%llu format.

The drm_sched_job patches don't affect gpuvis which has code to parse
the gpu_scheduler events but these events are not enabled.

Changes since v10:
* fixed 2 errors reported by kernel test robot
* rebased on drm-misc-next

Changes since v9:
* fixed documentation link syntax
* fixed typos in commit messages
* spelled out that these events cannot be used before
  drm_sched_job_arm has been called

Changes since v8:
* swapped patches 8 & 9
* rebased on drm-next

Changes since v7:
* uint64_t -> u64
* reworked dependencies tracing (Tvrtko)
* use common name prefix for all events (Tvrtko)
* dropped drm_sched_job::id (Tvrtko)

Useful links:
- userspace tool using the updated events:
https://gitlab.freedesktop.org/tomstdenis/umr/-/merge_requests/37
- v8:
https://lists.freedesktop.org/archives/dri-devel/2025-March/496781.html

Pierre-Eric Pelloux-Prayer (10):
  drm/debugfs: Output client_id in in drm_clients_info
  drm/sched: Store the drm client_id in drm_sched_fence
  drm/sched: Add device name to the drm_sched_process_job event
  drm/sched: Cleanup gpu_scheduler trace events
  drm/sched: Trace dependencies for GPU jobs
  drm/sched: Add the drm_client_id to the drm_sched_run/exec_job events
  drm/sched: Cleanup event names
  drm: Get rid of drm_sched_job.id
  drm/doc: Document some tracepoints as uAPI
  drm/amdgpu: update trace format to match gpu_scheduler_trace

 Documentation/gpu/drm-uapi.rst                |  19 ++++
 drivers/accel/amdxdna/aie2_ctx.c              |   3 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd.c    |   2 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c        |   3 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_job.c       |   8 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_job.h       |   3 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_trace.h     |  32 ++----
 drivers/gpu/drm/drm_debugfs.c                 |  10 +-
 drivers/gpu/drm/etnaviv/etnaviv_gem_submit.c  |   2 +-
 drivers/gpu/drm/imagination/pvr_job.c         |   2 +-
 drivers/gpu/drm/imagination/pvr_queue.c       |   5 +-
 drivers/gpu/drm/imagination/pvr_queue.h       |   2 +-
 drivers/gpu/drm/lima/lima_gem.c               |   2 +-
 drivers/gpu/drm/lima/lima_sched.c             |   6 +-
 drivers/gpu/drm/lima/lima_sched.h             |   3 +-
 drivers/gpu/drm/lima/lima_trace.h             |   6 +-
 drivers/gpu/drm/msm/msm_gem_submit.c          |   8 +-
 drivers/gpu/drm/nouveau/nouveau_sched.c       |   3 +-
 drivers/gpu/drm/panfrost/panfrost_drv.c       |   2 +-
 drivers/gpu/drm/panthor/panthor_drv.c         |   3 +-
 drivers/gpu/drm/panthor/panthor_mmu.c         |   2 +-
 drivers/gpu/drm/panthor/panthor_sched.c       |   5 +-
 drivers/gpu/drm/panthor/panthor_sched.h       |   3 +-
 .../gpu/drm/scheduler/gpu_scheduler_trace.h   | 103 +++++++++++++-----
 drivers/gpu/drm/scheduler/sched_entity.c      |  16 ++-
 drivers/gpu/drm/scheduler/sched_fence.c       |   4 +-
 drivers/gpu/drm/scheduler/sched_internal.h    |   2 +-
 drivers/gpu/drm/scheduler/sched_main.c        |  12 +-
 .../gpu/drm/scheduler/tests/mock_scheduler.c  |   3 +-
 drivers/gpu/drm/v3d/v3d_submit.c              |   2 +-
 drivers/gpu/drm/xe/xe_sched_job.c             |   3 +-
 include/drm/gpu_scheduler.h                   |  13 ++-
 32 files changed, 191 insertions(+), 101 deletions(-)

-- 
2.43.0

[PATCH v11 09/10] drm/doc: Document some tracepoints as uAPI

[Pierre-Eric Pelloux-Prayer]

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   | 22 +++++++++++++++++++
 2 files changed, 41 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..261713dd7d5a 100644
--- a/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h
+++ b/drivers/gpu/drm/scheduler/gpu_scheduler_trace.h
@@ -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),
-- 
2.43.0

Re: [PATCH v11 00/10] Improve gpu_scheduler trace events + UAPI

[Philipp Stanner]

On Mon, 2025-05-26 at 14:54 +0200, Pierre-Eric Pelloux-Prayer wrote:
> Hi,
> 
> The initial goal of this series was to improve the drm and amdgpu
> trace events to be able to expose more of the inner workings of
> the scheduler and drivers to developers via tools.
> 
> Then, the series evolved to become focused only on gpu_scheduler.
> The changes around vblank events will be part of a different
> series, as well as the amdgpu ones.
> 
> Moreover Sima suggested to make some trace events stable uAPI,
> so tools can rely on them long term.
> 
> The first patches extend and cleanup the gpu scheduler events,
> then add a documentation entry in drm-uapi.rst.
> 
> The last 2 patches are new in v8. One is based on a suggestion
> from Tvrtko and gets rid of drm_sched_job::id. The other is a
> cleanup of amdgpu trace events to use the fence=%llu:%llu format.
> 
> The drm_sched_job patches don't affect gpuvis which has code to parse
> the gpu_scheduler events but these events are not enabled.
> 
> Changes since v10:
> * fixed 2 errors reported by kernel test robot
> * rebased on drm-misc-next
> 
> Changes since v9:
> * fixed documentation link syntax
> * fixed typos in commit messages
> * spelled out that these events cannot be used before
>   drm_sched_job_arm has been called
> 
> Changes since v8:
> * swapped patches 8 & 9
> * rebased on drm-next
> 
> Changes since v7:
> * uint64_t -> u64
> * reworked dependencies tracing (Tvrtko)
> * use common name prefix for all events (Tvrtko)
> * dropped drm_sched_job::id (Tvrtko)
> 
> Useful links:
> - userspace tool using the updated events:
> https://gitlab.freedesktop.org/tomstdenis/umr/-/merge_requests/37
> - v8:
> https://lists.freedesktop.org/archives/dri-devel/2025-March/496781.html
> 
> Pierre-Eric Pelloux-Prayer (10):
>   drm/debugfs: Output client_id in in drm_clients_info
>   drm/sched: Store the drm client_id in drm_sched_fence
>   drm/sched: Add device name to the drm_sched_process_job event
>   drm/sched: Cleanup gpu_scheduler trace events
>   drm/sched: Trace dependencies for GPU jobs
>   drm/sched: Add the drm_client_id to the drm_sched_run/exec_job
> events
>   drm/sched: Cleanup event names
>   drm: Get rid of drm_sched_job.id
>   drm/doc: Document some tracepoints as uAPI
>   drm/amdgpu: update trace format to match gpu_scheduler_trace


Applied to drm-misc-next


Thanks
P.

> 
>  Documentation/gpu/drm-uapi.rst                |  19 ++++
>  drivers/accel/amdxdna/aie2_ctx.c              |   3 +-
>  drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd.c    |   2 +-
>  drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c        |   3 +-
>  drivers/gpu/drm/amd/amdgpu/amdgpu_job.c       |   8 +-
>  drivers/gpu/drm/amd/amdgpu/amdgpu_job.h       |   3 +-
>  drivers/gpu/drm/amd/amdgpu/amdgpu_trace.h     |  32 ++----
>  drivers/gpu/drm/drm_debugfs.c                 |  10 +-
>  drivers/gpu/drm/etnaviv/etnaviv_gem_submit.c  |   2 +-
>  drivers/gpu/drm/imagination/pvr_job.c         |   2 +-
>  drivers/gpu/drm/imagination/pvr_queue.c       |   5 +-
>  drivers/gpu/drm/imagination/pvr_queue.h       |   2 +-
>  drivers/gpu/drm/lima/lima_gem.c               |   2 +-
>  drivers/gpu/drm/lima/lima_sched.c             |   6 +-
>  drivers/gpu/drm/lima/lima_sched.h             |   3 +-
>  drivers/gpu/drm/lima/lima_trace.h             |   6 +-
>  drivers/gpu/drm/msm/msm_gem_submit.c          |   8 +-
>  drivers/gpu/drm/nouveau/nouveau_sched.c       |   3 +-
>  drivers/gpu/drm/panfrost/panfrost_drv.c       |   2 +-
>  drivers/gpu/drm/panthor/panthor_drv.c         |   3 +-
>  drivers/gpu/drm/panthor/panthor_mmu.c         |   2 +-
>  drivers/gpu/drm/panthor/panthor_sched.c       |   5 +-
>  drivers/gpu/drm/panthor/panthor_sched.h       |   3 +-
>  .../gpu/drm/scheduler/gpu_scheduler_trace.h   | 103 +++++++++++++---
> --
>  drivers/gpu/drm/scheduler/sched_entity.c      |  16 ++-
>  drivers/gpu/drm/scheduler/sched_fence.c       |   4 +-
>  drivers/gpu/drm/scheduler/sched_internal.h    |   2 +-
>  drivers/gpu/drm/scheduler/sched_main.c        |  12 +-
>  .../gpu/drm/scheduler/tests/mock_scheduler.c  |   3 +-
>  drivers/gpu/drm/v3d/v3d_submit.c              |   2 +-
>  drivers/gpu/drm/xe/xe_sched_job.c             |   3 +-
>  include/drm/gpu_scheduler.h                   |  13 ++-
>  32 files changed, 191 insertions(+), 101 deletions(-)
>