LIBPFM(3)

💖 LIBPFM(3) 💖

okay bestie, welcome to the Linux Programmer's Manual page for LIBPFM(3) — yes the whole libpfm situation — and today we're hyperfixating on exactly one function. sit down, grab a strawberry drink 🍓, and let's get into it.

✨ NAME ✨

pfm_get_event_info — bestie, it gets you event information. that's the whole job. she's focused, she's employed, she's serving.

🦋 SYNOPSIS 🦋

#include <perfmon/pfmlib.h>

int pfm_get_event_info(int idx, pfm_os_t os, pfm_event_info_t *info);

look at her. three args. no notes. 💅

🌸 DESCRIPTION 🌸

so this function drops info about one specific event into info. which event? the one with that opaque, unique little identifier idx — and it's for the operating system you name in os. that's it, that's the vibe check. ✨

the pfm_event_info_t structure is defined like this, and bestie I am copying this character for character, do not come for me:

typedef struct {
        const char              *name;
        const char              *desc;
        const char              *equiv;
        size_t              size;
        uint64_t                code;
        pfm_pmu_t               pmu;
        pfm_dtype_t             dtype
        int                     idx;
        int                     nattrs;
        struct {
          unsigned int is_precise:1;
          unsigned int reserved_bits:31;
        };
} pfm_event_info_t;

and now, the fields, one by one, no skips, no skimming, we read here 📖:

• name — the name of the event. it's a read-only string. hands off, she's not yours to edit.
• desc — the description of the event. also read-only. it can have multiple sentences in it, so she's a talker, we love that for her.
• equiv — okay so some events are literally just variations of actual events, offered as handy lil shortcuts so you don't have to type out a long list of attributes. for those events this field is not NULL and it holds the complete equivalent event string. iykyk.
• code — the raw event code. do not confuse this with the encoding of the event, bestie, that's a different thing. this field is only the event selection code — no unit mask, no attribute settings, none of that. just the code.
• pmu — which PMU model this event belongs to. it's of type pfm_pmu_t. and if you take this value plus the pfm_get_pmu_info function, you can get PMU information. combo move 🔥.
• dtype — this field returns the representation of the event data. by default it's PFM_DATA_UINT64.
• idx — the event's unique opaque identifier. it's identical to the idx you passed in, and it's there for completeness. she's showing up to be thorough, periodt.
• nattrs — how many attributes this event supports. attributes can be unit masks or modifiers. if the event has no attribute at all, this field is just 0. simple as that.
• size — the size of the struct you passed in. this field exists so the struct can be extended without breaking backward compatibility, which is honestly iconic engineering behavior 👑. you should set it to sizeof(pfm_event_info_t). but if you pass 0 instead, the library assumes the struct you handed over is identical to the first ABI version, whose size is PFM_EVENT_INFO_ABI0. so if fields got added after that first ABI, the library will not set them. and yes, the library does check that bytes beyond what's implemented are zeroes. she verifies. she's meticulous. 💅
• is_precise — this bitfield says whether or not the event supports precise sampling. precise sampling is a hardware mechanism that avoids instruction address skid when you're using interrupt-based sampling. when the event has umasks, this field means at least one umask supports precise sampling. on Intel X86 processors, this tells you whether the event supports Precise Event-Based Sampling, aka PEBS. 💀 hardware lore.
• is_speculative — this bitfield says whether or not the event includes occurrences happening during speculative execution, for both the wrong and correct path. and because this kind of event info isn't always available from vendors, this field uses multiple bits:
  • PFM_EVENT_INFO_SPEC_NA — speculation info is not available. 🤷
  • PFM_EVENT_INFO_SPEC_TRUE — the event does count during speculative execution.
  • PFM_EVENT_INFO_SPEC_FALS — the event does not count during speculative execution.

🌈 the pfm_os_t enumeration 🌈

she gives you these choices, pick your fighter:

• PFM_OS_NONE — what you get back pertains only to what the PMU hardware exports. no operating system attributes are taken into account. raw. unfiltered. au naturel.
• PFM_OS_PERF_EVENT — what you get back includes the actual PMU hardware plus the extra attributes exported by the perf_events kernel interface. those perf_event attributes pertain only to the PMU hardware. and heads up: if perf_events isn't detected, you get an error back. 🚨
• PFM_OS_PERF_EVENT_EXT — everything PFM_OS_PERF_EVENT already gives you, plus all the software attributes controlled by perf_events, like sampling period and precise sampling. the deluxe edition 🎀.

⭐ RETURN ⭐

if it works, the function returns PFM_SUCCESS and the event information lands in info. if not, you get an error code. no in-between, she doesn't do ambiguity.

💜 ERRORS 💜

• PFMLIB_ERR_NOINIT — the library has not been initialized properly. she woke up and nobody set her up. 😭
• PFMLIB_ERR_INVAL — the idx argument is invalid, or info is NULL, or size is not zero.
• PFMLIB_ERR_NOTSUPP — the os you requested is not detected or supported. not on the menu, bestie.

🫶 AUTHOR 🫶

Stephane Eranian <eranian@gmail.com>

okay that's the whole page, you absolutely ate this read 💅 go forth and query your events responsibly.

mwah 💖 this was the Linux Programmer's Manual, LIBPFM(3), dated December, 2009 — and that's the sign-off, bestie, love u, bye 🎀✨🦋