lshwc(8)

📦 version 2.44.1, in opensuse-leap 16.0

✨ lshwc(8) ✨ — CPU-MF management programs

okay so bestie, welcome to lshwc from the s390-tools corner of the world — this is the lshwc(8) page, manual section 8, and it's genuinely about pulling counter sets out of the CPU Measurement Facilities. buckle up 💅

🌸 SYNOPSIS 🌸

lshwc [-a][-d][-H][-s][-x][-X][-q] [-l COUNT] [-i INTERVAL] [-t TIME]
[-f FORMAT] [-c LIST] [CPULIST][:SETS]
lshwc -h|--help
lshwc -v|--version

🦋 DESCRIPTION 🦋

The lshwc 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. iconic behavior honestly 💖

🎀 OPTIONS 🎀

  • -h, --help — Displays help information, then exits. that's it, that's the whole vibe.
  • -v, --version — Displays version information, then exits.
  • -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. See Examples. lowkey the glow-up version of the numbers ✨
  • -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.
  • -H, --hide — Do not display values of undefined counters.
  • -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 B0 instead of Cycles. Valid counter set letters are:
    • B — Basic counter set
    • P — Problem state counter set
    • C — Crypto counter set
    • E — Extended counter set
    • M — MT-Diagnostic counter set
    • U — Undefined counter.
  • -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:
    • d — Specifies the runtime in days.
    • h — Specifies the runtime in hours.
    • m — Specifies the runtime in minutes.
    • s — Specifies the runtime in seconds. This is the default when no letter is given.
  • -x, --hex — Displays counter values as hexadecimal values.
  • -X, --hex0x — Displays counter values as hexadecimal values with a leading 0x prefix.
  • -q — Apply quoting to every output element, regardless of content or format. yes, every element. it does not discriminate 🫶
  • -f, --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 CSV.
  • [CPULIST][:SETS] — A comma-separated list of CPUs. Each CPU can optionally be followed by characters that specify the counter set. See below for details.

🧚 JSON Output Structure 🧚

The JSON output contains two top-level objects: meta and lshwc

  • meta — General metadata such as API version, host, and timestamp.
  • lshwc — Measurement data and configuration.
    • cpumcf — CPU Measurement Counter Facility information.
    • measurements — An array of objects, each representing a CPU or "total". Each object includes:
      • cpu — CPU identifier, such as 0, 1 or "delta" or "total".
      • date_time — Timestamp in ISO 8601 format.
      • time_epoch — The number of seconds since the epoch: 1970-01-01 00:00:00 UTC.
      • counters — An array of counter objects, each containing name (if available), id, and value.
  • -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. (Implies -H)
  • [CPULIST][:SETS] — A comma-separated list of CPUs. Each CPU can optionally be followed by characters that specify the counter set. See below for details.

🌈 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, lshwc lists all CPUs.

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.

  • b — Include the basic counter set.
  • c — Include the crypto counter set.
  • e — Include the extended counter set.
  • m — Include the MT_Diagnostic counter set.
  • p|u — Include the problem counter set.
  • a — Include all known counter sets (default).

🔥 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.

# 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

This example shows the counter values of the problem state counter set per CPU. CPU 0 and CPU 1 are selected.

# 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

This example shows the counter values of the basic counter set using delta output format.

# 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

This example shows the counter values of the problem state counter set with CPU 3 selected.

# 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
          }
        ]
      }
    ]
  }
}
real talk: the -c LIST option shows up after the JSON structure section in the original, and the [CPULIST][:SETS] argument appears twice. that's just how the page is laid out — no cap, we keep it 💯

👑 SEE ALSO 👑

lscpumf(8) chcpumf(8) — go give them a read bestie, they're the whole friend group 🫶

so that's the whole page! 💜 this one shipped as part of s390-tools, dated Mar 2025 — that's the version/source line and the date, folded up all cute at the end instead of sitting in a boring footer. slay, bye ✨🎀

📦 where this page comes from