pi_stress.8

pi_stress

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CAVEATS
BUGS
AUTHOR

---

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>

---