190 lines · plain
1.. _drm-client-usage-stats:2 3======================4DRM client usage stats5======================6 7DRM drivers can choose to export partly standardised text output via the8`fops->show_fdinfo()` as part of the driver specific file operations registered9in the `struct drm_driver` object registered with the DRM core.10 11One purpose of this output is to enable writing as generic as practically12feasible `top(1)` like userspace monitoring tools.13 14Given the differences between various DRM drivers the specification of the15output is split between common and driver specific parts. Having said that,16wherever possible effort should still be made to standardise as much as17possible.18 19File format specification20=========================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 be26 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 types32---------33 341. Mandatory, fully standardised.352. Optional, fully standardised.363. Driver specific.37 38Data types39----------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 keys46---------------------------------47 48- drm-driver: <valstr>49 50String shall contain the name this driver registered as via the respective51`struct drm_driver` data structure.52 53Optional fully standardised keys54--------------------------------55 56Identification57^^^^^^^^^^^^^^58 59- drm-pdev: <aaaa:bb.cc.d>60 61For PCI devices this should contain the PCI slot address of the device in62question.63 64- drm-client-id: <uint>65 66Unique value relating to the open DRM file descriptor used to distinguish67duplicated and shared file descriptors. Conceptually the value should map 1:168to the in kernel representation of `struct drm_file` instances.69 70Uniqueness of the value shall be either globally unique, or unique within the71scope 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 using74the above described criteria in order to associate data to individual clients.75 76Utilization77^^^^^^^^^^^78 79- drm-engine-<keystr>: <uint> ns80 81GPUs usually contain multiple execution engines. Each shall be given a stable82and unique name (keystr), with possible values documented in the driver specific83documentation.84 85Value shall be in specified time units which the respective GPU engine spent86busy executing workloads belonging to this client.87 88Values are not required to be constantly monotonic if it makes the driver89implementation easier, but are required to catch up with the previously reported90larger value within a reasonable period. Upon observing a value lower than what91was previously read, userspace is expected to stay with that larger previous92value until a monotonic update is seen.93 94- drm-engine-capacity-<keystr>: <uint>95 96Engine identifier string must be the same as the one specified in the97drm-engine-<keystr> tag and shall contain a greater than zero number in case the98exported engine corresponds to a group of identical hardware engines.99 100In the absence of this tag parser shall assume capacity of one. Zero capacity101is not allowed.102 103- drm-cycles-<keystr>: <uint>104 105Engine identifier string must be the same as the one specified in the106drm-engine-<keystr> tag and shall contain the number of busy cycles for the given107engine.108 109Values are not required to be constantly monotonic if it makes the driver110implementation easier, but are required to catch up with the previously reported111larger value within a reasonable period. Upon observing a value lower than what112was previously read, userspace is expected to stay with that larger previous113value until a monotonic update is seen.114 115- drm-total-cycles-<keystr>: <uint>116 117Engine identifier string must be the same as the one specified in the118drm-cycles-<keystr> tag and shall contain the total number cycles for the given119engine.120 121This is a timestamp in GPU unspecified unit that matches the update rate122of drm-cycles-<keystr>. For drivers that implement this interface, the engine123utilization can be calculated entirely on the GPU clock domain, without124considering the CPU sleep time between 2 samples.125 126A driver may implement either this key or drm-maxfreq-<keystr>, but not both.127 128- drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz]129 130Engine identifier string must be the same as the one specified in the131drm-engine-<keystr> tag and shall contain the maximum frequency for the given132engine. Taken together with drm-cycles-<keystr>, this can be used to calculate133percentage utilization of the engine, whereas drm-engine-<keystr> only reflects134time active without considering what frequency the engine is operating as a135percentage of its maximum frequency.136 137A driver may implement either this key or drm-total-cycles-<keystr>, but not138both.139 140Memory141^^^^^^142 143- drm-memory-<region>: <uint> [KiB|MiB]144 145Each possible memory type which can be used to store buffer objects by the146GPU in question shall be given a stable and unique name to be returned as the147string here. The name "memory" is reserved to refer to normal system memory.148 149Value shall reflect the amount of storage currently consumed by the buffer150objects belong to this client, in the respective memory region.151 152Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB'153indicating kibi- or mebi-bytes.154 155- drm-shared-<region>: <uint> [KiB|MiB]156 157The total size of buffers that are shared with another file (e.g., have more158than a single handle).159 160- drm-total-<region>: <uint> [KiB|MiB]161 162The total size of buffers that including shared and private memory.163 164- drm-resident-<region>: <uint> [KiB|MiB]165 166The total size of buffers that are resident in the specified region.167 168- drm-purgeable-<region>: <uint> [KiB|MiB]169 170The total size of buffers that are purgeable.171 172- drm-active-<region>: <uint> [KiB|MiB]173 174The total size of buffers that are active on one or more engines.175 176Implementation Details177======================178 179Drivers should use drm_show_fdinfo() in their `struct file_operations`, and180implement &drm_driver.show_fdinfo if they wish to provide any stats which181are not provided by drm_show_fdinfo(). But even driver specific stats should182be documented above and where possible, aligned with other drivers.183 184Driver specific implementations185-------------------------------186 187* :ref:`i915-usage-stats`188* :ref:`panfrost-usage-stats`189* :ref:`xe-usage-stats`190