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