pi_stress(8)          Linux System Administrator's Manual         pi_stress(8)

# SPDX-License-Identifier: GPL-2.0-or-later

NAME
       pi_stress - a stress test for POSIX Priority Inheritance mutexes

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

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


OPTIONS
       -d|--debug
              Run in debug mode; lots of extra prints

       -D TIME, --duration=TIME
              Specify a length for the test run.
              Append 'm', 'h', or 'd' to specify minutes, hours or days.

       -g N|--groups=N
              The number of inversion groups to run. Defaults to 10.

       -h|--help
              Display a short help message and options.

       -i N|--inversions=N
              N number of inversion conditions. This is the total number of
              inversions for all inversion groups. Default is -1 for infinite.

       --json=FILENAME
              Write final results into FILENAME , JSON formatted.

       -m|--mlockall
              Call mlockall to lock current and future memory allocations and
              prevent being paged out

       -p|--prompt
              Prompt before actually starting the stress test

       -q|--quiet
              Suppress running output

       -r|--rr
              Run inversion group threads as SCHED_RR (round-robin). The
              default is to run the inversion threads as SCHED_FIFO.

       -s OPTS|--sched OPTS
              scheduling options per thread type:
              id=[high|med|low],
              policy=[fifo,rr],priority=N,
              policy=deadline,runtime=N,deadline=N,period=N

       -u|--uniprocessor
              Run all threads on one processor. The default is to run all
              inversion group threads on one processor and the admin threads
              (reporting thread, keyboard reader, etc.) on a different
              processor.

       -v|--verbose
              Run with verbose messages

       -V|--version
              Print version number

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

BUGS
       No documented bugs.

AUTHOR
       Clark Williams <williams@redhat.com>

                               November 27, 2006                  pi_stress(8)