1 .. _drm-client-usage-stats: 1 .. _drm-client-usage-stats:
2 2
3 ====================== 3 ======================
4 DRM client usage stats 4 DRM client usage stats
5 ====================== 5 ======================
6 6
7 DRM drivers can choose to export partly standa 7 DRM drivers can choose to export partly standardised text output via the
8 `fops->show_fdinfo()` as part of the driver sp 8 `fops->show_fdinfo()` as part of the driver specific file operations registered
9 in the `struct drm_driver` object registered w 9 in the `struct drm_driver` object registered with the DRM core.
10 10
11 One purpose of this output is to enable writin 11 One purpose of this output is to enable writing as generic as practically
12 feasible `top(1)` like userspace monitoring to 12 feasible `top(1)` like userspace monitoring tools.
13 13
14 Given the differences between various DRM driv 14 Given the differences between various DRM drivers the specification of the
15 output is split between common and driver spec 15 output is split between common and driver specific parts. Having said that,
16 wherever possible effort should still be made 16 wherever possible effort should still be made to standardise as much as
17 possible. 17 possible.
18 18
19 File format specification 19 File format specification
20 ========================= 20 =========================
21 21
22 - File shall contain one key value pair per on 22 - File shall contain one key value pair per one line of text.
23 - Colon character (`:`) must be used to delimi 23 - Colon character (`:`) must be used to delimit keys and values.
24 - All keys shall be prefixed with `drm-`. 24 - All keys shall be prefixed with `drm-`.
25 - Whitespace between the delimiter and first n 25 - Whitespace between the delimiter and first non-whitespace character shall be
26 ignored when parsing. 26 ignored when parsing.
27 - Keys are not allowed to contain whitespace c 27 - Keys are not allowed to contain whitespace characters.
28 - Numerical key value pairs can end with optio 28 - Numerical key value pairs can end with optional unit string.
29 - Data type of the value is fixed as defined i 29 - Data type of the value is fixed as defined in the specification.
30 30
31 Key types 31 Key types
32 --------- 32 ---------
33 33
34 1. Mandatory, fully standardised. 34 1. Mandatory, fully standardised.
35 2. Optional, fully standardised. 35 2. Optional, fully standardised.
36 3. Driver specific. 36 3. Driver specific.
37 37
38 Data types 38 Data types
39 ---------- 39 ----------
40 40
41 - <uint> - Unsigned integer without defining t 41 - <uint> - Unsigned integer without defining the maximum value.
42 - <keystr> - String excluding any above define 42 - <keystr> - String excluding any above defined reserved characters or whitespace.
43 - <valstr> - String. 43 - <valstr> - String.
44 44
45 Mandatory fully standardised keys 45 Mandatory fully standardised keys
46 --------------------------------- 46 ---------------------------------
47 47
48 - drm-driver: <valstr> 48 - drm-driver: <valstr>
49 49
50 String shall contain the name this driver regi 50 String shall contain the name this driver registered as via the respective
51 `struct drm_driver` data structure. 51 `struct drm_driver` data structure.
52 52
53 Optional fully standardised keys 53 Optional fully standardised keys
54 -------------------------------- 54 --------------------------------
55 55
56 Identification 56 Identification
57 ^^^^^^^^^^^^^^ 57 ^^^^^^^^^^^^^^
58 58
59 - drm-pdev: <aaaa:bb.cc.d> 59 - drm-pdev: <aaaa:bb.cc.d>
60 60
61 For PCI devices this should contain the PCI sl 61 For PCI devices this should contain the PCI slot address of the device in
62 question. 62 question.
63 63
64 - drm-client-id: <uint> 64 - drm-client-id: <uint>
65 65
66 Unique value relating to the open DRM file des 66 Unique value relating to the open DRM file descriptor used to distinguish
67 duplicated and shared file descriptors. Concep 67 duplicated and shared file descriptors. Conceptually the value should map 1:1
68 to the in kernel representation of `struct drm 68 to the in kernel representation of `struct drm_file` instances.
69 69
70 Uniqueness of the value shall be either global 70 Uniqueness of the value shall be either globally unique, or unique within the
71 scope of each device, in which case `drm-pdev` 71 scope of each device, in which case `drm-pdev` shall be present as well.
72 72
73 Userspace should make sure to not double accou 73 Userspace should make sure to not double account any usage statistics by using
74 the above described criteria in order to assoc 74 the above described criteria in order to associate data to individual clients.
75 75
76 Utilization 76 Utilization
77 ^^^^^^^^^^^ 77 ^^^^^^^^^^^
78 78
79 - drm-engine-<keystr>: <uint> ns 79 - drm-engine-<keystr>: <uint> ns
80 80
81 GPUs usually contain multiple execution engine 81 GPUs usually contain multiple execution engines. Each shall be given a stable
82 and unique name (keystr), with possible values 82 and unique name (keystr), with possible values documented in the driver specific
83 documentation. 83 documentation.
84 84
85 Value shall be in specified time units which t 85 Value shall be in specified time units which the respective GPU engine spent
86 busy executing workloads belonging to this cli 86 busy executing workloads belonging to this client.
87 87
88 Values are not required to be constantly monot 88 Values are not required to be constantly monotonic if it makes the driver
89 implementation easier, but are required to cat 89 implementation easier, but are required to catch up with the previously reported
90 larger value within a reasonable period. Upon 90 larger value within a reasonable period. Upon observing a value lower than what
91 was previously read, userspace is expected to 91 was previously read, userspace is expected to stay with that larger previous
92 value until a monotonic update is seen. 92 value until a monotonic update is seen.
93 93
94 - drm-engine-capacity-<keystr>: <uint> 94 - drm-engine-capacity-<keystr>: <uint>
95 95
96 Engine identifier string must be the same as t 96 Engine identifier string must be the same as the one specified in the
97 drm-engine-<keystr> tag and shall contain a gr 97 drm-engine-<keystr> tag and shall contain a greater than zero number in case the
98 exported engine corresponds to a group of iden 98 exported engine corresponds to a group of identical hardware engines.
99 99
100 In the absence of this tag parser shall assume 100 In the absence of this tag parser shall assume capacity of one. Zero capacity
101 is not allowed. 101 is not allowed.
102 102
103 - drm-cycles-<keystr>: <uint> 103 - drm-cycles-<keystr>: <uint>
104 104
105 Engine identifier string must be the same as t 105 Engine identifier string must be the same as the one specified in the
106 drm-engine-<keystr> tag and shall contain the 106 drm-engine-<keystr> tag and shall contain the number of busy cycles for the given
107 engine. 107 engine.
108 108
109 Values are not required to be constantly monot 109 Values are not required to be constantly monotonic if it makes the driver
110 implementation easier, but are required to cat 110 implementation easier, but are required to catch up with the previously reported
111 larger value within a reasonable period. Upon 111 larger value within a reasonable period. Upon observing a value lower than what
112 was previously read, userspace is expected to 112 was previously read, userspace is expected to stay with that larger previous
113 value until a monotonic update is seen. 113 value until a monotonic update is seen.
114 114
115 - drm-total-cycles-<keystr>: <uint> 115 - drm-total-cycles-<keystr>: <uint>
116 116
117 Engine identifier string must be the same as t 117 Engine identifier string must be the same as the one specified in the
118 drm-cycles-<keystr> tag and shall contain the 118 drm-cycles-<keystr> tag and shall contain the total number cycles for the given
119 engine. 119 engine.
120 120
121 This is a timestamp in GPU unspecified unit th 121 This is a timestamp in GPU unspecified unit that matches the update rate
122 of drm-cycles-<keystr>. For drivers that imple 122 of drm-cycles-<keystr>. For drivers that implement this interface, the engine
123 utilization can be calculated entirely on the 123 utilization can be calculated entirely on the GPU clock domain, without
124 considering the CPU sleep time between 2 sampl 124 considering the CPU sleep time between 2 samples.
125 125
126 A driver may implement either this key or drm- 126 A driver may implement either this key or drm-maxfreq-<keystr>, but not both.
127 127
128 - drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz] 128 - drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz]
129 129
130 Engine identifier string must be the same as t 130 Engine identifier string must be the same as the one specified in the
131 drm-engine-<keystr> tag and shall contain the 131 drm-engine-<keystr> tag and shall contain the maximum frequency for the given
132 engine. Taken together with drm-cycles-<keyst 132 engine. Taken together with drm-cycles-<keystr>, this can be used to calculate
133 percentage utilization of the engine, whereas 133 percentage utilization of the engine, whereas drm-engine-<keystr> only reflects
134 time active without considering what frequency 134 time active without considering what frequency the engine is operating as a
135 percentage of its maximum frequency. 135 percentage of its maximum frequency.
136 136
137 A driver may implement either this key or drm- 137 A driver may implement either this key or drm-total-cycles-<keystr>, but not
138 both. 138 both.
139 139
140 Memory 140 Memory
141 ^^^^^^ 141 ^^^^^^
142 142
143 - drm-memory-<region>: <uint> [KiB|MiB] 143 - drm-memory-<region>: <uint> [KiB|MiB]
144 144
145 Each possible memory type which can be used to 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 un 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 147 string here. The name "memory" is reserved to refer to normal system memory.
148 148
149 Value shall reflect the amount of storage curr 149 Value shall reflect the amount of storage currently consumed by the buffer
150 objects belong to this client, in the respecti 150 objects belong to this client, in the respective memory region.
151 151
152 Default unit shall be bytes with optional unit 152 Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB'
153 indicating kibi- or mebi-bytes. 153 indicating kibi- or mebi-bytes.
154 154
155 - drm-shared-<region>: <uint> [KiB|MiB] 155 - drm-shared-<region>: <uint> [KiB|MiB]
156 156
157 The total size of buffers that are shared with 157 The total size of buffers that are shared with another file (e.g., have more
158 than a single handle). 158 than a single handle).
159 159
160 - drm-total-<region>: <uint> [KiB|MiB] 160 - drm-total-<region>: <uint> [KiB|MiB]
161 161
162 The total size of buffers that including share 162 The total size of buffers that including shared and private memory.
163 163
164 - drm-resident-<region>: <uint> [KiB|MiB] 164 - drm-resident-<region>: <uint> [KiB|MiB]
165 165
166 The total size of buffers that are resident in 166 The total size of buffers that are resident in the specified region.
167 167
168 - drm-purgeable-<region>: <uint> [KiB|MiB] 168 - drm-purgeable-<region>: <uint> [KiB|MiB]
169 169
170 The total size of buffers that are purgeable. 170 The total size of buffers that are purgeable.
171 171
172 - drm-active-<region>: <uint> [KiB|MiB] 172 - drm-active-<region>: <uint> [KiB|MiB]
173 173
174 The total size of buffers that are active on o 174 The total size of buffers that are active on one or more engines.
175 175
176 Implementation Details 176 Implementation Details
177 ====================== 177 ======================
178 178
179 Drivers should use drm_show_fdinfo() in their 179 Drivers should use drm_show_fdinfo() in their `struct file_operations`, and
180 implement &drm_driver.show_fdinfo if they wish 180 implement &drm_driver.show_fdinfo if they wish to provide any stats which
181 are not provided by drm_show_fdinfo(). But ev 181 are not provided by drm_show_fdinfo(). But even driver specific stats should
182 be documented above and where possible, aligne 182 be documented above and where possible, aligned with other drivers.
183 183
184 Driver specific implementations 184 Driver specific implementations
185 ------------------------------- 185 -------------------------------
186 186
187 * :ref:`i915-usage-stats` 187 * :ref:`i915-usage-stats`
188 * :ref:`panfrost-usage-stats` 188 * :ref:`panfrost-usage-stats`
189 * :ref:`xe-usage-stats` 189 * :ref:`xe-usage-stats`
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.