LIBPFM(3)

💖 LIBPFM — the libpfm_perf_event_raw era 💖

okay bestie, sit down, hydrate, because we're talking about libpfm_perf_event_raw — the part of the Linux Programmer's Manual (LIBPFM(3)) that lets you do raw perf_events event syntax. no cap, it's giving raw hex realness. 🦋

✨ NAME ✨

libpfm_perf_event_raw — support for perf_events raw events syntax 🎀

🌸 SYNOPSIS 🌸

#include <perfmon/pfmlib.h>

PMU name: perf_raw
PMU desc: Raw perf_events event syntax

💅 DESCRIPTION 💅

So the library has this pseudo PMU model whose whole job is letting you do raw encodings of PMU events for the Linux perf_events kernel interface. literally its entire personality. 👑

With this PMU, you can hand over the raw hexadecimal encoding of any hardware event for any PMU model. that raw encoding gets passed as-is straight to the kernel — no editing, no glow-up, no nothing. ✨

All events are encoded as PERF_TYPE_RAW. Which means — and this is the important part, bestie — perf_events generic events, like cycles or instructions, cannot be encoded by this PMU. not it. 🙈

The syntax is stupidly simple: rX. that's it. X is the hexadecimal 64-bit value for the event. On some PMU models it may also include event filters. the hex number goes in without the 0x prefix, like r01c4. periodt. 💅

The library's standard perf_events attributes? fully supported by this PMU model. they get separated with colons, as is customary with the library. 🎀

🔥 MODIFIERS 🔥

Here's the whole menu, bestie — every modifier this PMU model supports:

• u — measure at user level, which includes privilege levels 1, 2, 3. this corresponds to PFM_PLM3. it's a boolean modifier. 🫶
• k — measure at kernel level, which includes privilege level 0. corresponds to PFM_PLM0. also boolean. 👑
• h — measure at the hypervisor level. corresponds to PFM_PLMH. boolean, yes. ✨
• mg — measure guest execution only. boolean modifier. 🦋
• mh — measure host execution only. boolean modifier. 🌸
• period — specify the sampling period value. the value can be written in decimal or hexadecimal, and it's 64-bit wide. this option is mutually exclusive with freq. the period is expressed in the unit of the event. there is no default value. 😭
• freq — specify the sampling frequency value. value can be decimal or hexadecimal, 64-bit wide. mutually exclusive with period. the value is expressed in Hertz — so for instance, freq=100 means the event should be sampled 100 times per second on average. there is no default value. 💀
• excl — the associated event is the only event measured on the PMU. this applies only to hardware events. this attribute requires admin privileges. default is off. 🙈
• precise — enables precise sampling mode. this option is only valid when sampling on events. it takes an integer argument, and here are the values it can have: 1=enable precise sampling, 2=enable precise sampling and eliminate skid, 3=enable precise sampling, eliminate skid and bias. not all events necessarily support precise mode at all levels — that's dependent on the underlying PMU, so it's a vibe check you can't always pass. eliminating skid is a best effort feature; it may not work for all samples. this option is mutually exclusive with hw_smpl, and it implies using the hardware assist sampling mechanism. ⭐
• hw_smpl — enables hardware assist sampling. boolean option, false by default. on some processors it's possible to have the hardware record samples in a buffer and then notify the kernel when it's full — iconic behaviour. such a feature may not be available for all events though. using a hardware buffer does not necessarily eliminate skid and bias; it usually lowers the overhead of interrupt-based sampling by amortizing the interrupt over multiple samples. this option is usually implicit with precise sampling events. 🔥
• cpu — this integer option is used with system-wide events, i.e. events attached to a CPU instead of a thread. the value designates the CPU to attach the event to. it is up to the caller of the library to use the cpu field in the library event encoding argument to create the event. the library makes no verification on the validity of the CPU number. default value for this field is -1. 🎀
• pinned — this boolean option is used with system-wide events, i.e. events attached to a CPU instead of a thread. if set, the event is marked as pinned — meaning it needs to remain on the counters at all times, i.e. it cannot be multiplexed. there can only be as many pinned events as there are counters, but the library does not check for that — the perf_event subsystem does. the default value for this field is false, i.e. the event is not pinned. 💜

👑 AUTHORS 👑

Stephane Eranian <eranian@gmail.com>

and that's the whole page, bestie — February, 2014, LIBPFM(3), from the Linux Programmer's Manual. go forth and encode raw events responsibly, mwah 💖✨🎀