diff --git a/man/pw-top.1.rst.in b/man/pw-top.1.rst.in index 7289ab004..57eb040ac 100644 --- a/man/pw-top.1.rst.in +++ b/man/pw-top.1.rst.in @@ -19,6 +19,11 @@ DESCRIPTION The *pw-top* program provides a dynamic real-time view of the pipewire node and device statistics. +A hierarchical view is shown of Driver nodes and follower nodes. The Driver +nodes are actively using a timer to schedule dataflow in the followers. The +followers of a driver node as shown below their driver with a + sign in +a tree-like representation. + The columns presented are as follows: S @@ -31,25 +36,85 @@ ID The ID of the pipewire node/device, as found in *pw-dump* QUANT - Current quantum at which the device/node is polled. - See https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#pipewire-buffering-explained + The current quantum (for drivers) and the suggested quantum for follower + nodes. + + The quantum by itself needs to be divided by the RATE column to calculate + the duration of a scheduling period in fractions of a second. + + For a QUANT of 1024 and a RATE of 48000, the duration of one period in the + graph is 1024/48000 or 21.3 milliseconds. + + Follower nodes can have a 0 QUANT field, which means that the node does not + have a suggestion for the quantum and thus uses what the driver selected. + + The driver will use the lowest quantum of any of the followers. If none of + the followers select a quantum, the default quantum in the pipewire configuration + file will be used. + + The QUANT on the drivers usually translates directly into the number of audio + samples processed per processing cycle of the graph. + + See also https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#pipewire-buffering-explained RATE - Sample rate used for communicating with this device/node. + The current rate (for drivers) and the suggested rate for follower + nodes. + + This is the rate at which the graph processes data and needs to be combined with + the QUANT value to derive the duration of a processing cycle in the graph. + + Some nodes can have a 0 RATE, which means that they don't have any rate + suggestion for the graph. Nodes that suggest a rate can make the graph switch + rates if the graph is otherwise idle and the new rate is allowed as + a possible graph rate (see the pipewire configuration file). + + The RATE on (audio) driver nodes usually also translates directly to the + samplerate used by the device. Although some devices might not be able to + operate at the given samplerate, in which case resampling will need to be + done. WAIT + The waiting time of a node is the elapsed time between when the node + is ready to start processing and when it actually started processing. + + For Driver nodes, this is the time between when the node wakes up to + start processing the graph and when the driver (and thus also the graph) + completes a cycle. The WAIT time for driver is thus the elapsed time + processing the graph. + + For follower nodes, it is the time spent between being woken up (when all + dependencies of the node are satisfied) and when processing starts. The + WAIT time for follower nodes is thus mostly caused by context switching. BUSY + The processing time is started when the node starts processing until it + completes and wakes up the next nodes in the graph. W/Q Ratio of WAIT / QUANT. + The W/Q time of the driver node is a good measure of the graph + load. The running averages of the driver W/Q ratios are used as the DSP + load in other (JACK) tools. + B/Q Ratio of BUSY / QUANT + This is a good measure of the load of a particular driver or follower + node. + ERR Total of Xruns and Errors + Xruns for drivers are when the graph did not complete a cycle. This can + be because a node in the graph also has an Xrun. It can also be caused when + scheduling delays cause a deadline to be missed, causing a hardware + Xrun. + + Xruns for followers are incremented when the node started processing but + did not complete before the end of the graph cycle deadline. + NAME Name assigned to the device/node, as found in *pw-dump* node.name