[PATCH v5 4/4] drm/doc: document some tracepoints as uAPI

[Pierre-Eric Pelloux-Prayer]

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 at 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 at 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. */