Documentation/gpu/drm-usage-stats.rst

   1 .. _drm-client-usage-stats:
   2
   3 ======================
   4 DRM client usage stats
   5 ======================
   6
   7 DRM drivers can choose to export partly standardised text output via the
   8 `fops->show_fdinfo()` as part of the driver specific file operations registered
   9 in the `struct drm_driver` object registered with the DRM core.
  10
  11 One purpose of this output is to enable writing as generic as practically
  12 feasible `top(1)` like userspace monitoring tools.
  13
  14 Given the differences between various DRM drivers the specification of the
  15 output is split between common and driver specific parts. Having said that,
  16 wherever possible effort should still be made to standardise as much as
  17 possible.
  18
  19 File 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 - Keys are not 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
  31 Key types
  32 ---------
  33
  34 1. Mandatory, fully standardised.
  35 2. Optional, fully standardised.
  36 3. Driver specific.
  37
  38 Data types
  39 ----------
  40
  41 - <uint> - Unsigned integer without defining the maximum value.
  42 - <keystr> - String excluding any above defined reserved characters or whitespace.
  43 - <valstr> - String.
  44
  45 Mandatory fully standardised keys
  46 ---------------------------------
  47
  48 - drm-driver: <valstr>
  49
  50 String shall contain the name this driver registered as via the respective
  51 `struct drm_driver` data structure.
  52
  53 Optional fully standardised keys
  54 --------------------------------
  55
  56 Identification
  57 ^^^^^^^^^^^^^^
  58
  59 - drm-pdev: <aaaa:bb.cc.d>
  60
  61 For PCI devices this should contain the PCI slot address of the device in
  62 question.
  63
  64 - drm-client-id: <uint>
  65
  66 Unique value relating to the open DRM file descriptor used to distinguish
  67 duplicated and shared file descriptors. Conceptually the value should map 1:1
  68 to the in kernel representation of `struct drm_file` instances.
  69
  70 Uniqueness of the value shall be either globally unique, or unique within the
  71 scope of each device, in which case `drm-pdev` shall be present as well.
  72
  73 Userspace should make sure to not double account any usage statistics by using
  74 the above described criteria in order to associate data to individual clients.
  75
  76 - drm-client-name: <valstr>
  77
  78 String optionally set by userspace using DRM_IOCTL_SET_CLIENT_NAME.
  79
  80
  81 Utilization
  82 ^^^^^^^^^^^
  83
  84 - drm-engine-<keystr>: <uint> ns
  85
  86 GPUs usually contain multiple execution engines. Each shall be given a stable
  87 and unique name (keystr), with possible values documented in the driver specific
  88 documentation.
  89
  90 Value shall be in specified time units which the respective GPU engine spent
  91 busy executing workloads belonging to this client.
  92
  93 Values are not required to be constantly monotonic if it makes the driver
  94 implementation easier, but are required to catch up with the previously reported
  95 larger value within a reasonable period. Upon observing a value lower than what
  96 was previously read, userspace is expected to stay with that larger previous
  97 value until a monotonic update is seen.
  98
  99 - drm-engine-capacity-<keystr>: <uint>
 100
 101 Engine identifier string must be the same as the one specified in the
 102 drm-engine-<keystr> tag and shall contain a greater than zero number in case the
 103 exported engine corresponds to a group of identical hardware engines.
 104
 105 In the absence of this tag parser shall assume capacity of one. Zero capacity
 106 is not allowed.
 107
 108 - drm-cycles-<keystr>: <uint>
 109
 110 Engine identifier string must be the same as the one specified in the
 111 drm-engine-<keystr> tag and shall contain the number of busy cycles for the given
 112 engine.
 113
 114 Values are not required to be constantly monotonic if it makes the driver
 115 implementation easier, but are required to catch up with the previously reported
 116 larger value within a reasonable period. Upon observing a value lower than what
 117 was previously read, userspace is expected to stay with that larger previous
 118 value until a monotonic update is seen.
 119
 120 - drm-total-cycles-<keystr>: <uint>
 121
 122 Engine identifier string must be the same as the one specified in the
 123 drm-cycles-<keystr> tag and shall contain the total number cycles for the given
 124 engine.
 125
 126 This is a timestamp in GPU unspecified unit that matches the update rate
 127 of drm-cycles-<keystr>. For drivers that implement this interface, the engine
 128 utilization can be calculated entirely on the GPU clock domain, without
 129 considering the CPU sleep time between 2 samples.
 130
 131 A driver may implement either this key or drm-maxfreq-<keystr>, but not both.
 132
 133 - drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz]
 134
 135 Engine identifier string must be the same as the one specified in the
 136 drm-engine-<keystr> tag and shall contain the maximum frequency for the given
 137 engine.  Taken together with drm-cycles-<keystr>, this can be used to calculate
 138 percentage utilization of the engine, whereas drm-engine-<keystr> only reflects
 139 time active without considering what frequency the engine is operating as a
 140 percentage of its maximum frequency.
 141
 142 A driver may implement either this key or drm-total-cycles-<keystr>, but not
 143 both.
 144
 145 Memory
 146 ^^^^^^
 147
 148 Each possible memory type which can be used to store buffer objects by the GPU
 149 in question shall be given a stable and unique name to be used as the "<region>"
 150 string.
 151
 152 The region name "memory" is reserved to refer to normal system memory.
 153
 154 The value shall reflect the amount of storage currently consumed by the buffer
 155 objects belong to this client, in the respective memory region.
 156
 157 Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB'
 158 indicating kibi- or mebi-bytes.
 159
 160 - drm-total-<region>: <uint> [KiB|MiB]
 161
 162 The total size of all requested buffers, including both shared and private
 163 memory. The backing store for the buffers does not need to be currently
 164 instantiated to count under this category. To avoid double-counting, if a buffer
 165 has multiple regions where it can be allocated to, the implementation should
 166 consistently select a single region for accounting purposes.
 167
 168 - drm-shared-<region>: <uint> [KiB|MiB]
 169
 170 The total size of buffers that are shared with another file (i.e., have more
 171 than one handle). The same requirement to avoid double-counting that applies to
 172 drm-total-<region> also applies here.
 173
 174 - drm-resident-<region>: <uint> [KiB|MiB]
 175
 176 The total size of buffers that are resident (i.e., have their backing store
 177 present or instantiated) in the specified region.
 178
 179 - drm-memory-<region>: <uint> [KiB|MiB]
 180
 181 This key is deprecated and is only printed by amdgpu; it is an alias for
 182 drm-resident-<region>.
 183
 184 - drm-purgeable-<region>: <uint> [KiB|MiB]
 185
 186 The total size of buffers that are resident and purgeable.
 187
 188 For example, drivers that implement functionality similar to 'madvise' can count
 189 buffers that have instantiated backing stores but have been marked with an
 190 equivalent of MADV_DONTNEED.
 191
 192 - drm-active-<region>: <uint> [KiB|MiB]
 193
 194 The total size of buffers that are active on one or more engines.
 195
 196 One practical example of this could be the presence of unsignaled fences in a
 197 GEM buffer reservation object. Therefore, the active category is a subset of the
 198 resident category.
 199
 200 Implementation Details
 201 ======================
 202
 203 Drivers should use drm_show_fdinfo() in their `struct file_operations`, and
 204 implement &drm_driver.show_fdinfo if they wish to provide any stats which
 205 are not provided by drm_show_fdinfo().  But even driver specific stats should
 206 be documented above and where possible, aligned with other drivers.
 207
 208 Driver specific implementations
 209 -------------------------------
 210
 211 * :ref:`i915-usage-stats`
 212 * :ref:`panfrost-usage-stats`
 213 * :ref:`panthor-usage-stats`
 214 * :ref:`xe-usage-stats`