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 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-total-cycles-<keystr>: <uint> 116 117 Engine identifier string must be the same as the one specified in the 118 drm-cycles-<keystr> tag and shall contain the total number cycles for the given 119 engine. 120 121 This is a timestamp in GPU unspecified unit that matches the update rate 122 of drm-cycles-<keystr>. For drivers that implement this interface, the engine 123 utilization can be calculated entirely on the GPU clock domain, without 124 considering the CPU sleep time between 2 samples. 125 126 A driver may implement either this key or drm-maxfreq-<keystr>, but not both. 127 128 - drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz] 129 130 Engine identifier string must be the same as the one specified in the 131 drm-engine-<keystr> tag and shall contain the maximum frequency for the given 132 engine. Taken together with drm-cycles-<keystr>, this can be used to calculate 133 percentage utilization of the engine, whereas drm-engine-<keystr> only reflects 134 time active without considering what frequency the engine is operating as a 135 percentage of its maximum frequency. 136 137 A driver may implement either this key or drm-total-cycles-<keystr>, but not 138 both. 139 140 Memory 141 ^^^^^^ 142 143 - drm-memory-<region>: <uint> [KiB|MiB] 144 145 Each possible memory type which can be used to store buffer objects by the 146 GPU in question shall be given a stable and unique name to be returned as the 147 string here. The name "memory" is reserved to refer to normal system memory. 148 149 Value shall reflect the amount of storage currently consumed by the buffer 150 objects belong to this client, in the respective memory region. 151 152 Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB' 153 indicating kibi- or mebi-bytes. 154 155 - drm-shared-<region>: <uint> [KiB|MiB] 156 157 The total size of buffers that are shared with another file (e.g., have more 158 than a single handle). 159 160 - drm-total-<region>: <uint> [KiB|MiB] 161 162 The total size of buffers that including shared and private memory. 163 164 - drm-resident-<region>: <uint> [KiB|MiB] 165 166 The total size of buffers that are resident in the specified region. 167 168 - drm-purgeable-<region>: <uint> [KiB|MiB] 169 170 The total size of buffers that are purgeable. 171 172 - drm-active-<region>: <uint> [KiB|MiB] 173 174 The total size of buffers that are active on one or more engines. 175 176 Implementation Details 177 ====================== 178 179 Drivers should use drm_show_fdinfo() in their `struct file_operations`, and 180 implement &drm_driver.show_fdinfo if they wish to provide any stats which 181 are not provided by drm_show_fdinfo(). But even driver specific stats should 182 be documented above and where possible, aligned with other drivers. 183 184 Driver specific implementations 185 ------------------------------- 186 187 * :ref:`i915-usage-stats` 188 * :ref:`panfrost-usage-stats` 189 * :ref:`xe-usage-stats`
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.