lspai(8)

📦 version 2.44.1, in opensuse-leap 16.0

🌸 NAME 🌸

Hiii bestie 💖 meet lspai(8), one of the CPU-MF management programs. The NAME line is literally: lspai - list Processor Activity Instrumentation (PAI) counters and values. That’s the whole gig ✨

✨ SYNOPSIS ✨

lspai [--format FORMAT] [-n] [-t TYPE]
lspai [--format FORMAT] [-n] [-t  TYPE] [-a][-d][-i SECONDS] [-l COUNT]
[-s][-x][-x] [-c LIST] [CPULIST]
lspai -h|--help
lspai -v|--version

🎀 DESCRIPTION 🎀

Okay so on the first line, lspai displays the Processor Activity Instrumentation (PAI) counters for Linux on IBM Z 🦋 The output lists the available PAI counter names and numbers in various formats.

If CPULIST is specified, or any of the options -a, -d, -s, -x, -X, -l or -i are present on the command line, the lspai command extracts counter values from the specified PAI counter sets. Counter sets can be specified and extracted for individual CPUs 🌈

By default the output is a comma-separated list of values. Each line starts with a timestamp followed by the extracted counter values. A header line shows each counter name and the counter number in parenthesis. For other formats, use the --format option 💅

💖 OPTIONS 💖

  • -h, --help — Displays help information, then exits. Bye for now 👋
  • -v, --version — Displays version information, then exits. Iconic behavior ✨
  • -a, --all — Displays counter values from each CPU. The default is a total summary line of all counters from all CPUs.
  • -d, --delta — Displays counter values in form of deltas. Each counter value shows the increment to the previous output line. Without this flag the total value of each counter is displayed.
  • -c, --counters LIST — Specify a comma separated list of counter names to be printed. If a counter name does not match any valid counter name, it is omitted.
  • -s, --short — Displays counter names as short names in the heading. A short name consists of a letter for the counter set followed by a number. For example, this flag displays counter number 0 in the PAI crypto counter set as C0 instead of CRYPTO_ALL. Valid counter set letters are:
    • C — PAI crypto counter set
    • N — PAI NNPA counter set
  • -t, --type TYPE — Specifies the PAI counter set to list. Valid counter set values are crypto and nnpa. By default, the command lists all available PAI counter sets. NNPA refers to the Neural Network Processing Assist facility counter set. Crypto refers to the Cryptografic Processing Assist facility counter set.
  • -n, --numeric — Shows the PAI counter sets sorted by counter number. Default sort order is PAI counter name.
  • --format FORMAT — Retrieve output in one of the following formats: JSON, csv, json-seq, jsonl or pairs. If no format is specified, the output defaults to a human-readable format.
  • -i, --interval SECONDS — Specifies a time interval, in seconds, that the command waits between read operations. The default is 60 seconds.
  • -l, --loop COUNT — Performs the specified number of read operations. The default is one.
  • -x, --hex — Displays counter values as hexadecimal values.
  • -X, --hex0x — Displays counter values as hexadecimal values with a leading 0x prefix.

🔥 EXAMPLE 🔥

The lspai invocation lists all PAI Neural Network Processing Assist Facility (NNPA) counters in numeric order:

# lspai -t nnpa -n
RAW     NAME             DESCRIPTION
13:6144 NNPA_ALL         Counter 0 / PAI NNPA counter set
13:6145 NNPA_ADD         Counter 1 / PAI NNPA counter set
13:6146 NNPA_SUB         Counter 2 / PAI NNPA counter set
13:6147 NNPA_MUL         Counter 3 / PAI NNPA counter set
...

The first column shows the raw event number suitable for perf(8) raw event specification. The second column shows the PAI NNPA counter name, suitable for perf(8) event specification by name. The third gives a short explanation, if available.

The lspai invocation displays all PAI Neural Network Processing Assist Facility (NNPA) counters values. Ten iterations with a two second delay in between is printed on the screen.

# lspai -i 2 -l 10 -t nnpa -n
Date,Time,CPU,NNPA_ALL(0),NNPA_ADD(1),NNPA_SUB(2),NNPA_MUL(3),NNPA_DIV(4),
NNPA_MIN(5),NNPA_MAX(6),NNPA_LOG(7),NNPA_EXP(8),NNPA_IBM_RESERVED_9(9),
NNPA_RELU(10),NNPA_TANH(11),NNPA_SIGMOID(12),NNPA_SOFTMAX(13),NNPA_BATCHNORM(14),
NNPA_MAXPOOL2D(15),NNPA_AVGPOOL2D(16),NNPA_LSTMACT(17),NNPA_GRUACT(18),
NNPA_CONVOLUTION(19),NNPA_MATMUL_OP(20),NNPA_MATMUL_OP_BCAST23(21),
NNPA_SMALLBATCH(22),NNPA_LARGEDIM(23),NNPA_SMALLTENSOR(24),NNPA_1MFRAME(25),
NNPA_2GFRAME(26),NNPA_ACCESSEXCEPT(27)
2025-05-13,08:18:27,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:29,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:31,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:33,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:35,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:37,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:39,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:41,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:43,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
2025-05-13,08:18:45,Total,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
#

This lspai example displays the value of PAI crypto counter number 7. It is field number 116 in the output. This counter is incremented after lspai is started and the table shows the delta values for PAI crypto counter 7.

# lspai -d -s -i 5 -l3 -t crypto | awk -F , '{ print $1 ","  $2 "," $3 ","  $4 "," $116; }'
Date,Time,CPU,C0,C7
2025-06-24,13:02:24,Total,0,0
2025-06-24,13:02:29,Delta,77122286,77122284
2025-06-24,13:02:34,Delta,92574403,92574403
#

The following table shows the total value for PAI crypto counter 7 after lspai is started.

# lspai -s -i 5 -l3 -t crypto | awk -F , '{ print $1 ","  $2 "," $3 ","  $4 "," $116; }'
Date,Time,CPU,C0,C7
2025-06-24,13:03:01,Total,0,0
2025-06-24,13:03:06,Total,72550754,72566121
2025-06-24,13:03:11,Total,164633982,164650377
#

🌈 SEE ALSO 🌈

Source/version: s390-tools · date: August 2023. Bye bestie, go count some PAI counters 💖✨

📦 where this page comes from