LIBPFM(3)

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

okay bestie, sit down, hydrate, and let me tell you about pfm_find_event — she's a libpfm girlie and she's here to turn your little event strings into actual event identifiers. no cap. ✨

🌸 NAME 🌸

pfm_find_event — search for an event masks 👑

🎀 SYNOPSIS 🎀

#include <perfmon/pfmlib.h>

int pfm_find_event(const char *str);

🦋 DESCRIPTION 🦋

So basically? This function takes the event string you shoved into str and converts it into an opaque event identifier, which is literally just the return value. that's the whole job. she ate. 💅

Events start their life as strings — they hold the event name, the sub-event names, and any optional filters and modifiers. This function reads that string and goes looking for the matching event. fr fr. 🔍

The event string is a structured string, and it's built like this:

[pmu_name::]event_name[:unit_mask][:modifier|:modifier=val]

All the little pieces get separated by : or ::, and here's what each one actually means:

• pmu_name — this is an optional prefix that says "hey, use this specific PMU model". With the prefix, the event matching event_name is the one that gets used. And here's the tea: when multiple PMU models are activated, identical event names can conflict — they might mean the same thing, or they might mean totally different things. 😭 When that happens, you have to fully specify the event with a pmu_name. That string corresponds to whatever pfm_get_pmu_name() hands back.
• event_name — the event name, and it's required, no skipping. The library is not case sensitive on event strings, so don't stress the caps. But heads up: the event name must match the actual event name completely — it cannot be a substring. no partial credit, bestie. 🙅
• unit_mask — optional, and you can think of it like a sub-event of the major event. If an event has unit masks and there's no default, then you must pass at least one unit mask in the string. Also, multiple unit masks may be specified for a single event. the more the merrier honestly. 🫶
• modifier — an optional filter, provided either by the hardware register hosting the event or by the underlying kernel infrastructure. Typical modifiers include privilege level filters. Some modifiers are simple booleans, in which case just passing their names is the same as setting their value to true. Other modifiers need a specific value, and that value goes after the equal sign. > 🚨 No space is tolerated around the equal sign. none. zero. don't do it. 🚨 The list of modifiers depends on the host PMU and the underlying kernel API, and they're documented in PMU-specific documentation. Multiple modifiers may be passed, and there is no order between unit masks and modifiers — they can vibe in whatever order they want.

The library uses the generic term attribute to mean both unit masks and modifiers. one word, two jobs, iconic.

✨ examples, because we love a visual ✨

amd64::RETIRED_INSTRUCTIONS:u

Event RETIRED_INSTRUCTION on AMD64 processor, measured at user privilege level only. 💖

RS_UOPS_DISPATCHED:c=1:i:u

Event RS_UOPS_DISPATCHED measured at user privilege level only, and with counter-mask set to 1.

🧚 the fine print, but make it friendly 🧚

For the purpose of this function, only the pmu_name and event_name are actually considered. Everything else is parsed — so it has to be valid — but it gets ignored. parsed and then ghosted, honestly. 👻

And the function searches for only one event per call. As a convenience, it'll identify the event up to the first comma. In other words, if str is equal to "EVENTA,EVENTB", then the function will only look at EVENTA and will not return an error because of an invalid event string. Super handy when you're parsing constant event strings containing multiple, comma-separated, events. main character energy tbh. 🌟

💖 RETURN 💖

She returns the opaque event identifier that corresponds to the event string. And if something goes wrong? A negative error code comes back instead. sad girl hours. 😭

🌈 ERRORS 🌈

• PFMLIB_ERR_NOINIT — the library has not been initialized properly. she wasn't ready. 💀
• PFMLIB_ERR_INVAL — the event string is NULL.
• PFMLIB_ERR_NOMEM — the library ran out of memory.
• PFMLIB_ERR_NOTFOUND — the event was not found. gone. vanished. 🙈
• PFMLIB_ERR_ATTR — invalid event attribute
• PFMLIB_ERR_ATTR_VAL — invalid event attribute value
• PFMLIB_ERR_TOOMANY — too many event attributes passed

👑 AUTHOR 👑

Stephane Eranian <eranian@gmail.com> — legend behavior, honestly. 🫶

okay that's the whole page, bestie!! this was LIBPFM(3), from the Linux Programmer's Manual, and it's dated September, 2009. go forth and find your events 💖✨🌸🦋