pai(8)

NAME
pai - record and report Processor Activity Instrumentation (PAI) counters

SYNOPSIS
pai [-V][-m|--mapsize size] [-i|--interval ms] [-R|--realtime prio] -c|--crypto[cpulist][:data] [loops]
pai [-V][-m|--mapsize size] [-i|--interval ms] [-R|--realtime prio] -n|--nnpa[cpulist][:data] [loops]
pai [-V][-H|--humantime][-S|--summary] -r|--report [files]
pai -h|--help
pai -v|--version

DESCRIPTION
pai counters tally calls for specific CPU instructions. The pai command records PAI counters in a ring buffer. pai can record counter data for all CPUs or for selected CPUs. The main command options are -c for recording cryptographic CPU instructions, -n for recording NNPA CPU instructions and -r for reporting. If all three options are omitted, option -r is assumed and a message is printed. Recording stores data, by CPU, in files paicrypto.<XXX>, for option -c or painnpa.<XXX>, for option -n where <XXX> specifies the CPU number with leading zeros. The files are created in the working directory, existing files are overwritten. Reporting evaluates files that are created by recording.

OPTIONS

-c, --crypto[cpulist][:data]
    Records data for all (default) or a specified list of CPUs. The CPU list is a comma-separated list of CPU numbers and ranges. In a range, a hyphen separates the first CPU number from the last CPU number. By default pai lists all CPUs.
    The optional data specification follows the colon and determines additional collection of data. The specification consists of alphabetic characters that can be upper or lower case:

    c|C Include task rename system calls exec and prctl.

    f|F Include task creation and deletion system calls fork and exit.

    s|S Include context switch records created by the kernel scheduler.

    k|K Include only PAI cryptographic counters changed during system call execution.

    u|U Include only PAI cryptographic counters changed during user space execution.

-n, --nnpa[cpulist][:data]
    Records data for all (default) or a specified list of CPUs. The CPU list is a comma-separated list of CPU numbers and ranges. In a range, a hyphen separates the first CPU number from the last CPU number. By default pai lists all CPUs.
    The optional data specification follows the colon and determines additional collection of data. The specification consists of alphabetic characters that can be upper or lower case:

    c|C Include task rename system calls exec and prctl.

    f|F Include task creation and deletion system calls fork and exit.

    s|S Include context switch records created by the kernel scheduler.

-r, --report
    Generates a report from the specified files. Files is a list of blank-separated file names. If no files are specified, uses all files named paicrypto.<X>, in the working directory, where <X> is a CPU number that identifies the CPU for which the data was recorded.

-h, --help
    Displays help information, then exits.

-v, --version
    Displays version information, then exits.

-V, --verbose
    Displays the following information during reporting: the file name and the hexadecimal offset for each sample header. Displays the following information during recording: the read position in the ring buffer, the file name, and the hexadecimal offset for each sample header.

-H, --humantime
    Changes the time stamp format for sample entries from a hexadecimal number to a human readable <seconds>.<nanoseconds> format. The time stamp specifies the elapsed time since Linux was booted.

-S, --summary
    Prints a summary of counter names and counter numbers with non-zero values. The summary is the last line in the command output. It shows the sum of the counter values of all processed files.

-i, --interval ms
    Specifies the waiting time, in milliseconds, between ring buffer read operations during recording. The default is 1000 milliseconds. Argument loops is an integer that specifies the number of read operations during recording. The default is 1.

-m, --mapsize size
    Specifies the size of the ring buffer that holds the collected data. The value specifies the number of 4 KB pages to be allocated and must be a power of 2. The default size is 512 pages. The ring buffer is created with the mmap(2) system call.

-R, --realtime prio
    Collect data using the RT SCHED_FIFO priority specified by prio. Valid values are integers in the range 1 (low) to 99 (high). Use this option when gathering data from multiple CPUs to prevent data loss.

ARGUMENT
The command line options determine how command line arguments are interpreted. For option -c to start recording, the argument specifies the number of read operations. If omitted, the default is one. For option -r to start reporting, the argument specifies the file names to be read. If omitted all files in the current directory with file name paicryto.<X> are read.

Concurrency with perf tool
The following concurrency restrictions apply for pai and the perf tool. Both tools use the perf_event_open() system call and use the same device driver. The device driver supports limited concurrency:

Counting:
    Counting pai events can run in parallel.

Sampling:
    Only one sampling event pai_crypto/CRYPTO_ALL can be active at any one time. If a sampling event is active, no pai counting event can be active. Both tools stop with an error message if they detect a collision reported by the device driver.

EXAMPLES
This example collects cryptographic counter on CPU 0. The program runs for 10 seconds (10 intervals of 1000 milliseconds).

# pai -c0 10

This example displays the data that is collected in the first example. Each data line shows the time stamp in jiffies, followed by the CPU number, the event number, process and thread identifier (pid/tid) separated by slash (/), and a comma-separated list of counter number, colon (:), and the counter value n hexadecimal notation.

# pai -r
0x62a668f2fa 0 event 4096 sample pid 4956/4956 9:0xa7,73:0x8,74:0x18
0x6319c75653 0 event 4096 sample pid 4972/4972 32:0x1
0x6319e2ddee 0 event 4096 sample pid 4972/4972 32:0x1
0x631d3e44f5 0 event 4096 sample pid 4972/4972 32:0x2
0x631d4cfc2e 0 event 4096 sample pid 4972/4972 32:0x3
0x631d529fdd 0 event 4096 sample pid 4972/4972 32:0x2
0x631d84cfa0 0 event 4096 sample pid 4972/4972 73:0x1
0x636e9826bc 0 event 4096 sample pid 4984/4984 9:0xa7,73:0x8,74:0x18
0x636f81a137 0 event 4096 sample pid 4984/4984 9:0x2,74:0x7
0x6378026e54 0 event 4096 sample pid 4984/4984 73:0x2
0x637bcdc8da 0 event 4096 sample pid 4984/4984 73:0x2
0x637bd426cd 0 event 4096 sample pid 4984/4984 73:0x6
0x637c503384 0 event 4096 sample pid 4984/4984 73:0x2
0x64991d83ba 0 event 4096 sample pid 5026/5026 9:0xb0,73:0x8,74:0x18
#

SEE ALSO
perf(1)