kata-containers/s390-tools
1
0
Fork 0
mirror of https://github.com/ibm-s390-linux/s390-tools.git synced 2026-08-05 02:14:52 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
7fffdcfe8cae3f6fd003cd2f5f70bd11fc6bc2bf
s390-tools/cpumf/man/lspai.8
Jan Höppner 88bf638487 cpumf: Adapt to new JSON Lines text format 
util_fmt now provides support for JSON Lines text format. Adapt certain
checks in the code and document the newly supported format in the man
pages for lshwc and lspai accordingly.

Reviewed-by: Steffen Eiden <seiden@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
2026-04-30 08:44:02 +02:00

237 lines
6.5 KiB
Groff
Raw Blame History

.\" lspai.8
.\"
.\"
.\" Copyright IBM Corp. 2021
.\" s390-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the MIT license. See LICENSE for details.
.\" ----------------------------------------------------------------------
.ds c \fBlspai\fP
.
.TH \*c "8" "August 2023" "s390-tools" "CPU-MF management programs"
.
.SH NAME
\*c \- list Processor Activity Instrumentation (PAI) counters and values
.
.SH SYNOPSIS
\*c
.RB [ \-\-format
.IR FORMAT ]
.RB [ \-n ]
.RB [ \-t
.IR TYPE ]
.br
\*c
.RB [ \-\-format
.IR FORMAT ]
.RB [ \-n ]
.RB [ \-t
.IR "\ TYPE" ]
.RB [ \-a ][ \-d ][ \-i
.IR SECONDS ]
.RB [ \-l
.IR COUNT ]
.RB [ \-s ][ \-x ][ \-x ]
.RB [ \-c
.IR LIST ]
.RI [ CPULIST ]
.br
\*c
.BR \-h | \-\-help
.br
\*c
.BR \-v | \-\-version
.
.
.SH DESCRIPTION
On the first line
\*c 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
.I CPULIST
is specified or any of the options
.BR \-a ,
.BR \-d ,
.BR \-s ,
.BR \-x ,
.BR \-X ,
.B \-l
or
.BR \-i,
are present on the command line,
\*c 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
.B \-\-format
option.
.SH OPTIONS
.TP
.BR \-h ", " \-\-help
Displays help information, then exits.
.
.TP
.BR \-v ", " \-\-version
Displays version information, then exits.
.
.TP
.BR \-a ", " \-\-allcpu
Displays counter values from each CPU.
The default is a total summary line of all counters from all CPUs.
.
.TP
.BR \-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.
.
.TP
.BR \-c ", " \-\-counters \fI\ LIST\fP
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.
.
.TP
.BR \-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
.B C0
instead of
.BR CRYPTO_ALL .
Valid counter set letters are:
.RS
.IP C
PAI crypto counter set
.IP N
PAI NNPA counter set
.RE
.
.TP
.BR \-t ", " \-\-type "\ \fITYPE\fP"
Specifies the PAI counter set to list.
Valid counter set values are
.I crypto
and
.IR 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.
.
.TP
.BR \-n ", " \-\-numeric
Shows the PAI counter sets sorted by counter number.
Default sort order is PAI counter name.
.
.TP
.BI \-\-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.
.
.TP
.BR \-i ", " \-\-interval \fI\ SECONDS\fP
Specifies a time interval, in seconds,
that the command waits between read operations.
The default is 60 seconds.
.
.TP
.BR \-l ", " \-\-loop \fI\ COUNT\fP
Performs the specified number of read operations.
The default is one.
.
.TP
.BR \-x ", " \-\-hex
Displays counter values as hexadecimal values.
.
.TP
.BR \-X ", " \-\-hex0x
Displays counter values as hexadecimal values with a leading 0x prefix.
.
.SH "EXAMPLE"
The \*c invocation lists all PAI Neural Network Processing Assist Facility
(NNPA) counters in numeric order:
.nf
# 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
\&...
.fi
The first column shows the raw event number suitable for
.IR perf "(8)"
raw event specification.
The second column shows the PAI NNPA counter name,
suitable for
.IR perf "(8)"
event specification by name.
The third gives a short explanation, if available.
.sp 1
The \*c 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.
.nf
# 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
#
.fi
.sp 1
This \*c example displays the value of PAI crypto counter number 7.
It is field number 116 in the output.
This counter is incremented after \*c is started and
the table shows the delta values for PAI crypto counter 7.
.nf
# 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
#
.fi
.sp 1
The following table shows the total value for PAI crypto counter 7
after \*c is started.
.nf
# 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
#
.fi
.SH "SEE ALSO"
.BR pai (8)
.BR lscpumf (8)
Reference in New Issue View Git Blame Copy Permalink