diff options
Diffstat (limited to 'Documentation/gpu/drm-usage-stats.rst')
| -rw-r--r-- | Documentation/gpu/drm-usage-stats.rst | 75 |
1 files changed, 60 insertions, 15 deletions
diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst index 6dc299343b48..63d6b2abe5ad 100644 --- a/Documentation/gpu/drm-usage-stats.rst +++ b/Documentation/gpu/drm-usage-stats.rst @@ -21,7 +21,10 @@ 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 keys shall be prefixed with `drm-`. +- All standardised keys shall be prefixed with `drm-`. +- Driver-specific keys shall be prefixed with `driver_name-`, where + driver_name should ideally be the same as the `name` field in + `struct drm_driver`, although this is not mandatory. - Whitespace between the delimiter and first non-whitespace character shall be ignored when parsing. - Keys are not allowed to contain whitespace characters. @@ -73,6 +76,11 @@ scope of each device, in which case `drm-pdev` shall be present as well. Userspace should make sure to not double account any usage statistics by using the 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 ^^^^^^^^^^^ @@ -112,6 +120,19 @@ larger value within a reasonable period. Upon observing a value lower than what was previously read, userspace is expected to stay with that larger previous value until a monotonic update is seen. +- drm-total-cycles-<keystr>: <uint> + +Engine identifier string must be the same as the one specified in the +drm-cycles-<keystr> tag and shall contain the total number cycles for the given +engine. + +This is a timestamp in GPU unspecified unit that matches the update rate +of drm-cycles-<keystr>. For drivers that implement this interface, the engine +utilization can be calculated entirely on the GPU clock domain, without +considering 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 the @@ -121,42 +142,64 @@ percentage utilization of the engine, whereas drm-engine-<keystr> only reflects time active without considering what frequency the engine is operating as a percentage of its maximum frequency. +A driver may implement either this key or drm-total-cycles-<keystr>, but not +both. + Memory ^^^^^^ -- drm-memory-<region>: <uint> [KiB|MiB] +Each possible memory type which can be used to store buffer objects by the GPU +in question shall be given a stable and unique name to be used as the "<region>" +string. -Each possible memory type which can be used to store buffer objects by the -GPU in question shall be given a stable and unique name to be returned as the -string here. The name "memory" is reserved to refer to normal system memory. +The region name "memory" is reserved to refer to normal system memory. -Value shall reflect the amount of storage currently consumed by the buffer +The value shall reflect the amount of storage currently consumed by the buffer objects 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-shared-<region>: <uint> [KiB|MiB] +- drm-total-<region>: <uint> [KiB|MiB] -The total size of buffers that are shared with another file (e.g., have more -than a single handle). +The total size of all requested buffers, including both shared and private +memory. The backing store for the buffers does not need to be currently +instantiated to count under this category. To avoid double-counting, if a buffer +has multiple regions where it can be allocated to, the implementation should +consistently select a single region for accounting purposes. -- drm-total-<region>: <uint> [KiB|MiB] +- drm-shared-<region>: <uint> [KiB|MiB] -The total size of buffers that including shared and private memory. +The total size of buffers that are shared with another file (i.e., have more +than one handle). The same requirement to avoid double-counting that applies to +drm-total-<region> also applies here. - drm-resident-<region>: <uint> [KiB|MiB] -The total size of buffers that are resident in the specified region. +The total size of buffers that are resident (i.e., have their backing store +present 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 for +drm-resident-<region>. - drm-purgeable-<region>: <uint> [KiB|MiB] -The total size of buffers that are purgeable. +The total size of buffers that are resident and purgeable. + +For example, drivers that implement functionality similar to 'madvise' can count +buffers that have instantiated backing stores but have been marked with an +equivalent 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 a +GEM buffer reservation object. Therefore, the active category is a subset of the +resident category. + Implementation Details ====================== @@ -168,5 +211,7 @@ be documented above and where possible, aligned with other drivers. Driver specific implementations ------------------------------- -:ref:`i915-usage-stats` -:ref:`panfrost-usage-stats` +* :ref:`i915-usage-stats` +* :ref:`panfrost-usage-stats` +* :ref:`panthor-usage-stats` +* :ref:`xe-usage-stats` |