LIBPFM(3)

💖 LIBPFM(3) — the Linux Programmer's Manual, but make it cute 💖

okay bestie, sit down, hydrate, and let's talk about libpfm_intel_bdx_unc_cbo — yeah the name is a mouthful, i know, but it's literally the support page for the Intel Broadwell Server C-Box uncore PMU and she is serving.

✨ NAME ✨

libpfm_intel_bdx_unc_cbo — the whole entire vibe is: support for the Intel Broadwell Server C-Box uncore PMU. that's it, that's the name, periodt.

✨ SYNOPSIS ✨

#include <perfmon/pfmlib.h>

PMU name: bdx_unc_cbo[0-21]
PMU desc: Intel Broadwell Server C-Box uncore PMU

like, just include the header and you're in. slay.

✨ DESCRIPTION ✨

so the library supports the Intel Broadwell Server C-Box (that's the coherency engine, bestie) uncore PMU. this PMU model shows up on various Broadwell server models — specifically 79 and 86. 💅

here's the tea: there's one C-box PMU per physical core. which means there are up to twenty-one identical C-Box PMU instances, numbered from 0 to 21. 🎀

and on dual-socket systems?? the number refers to the C-Box PMU on the socket where the program runs. so like, if you're running on CPU18, then bdx_unc_cbo0 refers to the C-Box for physical core 0 on socket 1. conversely, if you're running on CPU0, then that same exact bdx_unc_cbo0 refers to the C-Box for physical core 0 but on socket 0. same name, different socket, it's giving ✨context-dependent✨ and honestly? iconic behavior. 🦋

also each C-Box PMU implements 4 generic counters and two filter registers that are used only with certain events and umasks. noted, bestie, don't forget it. 📝

✨ MODIFIERS ✨

these are the modifiers supported on the Intel Broadwell C-Box uncore PMU, and no you cannot skip any of them, we're doing all of them:

• e — enable edge detection, i.e. count only when there's a state transition from no occurrence of the event to at least one occurrence. ⚠️ this one must be combined with a threshold modifier (t) with a value greater or equal to one, or it's not gonna work, bestie. this is a boolean modifier.
• t — set the threshold value. when it's set to a non-zero value, the counter counts the number of C-Box cycles in which the number of occurrences of the event is greater or equal to the threshold. this is an integer modifier with values in the range [0:255]. 🍓
• nf — Node filter. certain events, like UNC_C_LLC_LOOKUP and UNC_C_LLC_VICTIMS, provide a NID umask. sometimes the NID is combined with other filtering capabilities, such as opcodes. the node filter is an 8-bit max bitmask. a node corresponds to a processor socket. the legal values therefore depend on the underlying hardware configuration. for dual-socket systems, the bitmask has two valid bits [0:1]. 💀 (yes, hardware-dependent, read the room before you pick a number)
• cf — Core Filter. this is a 5-bit filter used to filter based on the physical core origin of the C-Box request. possible values are 0-63. if the filter isn't specified, then no filtering takes place. bits 0-3 indicate the physical core id and bit 4 filters on non thread-related data. 👑
• tf — Thread Filter. this is a 1-bit filter used to filter C-Box requests based on logical processor (hyper-thread) identification. possible values are 0-1. if the filter isn't specified, then no filtering takes place. 🧚
• nc — Non-Coherent. this is a 1-bit filter used to filter C-Box requests only for the TOR_INSERTS and TOR_OCCUPANCY umasks using the OPCODE matcher. if the filter isn't specified, then no filtering takes place. 🙈
• isoc — Isochronous. this is a 1-bit filter used to filter C-Box requests only for the TOR_INSERTS and TOR_OCCUPANCY umasks using the OPCODE matcher. if the filter isn't specified, then no filtering takes place. 🌈

✨ Opcode filtering ✨

certain events, such as UNC_C_TOR_INSERTS, support opcode matching on the C-BOX transaction type. bestie, this is a two-step situation, pay attention:

1. first, an opcode matching umask must be selected, e.g. MISS_OPCODE.
2. second, the opcode to match on must be selected via a second umask among the OPC_* umasks.

for instance:

UNC_C_TOR_INSERTS:OPCODE:OPC_RFO

counts the number of TOR insertions for RFO transactions. ate. 💅

opcode matching may also be combined with node filtering with certain umasks. in general, the filtering support is encoded into the umask name, e.g. NID_OPCODE supports both node and opcode filtering. for instance:

UNC_C_TOR_INSERTS:NID_OPCODE:OPC_RFO:nf=1

see how she did that? both filters, one event, main character energy fr fr. 🔥

✨ AUTHORS ✨

Stephane Eranian <eranian@gmail.com> — the icon, the legend, the moment. 🫶

and that's the whole page, bestie!! 🎀 this was LIBPFM(3) from the Linux Programmer's Manual, dated June, 2017 — shoutout to that source and version, she's aging like fine wine. now go count some C-Box cycles, you absolute legend. 💖✨🦋🌸👑