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 practicaly
  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 Utilization
  77 ^^^^^^^^^^^
  78
  79 - drm-engine-<keystr>: <uint> ns
  80
  81 GPUs usually contain multiple execution engines. Each shall be given a stable
  82 and unique name (keystr), with possible values documented in the driver specific
  83 documentation.
  84
  85 Value shall be in specified time units which the respective GPU engine spent
  86 busy executing workloads belonging to this client.
  87
  88 Values are not required to be constantly monotonic if it makes the driver
  89 implementation easier, but are required to catch up with the previously reported
  90 larger value within a reasonable period. Upon observing a value lower than what
  91 was previously read, userspace is expected to stay with that larger previous
  92 value until a monotonic update is seen.
  93
  94 - drm-engine-capacity-<keystr>: <uint>
  95
  96 Engine identifier string must be the same as the one specified in the
  97 drm-engine-<keystr> tag and shall contain a greater than zero number in case the
  98 exported engine corresponds to a group of identical hardware engines.
  99
 100 In the absence of this tag parser shall assume capacity of one. Zero capacity
 101 is not allowed.
 102
 103 - drm-cycles-<keystr>: <uint>
 104
 105 Engine identifier string must be the same as the one specified in the
 106 drm-engine-<keystr> tag and shall contain the number of busy cycles for the given
 107 engine.
 108
 109 Values are not required to be constantly monotonic if it makes the driver
 110 implementation easier, but are required to catch up with the previously reported
 111 larger value within a reasonable period. Upon observing a value lower than what
 112 was previously read, userspace is expected to stay with that larger previous
 113 value until a monotonic update is seen.
 114
 115 - drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz]
 116
 117 Engine identifier string must be the same as the one specified in the
 118 drm-engine-<keystr> tag and shall contain the maximum frequency for the given
 119 engine.  Taken together with drm-cycles-<keystr>, this can be used to calculate
 120 percentage utilization of the engine, whereas drm-engine-<keystr> only reflects
 121 time active without considering what frequency the engine is operating as a
 122 percentage of it's maximum frequency.
 123
 124 Memory
 125 ^^^^^^
 126
 127 - drm-memory-<region>: <uint> [KiB|MiB]
 128
 129 Each possible memory type which can be used to store buffer objects by the
 130 GPU in question shall be given a stable and unique name to be returned as the
 131 string here.  The name "memory" is reserved to refer to normal system memory.
 132
 133 Value shall reflect the amount of storage currently consumed by the buffer
 134 objects belong to this client, in the respective memory region.
 135
 136 Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB'
 137 indicating kibi- or mebi-bytes.
 138
 139 - drm-shared-<region>: <uint> [KiB|MiB]
 140
 141 The total size of buffers that are shared with another file (ie. have more
 142 than a single handle).
 143
 144 - drm-total-<region>: <uint> [KiB|MiB]
 145
 146 The total size of buffers that including shared and private memory.
 147
 148 - drm-resident-<region>: <uint> [KiB|MiB]
 149
 150 The total size of buffers that are resident in the specified region.
 151
 152 - drm-purgeable-<region>: <uint> [KiB|MiB]
 153
 154 The total size of buffers that are purgeable.
 155
 156 - drm-active-<region>: <uint> [KiB|MiB]
 157
 158 The total size of buffers that are active on one or more engines.
 159
 160 Implementation Details
 161 ======================
 162
 163 Drivers should use drm_show_fdinfo() in their `struct file_operations`, and
 164 implement &drm_driver.show_fdinfo if they wish to provide any stats which
 165 are not provided by drm_show_fdinfo().  But even driver specific stats should
 166 be documented above and where possible, aligned with other drivers.
 167
 168 Driver specific implementations
 169 -------------------------------
 170
 171 :ref:`i915-usage-stats`