mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
c746c5c267
Corrected a grammatical error for proper subject-verb agreement. Signed-off-by: Jan Polensky <japo@linux.ibm.com> Reviewed-by: Jan Höppner <hoeppner@linux.ibm.com> Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>
356 lines
8.7 KiB
Groff
356 lines
8.7 KiB
Groff
.\" lshwc.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 \fBlshwc\fP
|
||
.
|
||
.TH \*c "8" "Mar 2025" "s390-tools" "CPU-MF management programs"
|
||
.
|
||
.SH NAME
|
||
lshwc \- extract CPU Measurement Facilities counter sets
|
||
.
|
||
.SH SYNOPSIS
|
||
\*c
|
||
.RB [ \-a ][ \-d ][ \-H ][ \-s ][ \-x ][ \-X ][ \-q ]
|
||
.RB [ \-l
|
||
.IR count ]
|
||
.RB [ \-i
|
||
.IR interval ]
|
||
.RB [ \-t
|
||
.IR time ]
|
||
.RB [ \-f
|
||
.IR format ]
|
||
\fR[\fIcpulist\fR][:\fIsets\fR]\fP
|
||
.br
|
||
\*c
|
||
.BR \-h | \-\-help
|
||
.br
|
||
\*c
|
||
.BR \-v | \-\-version
|
||
.
|
||
.
|
||
.SH DESCRIPTION
|
||
The \*c command extracts complete counter sets from the CPU
|
||
Measurement Facilities for Linux on Z.
|
||
Counter sets can be specified and extracted for individual CPUs.
|
||
The output is a comma-separated values file.
|
||
Each line starts with a timestamp and the CPU number,
|
||
followed by the extracted counter values.
|
||
.
|
||
.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.
|
||
See Examples.
|
||
.
|
||
.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.
|
||
.
|
||
.TP
|
||
.BR \-H ", " \-\-hide
|
||
Do not display values of undefined counters.
|
||
.
|
||
.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 basic counter
|
||
set as
|
||
.B B0
|
||
instead of
|
||
.BR Cycles .
|
||
Valid counter set letters are:
|
||
.RS
|
||
.IP B
|
||
Basic counter set
|
||
.IP P
|
||
Problem state counter set
|
||
.IP C
|
||
Crypto counter set
|
||
.IP E
|
||
Extended counter set
|
||
.IP M
|
||
MT-Diagnostic counter set
|
||
.IP U
|
||
Undefined counter.
|
||
.RE
|
||
.
|
||
.TP
|
||
.BR \-t ", " \-\-time
|
||
Specifies the runtime as an integer in days,
|
||
hours, minutes or seconds.
|
||
This option can be specified multiple times:
|
||
the runtime sums up.
|
||
Specify time as an integer followed by one of the letters
|
||
.RS
|
||
.IP d
|
||
Specifies the runtime in days.
|
||
.IP h
|
||
Specifies the runtime in hours.
|
||
.IP m
|
||
Specifies the runtime in minutes.
|
||
.IP s
|
||
Specifies the runtime in seconds.
|
||
This is the default when no letter is given.
|
||
.RE
|
||
.
|
||
.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.
|
||
.
|
||
.TP
|
||
.BR \-q
|
||
Apply quoting to every output element, regardless of content or format.
|
||
.
|
||
.TP
|
||
.BR \-f ", " \-\-format \fI\ format\fP
|
||
Retrieve output in one of the following formats:
|
||
JSON, CSV, JSON-SEQ or PAIRS.
|
||
If no format is specified, the output defaults to CSV.
|
||
.
|
||
.SS JSON Output Structure
|
||
The JSON output contains two top-level objects:
|
||
.B "meta"
|
||
and
|
||
.B "lshwc"
|
||
|
||
.TP
|
||
.B meta
|
||
General metadata such as API version, host, and timestamp.
|
||
|
||
.TP
|
||
.B lshwc
|
||
Measurement data and configuration.
|
||
|
||
.RS
|
||
.IP \fBcpumcf info\fP
|
||
CPU Measurement Counter Facility information.
|
||
.IP \fBmeasurements\fP
|
||
An array of objects, each representing a CPU or "total".
|
||
Each object includes:
|
||
.RS
|
||
.IP \fBcpu\fP
|
||
CPU identifier, such as 0, 1 or "delta" or "total".
|
||
.IP \fBdate_time\fP
|
||
Timestamp in ISO 8601 format.
|
||
.IP \fBtime_epoch\fP
|
||
The number of seconds since the epoch: 1970-01-01 00:00:00 UTC.
|
||
.IP \fBcounters\fP
|
||
An array of counter objects, each containing \fBname\fP (if available), \fBid\fP,
|
||
and \fBvalue\fP.
|
||
.RE
|
||
.RE
|
||
.
|
||
.TP
|
||
\fR[\fIcpulist\fR][:\fIsets\fR]\fP
|
||
A comma-separated list of CPUs.
|
||
Each CPU can optionally be followed by characters that specify the counter set.
|
||
See below for details.
|
||
.
|
||
.SS "CPU List and counter-set specification"
|
||
In the comma-separated list of CPUs,
|
||
each element is a CPU or a range of CPUs.
|
||
By default, \*c lists all CPUs.
|
||
.P
|
||
The CPU list can be followed by an optional list
|
||
of characters that specify the counter sets to be extracted,
|
||
preceded by a colon.
|
||
The characters can be upper or lower case.
|
||
By default, all counter sets are used.
|
||
.IP b
|
||
Include the basic counter set.
|
||
.IP c
|
||
Include the crypto counter set.
|
||
.IP e
|
||
Include the extended counter set.
|
||
.IP m
|
||
Include the MT_Diagnostic counter set.
|
||
.IP p|u
|
||
Include the problem counter set.
|
||
.IP a
|
||
Include all known counter sets (default).
|
||
.SH "EXAMPLES"
|
||
The first example enables the basic and problem counter sets on CPU 0 and 1.
|
||
Two read operations are performed and a summary line is printed for each
|
||
read operation.
|
||
.sp 1
|
||
.nf
|
||
.ft CW
|
||
# lshwc -l2 0-1:BP
|
||
Date,Time,CPU,CPU_CYCLES(0),INSTRUCTIONS(1),L1I_DIR_WRITES(2),L1I_PENALTY_CYCLES(3),L1D_DIR_WRITES(4),
|
||
L1D_PENALTY_CYCLES(5),PROBLEM_STATE_CPU_CYCLES(32),PROBLEM_STATE_INSTRUCTIONS(33)
|
||
2021-04-01,11:50:32,Total,125422,39421,304,13953,454,
|
||
97489,0,0
|
||
2021-04-01,11:51:32,Total,68074231,16386850,194028,21382384,317227,
|
||
104503489,777383,14198
|
||
.ft
|
||
.fi
|
||
.sp 1
|
||
This example shows the counter values of the problem state counter set per CPU.
|
||
CPU 0 and CPU 1 are selected.
|
||
.nf
|
||
.ft CW
|
||
.sp 1
|
||
# lshwc -l3 -a 0-1:P
|
||
Date,Time,CPU,PROBLEM_STATE_CPU_CYCLES(32),PROBLEM_STATE_INSTRUCTIONS(33)
|
||
2021-04-01,11:54:47,CPU0,0,0
|
||
2021-04-01,11:54:47,CPU1,0,0
|
||
2021-04-01,11:54:47,Total,0,0
|
||
2021-04-01,11:55:47,CPU0,818775,14198
|
||
2021-04-01,11:55:47,CPU1,125689,1306
|
||
2021-04-01,11:55:47,Total,944464,15504
|
||
2021-04-01,11:56:47,CPU0,3207071426,1489122591
|
||
2021-04-01,11:56:47,CPU1,3225092021,1489278312
|
||
2021-04-01,11:56:47,Total,6432163447,2978400903
|
||
.ft
|
||
.fi
|
||
.sp 1
|
||
This example shows the counter values of the basic counter set
|
||
using delta output format.
|
||
.nf
|
||
.ft CW
|
||
.sp 1
|
||
# lshwc -d -l 10 -i 5 -s :b
|
||
Date,Time,CPU,B0,B1,B2,B3,B4,B5
|
||
2025-03-26,10:34:19,Total,208075,117287,1950,50548,1082,49609
|
||
2025-03-26,10:34:24,Delta,85800055,70353492,590286,13228290,364034,12945804
|
||
2025-03-26,10:34:29,Delta,70654751,60656797,483047,10838672,305703,10570868
|
||
2025-03-26,10:34:34,Delta,81043162,69476160,587141,13228161,376662,12868298
|
||
2025-03-26,10:34:39,Delta,73434017,62675417,524857,11787256,333966,11543649
|
||
2025-03-26,10:34:44,Delta,68367967,58452919,506712,11370740,310785,10589883
|
||
2025-03-26,10:34:49,Delta,70351947,57607764,507675,11433377,312433,10676243
|
||
2025-03-26,10:34:54,Delta,77154817,65371168,562153,12671030,349750,12311061
|
||
2025-03-26,10:34:59,Delta,88871882,75441201,655310,14875963,392530,13773130
|
||
2025-03-26,10:35:04,Delta,83763472,71730813,609260,13643680,366992,12672405
|
||
.ft
|
||
.fi
|
||
.sp 1
|
||
This example shows the counter values of the problem state counter set with
|
||
CPU 3 selected.
|
||
.nf
|
||
.ft CW
|
||
.sp 1
|
||
# lshwc -l2 -a 3:P -H --format json
|
||
{
|
||
"meta": {
|
||
"api_level": 1,
|
||
"version": "2.37.0-build-20250616",
|
||
"host": "b46lp08.lnxne.boe",
|
||
"time_epoch": 1750094646,
|
||
"time": "2025-06-16 19:24:06+0200"
|
||
},
|
||
"lshwc": {
|
||
"cpumcf info": {
|
||
"counter first": 3,
|
||
"counter second": 8,
|
||
"authorization": 47
|
||
},
|
||
"measurements": [
|
||
{
|
||
"date_time": "2025-06-16 19:24:06+0200",
|
||
"time_epoch": 1750094646,
|
||
"cpu": 3,
|
||
"counters": [
|
||
{
|
||
"name": "problem_state_cpu_cycles",
|
||
"id": 32,
|
||
"value": 0
|
||
},
|
||
{
|
||
"name": "problem_state_instructions",
|
||
"id": 33,
|
||
"value": 0
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"date_time": "2025-06-16 19:24:06+0200",
|
||
"time_epoch": 1750094646,
|
||
"cpu": "total",
|
||
"counters": [
|
||
{
|
||
"name": "problem_state_cpu_cycles",
|
||
"id": 32,
|
||
"value": 0
|
||
},
|
||
{
|
||
"name": "problem_state_instructions",
|
||
"id": 33,
|
||
"value": 0
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"date_time": "2025-06-16 19:25:06+0200",
|
||
"time_epoch": 1750094706,
|
||
"cpu": 3,
|
||
"counters": [
|
||
{
|
||
"name": "problem_state_cpu_cycles",
|
||
"id": 32,
|
||
"value": 0
|
||
},
|
||
{
|
||
"name": "problem_state_instructions",
|
||
"id": 33,
|
||
"value": 0
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"date_time": "2025-06-16 19:25:06+0200",
|
||
"time_epoch": 1750094706,
|
||
"cpu": "total",
|
||
"counters": [
|
||
{
|
||
"name": "problem_state_cpu_cycles",
|
||
"id": 32,
|
||
"value": 0
|
||
},
|
||
{
|
||
"name": "problem_state_instructions",
|
||
"id": 33,
|
||
"value": 0
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
.ft
|
||
.fi
|
||
.SH "SEE ALSO"
|
||
.BR lscpumf (8)
|
||
.BR chcpumf (8)
|