pai(8)

📦 version 2.44.1, in opensuse-leap 16.0

💅 pai(8) — The PAI Management Programs 💅

okay so bestie, you know how your CPU does stuff and you wanna know exactly what it's doing? yeah, that's this. welcome to pai — the Processor Activity Instrumentation vibe check for your counters. it's giving observability, it's giving main character energy, and it's about to become your new obsession. 🎀

✨ 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 🌸

okay so pai counters are literally just tallies of calls for specific CPU instructions. slay. the pai command records those counters into a ring buffer (iykyk). you can record counter data for all the CPUs or just the special ones you care about. no cap.

the main character options are:

  • -c for recording cryptographic CPU instructions 🔐
  • -n for recording NNPA CPU instructions 🧠
  • -r for reporting 📊

if you forget all three, it's not the end of the world — option -r gets assumed and it prints a little message so you're not confused. bestie behavior, honestly.

recording stores data by CPU in files: paicrypto.<XXX> for -c or painnpa.<XXX> for -n, where <XXX> is the CPU number with leading zeros. these files are created in the working directory, and like… if they already exist? they get overwritten. fair warning, bestie. 🙈

reporting evaluates the files that were created by recording. it's a whole ecosystem, periodt.

💖 OPTIONS 💖

  • -c, --crypto[CPULIST][:DATA] — records data for all CPUs (the default) or a specified list of CPUs. the CPU list is a comma-separated list of CPU numbers and ranges, and 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. this spec is 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 CPUs (the default) or a specified list of CPUs. same deal: comma-separated list of CPU numbers and ranges, hyphen for ranges, defaults to all CPUs. the optional data specification follows the colon and determines additional collection of data. alphabetic characters, 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, it 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. iconic default behavior. 📁
  • -h, --help — displays help information, then exits. the classic "what does this do again" button. 🆘
  • -v, --version — displays version information, then exits. for when you need to know exactly which flavor of slay you're running. ✨
  • -V, --verbose — spills the tea during reporting: the file name and the hexadecimal offset for each sample header. during recording it shows the read position in the ring buffer, the file name, and the hexadecimal offset for each sample header. it's giving "I want to see everything." 👀
  • -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. so much more readable, bestie. ⏰
  • -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. the receipts, basically. 🧾
  • -i, --interval ms — specifies the waiting time, in milliseconds, between ring buffer read operations during recording. default is 1000 milliseconds. argument loops is an integer that specifies the number of read operations during recording. default is 1. so chill. 😌
  • -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. default size is 512 pages. the ring buffer is created with the mmap(2) system call. fancy. 🧚
  • -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. highkey important. 🔥

🦋 ARGUMENT 🦋

okay so 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. (yes, paicryto — that's exactly what the original says, bestie, I don't make the rules.) 📜

🌈 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. it's giving "there can only be one." ⚔️

bestie, if you're running both tools at once, just know the driver will call you out. no cap.

🍓 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 in 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) — the other tool in this concurrency situationship. go check it out, bestie. 💜

that's the whole manual, bestie. you ate that. go forth and instrument some processors. 💅✨

s390-tools · May 2022 · pai(8) 🦋

📦 where this page comes from