LIBPFM(3)

💖 LIBPFM(3) — the Linux Programmer's Manual glow-up 💖

okay bestie, sit down, hydrate, and let me tell you about a page from the Linux Programmer's Manual that is genuinely so niche and so good. it's LIBPFM(3) and it's giving ✨uncore PMU lore✨. let's go.

✨ NAME ✨

libpfm_intel_hswep_unc_cbo — the support page for the Intel Haswell-EP C-Box uncore PMU. that's it, that's the whole vibe. 🎀

🦋 SYNOPSIS 🦋

#include <perfmon/pfmlib.h>

PMU name: hswep_unc_cbo[0-17]
PMU desc: Intel Haswell-EP C-Box uncore PMU

like, that's the whole thing. short, sweet, iconic. 💅

🌸 DESCRIPTION 🌸

so the library supports the Intel Haswell C-Box (that's the coherency engine, bestie, it's the part that keeps everyone's caches from lying to each other) uncore PMU. this PMU model only exists on Haswell model 63 — no cap, if you're not on model 63, this whole page is not for you. 💀

there is one C-box PMU per physical core. so that means there are up to eighteen identical C-Box PMU instances, numbered from 0 to 17.

now here's the part that lowkey trips people up: on dual-socket systems, that number refers to the C-Box PMU on the socket where the program is running. so for example, if you're running on CPU18, then hswep_unc_cbo0 refers to the C-Box for physical core 0 on socket 1. but flip it — if you're running on CPU0, then that exact same hswep_unc_cbo0 refers to the C-Box for physical core 0, but on socket 0. same name, different physical thing, depending on where you're standing. it's giving relativity, honestly. 🌈

and each C-Box PMU implements 4 generic counters and two filter registers, and those filter registers are only used with certain events and umasks. not everything, just certain ones. periodt. 💅

👑 MODIFIERS 👑

the following modifiers are supported on the Intel Haswell C-Box uncore PMU — read them all, don't skip, I will know:

• e — enables edge detection, meaning it counts only when there's a state transition from no occurrence of the event to at least one occurrence. this modifier must be combined with a threshold modifier (t) with a value greater than or equal to one. it's a boolean modifier. 🦋
• t — sets the threshold value. when you set it 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 than or equal to the threshold. this is an integer modifier and the legal range is [0:255]. 🌸
• nf — the Node filter. certain events, like UNC_C_LLC_LOOKUP and UNC_C_LLC_VICTIMS, provide a NID umask. sometimes that NID gets combined with other filtering capabilities, like opcodes. the node filter is an 8-bit max bitmask. a node corresponds to a processor socket, so the legal values totally depend on your underlying hardware configuration. for dual-socket systems, the bitmask has two valid bits, [0:1]. ✨
• cf — the 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 you don't specify the filter, then no filtering takes place. bits 0-3 indicate the physical core id, and bit 4 filters on non thread-related data. 🎀
• tf — the 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 you don't specify the filter, 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 you don't specify the filter, 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 you don't specify the filter, then no filtering takes place. 🔥

🌈 Opcode filtering 🌈

certain events, like UNC_C_TOR_INSERTS, support opcode matching on the C-BOX transaction type. here's the two-step, bestie:

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.

so for instance, UNC_C_TOR_INSERTS:OPCODE:OPC_RFO counts the number of TOR insertions for RFO transactions. 🍓

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. so like:

UNC_C_TOR_INSERTS:NID_OPCODE:OPC_RFO:nf=1

ate. no crumbs. 💅

💜 AUTHORS 💜

Stephane Eranian <eranian@gmail.com> — ty for your service, king. 👑

💌 and that's the whole page, bestie. May, 2015, from the Linux Programmer's Manual, LIBPFM(3). go forth and count your C-Box cycles responsibly. mwah. 😭🫶✨