mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2025-11-02 09:01:50 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

man: improve pw-top man page

Browse source
This commit is contained in:
Wim Taymans 2022-04-19 15:20:10 +02:00
parent e3ff445d4b
commit 1dcc81b260
1 changed files with 68 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

71
man/pw-top.1.rst.in
View file

@ -19,6 +19,11 @@ DESCRIPTION
The *pw-top* program provides a dynamic real-time view of the pipewire The *pw-top* program provides a dynamic real-time view of the pipewire
node and device statistics. 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: The columns presented are as follows:
S S
@ -31,25 +36,85 @@ ID
The ID of the pipewire node/device, as found in *pw-dump* The ID of the pipewire node/device, as found in *pw-dump*
QUANT QUANT
Current quantum at which the device/node is polled. The current quantum (for drivers) and the suggested quantum for follower
See https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#pipewire-buffering-explained 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 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 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 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 W/Q
Ratio of WAIT / QUANT. 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 B/Q
Ratio of BUSY / QUANT Ratio of BUSY / QUANT
This is a good measure of the load of a particular driver or follower
node.
ERR ERR
Total of Xruns and Errors 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
Name assigned to the device/node, as found in *pw-dump* node.name Name assigned to the device/node, as found in *pw-dump* node.name