0001 .. _drm-client-usage-stats:
0002
0003 ======================
0004 DRM client usage stats
0005 ======================
0006
0007 DRM drivers can choose to export partly standardised text output via the
0008 `fops->show_fdinfo()` as part of the driver specific file operations registered
0009 in the `struct drm_driver` object registered with the DRM core.
0010
0011 One purpose of this output is to enable writing as generic as practicaly
0012 feasible `top(1)` like userspace monitoring tools.
0013
0014 Given the differences between various DRM drivers the specification of the
0015 output is split between common and driver specific parts. Having said that,
0016 wherever possible effort should still be made to standardise as much as
0017 possible.
0018
0019 File format specification
0020 =========================
0021
0022 - File shall contain one key value pair per one line of text.
0023 - Colon character (`:`) must be used to delimit keys and values.
0024 - All keys shall be prefixed with `drm-`.
0025 - Whitespace between the delimiter and first non-whitespace character shall be
0026 ignored when parsing.
0027 - Neither keys or values are allowed to contain whitespace characters.
0028 - Numerical key value pairs can end with optional unit string.
0029 - Data type of the value is fixed as defined in the specification.
0030
0031 Key types
0032 ---------
0033
0034 1. Mandatory, fully standardised.
0035 2. Optional, fully standardised.
0036 3. Driver specific.
0037
0038 Data types
0039 ----------
0040
0041 - <uint> - Unsigned integer without defining the maximum value.
0042 - <str> - String excluding any above defined reserved characters or whitespace.
0043
0044 Mandatory fully standardised keys
0045 ---------------------------------
0046
0047 - drm-driver: <str>
0048
0049 String shall contain the name this driver registered as via the respective
0050 `struct drm_driver` data structure.
0051
0052 Optional fully standardised keys
0053 --------------------------------
0054
0055 - drm-pdev: <aaaa:bb.cc.d>
0056
0057 For PCI devices this should contain the PCI slot address of the device in
0058 question.
0059
0060 - drm-client-id: <uint>
0061
0062 Unique value relating to the open DRM file descriptor used to distinguish
0063 duplicated and shared file descriptors. Conceptually the value should map 1:1
0064 to the in kernel representation of `struct drm_file` instances.
0065
0066 Uniqueness of the value shall be either globally unique, or unique within the
0067 scope of each device, in which case `drm-pdev` shall be present as well.
0068
0069 Userspace should make sure to not double account any usage statistics by using
0070 the above described criteria in order to associate data to individual clients.
0071
0072 - drm-engine-<str>: <uint> ns
0073
0074 GPUs usually contain multiple execution engines. Each shall be given a stable
0075 and unique name (str), with possible values documented in the driver specific
0076 documentation.
0077
0078 Value shall be in specified time units which the respective GPU engine spent
0079 busy executing workloads belonging to this client.
0080
0081 Values are not required to be constantly monotonic if it makes the driver
0082 implementation easier, but are required to catch up with the previously reported
0083 larger value within a reasonable period. Upon observing a value lower than what
0084 was previously read, userspace is expected to stay with that larger previous
0085 value until a monotonic update is seen.
0086
0087 - drm-engine-capacity-<str>: <uint>
0088
0089 Engine identifier string must be the same as the one specified in the
0090 drm-engine-<str> tag and shall contain a greater than zero number in case the
0091 exported engine corresponds to a group of identical hardware engines.
0092
0093 In the absence of this tag parser shall assume capacity of one. Zero capacity
0094 is not allowed.
0095
0096 - drm-memory-<str>: <uint> [KiB|MiB]
0097
0098 Each possible memory type which can be used to store buffer objects by the
0099 GPU in question shall be given a stable and unique name to be returned as the
0100 string here.
0101
0102 Value shall reflect the amount of storage currently consumed by the buffer
0103 object belong to this client, in the respective memory region.
0104
0105 Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB'
0106 indicating kibi- or mebi-bytes.
0107
0108 - drm-cycles-<str> <uint>
0109
0110 Engine identifier string must be the same as the one specified in the
0111 drm-engine-<str> tag and shall contain the number of busy cycles for the given
0112 engine.
0113
0114 Values are not required to be constantly monotonic if it makes the driver
0115 implementation easier, but are required to catch up with the previously reported
0116 larger value within a reasonable period. Upon observing a value lower than what
0117 was previously read, userspace is expected to stay with that larger previous
0118 value until a monotonic update is seen.
0119
0120 - drm-maxfreq-<str> <uint> [Hz|MHz|KHz]
0121
0122 Engine identifier string must be the same as the one specified in the
0123 drm-engine-<str> tag and shall contain the maximum frequency for the given
0124 engine. Taken together with drm-cycles-<str>, this can be used to calculate
0125 percentage utilization of the engine, whereas drm-engine-<str> only reflects
0126 time active without considering what frequency the engine is operating as a
0127 percentage of it's maximum frequency.
0128
0129 ===============================
0130 Driver specific implementations
0131 ===============================
0132
0133 :ref:`i915-usage-stats`
