|
| 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 | +- Neither keys or values are 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 | +- <str> - String excluding any above defined reserved characters or whitespace. |
| 43 | + |
| 44 | +Mandatory fully standardised keys |
| 45 | +--------------------------------- |
| 46 | + |
| 47 | +- drm-driver: <str> |
| 48 | + |
| 49 | +String shall contain the name this driver registered as via the respective |
| 50 | +`struct drm_driver` data structure. |
| 51 | + |
| 52 | +Optional fully standardised keys |
| 53 | +-------------------------------- |
| 54 | + |
| 55 | +- drm-pdev: <aaaa:bb.cc.d> |
| 56 | + |
| 57 | +For PCI devices this should contain the PCI slot address of the device in |
| 58 | +question. |
| 59 | + |
| 60 | +- drm-client-id: <uint> |
| 61 | + |
| 62 | +Unique value relating to the open DRM file descriptor used to distinguish |
| 63 | +duplicated and shared file descriptors. Conceptually the value should map 1:1 |
| 64 | +to the in kernel representation of `struct drm_file` instances. |
| 65 | + |
| 66 | +Uniqueness of the value shall be either globally unique, or unique within the |
| 67 | +scope of each device, in which case `drm-pdev` shall be present as well. |
| 68 | + |
| 69 | +Userspace should make sure to not double account any usage statistics by using |
| 70 | +the above described criteria in order to associate data to individual clients. |
| 71 | + |
| 72 | +- drm-engine-<str>: <uint> ns |
| 73 | + |
| 74 | +GPUs usually contain multiple execution engines. Each shall be given a stable |
| 75 | +and unique name (str), with possible values documented in the driver specific |
| 76 | +documentation. |
| 77 | + |
| 78 | +Value shall be in specified time units which the respective GPU engine spent |
| 79 | +busy executing workloads belonging to this client. |
| 80 | + |
| 81 | +Values are not required to be constantly monotonic if it makes the driver |
| 82 | +implementation easier, but are required to catch up with the previously reported |
| 83 | +larger value within a reasonable period. Upon observing a value lower than what |
| 84 | +was previously read, userspace is expected to stay with that larger previous |
| 85 | +value until a monotonic update is seen. |
| 86 | + |
| 87 | +- drm-engine-capacity-<str>: <uint> |
| 88 | + |
| 89 | +Engine identifier string must be the same as the one specified in the |
| 90 | +drm-engine-<str> tag and shall contain a greater than zero number in case the |
| 91 | +exported engine corresponds to a group of identical hardware engines. |
| 92 | + |
| 93 | +In the absence of this tag parser shall assume capacity of one. Zero capacity |
| 94 | +is not allowed. |
| 95 | + |
| 96 | +- drm-memory-<str>: <uint> [KiB|MiB] |
| 97 | + |
| 98 | +Each possible memory type which can be used to store buffer objects by the |
| 99 | +GPU in question shall be given a stable and unique name to be returned as the |
| 100 | +string here. |
| 101 | + |
| 102 | +Value shall reflect the amount of storage currently consumed by the buffer |
| 103 | +object belong to this client, in the respective memory region. |
| 104 | + |
| 105 | +Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB' |
| 106 | +indicating kibi- or mebi-bytes. |
| 107 | + |
| 108 | +=============================== |
| 109 | +Driver specific implementations |
| 110 | +=============================== |
| 111 | + |
| 112 | +:ref:`i915-usage-stats` |
0 commit comments