| Message ID | 20240614081657.408397-5-pierre-eric.pelloux-prayer@amd.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Improve gpu_scheduler trace events + uAPI | expand |
[adding more people to this thread based on the drivers using gpu_scheduler] Hi, Christian's comment on patch 1/5 will be addressed in v6, but before pushing another version I'd like to know if there's a consensus among the drivers maintainers regarding the changes proposed in this series. Thanks! Pierre-Eric Le 14/06/2024 à 10:16, Pierre-Eric Pelloux-Prayer a écrit : > 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@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 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. > +In the drm subsystem, some events are considered stable uAPI to avoid > +breaking tools (eg: 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 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. > + * > + * 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. */
Am Freitag, dem 14.06.2024 um 10:16 +0200 schrieb 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. > > 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 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. > +In the drm subsystem, some events are considered stable uAPI to avoid > +breaking tools (eg: 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. What are those "normal uAPI requirements" in this context? Aside from not being able to remove or change any fields? Regards, Lucas > + > +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 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. > + * > + * 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. */
Hi Pierre-Eric, Am Montag, dem 01.07.2024 um 14:44 +0200 schrieb Pierre-Eric Pelloux- Prayer: > [adding more people to this thread based on the drivers using gpu_scheduler] > > Hi, > > Christian's comment on patch 1/5 will be addressed in v6, but before > pushing another version I'd like to know if there's a consensus among > the drivers maintainers regarding the changes proposed in this series. > I absolutely agree with the changes done in this series. The pointer values in the existing tracepoints are close to useless. Being able to tie events together through a stable representation of the fences is a very welcome improvement. Acked-by: Lucas Stach <l.stach@pengutronix.de> Regards, Lucas > Thanks! > Pierre-Eric > > > Le 14/06/2024 à 10:16, Pierre-Eric Pelloux-Prayer a écrit : > > 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@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 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. > > +In the drm subsystem, some events are considered stable uAPI to avoid > > +breaking tools (eg: 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 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. > > + * > > + * 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. */
Le 03/07/2024 à 12:46, Lucas Stach a écrit : > Am Freitag, dem 14.06.2024 um 10:16 +0200 schrieb 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. >> >> 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 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. >> +In the drm subsystem, some events are considered stable uAPI to avoid >> +breaking tools (eg: 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. > > What are those "normal uAPI requirements" in this context? Aside from > not being able to remove or change any fields? The ones from https://dri.freedesktop.org/docs/drm/gpu/drm-uapi.html#open-source-userspace-requirements For the trace events, the sentence "patches must be reviewed and ready for merging into a suitable and canonical upstream project" could be read as "gpuvis patches must be reviewed and ready for merging". Thanks, Pierre-Eric > > Regards, > Lucas > >> + >> +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 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. >> + * >> + * 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. */
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@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 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@igalia.com> 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. */
Hi Maíra, Le 03/07/2024 à 17:41, Maíra Canal a écrit : > 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@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 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@igalia.com> Thanks a lot for the feedback, I'll integrate it in v6. Regards, Pierre-Eric > > 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. */
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. +In the drm subsystem, some events are considered stable uAPI to avoid +breaking tools (eg: 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 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. + * + * 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. */
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@amd.com> --- Documentation/gpu/drm-uapi.rst | 19 ++++++++++++++++ .../gpu/drm/scheduler/gpu_scheduler_trace.h | 22 +++++++++++++++++++ 2 files changed, 41 insertions(+)