diff options
Diffstat (limited to 'tools/perf/Documentation/perf-lock.txt')
| -rw-r--r-- | tools/perf/Documentation/perf-lock.txt | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/tools/perf/Documentation/perf-lock.txt b/tools/perf/Documentation/perf-lock.txt new file mode 100644 index 0000000000..30eea57672 --- /dev/null +++ b/tools/perf/Documentation/perf-lock.txt @@ -0,0 +1,214 @@ +perf-lock(1) +============ + +NAME +---- +perf-lock - Analyze lock events + +SYNOPSIS +-------- +[verse] +'perf lock' {record|report|script|info|contention} + +DESCRIPTION +----------- +You can analyze various lock behaviours +and statistics with this 'perf lock' command. + + 'perf lock record <command>' records lock events + between start and end <command>. And this command + produces the file "perf.data" which contains tracing + results of lock events. + + 'perf lock report' reports statistical data. + + 'perf lock script' shows raw lock events. + + 'perf lock info' shows metadata like threads or addresses + of lock instances. + + 'perf lock contention' shows contention statistics. + +COMMON OPTIONS +-------------- + +-i:: +--input=<file>:: + Input file name. (default: perf.data unless stdin is a fifo) + +--output=<file>:: + Output file name for perf lock contention and report. + +-v:: +--verbose:: + Be more verbose (show symbol address, etc). + +-q:: +--quiet:: + Do not show any warnings or messages. (Suppress -v) + +-D:: +--dump-raw-trace:: + Dump raw trace in ASCII. + +-f:: +--force:: + Don't complain, do it. + +--vmlinux=<file>:: + vmlinux pathname + +--kallsyms=<file>:: + kallsyms pathname + + +REPORT OPTIONS +-------------- + +-k:: +--key=<value>:: + Sorting key. Possible values: acquired (default), contended, + avg_wait, wait_total, wait_max, wait_min. + +-F:: +--field=<value>:: + Output fields. By default it shows all the fields but users can + customize that using this. Possible values: acquired, contended, + avg_wait, wait_total, wait_max, wait_min. + +-c:: +--combine-locks:: + Merge lock instances in the same class (based on name). + +-t:: +--threads:: + The -t option is to show per-thread lock stat like below: + + $ perf lock report -t -F acquired,contended,avg_wait + + Name acquired contended avg wait (ns) + + perf 240569 9 5784 + swapper 106610 19 543 + :15789 17370 2 14538 + ContainerMgr 8981 6 874 + sleep 5275 1 11281 + ContainerThread 4416 4 944 + RootPressureThr 3215 5 1215 + rcu_preempt 2954 0 0 + ContainerMgr 2560 0 0 + unnamed 1873 0 0 + EventManager_De 1845 1 636 + futex-default-S 1609 0 0 + +-E:: +--entries=<value>:: + Display this many entries. + + +INFO OPTIONS +------------ + +-t:: +--threads:: + dump thread list in perf.data + +-m:: +--map:: + dump map of lock instances (address:name table) + + +CONTENTION OPTIONS +-------------- + +-k:: +--key=<value>:: + Sorting key. Possible values: contended, wait_total (default), + wait_max, wait_min, avg_wait. + +-F:: +--field=<value>:: + Output fields. By default it shows all but the wait_min fields + and users can customize that using this. Possible values: + contended, wait_total, wait_max, wait_min, avg_wait. + +-t:: +--threads:: + Show per-thread lock contention stat + +-b:: +--use-bpf:: + Use BPF program to collect lock contention stats instead of + using the input data. + +-a:: +--all-cpus:: + System-wide collection from all CPUs. + +-C:: +--cpu=<value>:: + Collect samples only on the list of CPUs provided. Multiple CPUs can be + provided as a comma-separated list with no space: 0,1. Ranges of CPUs + are specified with -: 0-2. Default is to monitor all CPUs. + +-p:: +--pid=<value>:: + Record events on existing process ID (comma separated list). + +--tid=<value>:: + Record events on existing thread ID (comma separated list). + +-M:: +--map-nr-entries=<value>:: + Maximum number of BPF map entries (default: 16384). + This will be aligned to a power of 2. + +--max-stack=<value>:: + Maximum stack depth when collecting lock contention (default: 8). + +--stack-skip=<value>:: + Number of stack depth to skip when finding a lock caller (default: 3). + +-E:: +--entries=<value>:: + Display this many entries. + +-l:: +--lock-addr:: + Show lock contention stat by address + +-o:: +--lock-owner:: + Show lock contention stat by owners. Implies --threads and + requires --use-bpf. + +-Y:: +--type-filter=<value>:: + Show lock contention only for given lock types (comma separated list). + Available values are: + semaphore, spinlock, rwlock, rwlock:R, rwlock:W, rwsem, rwsem:R, rwsem:W, + rtmutex, rwlock-rt, rwlock-rt:R, rwlock-rt:W, pcpu-sem, pcpu-sem:R, pcpu-sem:W, + mutex + + Note that RW-variant of locks have :R and :W suffix. Names without the + suffix are shortcuts for the both variants. Ex) rwsem = rwsem:R + rwsem:W. + +-L:: +--lock-filter=<value>:: + Show lock contention only for given lock addresses or names (comma separated list). + +-S:: +--callstack-filter=<value>:: + Show lock contention only if the callstack contains the given string. + Note that it matches the substring so 'rq' would match both 'raw_spin_rq_lock' + and 'irq_enter_rcu'. + +-x:: +--field-separator=<SEP>:: + Show results using a CSV-style output to make it easy to import directly + into spreadsheets. Columns are separated by the string specified in SEP. + + +SEE ALSO +-------- +linkperf:perf[1] |