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 | ||
11 | One purpose of this output is to enable writing as generic as practicaly | |
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. | |
27 | - Neither keys or values are 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 | ||
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. | |
42 | - <str> - String excluding any above defined reserved characters or whitespace. | |
43 | ||
44 | Mandatory fully standardised keys | |
45 | --------------------------------- | |
46 | ||
47 | - drm-driver: <str> | |
48 | ||
49 | String shall contain the name this driver registered as via the respective | |
50 | `struct drm_driver` data structure. | |
51 | ||
52 | Optional fully standardised keys | |
53 | -------------------------------- | |
54 | ||
55 | - drm-pdev: <aaaa:bb.cc.d> | |
56 | ||
57 | For PCI devices this should contain the PCI slot address of the device in | |
58 | question. | |
59 | ||
60 | - drm-client-id: <uint> | |
61 | ||
62 | Unique value relating to the open DRM file descriptor used to distinguish | |
63 | duplicated and shared file descriptors. Conceptually the value should map 1:1 | |
64 | to the in kernel representation of `struct drm_file` instances. | |
65 | ||
66 | Uniqueness of the value shall be either globally unique, or unique within the | |
67 | scope of each device, in which case `drm-pdev` shall be present as well. | |
68 | ||
69 | Userspace should make sure to not double account any usage statistics by using | |
70 | the above described criteria in order to associate data to individual clients. | |
71 | ||
72 | - drm-engine-<str>: <uint> ns | |
73 | ||
74 | GPUs usually contain multiple execution engines. Each shall be given a stable | |
75 | and unique name (str), with possible values documented in the driver specific | |
76 | documentation. | |
77 | ||
78 | Value shall be in specified time units which the respective GPU engine spent | |
79 | busy executing workloads belonging to this client. | |
80 | ||
81 | Values are not required to be constantly monotonic if it makes the driver | |
82 | implementation easier, but are required to catch up with the previously reported | |
83 | larger value within a reasonable period. Upon observing a value lower than what | |
84 | was previously read, userspace is expected to stay with that larger previous | |
85 | value until a monotonic update is seen. | |
86 | ||
87 | - drm-engine-capacity-<str>: <uint> | |
88 | ||
89 | Engine 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 | |
91 | exported engine corresponds to a group of identical hardware engines. | |
92 | ||
93 | In the absence of this tag parser shall assume capacity of one. Zero capacity | |
94 | is not allowed. | |
95 | ||
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. | |
055634e4 | 107 | |
cfebe3fd RC |
108 | - drm-cycles-<str> <uint> |
109 | ||
110 | Engine 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 | |
112 | engine. | |
113 | ||
114 | Values are not required to be constantly monotonic if it makes the driver | |
115 | implementation easier, but are required to catch up with the previously reported | |
116 | larger value within a reasonable period. Upon observing a value lower than what | |
117 | was previously read, userspace is expected to stay with that larger previous | |
118 | value until a monotonic update is seen. | |
119 | ||
120 | - drm-maxfreq-<str> <uint> [Hz|MHz|KHz] | |
121 | ||
122 | Engine 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 | |
126 | time active without considering what frequency the engine is operating as a | |
127 | percentage of it's maximum frequency. | |
128 | ||
055634e4 TU |
129 | =============================== |
130 | Driver specific implementations | |
131 | =============================== | |
132 | ||
133 | :ref:`i915-usage-stats` |