diff mbox series

[RFC,6/8] drm: Document fdinfo format specification

Message ID 20210823112859.103561-7-tvrtko.ursulin@linux.intel.com (mailing list archive)
State New, archived
Headers show
Series Per client GPU stats | expand

Commit Message

Tvrtko Ursulin Aug. 23, 2021, 11:28 a.m. UTC
From: Tvrtko Ursulin <tvrtko.ursulin@intel.com>

Proposal to standardise the fdinfo text format as optionally output by DRM
drivers.

Idea is that a simple but, well defined, spec will enable generic
userspace tools to be written while at the same time avoiding a more heavy
handed approach of adding a mid-layer to DRM.

i915 implements a subset of the spec, everything apart from the memory
stats currently, and a matching intel_gpu_top tool exists.

Open is to see if AMD can migrate to using the proposed GPU utilisation
key-value pairs, or if they are not workable to see whether to go
vendor specific, or if a standardised  alternative can be found which is
workable for both drivers.

Same for the memory utilisation key-value pairs proposal.

v2:
 * Update for removal of name and pid.

v3:
 * 'Drm-driver' tag will be obtained from struct drm_driver.name. (Daniel)

Signed-off-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
Cc: David M Nieto <David.Nieto@amd.com>
Cc: Christian König <christian.koenig@amd.com>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Daniel Stone <daniel@fooishbar.org>
---
 Documentation/gpu/drm-usage-stats.rst | 97 +++++++++++++++++++++++++++
 Documentation/gpu/index.rst           |  1 +
 2 files changed, 98 insertions(+)
 create mode 100644 Documentation/gpu/drm-usage-stats.rst

Comments

Christian König Aug. 23, 2021, 1:32 p.m. UTC | #1
Am 23.08.21 um 13:28 schrieb Tvrtko Ursulin:
> From: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
>
> Proposal to standardise the fdinfo text format as optionally output by DRM
> drivers.
>
> Idea is that a simple but, well defined, spec will enable generic
> userspace tools to be written while at the same time avoiding a more heavy
> handed approach of adding a mid-layer to DRM.
>
> i915 implements a subset of the spec, everything apart from the memory
> stats currently, and a matching intel_gpu_top tool exists.
>
> Open is to see if AMD can migrate to using the proposed GPU utilisation
> key-value pairs, or if they are not workable to see whether to go
> vendor specific, or if a standardised  alternative can be found which is
> workable for both drivers.
>
> Same for the memory utilisation key-value pairs proposal.
>
> v2:
>   * Update for removal of name and pid.
>
> v3:
>   * 'Drm-driver' tag will be obtained from struct drm_driver.name. (Daniel)
>
> Signed-off-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
> Cc: David M Nieto <David.Nieto@amd.com>
> Cc: Christian König <christian.koenig@amd.com>
> Cc: Daniel Vetter <daniel@ffwll.ch>
> Cc: Daniel Stone <daniel@fooishbar.org>

I'm not an expert on that stuff, but as far as I can see this totally 
makes sense to me.

Feel free to add an Acked-by: Christian König <christian.koenig@amd.com> 
to those three patches.

Regards,
Christian.

> ---
>   Documentation/gpu/drm-usage-stats.rst | 97 +++++++++++++++++++++++++++
>   Documentation/gpu/index.rst           |  1 +
>   2 files changed, 98 insertions(+)
>   create mode 100644 Documentation/gpu/drm-usage-stats.rst
>
> diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst
> new file mode 100644
> index 000000000000..c669026be244
> --- /dev/null
> +++ b/Documentation/gpu/drm-usage-stats.rst
> @@ -0,0 +1,97 @@
> +.. _drm-client-usage-stats:
> +
> +======================
> +DRM client usage stats
> +======================
> +
> +DRM drivers can choose to export partly standardised text output via the
> +`fops->show_fdinfo()` as part of the driver specific file operations registered
> +in the `struct drm_driver` object registered with the DRM core.
> +
> +One purpose of this output is to enable writing as generic as practicaly
> +feasible `top(1)` like userspace monitoring tools.
> +
> +Given the differences between various DRM drivers the specification of the
> +output is split between common and driver specific parts. Having said that,
> +wherever possible effort should still be made to standardise as much as
> +possible.
> +
> +File format specification
> +=========================
> +
> +- File shall contain one key value pair per one line of text.
> +- Colon character (`:`) must be used to delimit keys and values.
> +- All keys shall be prefixed with `drm-`.
> +- Whitespace between the delimiter and first non-whitespace character shall be
> +  ignored when parsing.
> +- Neither keys or values are allowed to contain whitespace characters.
> +- Numerical key value pairs can end with optional unit string.
> +- Data type of the value is fixed as defined in the specification.
> +
> +Key types
> +---------
> +
> +1. Mandatory, fully standardised.
> +2. Optional, fully standardised.
> +3. Driver specific.
> +
> +Data types
> +----------
> +
> +- <uint> - Unsigned integer without defining the maximum value.
> +- <str> - String excluding any above defined reserved characters or whitespace.
> +
> +Mandatory fully standardised keys
> +---------------------------------
> +
> +- drm-driver: <str>
> +
> +String shall contain the name this driver registered as via the respective
> +`struct drm_driver` data structure.
> +
> +Optional fully standardised keys
> +--------------------------------
> +
> +- drm-pdev: <aaaa:bb.cc.d>
> +
> +For PCI devices this should contain the PCI slot address of the device in
> +question.
> +
> +- drm-client-id: <uint>
> +
> +Unique value relating to the open DRM file descriptor used to distinguish
> +duplicated and shared file descriptors. Conceptually the value should map 1:1
> +to the in kernel representation of `struct drm_file` instances.
> +
> +Uniqueness of the value shall be either globally unique, or unique within the
> +scope of each device, in which case `drm-pdev` shall be present as well.
> +
> +Userspace should make sure to not double account any usage statistics by using
> +the above described criteria in order to associate data to individual clients.
> +
> +- drm-engine-<str>: <uint> ns
> +
> +GPUs usually contain multiple execution engines. Each shall be given a stable
> +and unique name (str), with possible values documented in the driver specific
> +documentation.
> +
> +Value shall be in specified time units which the respective GPU engine spent
> +busy executing workloads belonging to this client.
> +
> +Values are not required to be constantly monotonic if it makes the driver
> +implementation easier, but are required to catch up with the previously reported
> +larger value within a reasonable period. Upon observing a value lower than what
> +was previously read, userspace is expected to stay with that larger previous
> +value until a monotonic update is seen.
> +
> +- drm-memory-<str>: <uint> [KiB|MiB]
> +
> +Each possible memory type which can be used to store buffer objects by the
> +GPU in question shall be given a stable and unique name to be returned as the
> +string here.
> +
> +Value shall reflect the amount of storage currently consumed by the buffer
> +object belong to this client, in the respective memory region.
> +
> +Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB'
> +indicating kibi- or mebi-bytes.
> diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
> index b9c1214d8f23..b99dede9a5b1 100644
> --- a/Documentation/gpu/index.rst
> +++ b/Documentation/gpu/index.rst
> @@ -10,6 +10,7 @@ Linux GPU Driver Developer's Guide
>      drm-kms
>      drm-kms-helpers
>      drm-uapi
> +   drm-usage-stats
>      driver-uapi
>      drm-client
>      drivers
Tvrtko Ursulin Aug. 24, 2021, 9:25 a.m. UTC | #2
On 23/08/2021 14:32, Christian König wrote:
> Am 23.08.21 um 13:28 schrieb Tvrtko Ursulin:
>> From: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
>>
>> Proposal to standardise the fdinfo text format as optionally output by 
>> DRM
>> drivers.
>>
>> Idea is that a simple but, well defined, spec will enable generic
>> userspace tools to be written while at the same time avoiding a more 
>> heavy
>> handed approach of adding a mid-layer to DRM.
>>
>> i915 implements a subset of the spec, everything apart from the memory
>> stats currently, and a matching intel_gpu_top tool exists.
>>
>> Open is to see if AMD can migrate to using the proposed GPU utilisation
>> key-value pairs, or if they are not workable to see whether to go
>> vendor specific, or if a standardised  alternative can be found which is
>> workable for both drivers.
>>
>> Same for the memory utilisation key-value pairs proposal.
>>
>> v2:
>>   * Update for removal of name and pid.
>>
>> v3:
>>   * 'Drm-driver' tag will be obtained from struct drm_driver.name. 
>> (Daniel)
>>
>> Signed-off-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
>> Cc: David M Nieto <David.Nieto@amd.com>
>> Cc: Christian König <christian.koenig@amd.com>
>> Cc: Daniel Vetter <daniel@ffwll.ch>
>> Cc: Daniel Stone <daniel@fooishbar.org>
> 
> I'm not an expert on that stuff, but as far as I can see this totally 
> makes sense to me.

Thanks!

> Feel free to add an Acked-by: Christian König <christian.koenig@amd.com> 
> to those three patches.

However note that the last one is full of TODO markers, including the 
commit message, where I was hoping to nudge the feature owners of the 
amdgpu side to fill in the blanks in my understanding of how things work 
over there. At least the different semantics need to be documented so 
random userspace can interpret the amdgpu values correctly.

Or alternatively I drop the last patch and if someone is interested they 
can resurrect and complete it at their leisure.

Just not sure how Daniel would accept this since his push was to gate 
i915 addition behind a drive for common solution.

Regards,

Tvrtko

>> ---
>>   Documentation/gpu/drm-usage-stats.rst | 97 +++++++++++++++++++++++++++
>>   Documentation/gpu/index.rst           |  1 +
>>   2 files changed, 98 insertions(+)
>>   create mode 100644 Documentation/gpu/drm-usage-stats.rst
>>
>> diff --git a/Documentation/gpu/drm-usage-stats.rst 
>> b/Documentation/gpu/drm-usage-stats.rst
>> new file mode 100644
>> index 000000000000..c669026be244
>> --- /dev/null
>> +++ b/Documentation/gpu/drm-usage-stats.rst
>> @@ -0,0 +1,97 @@
>> +.. _drm-client-usage-stats:
>> +
>> +======================
>> +DRM client usage stats
>> +======================
>> +
>> +DRM drivers can choose to export partly standardised text output via the
>> +`fops->show_fdinfo()` as part of the driver specific file operations 
>> registered
>> +in the `struct drm_driver` object registered with the DRM core.
>> +
>> +One purpose of this output is to enable writing as generic as practicaly
>> +feasible `top(1)` like userspace monitoring tools.
>> +
>> +Given the differences between various DRM drivers the specification 
>> of the
>> +output is split between common and driver specific parts. Having said 
>> that,
>> +wherever possible effort should still be made to standardise as much as
>> +possible.
>> +
>> +File format specification
>> +=========================
>> +
>> +- File shall contain one key value pair per one line of text.
>> +- Colon character (`:`) must be used to delimit keys and values.
>> +- All keys shall be prefixed with `drm-`.
>> +- Whitespace between the delimiter and first non-whitespace character 
>> shall be
>> +  ignored when parsing.
>> +- Neither keys or values are allowed to contain whitespace characters.
>> +- Numerical key value pairs can end with optional unit string.
>> +- Data type of the value is fixed as defined in the specification.
>> +
>> +Key types
>> +---------
>> +
>> +1. Mandatory, fully standardised.
>> +2. Optional, fully standardised.
>> +3. Driver specific.
>> +
>> +Data types
>> +----------
>> +
>> +- <uint> - Unsigned integer without defining the maximum value.
>> +- <str> - String excluding any above defined reserved characters or 
>> whitespace.
>> +
>> +Mandatory fully standardised keys
>> +---------------------------------
>> +
>> +- drm-driver: <str>
>> +
>> +String shall contain the name this driver registered as via the 
>> respective
>> +`struct drm_driver` data structure.
>> +
>> +Optional fully standardised keys
>> +--------------------------------
>> +
>> +- drm-pdev: <aaaa:bb.cc.d>
>> +
>> +For PCI devices this should contain the PCI slot address of the 
>> device in
>> +question.
>> +
>> +- drm-client-id: <uint>
>> +
>> +Unique value relating to the open DRM file descriptor used to 
>> distinguish
>> +duplicated and shared file descriptors. Conceptually the value should 
>> map 1:1
>> +to the in kernel representation of `struct drm_file` instances.
>> +
>> +Uniqueness of the value shall be either globally unique, or unique 
>> within the
>> +scope of each device, in which case `drm-pdev` shall be present as well.
>> +
>> +Userspace should make sure to not double account any usage statistics 
>> by using
>> +the above described criteria in order to associate data to individual 
>> clients.
>> +
>> +- drm-engine-<str>: <uint> ns
>> +
>> +GPUs usually contain multiple execution engines. Each shall be given 
>> a stable
>> +and unique name (str), with possible values documented in the driver 
>> specific
>> +documentation.
>> +
>> +Value shall be in specified time units which the respective GPU 
>> engine spent
>> +busy executing workloads belonging to this client.
>> +
>> +Values are not required to be constantly monotonic if it makes the 
>> driver
>> +implementation easier, but are required to catch up with the 
>> previously reported
>> +larger value within a reasonable period. Upon observing a value lower 
>> than what
>> +was previously read, userspace is expected to stay with that larger 
>> previous
>> +value until a monotonic update is seen.
>> +
>> +- drm-memory-<str>: <uint> [KiB|MiB]
>> +
>> +Each possible memory type which can be used to store buffer objects 
>> by the
>> +GPU in question shall be given a stable and unique name to be 
>> returned as the
>> +string here.
>> +
>> +Value shall reflect the amount of storage currently consumed by the 
>> buffer
>> +object belong to this client, in the respective memory region.
>> +
>> +Default unit shall be bytes with optional unit specifiers of 'KiB' or 
>> 'MiB'
>> +indicating kibi- or mebi-bytes.
>> diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
>> index b9c1214d8f23..b99dede9a5b1 100644
>> --- a/Documentation/gpu/index.rst
>> +++ b/Documentation/gpu/index.rst
>> @@ -10,6 +10,7 @@ Linux GPU Driver Developer's Guide
>>      drm-kms
>>      drm-kms-helpers
>>      drm-uapi
>> +   drm-usage-stats
>>      driver-uapi
>>      drm-client
>>      drivers
>
Christian König Aug. 24, 2021, 9:34 a.m. UTC | #3
Am 24.08.21 um 11:25 schrieb Tvrtko Ursulin:
>
> On 23/08/2021 14:32, Christian König wrote:
>> Am 23.08.21 um 13:28 schrieb Tvrtko Ursulin:
>>> From: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
>>>
>>> Proposal to standardise the fdinfo text format as optionally output 
>>> by DRM
>>> drivers.
>>>
>>> Idea is that a simple but, well defined, spec will enable generic
>>> userspace tools to be written while at the same time avoiding a more 
>>> heavy
>>> handed approach of adding a mid-layer to DRM.
>>>
>>> i915 implements a subset of the spec, everything apart from the memory
>>> stats currently, and a matching intel_gpu_top tool exists.
>>>
>>> Open is to see if AMD can migrate to using the proposed GPU utilisation
>>> key-value pairs, or if they are not workable to see whether to go
>>> vendor specific, or if a standardised  alternative can be found 
>>> which is
>>> workable for both drivers.
>>>
>>> Same for the memory utilisation key-value pairs proposal.
>>>
>>> v2:
>>>   * Update for removal of name and pid.
>>>
>>> v3:
>>>   * 'Drm-driver' tag will be obtained from struct drm_driver.name. 
>>> (Daniel)
>>>
>>> Signed-off-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
>>> Cc: David M Nieto <David.Nieto@amd.com>
>>> Cc: Christian König <christian.koenig@amd.com>
>>> Cc: Daniel Vetter <daniel@ffwll.ch>
>>> Cc: Daniel Stone <daniel@fooishbar.org>
>>
>> I'm not an expert on that stuff, but as far as I can see this totally 
>> makes sense to me.
>
> Thanks!
>
>> Feel free to add an Acked-by: Christian König 
>> <christian.koenig@amd.com> to those three patches.
>
> However note that the last one is full of TODO markers, including the 
> commit message, where I was hoping to nudge the feature owners of the 
> amdgpu side to fill in the blanks in my understanding of how things 
> work over there. At least the different semantics need to be 
> documented so random userspace can interpret the amdgpu values correctly.

Yeah, that's the reason why I only dare to give an ack. David is driving 
this at AMD.

If you ask me exposing ns like the i915 wants to do is perfectly 
sufficient for us as well.

Regards,
Christian.

>
> Or alternatively I drop the last patch and if someone is interested 
> they can resurrect and complete it at their leisure.
>
> Just not sure how Daniel would accept this since his push was to gate 
> i915 addition behind a drive for common solution.
>
> Regards,
>
> Tvrtko
>
>>> ---
>>>   Documentation/gpu/drm-usage-stats.rst | 97 
>>> +++++++++++++++++++++++++++
>>>   Documentation/gpu/index.rst           |  1 +
>>>   2 files changed, 98 insertions(+)
>>>   create mode 100644 Documentation/gpu/drm-usage-stats.rst
>>>
>>> diff --git a/Documentation/gpu/drm-usage-stats.rst 
>>> b/Documentation/gpu/drm-usage-stats.rst
>>> new file mode 100644
>>> index 000000000000..c669026be244
>>> --- /dev/null
>>> +++ b/Documentation/gpu/drm-usage-stats.rst
>>> @@ -0,0 +1,97 @@
>>> +.. _drm-client-usage-stats:
>>> +
>>> +======================
>>> +DRM client usage stats
>>> +======================
>>> +
>>> +DRM drivers can choose to export partly standardised text output 
>>> via the
>>> +`fops->show_fdinfo()` as part of the driver specific file 
>>> operations registered
>>> +in the `struct drm_driver` object registered with the DRM core.
>>> +
>>> +One purpose of this output is to enable writing as generic as 
>>> practicaly
>>> +feasible `top(1)` like userspace monitoring tools.
>>> +
>>> +Given the differences between various DRM drivers the specification 
>>> of the
>>> +output is split between common and driver specific parts. Having 
>>> said that,
>>> +wherever possible effort should still be made to standardise as 
>>> much as
>>> +possible.
>>> +
>>> +File format specification
>>> +=========================
>>> +
>>> +- File shall contain one key value pair per one line of text.
>>> +- Colon character (`:`) must be used to delimit keys and values.
>>> +- All keys shall be prefixed with `drm-`.
>>> +- Whitespace between the delimiter and first non-whitespace 
>>> character shall be
>>> +  ignored when parsing.
>>> +- Neither keys or values are allowed to contain whitespace characters.
>>> +- Numerical key value pairs can end with optional unit string.
>>> +- Data type of the value is fixed as defined in the specification.
>>> +
>>> +Key types
>>> +---------
>>> +
>>> +1. Mandatory, fully standardised.
>>> +2. Optional, fully standardised.
>>> +3. Driver specific.
>>> +
>>> +Data types
>>> +----------
>>> +
>>> +- <uint> - Unsigned integer without defining the maximum value.
>>> +- <str> - String excluding any above defined reserved characters or 
>>> whitespace.
>>> +
>>> +Mandatory fully standardised keys
>>> +---------------------------------
>>> +
>>> +- drm-driver: <str>
>>> +
>>> +String shall contain the name this driver registered as via the 
>>> respective
>>> +`struct drm_driver` data structure.
>>> +
>>> +Optional fully standardised keys
>>> +--------------------------------
>>> +
>>> +- drm-pdev: <aaaa:bb.cc.d>
>>> +
>>> +For PCI devices this should contain the PCI slot address of the 
>>> device in
>>> +question.
>>> +
>>> +- drm-client-id: <uint>
>>> +
>>> +Unique value relating to the open DRM file descriptor used to 
>>> distinguish
>>> +duplicated and shared file descriptors. Conceptually the value 
>>> should map 1:1
>>> +to the in kernel representation of `struct drm_file` instances.
>>> +
>>> +Uniqueness of the value shall be either globally unique, or unique 
>>> within the
>>> +scope of each device, in which case `drm-pdev` shall be present as 
>>> well.
>>> +
>>> +Userspace should make sure to not double account any usage 
>>> statistics by using
>>> +the above described criteria in order to associate data to 
>>> individual clients.
>>> +
>>> +- drm-engine-<str>: <uint> ns
>>> +
>>> +GPUs usually contain multiple execution engines. Each shall be 
>>> given a stable
>>> +and unique name (str), with possible values documented in the 
>>> driver specific
>>> +documentation.
>>> +
>>> +Value shall be in specified time units which the respective GPU 
>>> engine spent
>>> +busy executing workloads belonging to this client.
>>> +
>>> +Values are not required to be constantly monotonic if it makes the 
>>> driver
>>> +implementation easier, but are required to catch up with the 
>>> previously reported
>>> +larger value within a reasonable period. Upon observing a value 
>>> lower than what
>>> +was previously read, userspace is expected to stay with that larger 
>>> previous
>>> +value until a monotonic update is seen.
>>> +
>>> +- drm-memory-<str>: <uint> [KiB|MiB]
>>> +
>>> +Each possible memory type which can be used to store buffer objects 
>>> by the
>>> +GPU in question shall be given a stable and unique name to be 
>>> returned as the
>>> +string here.
>>> +
>>> +Value shall reflect the amount of storage currently consumed by the 
>>> buffer
>>> +object belong to this client, in the respective memory region.
>>> +
>>> +Default unit shall be bytes with optional unit specifiers of 'KiB' 
>>> or 'MiB'
>>> +indicating kibi- or mebi-bytes.
>>> diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
>>> index b9c1214d8f23..b99dede9a5b1 100644
>>> --- a/Documentation/gpu/index.rst
>>> +++ b/Documentation/gpu/index.rst
>>> @@ -10,6 +10,7 @@ Linux GPU Driver Developer's Guide
>>>      drm-kms
>>>      drm-kms-helpers
>>>      drm-uapi
>>> +   drm-usage-stats
>>>      driver-uapi
>>>      drm-client
>>>      drivers
>>
diff mbox series

Patch

diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst
new file mode 100644
index 000000000000..c669026be244
--- /dev/null
+++ b/Documentation/gpu/drm-usage-stats.rst
@@ -0,0 +1,97 @@ 
+.. _drm-client-usage-stats:
+
+======================
+DRM client usage stats
+======================
+
+DRM drivers can choose to export partly standardised text output via the
+`fops->show_fdinfo()` as part of the driver specific file operations registered
+in the `struct drm_driver` object registered with the DRM core.
+
+One purpose of this output is to enable writing as generic as practicaly
+feasible `top(1)` like userspace monitoring tools.
+
+Given the differences between various DRM drivers the specification of the
+output is split between common and driver specific parts. Having said that,
+wherever possible effort should still be made to standardise as much as
+possible.
+
+File format specification
+=========================
+
+- File shall contain one key value pair per one line of text.
+- Colon character (`:`) must be used to delimit keys and values.
+- All keys shall be prefixed with `drm-`.
+- Whitespace between the delimiter and first non-whitespace character shall be
+  ignored when parsing.
+- Neither keys or values are allowed to contain whitespace characters.
+- Numerical key value pairs can end with optional unit string.
+- Data type of the value is fixed as defined in the specification.
+
+Key types
+---------
+
+1. Mandatory, fully standardised.
+2. Optional, fully standardised.
+3. Driver specific.
+
+Data types
+----------
+
+- <uint> - Unsigned integer without defining the maximum value.
+- <str> - String excluding any above defined reserved characters or whitespace.
+
+Mandatory fully standardised keys
+---------------------------------
+
+- drm-driver: <str>
+
+String shall contain the name this driver registered as via the respective
+`struct drm_driver` data structure.
+
+Optional fully standardised keys
+--------------------------------
+
+- drm-pdev: <aaaa:bb.cc.d>
+
+For PCI devices this should contain the PCI slot address of the device in
+question.
+
+- drm-client-id: <uint>
+
+Unique value relating to the open DRM file descriptor used to distinguish
+duplicated and shared file descriptors. Conceptually the value should map 1:1
+to the in kernel representation of `struct drm_file` instances.
+
+Uniqueness of the value shall be either globally unique, or unique within the
+scope of each device, in which case `drm-pdev` shall be present as well.
+
+Userspace should make sure to not double account any usage statistics by using
+the above described criteria in order to associate data to individual clients.
+
+- drm-engine-<str>: <uint> ns
+
+GPUs usually contain multiple execution engines. Each shall be given a stable
+and unique name (str), with possible values documented in the driver specific
+documentation.
+
+Value shall be in specified time units which the respective GPU engine spent
+busy executing workloads belonging to this client.
+
+Values are not required to be constantly monotonic if it makes the driver
+implementation easier, but are required to catch up with the previously reported
+larger value within a reasonable period. Upon observing a value lower than what
+was previously read, userspace is expected to stay with that larger previous
+value until a monotonic update is seen.
+
+- drm-memory-<str>: <uint> [KiB|MiB]
+
+Each possible memory type which can be used to store buffer objects by the
+GPU in question shall be given a stable and unique name to be returned as the
+string here.
+
+Value shall reflect the amount of storage currently consumed by the buffer
+object belong to this client, in the respective memory region.
+
+Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB'
+indicating kibi- or mebi-bytes.
diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index b9c1214d8f23..b99dede9a5b1 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -10,6 +10,7 @@  Linux GPU Driver Developer's Guide
    drm-kms
    drm-kms-helpers
    drm-uapi
+   drm-usage-stats
    driver-uapi
    drm-client
    drivers