1.. _drm-client-usage-stats:
  2
  3======================
  4DRM client usage stats
  5======================
  6
  7DRM drivers can choose to export partly standardised text output via the
  8`fops->show_fdinfo()` as part of the driver specific file operations registered
  9in the `struct drm_driver` object registered with the DRM core.
 10
 11One purpose of this output is to enable writing as generic as practicaly
 12feasible `top(1)` like userspace monitoring tools.
 13
 14Given the differences between various DRM drivers the specification of the
 15output is split between common and driver specific parts. Having said that,
 16wherever possible effort should still be made to standardise as much as
 17possible.
 18
 19File format specification
 20=========================
 21
 22- File shall contain one key value pair per one line of text.
 23- Colon character (`:`) must be used to delimit keys and values.
 24- All keys shall be prefixed with `drm-`.
 25- Whitespace between the delimiter and first non-whitespace character shall be
 26  ignored when parsing.
 27- Neither keys or values are allowed to contain whitespace characters.
 28- Numerical key value pairs can end with optional unit string.
 29- Data type of the value is fixed as defined in the specification.
 30
 31Key types
 32---------
 33
 341. Mandatory, fully standardised.
 352. Optional, fully standardised.
 363. Driver specific.
 37
 38Data types
 39----------
 40
 41- <uint> - Unsigned integer without defining the maximum value.
 42- <str> - String excluding any above defined reserved characters or whitespace.
 43
 44Mandatory fully standardised keys
 45---------------------------------
 46
 47- drm-driver: <str>
 48
 49String shall contain the name this driver registered as via the respective
 50`struct drm_driver` data structure.
 51
 52Optional fully standardised keys
 53--------------------------------
 54
 55- drm-pdev: <aaaa:bb.cc.d>
 56
 57For PCI devices this should contain the PCI slot address of the device in
 58question.
 59
 60- drm-client-id: <uint>
 61
 62Unique value relating to the open DRM file descriptor used to distinguish
 63duplicated and shared file descriptors. Conceptually the value should map 1:1
 64to the in kernel representation of `struct drm_file` instances.
 65
 66Uniqueness of the value shall be either globally unique, or unique within the
 67scope of each device, in which case `drm-pdev` shall be present as well.
 68
 69Userspace should make sure to not double account any usage statistics by using
 70the above described criteria in order to associate data to individual clients.
 71
 72- drm-engine-<str>: <uint> ns
 73
 74GPUs usually contain multiple execution engines. Each shall be given a stable
 75and unique name (str), with possible values documented in the driver specific
 76documentation.
 77
 78Value shall be in specified time units which the respective GPU engine spent
 79busy executing workloads belonging to this client.
 80
 81Values are not required to be constantly monotonic if it makes the driver
 82implementation easier, but are required to catch up with the previously reported
 83larger value within a reasonable period. Upon observing a value lower than what
 84was previously read, userspace is expected to stay with that larger previous
 85value until a monotonic update is seen.
 86
 87- drm-engine-capacity-<str>: <uint>
 88
 89Engine identifier string must be the same as the one specified in the
 90drm-engine-<str> tag and shall contain a greater than zero number in case the
 91exported engine corresponds to a group of identical hardware engines.
 92
 93In the absence of this tag parser shall assume capacity of one. Zero capacity
 94is not allowed.
 95
 96- drm-memory-<str>: <uint> [KiB|MiB]
 97
 98Each possible memory type which can be used to store buffer objects by the
 99GPU in question shall be given a stable and unique name to be returned as the
100string here.
101
102Value shall reflect the amount of storage currently consumed by the buffer
103object belong to this client, in the respective memory region.
104
105Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB'
106indicating kibi- or mebi-bytes.
107
108- drm-cycles-<str> <uint>
109
110Engine identifier string must be the same as the one specified in the
111drm-engine-<str> tag and shall contain the number of busy cycles for the given
112engine.
113
114Values are not required to be constantly monotonic if it makes the driver
115implementation easier, but are required to catch up with the previously reported
116larger value within a reasonable period. Upon observing a value lower than what
117was previously read, userspace is expected to stay with that larger previous
118value until a monotonic update is seen.
119
120- drm-maxfreq-<str> <uint> [Hz|MHz|KHz]
121
122Engine identifier string must be the same as the one specified in the
123drm-engine-<str> tag and shall contain the maximum frequency for the given
124engine.  Taken together with drm-cycles-<str>, this can be used to calculate
125percentage utilization of the engine, whereas drm-engine-<str> only reflects
126time active without considering what frequency the engine is operating as a
127percentage of it's maximum frequency.
128
129Driver specific implementations
130===============================
131
132:ref:`i915-usage-stats`