| Message ID | 20230417201215.448099-2-robdclark@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm: Add comm/cmdline fdinfo fields | expand |
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. >
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. 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.