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