Commit | Line | Data |
---|---|---|
2d12d3da TU |
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 | ||
d56b699d | 11 | One purpose of this output is to enable writing as generic as practically |
2d12d3da TU |
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. | |
90d63a15 | 27 | - Keys are not allowed to contain whitespace characters. |
2d12d3da TU |
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. | |
90d63a15 RC |
42 | - <keystr> - String excluding any above defined reserved characters or whitespace. |
43 | - <valstr> - String. | |
2d12d3da TU |
44 | |
45 | Mandatory fully standardised keys | |
46 | --------------------------------- | |
47 | ||
90d63a15 | 48 | - drm-driver: <valstr> |
2d12d3da TU |
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 | ||
686b21b5 RC |
56 | Identification |
57 | ^^^^^^^^^^^^^^ | |
58 | ||
2d12d3da TU |
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 | ||
686b21b5 RC |
76 | Utilization |
77 | ^^^^^^^^^^^ | |
78 | ||
90d63a15 | 79 | - drm-engine-<keystr>: <uint> ns |
2d12d3da TU |
80 | |
81 | GPUs usually contain multiple execution engines. Each shall be given a stable | |
90d63a15 | 82 | and unique name (keystr), with possible values documented in the driver specific |
2d12d3da TU |
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 | ||
90d63a15 | 94 | - drm-engine-capacity-<keystr>: <uint> |
2d12d3da TU |
95 | |
96 | Engine identifier string must be the same as the one specified in the | |
90d63a15 | 97 | drm-engine-<keystr> tag and shall contain a greater than zero number in case the |
2d12d3da TU |
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 | ||
90d63a15 | 103 | - drm-cycles-<keystr>: <uint> |
cfebe3fd RC |
104 | |
105 | Engine identifier string must be the same as the one specified in the | |
90d63a15 | 106 | drm-engine-<keystr> tag and shall contain the number of busy cycles for the given |
cfebe3fd RC |
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 | ||
188ced1e LDM |
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 | ||
90d63a15 | 128 | - drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz] |
cfebe3fd RC |
129 | |
130 | Engine identifier string must be the same as the one specified in the | |
90d63a15 RC |
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 | |
cfebe3fd | 134 | time active without considering what frequency the engine is operating as a |
d56b699d | 135 | percentage of its maximum frequency. |
cfebe3fd | 136 | |
188ced1e LDM |
137 | A driver may implement either this key or drm-total-cycles-<keystr>, but not |
138 | both. | |
139 | ||
686b21b5 RC |
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 | ||
77d17c4c | 157 | The total size of buffers that are shared with another file (e.g., have more |
686b21b5 RC |
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 | ||
3f09a0cd RC |
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 | ||
055634e4 | 184 | Driver specific implementations |
3f09a0cd | 185 | ------------------------------- |
055634e4 | 186 | |
188ced1e LDM |
187 | * :ref:`i915-usage-stats` |
188 | * :ref:`panfrost-usage-stats` | |
189 | * :ref:`xe-usage-stats` |