| Message ID | 20241101191156.1272730-4-irogers@google.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v3,1/4] proc_pid_fdinfo.5: Reduce indent for most of the page | expand |
Hi Ian, At 2024-11-01T12:11:56-0700, Ian Rogers wrote: [...] > +.EX > +pos: 0 > +flags: 02100002 > +mnt_id: 26 > +ino: 284 > +drm-driver: i915 > +drm-client-id: 39 > +drm-pdev: 0000:00:02.0 > +drm-total-system0: 6044 KiB > +drm-shared-system0: 0 > +drm-active-system0: 0 > +drm-resident-system0: 6044 KiB > +drm-purgeable-system0: 1688 KiB > +drm-total-stolen-system0: 0 > +drm-shared-stolen-system0: 0 > +drm-active-stolen-system0: 0 > +drm-resident-stolen-system0: 0 > +drm-purgeable-stolen-system0: 0 > +drm-engine-render: 346249 ns > +drm-engine-copy: 0 ns > +drm-engine-video: 0 ns > +drm-engine-capacity-video: 2 > +drm-engine-video-enhance: 0 ns > +.EE > +.TP > +.IR drm-driver: " .+ (mandatory)" > +The name this driver registered. > +.TP > +.IR drm-pdev: " <aaaa:bb:cc.d>" > +For PCI devices this should contain the PCI slot address of the device > +in question. > +.TP > +.IR drm-client-id: " [0-9]+" > +Unique value relating to the open DRM file descriptor used to > +distinguish duplicated and shared file descriptors. > +.P > +GPUs usually contain multiple execution engines. Each shall be given a > +stable and unique name (<engine_name>), with possible values > +documented in the driver specific documentation. > +.TP > +.IR drm-engine-<engine_name>: " [0-9]+ ns" > +GPU engine utilization, time spent busy executing workloads for this client. [...] In my opinion the use of <bracketed_notation> like that is not idiomatic in man pages. (We sometimes see it anyway, because for a long time "rock star programmers" have treated the neglect of man page idioms as a competitive sport.[1]) Also the mixture of regex notation with <bracketed_notation> is a little bewildering (again, my opinion). I would recast these to use bold for the literal bits, italics for the variable parts, roman for nonliteral syntax, and, for this page, lean completely into the use of EREs. groff_man_style(7) offers suggestions: Font style macros ... Use bold for literal portions of syntax synopses, for command‐line options in running text, and for literals that are major topics of the subject under discussion; for example, this page uses bold for macro, string, and register names. In an .EX/.EE example of interactive I/O (such as a shell session), set only user input in bold. ... Use italics for file and path names, for environment variables, for C data types, for enumeration or preprocessor constants in C, for variant (user‐ replaceable) portions of syntax synopses, for the first occurrence (only) of a technical concept being introduced, for names of journals and of literary works longer than an article, and anywhere a parameter requiring replacement by the user is encountered. An exception involves variant text in a context already typeset in italics, such as file or path names with replaceable components; in such cases, follow the convention of mathematical typography: set the file or path name in italics as usual but use roman for the variant part (see .IR and .RI below), and italics again in running roman text when referring to the variant material. ... Observe what is not prescribed for setting in bold or italics above: elements of “synopsis language” such as ellipses and brackets around options; proper names and adjectives; titles of anything other than major works of literature; identifiers for standards documents or technical reports such as CSTR #54, RFC 1918, Unicode 13.0, or POSIX.1‐2017; acronyms; and occurrences after the first of a technical term. So I might write these more like the following. .P We use extended regular expressions to represent the expected parameter values; see .BR regex (7). \" `BR` for Linux man-pages documents only .TP .BR drm\-driver: " .+"\c .I " (mandatory)" The name this driver registered. .TP .BR drm\-pdev: " [0-9A-F]{4}:[0-9A-F]{2}:[0-9A-F]{2}.[0-9A-F]" For PCI devices this should contain the PCI slot address of the device in question. .TP .BR drm\-client\-id: " [0-9]+" Unique value relating to the open DRM file descriptor used to distinguish duplicated and shared file descriptors. .P GPUs usually contain multiple execution engines. Each shall be given a stable and unique .IR engine-name , with possible values documented in driver-specific documentation. .TP .BI drm\-engine\- engine-name :\c \& [0-9]+ ns GPU engine utilization: time spent busy executing workloads for this client. I also (1) used the `\c` escape sequence to fit three different font styles into a paragraph tag; and (2) escaped literal hyphens. Regards, Branden [1] I give you the Worst Man Page in the World. https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1 Fortunately the procps-ng maintainers eventually rewrote it.
diff --git a/man/man5/proc_pid_fdinfo.5 b/man/man5/proc_pid_fdinfo.5 index 290cae6a6..98ac12f16 100644 --- a/man/man5/proc_pid_fdinfo.5 +++ b/man/man5/proc_pid_fdinfo.5 @@ -301,5 +301,99 @@ fields contain the values that .BR timerfd_gettime (2) on this file descriptor would return.) .RE +.SS Direct Rendering Manager +.P +DRM drivers can optionally choose to expose usage stats through +/proc/pid/fdinfo/. For example: +.P +.in +4n +.EX +pos: 0 +flags: 02100002 +mnt_id: 26 +ino: 284 +drm-driver: i915 +drm-client-id: 39 +drm-pdev: 0000:00:02.0 +drm-total-system0: 6044 KiB +drm-shared-system0: 0 +drm-active-system0: 0 +drm-resident-system0: 6044 KiB +drm-purgeable-system0: 1688 KiB +drm-total-stolen-system0: 0 +drm-shared-stolen-system0: 0 +drm-active-stolen-system0: 0 +drm-resident-stolen-system0: 0 +drm-purgeable-stolen-system0: 0 +drm-engine-render: 346249 ns +drm-engine-copy: 0 ns +drm-engine-video: 0 ns +drm-engine-capacity-video: 2 +drm-engine-video-enhance: 0 ns +.EE +.TP +.IR drm-driver: " .+ (mandatory)" +The name this driver registered. +.TP +.IR drm-pdev: " <aaaa:bb:cc.d>" +For PCI devices this should contain the PCI slot address of the device +in question. +.TP +.IR drm-client-id: " [0-9]+" +Unique value relating to the open DRM file descriptor used to +distinguish duplicated and shared file descriptors. +.P +GPUs usually contain multiple execution engines. Each shall be given a +stable and unique name (<engine_name>), with possible values +documented in the driver specific documentation. +.TP +.IR drm-engine-<engine_name>: " [0-9]+ ns" +GPU engine utilization, time spent busy executing workloads for this client. +.TP +.IR drm-engine-capacity-<engine_name>: " [0-9]+" +Capacity of the engine if not 1, cannot be 0. +.TP +.IR drm-cycles-<engine_name>: " [0-9]+" +Contains the number of busy cycles for the given engine. Values are +not required to be constantly monotonic, 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. +.TP +.IR drm-total-cycles-<engine_name>: " [0-9]+" +Contains the total number cycles for the given engine. This is a +timestamp in GPU unspecified unit that matches the update rate of +drm-cycles-<engine_name>. 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. +.P +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 <region>. +The name "memory" is reserved to refer to normal system memory. +.TP +.IR drm-memory-<region>: " [0-9]+ [KiB|MiB]" +The amount of storage currently consumed by the buffer objects belong +to this client, in the respective memory region. +.IP +Default unit shall be bytes with optional unit specifiers of 'KiB' or 'MiB' +indicating kibi- or mebi-bytes. +.TP +.IR drm-shared-<region>: " [0-9]+ [KiB|MiB]" +The total size of buffers that are shared with another file (e.g., have more +than a single handle). +.TP +.IR drm-total-<region>: " [0-9]+ [KiB|MiB]" +The total size of buffers that including shared and private memory. +.TP +.IR drm-resident-<region>: " [0-9]+ [KiB|MiB]" +The total size of buffers that are resident in the specified region. +.TP +.IR drm-purgeable-<region>: " [0-9]+ [KiB|MiB]" +The total size of buffers that are purgeable. +.TP +.IR drm-active-<region>: " [0-9]+ [KiB|MiB]" +The total size of buffers that are active on one or more engines. + .SH SEE ALSO .BR proc (5)
Add description of DRM fdinfo information based on the Linux kernel's `Documentation/gpu/drm-usage-stats.rst`: https://docs.kernel.org/gpu/drm-usage-stats.html Signed-off-by: Ian Rogers <irogers@google.com> --- man/man5/proc_pid_fdinfo.5 | 94 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+)