1.. _drm-client-usage-stats:
2
3======================
4DRM client usage stats
5======================
6
7DRM drivers can choose to export partly standardised text output via the
8`fops->show_fdinfo()` as part of the driver specific file operations registered
9in the `struct drm_driver` object registered with the DRM core.
10
11One purpose of this output is to enable writing as generic as practicaly
12feasible `top(1)` like userspace monitoring tools.
13
14Given the differences between various DRM drivers the specification of the
15output is split between common and driver specific parts. Having said that,
16wherever possible effort should still be made to standardise as much as
17possible.
18
19File 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- 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 types
32---------
33
341. Mandatory, fully standardised.
352. Optional, fully standardised.
363. Driver specific.
37
38Data types
39----------
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 keys
46---------------------------------
47
48- drm-driver: <valstr>
49
50String shall contain the name this driver registered as via the respective
51`struct drm_driver` data structure.
52
53Optional fully standardised keys
54--------------------------------
55
56Identification
57^^^^^^^^^^^^^^
58
59- drm-pdev: <aaaa:bb.cc.d>
60
61For PCI devices this should contain the PCI slot address of the device in
62question.
63
64- drm-client-id: <uint>
65
66Unique value relating to the open DRM file descriptor used to distinguish
67duplicated and shared file descriptors. Conceptually the value should map 1:1
68to the in kernel representation of `struct drm_file` instances.
69
70Uniqueness of the value shall be either globally unique, or unique within the
71scope 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 using
74the above described criteria in order to associate data to individual clients.
75
76Utilization
77^^^^^^^^^^^
78
79- drm-engine-<keystr>: <uint> ns
80
81GPUs usually contain multiple execution engines. Each shall be given a stable
82and unique name (keystr), with possible values documented in the driver specific
83documentation.
84
85Value shall be in specified time units which the respective GPU engine spent
86busy executing workloads belonging to this client.
87
88Values are not required to be constantly monotonic if it makes the driver
89implementation easier, but are required to catch up with the previously reported
90larger value within a reasonable period. Upon observing a value lower than what
91was previously read, userspace is expected to stay with that larger previous
92value 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 the
97drm-engine-<keystr> tag and shall contain a greater than zero number in case the
98exported engine corresponds to a group of identical hardware engines.
99
100In the absence of this tag parser shall assume capacity of one. Zero capacity
101is not allowed.
102
103- drm-cycles-<keystr>: <uint>
104
105Engine identifier string must be the same as the one specified in the
106drm-engine-<keystr> tag and shall contain the number of busy cycles for the given
107engine.
108
109Values are not required to be constantly monotonic if it makes the driver
110implementation easier, but are required to catch up with the previously reported
111larger value within a reasonable period. Upon observing a value lower than what
112was previously read, userspace is expected to stay with that larger previous
113value until a monotonic update is seen.
114
115- drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz]
116
117Engine identifier string must be the same as the one specified in the
118drm-engine-<keystr> tag and shall contain the maximum frequency for the given
119engine.  Taken together with drm-cycles-<keystr>, this can be used to calculate
120percentage utilization of the engine, whereas drm-engine-<keystr> only reflects
121time active without considering what frequency the engine is operating as a
122percentage of it's maximum frequency.
123
124Memory
125^^^^^^
126
127- drm-memory-<region>: <uint> [KiB|MiB]
128
129Each possible memory type which can be used to store buffer objects by the
130GPU in question shall be given a stable and unique name to be returned as the
131string here.  The name "memory" is reserved to refer to normal system memory.
132
133Value shall reflect the amount of storage currently consumed by the buffer
134objects belong to this client, in the respective memory region.
135
136Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB'
137indicating kibi- or mebi-bytes.
138
139- drm-shared-<region>: <uint> [KiB|MiB]
140
141The total size of buffers that are shared with another file (ie. have more
142than a single handle).
143
144- drm-total-<region>: <uint> [KiB|MiB]
145
146The total size of buffers that including shared and private memory.
147
148- drm-resident-<region>: <uint> [KiB|MiB]
149
150The total size of buffers that are resident in the specified region.
151
152- drm-purgeable-<region>: <uint> [KiB|MiB]
153
154The total size of buffers that are purgeable.
155
156- drm-active-<region>: <uint> [KiB|MiB]
157
158The total size of buffers that are active on one or more engines.
159
160Implementation Details
161======================
162
163Drivers should use drm_show_fdinfo() in their `struct file_operations`, and
164implement &drm_driver.show_fdinfo if they wish to provide any stats which
165are not provided by drm_show_fdinfo().  But even driver specific stats should
166be documented above and where possible, aligned with other drivers.
167
168Driver specific implementations
169-------------------------------
170
171:ref:`i915-usage-stats`
172