[RFC,1/3] drm/doc: Relax fdinfo string constraints
Commit Message
From: Rob Clark <robdclark@chromium.org>
The restriction about no whitespace, etc, really only applies to the
usage of strings in keys. Values can contain anything (other than
newline).
Signed-off-by: Rob Clark <robdclark@chromium.org>
---
Documentation/gpu/drm-usage-stats.rst | 29 ++++++++++++++-------------
1 file changed, 15 insertions(+), 14 deletions(-)
Comments
On 17/04/2023 21:12, Rob Clark wrote:
> From: Rob Clark <robdclark@chromium.org>
>
> The restriction about no whitespace, etc, really only applies to the
> usage of strings in keys. Values can contain anything (other than
> newline).
>
> Signed-off-by: Rob Clark <robdclark@chromium.org>
> ---
> Documentation/gpu/drm-usage-stats.rst | 29 ++++++++++++++-------------
> 1 file changed, 15 insertions(+), 14 deletions(-)
>
> diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst
> index 258bdcc8fb86..8e00d53231e0 100644
> --- a/Documentation/gpu/drm-usage-stats.rst
> +++ b/Documentation/gpu/drm-usage-stats.rst
> @@ -24,7 +24,7 @@ File format specification
> - 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.
> +- Keys are not 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.
>
> @@ -39,12 +39,13 @@ Data types
> ----------
>
> - <uint> - Unsigned integer without defining the maximum value.
> -- <str> - String excluding any above defined reserved characters or whitespace.
> +- <keystr> - String excluding any above defined reserved characters or whitespace.
> +- <valstr> - String.
Makes sense I think. At least I can't remember that I had special reason
to word it as strict as it was. Lets give it some time to marinade so
for later:
Acked-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
Regards,
Tvrtko
>
> Mandatory fully standardised keys
> ---------------------------------
>
> -- drm-driver: <str>
> +- drm-driver: <valstr>
>
> String shall contain the name this driver registered as via the respective
> `struct drm_driver` data structure.
> @@ -69,10 +70,10 @@ 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
> +- drm-engine-<keystr>: <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
> +and unique name (keystr), with possible values documented in the driver specific
> documentation.
>
> Value shall be in specified time units which the respective GPU engine spent
> @@ -84,16 +85,16 @@ 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-engine-capacity-<str>: <uint>
> +- drm-engine-capacity-<keystr>: <uint>
>
> Engine identifier string must be the same as the one specified in the
> -drm-engine-<str> tag and shall contain a greater than zero number in case the
> +drm-engine-<keystr> tag and shall contain a greater than zero number in case the
> exported engine corresponds to a group of identical hardware engines.
>
> In the absence of this tag parser shall assume capacity of one. Zero capacity
> is not allowed.
>
> -- drm-memory-<str>: <uint> [KiB|MiB]
> +- drm-memory-<keystr>: <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
> @@ -126,10 +127,10 @@ The total size of buffers that are purgeable.
>
> The total size of buffers that are active on one or more rings.
>
> -- drm-cycles-<str>: <uint>
> +- drm-cycles-<keystr>: <uint>
>
> Engine identifier string must be the same as the one specified in the
> -drm-engine-<str> tag and shall contain the number of busy cycles for the given
> +drm-engine-<keystr> tag and shall contain the number of busy cycles for the given
> engine.
>
> Values are not required to be constantly monotonic if it makes the driver
> @@ -138,12 +139,12 @@ 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-maxfreq-<str>: <uint> [Hz|MHz|KHz]
> +- drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz]
>
> Engine identifier string must be the same as the one specified in the
> -drm-engine-<str> tag and shall contain the maximum frequency for the given
> -engine. Taken together with drm-cycles-<str>, this can be used to calculate
> -percentage utilization of the engine, whereas drm-engine-<str> only reflects
> +drm-engine-<keystr> tag and shall contain the maximum frequency for the given
> +engine. Taken together with drm-cycles-<keystr>, this can be used to calculate
> +percentage utilization of the engine, whereas drm-engine-<keystr> only reflects
> time active without considering what frequency the engine is operating as a
> percentage of it's maximum frequency.
>
@@ -24,7 +24,7 @@ File format specification
- 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.
+- Keys are not 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.
@@ -39,12 +39,13 @@ Data types
----------
- <uint> - Unsigned integer without defining the maximum value.
-- <str> - String excluding any above defined reserved characters or whitespace.
+- <keystr> - String excluding any above defined reserved characters or whitespace.
+- <valstr> - String.
Mandatory fully standardised keys
---------------------------------
-- drm-driver: <str>
+- drm-driver: <valstr>
String shall contain the name this driver registered as via the respective
`struct drm_driver` data structure.
@@ -69,10 +70,10 @@ 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
+- drm-engine-<keystr>: <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
+and unique name (keystr), with possible values documented in the driver specific
documentation.
Value shall be in specified time units which the respective GPU engine spent
@@ -84,16 +85,16 @@ 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-engine-capacity-<str>: <uint>
+- drm-engine-capacity-<keystr>: <uint>
Engine identifier string must be the same as the one specified in the
-drm-engine-<str> tag and shall contain a greater than zero number in case the
+drm-engine-<keystr> tag and shall contain a greater than zero number in case the
exported engine corresponds to a group of identical hardware engines.
In the absence of this tag parser shall assume capacity of one. Zero capacity
is not allowed.
-- drm-memory-<str>: <uint> [KiB|MiB]
+- drm-memory-<keystr>: <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
@@ -126,10 +127,10 @@ The total size of buffers that are purgeable.
The total size of buffers that are active on one or more rings.
-- drm-cycles-<str>: <uint>
+- drm-cycles-<keystr>: <uint>
Engine identifier string must be the same as the one specified in the
-drm-engine-<str> tag and shall contain the number of busy cycles for the given
+drm-engine-<keystr> tag and shall contain the number of busy cycles for the given
engine.
Values are not required to be constantly monotonic if it makes the driver
@@ -138,12 +139,12 @@ 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-maxfreq-<str>: <uint> [Hz|MHz|KHz]
+- drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz]
Engine identifier string must be the same as the one specified in the
-drm-engine-<str> tag and shall contain the maximum frequency for the given
-engine. Taken together with drm-cycles-<str>, this can be used to calculate
-percentage utilization of the engine, whereas drm-engine-<str> only reflects
+drm-engine-<keystr> tag and shall contain the maximum frequency for the given
+engine. Taken together with drm-cycles-<keystr>, this can be used to calculate
+percentage utilization of the engine, whereas drm-engine-<keystr> only reflects
time active without considering what frequency the engine is operating as a
percentage of it's maximum frequency.