DRM client usage stats¶
DRM drivers can choose to export partly standardised text output via thefops->show_fdinfo() as part of the driver specific file operations registeredin thestructdrm_driver object registered with the DRM core.
One purpose of this output is to enable writing as generic as practicallyfeasibletop(1) like userspace monitoring tools.
Given the differences between various DRM drivers the specification of theoutput is split between common and driver specific parts. Having said that,wherever possible effort should still be made to standardise as much aspossible.
File format specification¶
File shall contain one key value pair per one line of text.
Colon character (:) must be used to delimit keys and values.
All standardised keys shall be prefixed withdrm-.
Driver-specific keys shall be prefixed withdriver_name-, wheredriver_name should ideally be the same as thename field in
structdrm_driver, although this is not mandatory.Whitespace between the delimiter and first non-whitespace character shall beignored when parsing.
Keys are not allowed to contain whitespace characters.
Numerical key value pairs can end with optional unit string.
Data type of the value is fixed as defined in the specification.
Key types¶
Mandatory, fully standardised.
Optional, fully standardised.
Driver specific.
Data types¶
<uint> - Unsigned integer without defining the maximum value.
<keystr> - String excluding any above defined reserved characters or whitespace.
<valstr> - String.
Mandatory fully standardised keys¶
drm-driver: <valstr>
String shall contain the name this driver registered as via the respectivestructdrm_driver data structure.
Optional fully standardised keys¶
Identification¶
drm-pdev: <aaaa:bb.cc.d>
For PCI devices this should contain the PCI slot address of the device inquestion.
drm-client-id: <uint>
Unique value relating to the open DRM file descriptor used to distinguishduplicated and shared file descriptors. Conceptually the value should map 1:1to the in kernel representation ofstructdrm_file instances.
Uniqueness of the value shall be either globally unique, or unique within thescope of each device, in which casedrm-pdev shall be present as well.
Userspace should make sure to not double account any usage statistics by usingthe above described criteria in order to associate data to individual clients.
drm-client-name: <valstr>
String optionally set by userspace using DRM_IOCTL_SET_CLIENT_NAME.
Utilization¶
drm-engine-<keystr>: <uint> ns
GPUs usually contain multiple execution engines. Each shall be given a stableand unique name (keystr), with possible values documented in the driver specificdocumentation.
Value shall be in specified time units which the respective GPU engine spentbusy executing workloads belonging to this client.
Values are not required to be constantly monotonic if it makes the driverimplementation easier, but are required to catch up with the previously reportedlarger value within a reasonable period. Upon observing a value lower than whatwas previously read, userspace is expected to stay with that larger previousvalue until a monotonic update is seen.
drm-engine-capacity-<keystr>: <uint>
Engine identifier string must be the same as the one specified in thedrm-engine-<keystr> tag and shall contain a greater than zero number in case theexported engine corresponds to a group of identical hardware engines.
In the absence of this tag parser shall assume capacity of one. Zero capacityis not allowed.
drm-cycles-<keystr>: <uint>
Engine identifier string must be the same as the one specified in thedrm-engine-<keystr> tag and shall contain the number of busy cycles for the givenengine.
Values are not required to be constantly monotonic if it makes the driverimplementation easier, but are required to catch up with the previously reportedlarger value within a reasonable period. Upon observing a value lower than whatwas previously read, userspace is expected to stay with that larger previousvalue until a monotonic update is seen.
drm-total-cycles-<keystr>: <uint>
Engine identifier string must be the same as the one specified in thedrm-cycles-<keystr> tag and shall contain the total number cycles for the givenengine.
This is a timestamp in GPU unspecified unit that matches the update rateof drm-cycles-<keystr>. For drivers that implement this interface, the engineutilization can be calculated entirely on the GPU clock domain, withoutconsidering the CPU sleep time between 2 samples.
A driver may implement either this key or drm-maxfreq-<keystr>, but not both.
drm-maxfreq-<keystr>: <uint> [Hz|MHz|KHz]
Engine identifier string must be the same as the one specified in thedrm-engine-<keystr> tag and shall contain the maximum frequency for the givenengine. Taken together with drm-cycles-<keystr>, this can be used to calculatepercentage utilization of the engine, whereas drm-engine-<keystr> only reflectstime active without considering what frequency the engine is operating as apercentage of its maximum frequency.
A driver may implement either this key or drm-total-cycles-<keystr>, but notboth.
Memory¶
Each possible memory type which can be used to store buffer objects by the GPUin question shall be given a stable and unique name to be used as the “<region>”string.
The region name “memory” is reserved to refer to normal system memory.
The value shall reflect the amount of storage currently consumed by the bufferobjects belong to this client, in the respective memory region.
Default unit shall be bytes with optional unit specifiers of ‘KiB’ or ‘MiB’indicating kibi- or mebi-bytes.
drm-total-<region>: <uint> [KiB|MiB]
The total size of all requested buffers, including both shared and privatememory. The backing store for the buffers does not need to be currentlyinstantiated to count under this category. To avoid double-counting, if a bufferhas multiple regions where it can be allocated to, the implementation shouldconsistently select a single region for accounting purposes.
drm-shared-<region>: <uint> [KiB|MiB]
The total size of buffers that are shared with another file (i.e., have morethan one handle). The same requirement to avoid double-counting that applies todrm-total-<region> also applies here.
drm-resident-<region>: <uint> [KiB|MiB]
The total size of buffers that are resident (i.e., have their backing storepresent or instantiated) in the specified region.
drm-memory-<region>: <uint> [KiB|MiB]
This key is deprecated and is only printed by amdgpu; it is an alias fordrm-resident-<region>.
drm-purgeable-<region>: <uint> [KiB|MiB]
The total size of buffers that are resident and purgeable.
For example, drivers that implement functionality similar to ‘madvise’ can countbuffers that have instantiated backing stores but have been marked with anequivalent of MADV_DONTNEED.
drm-active-<region>: <uint> [KiB|MiB]
The total size of buffers that are active on one or more engines.
One practical example of this could be the presence of unsignaled fences in aGEM buffer reservation object. Therefore, the active category is a subset of theresident category.
Implementation Details¶
Drivers should usedrm_show_fdinfo() in theirstructfile_operations, andimplement &drm_driver.show_fdinfo if they wish to provide any stats whichare not provided bydrm_show_fdinfo(). But even driver specific stats shouldbe documented above and where possible, aligned with other drivers.