Add documentation for 'perf bench sync rcu'. This benchmark has three modes or subcommands that takes positional arguments. In addition, *kernel* module parameters are directly specified in the form of "name=value", without "--name". Multiple subsections are thus added to the 'sync' section for illustration.
Signed-off-by: Yuzhuo Jing <[email protected]> --- tools/perf/Documentation/perf-bench.txt | 131 ++++++++++++++++++++++++ 1 file changed, 131 insertions(+) diff --git a/tools/perf/Documentation/perf-bench.txt b/tools/perf/Documentation/perf-bench.txt index 8331bd28b10e..786c6e6880f5 100644 --- a/tools/perf/Documentation/perf-bench.txt +++ b/tools/perf/Documentation/perf-bench.txt @@ -49,6 +49,9 @@ SUBSYSTEM 'sched':: Scheduler and IPC mechanisms. +'sync':: + Synchronization primitives. + 'syscall':: System call performance (throughput). @@ -162,6 +165,134 @@ Example of *pipe* --------------------- +SUITES FOR 'sync' +~~~~~~~~~~~~~~~~~ +*rcu*:: +Suite for RCU performance. Depends on rcuscale kernel module. +This benchmark has three modes: once, range, ratio. Usage is defined as below. + +'perf bench sync rcu' [options..] [-- <command>..] +'perf bench sync rcu' [options..] once <gp_type> [<param=value>..] [-- <command>..] +'perf bench sync rcu' [options..] range <gp_type> [<param=range>..] [-- <command>..] +'perf bench sync rcu' [options..] ratio <gp_type> <total> <param1_range> <param1_name> <param2_name> [<param=value>..] [-- <command>..] + +Modes for *rcu* +^^^^^^^^^^^^^^^ + +default:: +Run 'once sync'.", + +once:: +Run benchmark once, with all parameters passed through to the kernel rcuscale +module. + +range:: +Run benchmark multiple times, with parameters as ranges. Range format is +defined as start[:end[:step]], inclusive, non-negative. The benchmark +instantiates all combinations of all ranges. + +ratio:: +Run benchmark that changes the ratio between two parameters. 'total' specifies +the sum of 'param1' and 'param2', and 'param1_range' is the range of 'param1' +values. 'param2' is calculated by 'total-param1'. Additional non-range +parameters may also be specified. + +Positional arguments for *rcu* +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +gp_type:: +The type of grace period to use: sync, async, exp (expedited) + +param:: +Any parameter of the rcuscale kernel module, except for "gp_exp", +"gp_async" and "block_start" that are managed by this benchmark. +Valid options can be found from "modinfo rcuscale". + +command:: +A child command to run during the experiment. If the command line +string contains {READER,WRITER,KFREE}_TASKS placeholders, they will be +substituted with the tasks PIDs, separated by comma. + +Options for *rcu* +^^^^^^^^^^^^^^^^^ +-c:: +--cooldown:: +Sleep time between each experiment (default: 3 seconds). + +-n:: +--dryrun:: +Dry run mode. Do not run experiments, but instead print what parameter +combination will run. + +--child-delay=:: +Wait for child startup before starting experiment (default: 1 second). + +--debugfs=:: +Debugfs mount point used to interact with the rcuscale kernel module. (default: +/sys/kernel/debug). + +--hist:: +Show the histogram of writer durations. + +Example of *rcu* +^^^^^^^^^^^^^^^^ + +--------------------- +% perf bench sync rcu once exp nreaders=1 nwriters=1 +# Running 'sync/rcu' benchmark: +Running experiment with options: gp_exp=1 nreaders=1 nwriters=1 +Experiment finished. +Average grace-period duration: 124.236 microseconds +Minimum grace-period duration: 8.783 +50th percentile grace-period duration: 9.033 +90th percentile grace-period duration: 9.665 +99th percentile grace-period duration: 20.911 +Maximum grace-period duration: 6025.167 + +% perf bench sync rcu range exp nreaders=1 nwriters=1 writer_cpu_offset=0:1 -- \ + perf stat -e ipi:ipi_send_cpu,rcu:rcu_grace_period \ + -t READER_TASKS,WRITER_TASKS +# Running 'sync/rcu' benchmark: +Running experiment with options: gp_exp=1 nreaders=1 nwriters=1 writer_cpu_offset=0 +Running child command: perf stat -e ipi:ipi_send_cpu,rcu:rcu_grace_period -t 2061441,2061442 + + Performance counter stats for thread id '2061441,2061442': + + 2400 ipi:ipi_send_cpu + 100 rcu:rcu_grace_period + + 6.006040148 seconds time elapsed + +Experiment finished. +Waiting for child process to exit. +Average grace-period duration: 301.177 microseconds +Minimum grace-period duration: 9.064 +50th percentile grace-period duration: 9.394 +90th percentile grace-period duration: 10.977 +99th percentile grace-period duration: 5926.781 +Maximum grace-period duration: 6011.067 +Cooling down (3s).. + +Running experiment with options: gp_exp=1 nreaders=1 nwriters=1 writer_cpu_offset=1 +Running child command: perf stat -e ipi:ipi_send_cpu,rcu:rcu_grace_period -t 2061461,2061462 + + Performance counter stats for thread id '2061461,2061462': + + 2144 ipi:ipi_send_cpu + 201 rcu:rcu_grace_period + + 6.006110747 seconds time elapsed + +Experiment finished. +Waiting for child process to exit. +Average grace-period duration: 12.23 microseconds +Minimum grace-period duration: 9.134 +50th percentile grace-period duration: 9.475 +90th percentile grace-period duration: 11.897 +99th percentile grace-period duration: 38.057 +Maximum grace-period duration: 67.19 +--------------------- + SUITES FOR 'syscall' ~~~~~~~~~~~~~~~~~~ *basic*:: -- 2.50.1.565.gc32cd1483b-goog
