?sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget'/translations/zh_CN/gpu/drm-usage-statsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/zh_TW/gpu/drm-usage-statsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/it_IT/gpu/drm-usage-statsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ja_JP/gpu/drm-usage-statsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ko_KR/gpu/drm-usage-statsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/pt_BR/gpu/drm-usage-statsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/sp_SP/gpu/drm-usage-statsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhtarget)}(h.. _drm-client-usage-stats:h]h}(h]h ]h"]h$]h&]refiddrm-client-usage-statsuh1hhKhhhhhA/var/lib/git/docbuild/linux/Documentation/gpu/drm-usage-stats.rstubhsection)}(hhh](htitle)}(hDRM client usage statsh]hDRM client usage stats}(hhhhhNhNubah}(h]h ]h"]h$]h&]hid2uh1hhhhhhhhKubh paragraph)}(hDRM drivers can choose to export partly standardised text output via the `fops->show_fdinfo()` as part of the driver specific file operations registered in the `struct drm_driver` object registered with the DRM core.h](hIDRM drivers can choose to export partly standardised text output via the }(hhhhhNhNubhtitle_reference)}(h`fops->show_fdinfo()`h]hfops->show_fdinfo()}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubhB as part of the driver specific file operations registered in the }(hhhhhNhNubh)}(h`struct drm_driver`h]hstruct drm_driver}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh% object registered with the DRM core.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(h|One purpose of this output is to enable writing as generic as practically feasible `top(1)` like userspace monitoring tools.h](hSOne purpose of this output is to enable writing as generic as practically feasible }(hjhhhNhNubh)}(h`top(1)`h]htop(1)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh! like userspace monitoring tools.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hGiven the differences between various DRM drivers the specification of the output is split between common and driver specific parts. Having said that, wherever possible effort should still be made to standardise as much as possible.h]hGiven the differences between various DRM drivers the specification of the output is split between common and driver specific parts. Having said that, wherever possible effort should still be made to standardise as much as possible.}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubhtopic)}(h Contents h](h)}(hContentsh]hContents}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj@hhhKubh bullet_list)}(hhh]h list_item)}(hhh](h)}(hhh]h reference)}(hhh]hDRM client usage stats}(hjahhhNhNubah}(h]hah ]h"]h$]h&]refidhuh1j_hj\ubah}(h]h ]h"]h$]h&]uh1hhjYubjS)}(hhh](jX)}(hhh](h)}(hhh]j`)}(hhh]hFile format specification}(hj~hhhNhNubah}(h]id3ah ]h"]h$]h&]refidfile-format-specificationuh1j_hj{ubah}(h]h ]h"]h$]h&]uh1hhjxubjS)}(hhh](jX)}(hhh]h)}(hhh]j`)}(hhh]h Key types}(hjhhhNhNubah}(h]id4ah ]h"]h$]h&]refid key-typesuh1j_hjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1jWhjubjX)}(hhh]h)}(hhh]j`)}(hhh]h Data types}(hjhhhNhNubah}(h]id5ah ]h"]h$]h&]refid data-typesuh1j_hjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1jWhjubjX)}(hhh]h)}(hhh]j`)}(hhh]h!Mandatory fully standardised keys}(hjhhhNhNubah}(h]id6ah ]h"]h$]h&]refid!mandatory-fully-standardised-keysuh1j_hjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1jWhjubjX)}(hhh](h)}(hhh]j`)}(hhh]h Optional fully standardised keys}(hjhhhNhNubah}(h]id7ah ]h"]h$]h&]refid optional-fully-standardised-keysuh1j_hjubah}(h]h ]h"]h$]h&]uh1hhjubjS)}(hhh](jX)}(hhh]h)}(hhh]j`)}(hhh]hIdentification}(hj"hhhNhNubah}(h]id8ah ]h"]h$]h&]refididentificationuh1j_hjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1jWhjubjX)}(hhh]h)}(hhh]j`)}(hhh]h Utilization}(hjDhhhNhNubah}(h]id9ah ]h"]h$]h&]refid utilizationuh1j_hjAubah}(h]h ]h"]h$]h&]uh1hhj>ubah}(h]h ]h"]h$]h&]uh1jWhjubjX)}(hhh]h)}(hhh]j`)}(hhh]hMemory}(hjfhhhNhNubah}(h]id10ah ]h"]h$]h&]refidmemoryuh1j_hjcubah}(h]h ]h"]h$]h&]uh1hhj`ubah}(h]h ]h"]h$]h&]uh1jWhjubeh}(h]h ]h"]h$]h&]uh1jRhjubeh}(h]h ]h"]h$]h&]uh1jWhjubeh}(h]h ]h"]h$]h&]uh1jRhjxubeh}(h]h ]h"]h$]h&]uh1jWhjuubjX)}(hhh](h)}(hhh]j`)}(hhh]hImplementation Details}(hjhhhNhNubah}(h]id11ah ]h"]h$]h&]refidimplementation-detailsuh1j_hjubah}(h]h ]h"]h$]h&]uh1hhjubjS)}(hhh]jX)}(hhh]h)}(hhh]j`)}(hhh]hDriver specific implementations}(hjhhhNhNubah}(h]id12ah ]h"]h$]h&]refiddriver-specific-implementationsuh1j_hjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1jWhjubah}(h]h ]h"]h$]h&]uh1jRhjubeh}(h]h ]h"]h$]h&]uh1jWhjuubeh}(h]h ]h"]h$]h&]uh1jRhjYubeh}(h]h ]h"]h$]h&]uh1jWhjTubah}(h]h ]h"]h$]h&]uh1jRhj@hhhNhNubeh}(h]contentsah ]contentsah"]contentsah$]h&]uh1j>hhhKhhhhubh)}(hhh](h)}(hFile format specificationh]hFile format specification}(hjhhhNhNubah}(h]h ]h"]h$]h&]hjuh1hhjhhhhhKubjS)}(hhh](jX)}(h;File shall contain one key value pair per one line of text.h]h)}(hjh]h;File shall contain one key value pair per one line of text.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubjX)}(h>Colon character (`:`) must be used to delimit keys and values.h]h)}(hj/h](hColon character (}(hj1hhhNhNubh)}(h`:`h]h:}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj1ubh*) must be used to delimit keys and values.}(hj1hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj-ubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubjX)}(h4All standardised keys shall be prefixed with `drm-`.h]h)}(hjXh](h-All standardised keys shall be prefixed with }(hjZhhhNhNubh)}(h`drm-`h]hdrm-}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhjZubh.}(hjZhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjVubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubjX)}(hDriver-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.h]h)}(hDriver-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.h](h,Driver-specific keys shall be prefixed with }(hjhhhNhNubh)}(h`driver_name-`h]h driver_name-}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh6, where driver_name should ideally be the same as the }(hjhhhNhNubh)}(h`name`h]hname}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh field in }(hjhhhNhNubh)}(h`struct drm_driver`h]hstruct drm_driver}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh!, although this is not mandatory.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubjX)}(hbWhitespace between the delimiter and first non-whitespace character shall be ignored when parsing.h]h)}(hbWhitespace between the delimiter and first non-whitespace character shall be ignored when parsing.h]hbWhitespace between the delimiter and first non-whitespace character shall be ignored when parsing.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubjX)}(h6Keys are not allowed to contain whitespace characters.h]h)}(hjh]h6Keys are not allowed to contain whitespace characters.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubjX)}(h - Unsigned integer without defining the maximum value.h]h)}(hjh]h= - Unsigned integer without defining the maximum value.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubjX)}(hP - String excluding any above defined reserved characters or whitespace.h]h)}(hjh]hP - String excluding any above defined reserved characters or whitespace.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK/hjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubjX)}(h - String. h]h)}(h - String.h]h - String.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK0hjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubeh}(h]h ]h"]h$]h&]j1j2uh1jRhhhK.hjhhubeh}(h]jah ]h"] data typesah$]h&]uh1hhjhhhhhK,ubh)}(hhh](h)}(h!Mandatory fully standardised keysh]h!Mandatory fully standardised keys}(hj hhhNhNubah}(h]h ]h"]h$]h&]hjuh1hhjhhhhhK3ubjS)}(hhh]jX)}(hdrm-driver: h]h)}(hdrm-driver: h]hdrm-driver: }(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK5hjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhK5hjhhubh)}(hnString shall contain the name this driver registered as via the respective `struct drm_driver` data structure.h](hKString shall contain the name this driver registered as via the respective }(hj:hhhNhNubh)}(h`struct drm_driver`h]hstruct drm_driver}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj:ubh data structure.}(hj:hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK7hjhhubeh}(h]jah ]h"]!mandatory fully standardised keysah$]h&]uh1hhjhhhhhK3ubh)}(hhh](h)}(h Optional fully standardised keysh]h Optional fully standardised keys}(hjdhhhNhNubah}(h]h ]h"]h$]h&]hj uh1hhjahhhhhK;ubh)}(hhh](h)}(hIdentificationh]hIdentification}(hjuhhhNhNubah}(h]h ]h"]h$]h&]hj+uh1hhjrhhhhhK>ubjS)}(hhh]jX)}(hdrm-pdev: h]h)}(hdrm-pdev: h]hdrm-pdev: }(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhK@hjrhhubh)}(hSFor PCI devices this should contain the PCI slot address of the device in question.h]hSFor PCI devices this should contain the PCI slot address of the device in question.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKBhjrhhubjS)}(hhh]jX)}(hdrm-client-id: h]h)}(hdrm-client-id: h]hdrm-client-id: }(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKEhjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKEhjrhhubh)}(hUnique value relating to the open DRM file descriptor used to distinguish duplicated and shared file descriptors. Conceptually the value should map 1:1 to the in kernel representation of `struct drm_file` instances.h](hUnique value relating to the open DRM file descriptor used to distinguish duplicated and shared file descriptors. Conceptually the value should map 1:1 to the in kernel representation of }(hjhhhNhNubh)}(h`struct drm_file`h]hstruct drm_file}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh instances.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKGhjrhhubh)}(hUniqueness of the value shall be either globally unique, or unique within the scope of each device, in which case `drm-pdev` shall be present as well.h](hrUniqueness of the value shall be either globally unique, or unique within the scope of each device, in which case }(hjhhhNhNubh)}(h `drm-pdev`h]hdrm-pdev}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh shall be present as well.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKKhjrhhubh)}(hUserspace should make sure to not double account any usage statistics by using the above described criteria in order to associate data to individual clients.h]hUserspace should make sure to not double account any usage statistics by using the above described criteria in order to associate data to individual clients.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKNhjrhhubjS)}(hhh]jX)}(hdrm-client-name: h]h)}(hdrm-client-name: h]hdrm-client-name: }(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKQhj$ubah}(h]h ]h"]h$]h&]uh1jWhj!hhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKQhjrhhubh)}(hCString optionally set by userspace using DRM_IOCTL_SET_CLIENT_NAME.h]hCString optionally set by userspace using DRM_IOCTL_SET_CLIENT_NAME.}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShjrhhubeh}(h]j1ah ]h"]identificationah$]h&]uh1hhjahhhhhK>ubh)}(hhh](h)}(h Utilizationh]h Utilization}(hjZhhhNhNubah}(h]h ]h"]h$]h&]hjMuh1hhjWhhhhhKWubjS)}(hhh]jX)}(hdrm-engine-: ns h]h)}(hdrm-engine-: nsh]hdrm-engine-: ns}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKYhjkubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKYhjWhhubh)}(hGPUs usually contain multiple execution engines. Each shall be given a stable and unique name (keystr), with possible values documented in the driver specific documentation.h]hGPUs usually contain multiple execution engines. Each shall be given a stable and unique name (keystr), with possible values documented in the driver specific documentation.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK[hjWhhubh)}(hValue shall be in specified time units which the respective GPU engine spent busy executing workloads belonging to this client.h]hValue shall be in specified time units which the respective GPU engine spent busy executing workloads belonging to this client.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK_hjWhhubh)}(hX_Values are not required to be constantly monotonic if it makes the driver implementation easier, but are required to catch up with the previously reported 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.h]hX_Values are not required to be constantly monotonic if it makes the driver implementation easier, but are required to catch up with the previously reported 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKbhjWhhubjS)}(hhh]jX)}(h%drm-engine-capacity-: h]h)}(h$drm-engine-capacity-: h]h$drm-engine-capacity-: }(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKhhjWhhubh)}(hEngine identifier string must be the same as the one specified in the drm-engine- tag and shall contain a greater than zero number in case the exported engine corresponds to a group of identical hardware engines.h]hEngine identifier string must be the same as the one specified in the drm-engine- tag and shall contain a greater than zero number in case the exported engine corresponds to a group of identical hardware engines.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjWhhubh)}(h]In the absence of this tag parser shall assume capacity of one. Zero capacity is not allowed.h]h]In the absence of this tag parser shall assume capacity of one. Zero capacity is not allowed.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhjWhhubjS)}(hhh]jX)}(hdrm-cycles-: h]h)}(hdrm-cycles-: h]hdrm-cycles-: }(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKqhjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKqhjWhhubh)}(hEngine identifier string must be the same as the one specified in the drm-engine- tag and shall contain the number of busy cycles for the given engine.h]hEngine identifier string must be the same as the one specified in the drm-engine- tag and shall contain the number of busy cycles for the given engine.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKshjWhhubh)}(hX_Values are not required to be constantly monotonic if it makes the driver implementation easier, but are required to catch up with the previously reported 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.h]hX_Values are not required to be constantly monotonic if it makes the driver implementation easier, but are required to catch up with the previously reported 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKwhjWhhubjS)}(hhh]jX)}(h"drm-total-cycles-: h]h)}(h!drm-total-cycles-: h]h!drm-total-cycles-: }(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK}hj0ubah}(h]h ]h"]h$]h&]uh1jWhj-hhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhK}hjWhhubh)}(hEngine identifier string must be the same as the one specified in the drm-cycles- tag and shall contain the total number cycles for the given engine.h]hEngine identifier string must be the same as the one specified in the drm-cycles- tag and shall contain the total number cycles for the given engine.}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjWhhubh)}(hXThis is a timestamp in GPU unspecified unit that matches the update rate of drm-cycles-. 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.h]hXThis is a timestamp in GPU unspecified unit that matches the update rate of drm-cycles-. 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.}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjWhhubh)}(hMA driver may implement either this key or drm-maxfreq-, but not both.h]hMA driver may implement either this key or drm-maxfreq-, but not both.}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjWhhubjS)}(hhh]jX)}(h*drm-maxfreq-: [Hz|MHz|KHz] h]h)}(h)drm-maxfreq-: [Hz|MHz|KHz]h]h)drm-maxfreq-: [Hz|MHz|KHz]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj{ubah}(h]h ]h"]h$]h&]uh1jWhjxhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKhjWhhubh)}(hXEngine identifier string must be the same as the one specified in the drm-engine- tag and shall contain the maximum frequency for the given engine. Taken together with drm-cycles-, this can be used to calculate percentage utilization of the engine, whereas drm-engine- only reflects time active without considering what frequency the engine is operating as a percentage of its maximum frequency.h]hXEngine identifier string must be the same as the one specified in the drm-engine- tag and shall contain the maximum frequency for the given engine. Taken together with drm-cycles-, this can be used to calculate percentage utilization of the engine, whereas drm-engine- only reflects time active without considering what frequency the engine is operating as a percentage of its maximum frequency.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjWhhubh)}(hRA driver may implement either this key or drm-total-cycles-, but not both.h]hRA driver may implement either this key or drm-total-cycles-, but not both.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjWhhubeh}(h]jSah ]h"] utilizationah$]h&]uh1hhjahhhhhKWubh)}(hhh](h)}(hMemoryh]hMemory}(hjhhhNhNubah}(h]h ]h"]h$]h&]hjouh1hhjhhhhhKubh)}(hEach 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 "" string.h]hEach 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 “” string.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hFThe region name "memory" is reserved to refer to normal system memory.h]hJThe region name “memory” is reserved to refer to normal system memory.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe value shall reflect the amount of storage currently consumed by the buffer objects belong to this client, in the respective memory region.h]hThe value shall reflect the amount of storage currently consumed by the buffer objects belong to this client, in the respective memory region.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hkDefault unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB' indicating kibi- or mebi-bytes.h]hsDefault unit shall be bytes with optional unit specifiers of ‘KiB’ or ‘MiB’ indicating kibi- or mebi-bytes.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjS)}(hhh]jX)}(h%drm-total-: [KiB|MiB] h]h)}(h$drm-total-: [KiB|MiB]h]h$drm-total-: [KiB|MiB]}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKhjhhubh)}(hXmThe 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.h]hXmThe 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.}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjS)}(hhh]jX)}(h&drm-shared-: [KiB|MiB] h]h)}(h%drm-shared-: [KiB|MiB]h]h%drm-shared-: [KiB|MiB]}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj7ubah}(h]h ]h"]h$]h&]uh1jWhj4hhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKhjhhubh)}(hThe 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- also applies here.h]hThe 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- also applies here.}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjS)}(hhh]jX)}(h(drm-resident-: [KiB|MiB] h]h)}(h'drm-resident-: [KiB|MiB]h]h'drm-resident-: [KiB|MiB]}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjfubah}(h]h ]h"]h$]h&]uh1jWhjchhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKhjhhubh)}(h}The total size of buffers that are resident (i.e., have their backing store present or instantiated) in the specified region.h]h}The total size of buffers that are resident (i.e., have their backing store present or instantiated) in the specified region.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjS)}(hhh]jX)}(h&drm-memory-: [KiB|MiB] h]h)}(h%drm-memory-: [KiB|MiB]h]h%drm-memory-: [KiB|MiB]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKhjhhubh)}(h_This key is deprecated and is only printed by amdgpu; it is an alias for drm-resident-.h]h_This key is deprecated and is only printed by amdgpu; it is an alias for drm-resident-.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjS)}(hhh]jX)}(h)drm-purgeable-: [KiB|MiB] h]h)}(h(drm-purgeable-: [KiB|MiB]h]h(drm-purgeable-: [KiB|MiB]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKhjhhubh)}(h:The total size of buffers that are resident and purgeable.h]h:The total size of buffers that are resident and purgeable.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hFor 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.h]hFor 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjS)}(hhh]jX)}(h&drm-active-: [KiB|MiB] h]h)}(h%drm-active-: [KiB|MiB]h]h%drm-active-: [KiB|MiB]}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jWhjhhhhhNubah}(h]h ]h"]h$]h&]j1j2uh1jRhhhKhjhhubh)}(hAThe total size of buffers that are active on one or more engines.h]hAThe total size of buffers that are active on one or more engines.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hOne 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.h]hOne 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.}(hj- hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]juah ]h"]memoryah$]h&]uh1hhjahhhhhKubeh}(h]jah ]h"] optional fully standardised keysah$]h&]uh1hhjhhhhhK;ubeh}(h]jah ]h"]file format specificationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hImplementation Detailsh]hImplementation Details}(hjS hhhNhNubah}(h]h ]h"]h$]h&]hjuh1hhjP hhhhhKubh)}(hX'Drivers should use drm_show_fdinfo() in their `struct file_operations`, and implement &drm_driver.show_fdinfo if they wish to provide any stats which are not provided by drm_show_fdinfo(). But even driver specific stats should be documented above and where possible, aligned with other drivers.h](h.Drivers should use drm_show_fdinfo() in their }(hja hhhNhNubh)}(h`struct file_operations`h]hstruct file_operations}(hji hhhNhNubah}(h]h ]h"]h$]h&]uh1hhja ubh, and implement &drm_driver.show_fdinfo if they wish to provide any stats which are not provided by drm_show_fdinfo(). But even driver specific stats should be documented above and where possible, aligned with other drivers.}(hja hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjP hhubh)}(hhh](h)}(hDriver specific implementationsh]hDriver specific implementations}(hj hhhNhNubah}(h]h ]h"]h$]h&]hjuh1hhj hhhhhKubjS)}(hhh](jX)}(h:ref:`i915-usage-stats`h]h)}(hj h]h)}(hj h]hinline)}(hj h]hi915-usage-stats}(hj hhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]refdocgpu/drm-usage-stats refdomainj reftyperef refexplicitrefwarn reftargeti915-usage-statsuh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jWhj hhhhhNubjX)}(h:ref:`panfrost-usage-stats`h]h)}(hj h]h)}(hj h]j )}(hj h]hpanfrost-usage-stats}(hj hhhNhNubah}(h]h ](j stdstd-refeh"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]refdocj refdomainj reftyperef refexplicitrefwarnj panfrost-usage-statsuh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jWhj hhhhhNubjX)}(h:ref:`panthor-usage-stats`h]h)}(hj h]h)}(hj h]j )}(hj h]hpanthor-usage-stats}(hj hhhNhNubah}(h]h ](j stdstd-refeh"]h$]h&]uh1j hj ubah}(h]h ]h"]h$]h&]refdocj refdomainj reftyperef refexplicitrefwarnj panthor-usage-statsuh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jWhj hhhhhNubjX)}(h:ref:`xe-usage-stats`h]h)}(hj2 h]h)}(hj2 h]j )}(hj2 h]hxe-usage-stats}(hj: hhhNhNubah}(h]h ](j stdstd-refeh"]h$]h&]uh1j hj7 ubah}(h]h ]h"]h$]h&]refdocj refdomainjD reftyperef refexplicitrefwarnj xe-usage-statsuh1hhhhKhj4 ubah}(h]h ]h"]h$]h&]uh1hhhhKhj0 ubah}(h]h ]h"]h$]h&]uh1jWhj hhhhhNubjX)}(h:ref:`amdxdna-usage-stats`h]h)}(hjd h]h)}(hjd h]j )}(hjd h]hamdxdna-usage-stats}(hjl hhhNhNubah}(h]h ](j stdstd-refeh"]h$]h&]uh1j hji ubah}(h]h ]h"]h$]h&]refdocj refdomainjv reftyperef refexplicitrefwarnj amdxdna-usage-statsuh1hhhhKhjf ubah}(h]h ]h"]h$]h&]uh1hhhhKhjb ubah}(h]h ]h"]h$]h&]uh1jWhj hhhhhNubeh}(h]h ]h"]h$]h&]j1*uh1jRhhhKhj hhubeh}(h]jah ]h"]driver specific implementationsah$]h&]uh1hhjP hhhhhKubeh}(h]jah ]h"]implementation detailsah$]h&]uh1hhhhhhhhKubeh}(h](hŒid1eh ]h"](drm client usage statsdrm-client-usage-statseh$]h&]uh1hhhhhhhhKexpect_referenced_by_name}j hsexpect_referenced_by_id}hhsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehÌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}h]hasnameids}(j hj j jjjM jjjjjj^jjF jjTj1jjSj? juj jj ju nametypes}(j j jjM jjj^jF jTjj? j j uh}(hhj hjj@jjjj3jjjjjjaj1jrjSjWjujjjP jj hjajj~jjjjjjj jj+j"jMjDjojfjjjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j K sRparse_messages]transform_messages]hsystem_message)}(hhh]h)}(hhh]h uba transformerN include_log] decorationNhhub.