1 .. _drm-client-usage-stats:
2
3 ======================
4 DRM client usage stats
5 ======================
6
7 DRM drivers can choose to export partly standa
8 `fops->show_fdinfo()` as part of the driver sp
9 in the `struct drm_driver` object registered w
10
11 One purpose of this output is to enable writin
12 feasible `top(1)` like userspace monitoring to
13
14 Given the differences between various DRM driv
15 output is split between common and driver spec
16 wherever possible effort should still be made
17 possible.
18
19 File format specification
20 =========================
21
22 - File shall contain one key value pair per on
23 - Colon character (`:`) must be used to delimi
24 - All keys shall be prefixed with `drm-`.
25 - Whitespace between the delimiter and first n
26 ignored when parsing.
27 - Keys are not allowed to contain whitespace c
28 - Numerical key value pairs can end with optio
29 - Data type of the value is fixed as defined i
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 t
42 - <keystr> - String excluding any above define
43 - <valstr> - String.
44
45 Mandatory fully standardised keys
46 ---------------------------------
47
48 - drm-driver: <valstr>
49
50 String shall contain the name this driver regi
51 `struct drm_driver` data structure.
52
53 Optional fully standardised keys
54 --------------------------------
55
56 Identification
57 ^^^^^^^^^^^^^^
58
59 - drm-pdev: <aaaa:bb.cc.d>
60
61 For PCI devices this should contain the PCI sl
62 question.
63
64 - drm-client-id: <uint>
65
66 Unique value relating to the open DRM file des
67 duplicated and shared file descriptors. Concep
68 to the in kernel representation of `struct drm
69
70 Uniqueness of the value shall be either global
71 scope of each device, in which case `drm-pdev`
72
73 Userspace should make sure to not double accou
74 the above described criteria in order to assoc
75
76 Utilization
77 ^^^^^^^^^^^
78
79 - drm-engine-<keystr>: <uint> ns
80
81 GPUs usually contain multiple execution engine
82 and unique name (keystr), with possible values
83 documentation.
84
85 Value shall be in specified time units which t
86 busy executing workloads belonging to this cli
87
88 Values are not required to be constantly monot
89 implementation easier, but are required to cat
90 larger value within a reasonable period. Upon
91 was previously read, userspace is expected to
92 value until a monotonic update is seen.
93
94 - drm-engine-capacity-<keystr>: <uint>
95
96 Engine identifier string must be the same as t
97 drm-engine-<keystr> tag and shall contain a gr
98 exported engine corresponds to a group of iden
99
100 In the absence of this tag parser shall assume
101 is not allowed.
102
103 - drm-cycles-<keystr>: <uint>
104
105 Engine identifier string must be the same as t
106 drm-engine-<keystr> tag and shall contain the
107 engine.
108
109 Values are not required to be constantly monot
110 implementation easier, but are required to cat
111 larger value within a reasonable period. Upon
112 was previously read, userspace is expected to
113 value until a monotonic update is seen.
114
115 - drm-total-cycles-<keystr>: <uint>
116
117 Engine identifier string must be the same as t
118 drm-cycles-<keystr> tag and shall contain the
119 engine.
120
121 This is a timestamp in GPU unspecified unit th
122 of drm-cycles-<keystr>. For drivers that imple
123 utilization can be calculated entirely on the
124 considering the CPU sleep time between 2 sampl
125
126 A driver may implement either this key or drm-
127
128 - drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz]
129
130 Engine identifier string must be the same as t
131 drm-engine-<keystr> tag and shall contain the
132 engine. Taken together with drm-cycles-<keyst
133 percentage utilization of the engine, whereas
134 time active without considering what frequency
135 percentage of its maximum frequency.
136
137 A driver may implement either this key or drm-
138 both.
139
140 Memory
141 ^^^^^^
142
143 - drm-memory-<region>: <uint> [KiB|MiB]
144
145 Each possible memory type which can be used to
146 GPU in question shall be given a stable and un
147 string here. The name "memory" is reserved to
148
149 Value shall reflect the amount of storage curr
150 objects belong to this client, in the respecti
151
152 Default unit shall be bytes with optional unit
153 indicating kibi- or mebi-bytes.
154
155 - drm-shared-<region>: <uint> [KiB|MiB]
156
157 The total size of buffers that are shared with
158 than a single handle).
159
160 - drm-total-<region>: <uint> [KiB|MiB]
161
162 The total size of buffers that including share
163
164 - drm-resident-<region>: <uint> [KiB|MiB]
165
166 The total size of buffers that are resident in
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 o
175
176 Implementation Details
177 ======================
178
179 Drivers should use drm_show_fdinfo() in their
180 implement &drm_driver.show_fdinfo if they wish
181 are not provided by drm_show_fdinfo(). But ev
182 be documented above and where possible, aligne
183
184 Driver specific implementations
185 -------------------------------
186
187 * :ref:`i915-usage-stats`
188 * :ref:`panfrost-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.