@@ -24,7 +24,7 @@ File format specification
2424- All keys shall be prefixed with `drm- `.
2525- Whitespace between the delimiter and first non-whitespace character shall be
2626 ignored when parsing.
27- - Neither keys or values are allowed to contain whitespace characters.
27+ - Keys are not allowed to contain whitespace characters.
2828- Numerical key value pairs can end with optional unit string.
2929- Data type of the value is fixed as defined in the specification.
3030
@@ -39,19 +39,23 @@ Data types
3939----------
4040
4141- <uint> - Unsigned integer without defining the maximum value.
42- - <str> - String excluding any above defined reserved characters or whitespace.
42+ - <keystr> - String excluding any above defined reserved characters or whitespace.
43+ - <valstr> - String.
4344
4445Mandatory fully standardised keys
4546---------------------------------
4647
47- - drm-driver: <str >
48+ - drm-driver: <valstr >
4849
4950String shall contain the name this driver registered as via the respective
5051`struct drm_driver ` data structure.
5152
5253Optional fully standardised keys
5354--------------------------------
5455
56+ Identification
57+ ^^^^^^^^^^^^^^
58+
5559- drm-pdev: <aaaa:bb.cc.d>
5660
5761For PCI devices this should contain the PCI slot address of the device in
@@ -69,10 +73,13 @@ scope of each device, in which case `drm-pdev` shall be present as well.
6973Userspace should make sure to not double account any usage statistics by using
7074the above described criteria in order to associate data to individual clients.
7175
72- - drm-engine-<str>: <uint> ns
76+ Utilization
77+ ^^^^^^^^^^^
78+
79+ - drm-engine-<keystr>: <uint> ns
7380
7481GPUs usually contain multiple execution engines. Each shall be given a stable
75- and unique name (str ), with possible values documented in the driver specific
82+ and unique name (keystr ), with possible values documented in the driver specific
7683documentation.
7784
7885Value shall be in specified time units which the respective GPU engine spent
@@ -84,31 +91,19 @@ larger value within a reasonable period. Upon observing a value lower than what
8491was previously read, userspace is expected to stay with that larger previous
8592value until a monotonic update is seen.
8693
87- - drm-engine-capacity-<str >: <uint>
94+ - drm-engine-capacity-<keystr >: <uint>
8895
8996Engine 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
97+ drm-engine-<keystr > tag and shall contain a greater than zero number in case the
9198exported engine corresponds to a group of identical hardware engines.
9299
93100In the absence of this tag parser shall assume capacity of one. Zero capacity
94101is not allowed.
95102
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- - drm-cycles-<str> <uint>
103+ - drm-cycles-<keystr>: <uint>
109104
110105Engine identifier string must be the same as the one specified in the
111- drm-engine-<str > tag and shall contain the number of busy cycles for the given
106+ drm-engine-<keystr > tag and shall contain the number of busy cycles for the given
112107engine.
113108
114109Values are not required to be constantly monotonic if it makes the driver
@@ -117,16 +112,60 @@ larger value within a reasonable period. Upon observing a value lower than what
117112was previously read, userspace is expected to stay with that larger previous
118113value until a monotonic update is seen.
119114
120- - drm-maxfreq-<str> <uint> [Hz|MHz|KHz]
115+ - drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz]
121116
122117Engine identifier string must be the same as the one specified in the
123- drm-engine-<str > tag and shall contain the maximum frequency for the given
124- engine. Taken together with drm-cycles-<str >, this can be used to calculate
125- percentage utilization of the engine, whereas drm-engine-<str > only reflects
118+ drm-engine-<keystr > tag and shall contain the maximum frequency for the given
119+ engine. Taken together with drm-cycles-<keystr >, this can be used to calculate
120+ percentage utilization of the engine, whereas drm-engine-<keystr > only reflects
126121time active without considering what frequency the engine is operating as a
127122percentage of it's maximum frequency.
128123
124+ Memory
125+ ^^^^^^
126+
127+ - drm-memory-<region>: <uint> [KiB|MiB]
128+
129+ Each possible memory type which can be used to store buffer objects by the
130+ GPU in question shall be given a stable and unique name to be returned as the
131+ string here. The name "memory" is reserved to refer to normal system memory.
132+
133+ Value shall reflect the amount of storage currently consumed by the buffer
134+ objects belong to this client, in the respective memory region.
135+
136+ Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB'
137+ indicating kibi- or mebi-bytes.
138+
139+ - drm-shared-<region>: <uint> [KiB|MiB]
140+
141+ The total size of buffers that are shared with another file (ie. have more
142+ than a single handle).
143+
144+ - drm-total-<region>: <uint> [KiB|MiB]
145+
146+ The total size of buffers that including shared and private memory.
147+
148+ - drm-resident-<region>: <uint> [KiB|MiB]
149+
150+ The total size of buffers that are resident in the specified region.
151+
152+ - drm-purgeable-<region>: <uint> [KiB|MiB]
153+
154+ The total size of buffers that are purgeable.
155+
156+ - drm-active-<region>: <uint> [KiB|MiB]
157+
158+ The total size of buffers that are active on one or more engines.
159+
160+ Implementation Details
161+ ======================
162+
163+ Drivers should use drm_show_fdinfo() in their `struct file_operations `, and
164+ implement &drm_driver.show_fdinfo if they wish to provide any stats which
165+ are not provided by drm_show_fdinfo(). But even driver specific stats should
166+ be documented above and where possible, aligned with other drivers.
167+
129168Driver specific implementations
130- ===============================
169+ -------------------------------
131170
132171:ref: `i915-usage-stats `
0 commit comments