LIBPFM(3)

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

okay bestie, so this is a page from the Linux Programmer's Manual, section 3, and it's all about libpfm — the perfmon library. and specifically? it's about one very specific little corner of it. let's go ✨

🎀 NAME 🎀

libpfm_intel_bdx_unc_pcu — the library's support for the Intel Broadwell Server Power Controller Unit (PCU) uncore PMU. that's it, that's the whole name, and yes it's a mouthful, we love her anyway 💅

🌸 SYNOPSIS 🌸

#include <perfmon/pfmlib.h>

• PMU name: bdx_unc_pcu
• PMU desc: Intel Broadwell Server PCU uncore PMU

🦋 DESCRIPTION 🦋

so basically, the library supports the Intel Broadwell Server Power Controller Unit uncore PMU. and here's the tea: this PMU model only exists on certain Broadwell server models — specifically 79 and 86. no cap, if you're not on one of those, this isn't your girl 🙈

👑 MODIFIERS 👑

here are the modifiers that this Intel Broadwell server PCU uncore PMU supports. they're little add-ons you tack onto an event, and each one changes the vibe of what gets counted ✨

• e — enables edge detection, meaning it only counts when there's a state transition from no occurrence of the event to at least one occurrence. and listen — this modifier must be combined with a threshold modifier (t) with a value greater than or equal to one. it's a boolean modifier, so it's on or it's off, periodt.
• t — sets the threshold value. when you set it to a non-zero value, the counter counts the number of HA 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 values live in the range [0:15]. small range, big power 🫶
• i — inverts the meaning of the threshold or edge filter. if it's set, the event counts when strictly less than N occurrences occur per cycle, given the threshold is set to N. when invert is set, the threshold must be set to a non-zero value. and if you're in edge-detection mode? setting invert means the event counts when the event transitions from occurring to not occurring — a falling edge. it's a boolean modifier 😌
• ff — enables frequency band filtering. this modifier applies only to the UNC_P_FREQ_BANDx_CYCLES events, where x is [0-3]. it expects an integer in the range [0-255], and that value gets interpreted as a frequency value to be multiplied by 100Mhz. so like — if the value is 32, then all cycles where the processor is running at 3.2GHz and more are counted. math is math, and this math is slaying 🔥

🌈 Frequency band filtering 🌈

okay so there are 3 events that support frequency band filtering. (yes, the manpage says 3 and then lists 4, and we're not here to fight the manpage, we're here to report it faithfully, bestie 💀) anyway, they are:

• UNC_P_FREQ_BAND0_CYCLES
• UNC_P_FREQ_BAND1_CYCLES
• UNC_P_FREQ_BAND2_CYCLES
• UNC_P_FREQ_BAND3_CYCLES

the frequency filter (the one you get at via the ff modifier) is stored into a PMU shared register which holds all 4 possible frequency bands — one per event. here's the catch though: the library generates the encoding for each event individually, because it processes events one at a time. so the caller, or the underlying kernel interface, may have to merge the band filter settings to program the filter register properly. it's giving "you gotta do a little assembly yourself, queen" 🧚

💜 AUTHORS 💜

Stephane Eranian <eranian@gmail.com>

and that's the whole page, bestie!! mwah 💖

this iconic little writeup comes to you from the Linux Programmer's Manual, dated June, 2017, and it's LIBPFM(3) through and through. go forth and count those PCU cycles, you absolute main character 👑✨🌸