1pi_stress(8)          Linux System Administrator's Manual         pi_stress(8)
2
3
4
5# SPDX-License-Identifier: GPL-2.0-or-later
6

NAME

8       pi_stress - a stress test for POSIX Priority Inheritance mutexes
9

SYNOPSIS

11       pi_stress  [-d|--debug] [-D|--duration [-g|--groups N] [-i|--inversions
12       INV]  [--json  FILENAME]  [-m|--mlockall]  [-p|--prompt]   [-q|--quiet]
13       [-r|--rr]    [-s|--sched   OPTS]   [-u|--uniprocessor]   [-v|--verbose]
14       [-V|--version]
15

DESCRIPTION

17       pi_stress is a program used to  stress  the  priority-inheritance  code
18       paths for POSIX mutexes, in both the Linux kernel and the C library. It
19       runs as a realtime-priority task and launches inversion machine  thread
20       groups. Each inversion group causes a priority inversion condition that
21       will deadlock if priority inheritance doesn't work.
22
23

OPTIONS

25       -d|--debug
26              Run in debug mode; lots of extra prints
27
28       -D TIME, --duration=TIME
29              Specify a length for the test run.
30              Append 'm', 'h', or 'd' to specify minutes, hours or days.
31
32       -g N|--groups=N
33              The number of inversion groups to run. Defaults to 10.
34
35       -h|--help
36              Display a short help message and options.
37
38       -i N|--inversions=N
39              N number of inversion conditions. This is the  total  number  of
40              inversions for all inversion groups. Default is -1 for infinite.
41
42       --json=FILENAME
43              Write final results into FILENAME , JSON formatted.
44
45       -m|--mlockall
46              Call  mlockall to lock current and future memory allocations and
47              prevent being paged out
48
49       -p|--prompt
50              Prompt before actually starting the stress test
51
52       -q|--quiet
53              Suppress running output
54
55       -r|--rr
56              Run inversion group threads as SCHED_RR (round-robin).  The  de‐
57              fault is to run the inversion threads as SCHED_FIFO.
58
59       -s OPTS|--sched OPTS
60              scheduling options per thread type:
61              id=[high|med|low],
62              policy=[fifo,rr],priority=N,
63              policy=deadline,runtime=N,deadline=N,period=N
64
65       -u|--uniprocessor
66              Run  all threads on one processor. The default is to run all in‐
67              version group threads on one processor  and  the  admin  threads
68              (reporting thread, keyboard reader, etc.) on a different proces‐
69              sor.
70
71       -v|--verbose
72              Run with verbose messages
73
74       -V|--version
75              Print version number
76

CAVEATS

78       The pi_stress test threads run as SCHED_FIFO or SCHED_RR threads, which
79       means  that they can starve critical system threads. It is advisable to
80       change  the  scheduling  policy  of  critical  system  threads  to   be
81       SCHED_FIFO  prior  to  running  pi_stress  and  use a priority of 10 or
82       higher, to prevent those threads from being starved by the stress test.
83

BUGS

85       No documented bugs.
86

AUTHOR

88       Clark Williams <williams@redhat.com>
89
90
91
92                                 Nov 27, 2006                     pi_stress(8)