LIBPFM(3)

🌸 LIBPFM(3) 🌸

okay bestie, listen up — this is a page from the Linux Programmer's Manual, and it's all about one very specific little function. no cap. let's get into it 💖

---

✨ NAME ✨

pfm_get_event_attr_info — get event attribute information

---

✨ SYNOPSIS ✨

#include <perfmon/pfmlib.h>

int pfm_get_event_attr_info(int idx, int attr, pfm_os_t os, pfm_event_attr_info_t *info);

---

✨ DESCRIPTION ✨

so this function fills in info with the tea about the attribute that attr points to, for the event you named in idx, and for the os layer you picked in os. that's it, that's the whole vibe 🦋

the pfm_os_t enumeration gives you these choices:

• PFM_OS_NONE — the info you get back is only about what the PMU hardware itself exports. no operating system attributes get taken into account at all. pure hardware, no notes 💅
• PFM_OS_PERF_EVENT — the info you get back includes the actual PMU hardware plus the extra attributes exported by the perf_events kernel interface. the perf_event attributes pertain only to the PMU hardware. and if perf_events isn't detected? boom, you get an error back. 😭
• PFM_OS_PERF_EVENT_EXT — the info you get back includes everything PFM_OS_PERF_EVENT already gives you plus all the software attributes controlled by perf_events, like sampling period and precise sampling. the full package, fr fr ✨

🌟 the pfm_event_attr_info_t structure 🌟

it's defined like this, bestie:

typedef struct {
        const char              *name;
        const char              *desc;
        const char              *equiv;
        size_t              size;
        uint64_t                code;
        pfm_attr_t              type;
        int                     idx;
        pfm_attr_ctrl_t         ctrl;
        int                     reserved1;
        struct {
                int             is_dfl:1;
                int             is_precise:1;
                int             is_speculative:2;
          int       support_hw_smpl:1;
          int       support_no_mods:1;
                int             reserved:26;
        };
        union {
                uint64_t        dfl_val64;
                const char      *dfl_str;
                int             dfl_bool;
                int             dfl_int;
        };
} pfm_event_attr_info_t;

and now the field-by-field breakdown, because you deserve to know what every single one of these is doing 👑

🎀 the fields 🎀

• name — this is the name of the attribute. it's a read-only string, don't even try it.
• desc — this is the description of the attribute. also a read-only string. it may contain multiple sentences, so like, a whole paragraph sometimes, she's chatty.
• equiv — okay so some attributes are literally just variations of other attributes for the same event. they're offered as handy shortcuts so you don't have to supply a long list of attributes. for those attributes, this field is not NULL and it holds the complete equivalent attribute string. that string, once you append it to the event name, may be used in library calls that require an event string. convenient queen 💅
• code — this is the raw attribute code. for PFM_ATTR_UMASK, this is the unit mask code. for all other attributes, it's an opaque index. mysterious but valid.
• type — this is the type of the attribute. attributes represent either sub-events or extra filters you can apply to the event. filters (also called modifiers) may be tied to the event or to the PMU register the event is programmed into. the type of an attribute determines how you have to specify it. here are the types:
  • PFM_ATTR_UMASK — this is a unit mask, i.e., a sub-event. you specify it using its name. depending on the event, it may be possible to specify multiple unit masks. collect them all ✨
  • PFM_ATTR_MOD_BOOL — this is a boolean attribute. it has a value of 0, 1, y or n. the value goes after the equal sign, e.g., foo=1. as a convenience, the equal sign and value may be omitted, in which case this is equivalent to =1. lazy-girl friendly, we love that.
  • PFM_ATTR_MOD_INTEGER — this is an integer attribute. it has a value which must be passed after the equal sign. the range of valid values depends on the attribute and is usually specified in its description. so read the description, bestie, it's there for a reason.
• idx — this is the attribute index. it's identical to the value of attr you passed to the call, and it's provided for completeness. a little echo of your own choices, cute.
• size — this field contains the size of the struct passed. it exists so the struct can be extended without breaking backward compatibility. the value should be set to sizeof(pfm_event_attr_info_t). if instead you specify a value of 0, the library assumes the struct you passed is identical to the first ABI version, whose size is PFM_ATTR_INFO_ABI0. so if fields were added after that first ABI, they will not be set by the library. the library does check that bytes beyond what is implemented are zeroes. it's checking up on you 🙈
• is_dfl — this field tells you whether or not this attribute is set by default. this applies mostly to PFM_ATTR_UMASK. if a unit mask is marked as default, and no unit mask is specified in the event string, then the library uses it by default. note that there may be multiple defaults per event depending on how unit masks are grouped. so many main characters.
• is_precise — this field tells you whether or not this umask supports precise sampling. precise sampling is a hardware mechanism that avoids instruction address skid when using interrupt-based sampling. on Intel X86 processors, this field indicates that the umask supports Precise Event-Based Sampling (PEBS). iconic behavior tbh.
• is_speculative — this bitfield tells you whether or not the attribute includes occurrences happening during speculative execution, for both wrong and correct paths. given that this kind of event information isn't always available from vendors, this field uses multiple bits. a value of PFM_EVENT_INFO_SPEC_NA means speculation information is not available. a value of PFM_EVENT_INFO_SPEC_TRUE means the attribute counts during speculative execution. a value of PFM_EVENT_INFO_SPEC_FALSE means the attribute does not count during speculative execution. three moods, pick one 💀
• support_hw_smpl — this boolean field indicates that the attribute (in this case a umask) supports hardware sampling. that means the hardware can sample this event + umasks without involving the kernel at each sample. no kernel, no drama.
• support_no_mods — this boolean field indicates that the attribute (in this case a umask) does not support any hardware or software modifiers, such as privilege level filters, sampling, precise sampling, and such. this is necessary when select umasks of an event have more restrictions than others, e.g., the event and most umasks support modifiers except a few umasks. some of them just want to be left alone.
• dfl_val64, dfl_str, dfl_bool, dfl_int — this union contains the value of an attribute. for PFM_ATTR_UMASK, it's the unit mask code; for all other types, it's the actual value of the attribute.
• ctrl — this field indicates which layer or source controls the attribute. here are the sources:
  • PFM_ATTR_CTRL_UNKNOWN — the source controlling the attribute is not known. mystery era 🕵️
  • PFM_ATTR_CTRL_PMU — the attribute is controlled by the PMU hardware.
  • PFM_ATTR_CTRL_PERF_EVENT — the attribute is controlled by the perf_events kernel interface.
• reserved — these fields must be set to zero. no negotiation. zero. 🫶

---

✨ RETURN ✨

if everything goes well, the function returns PFM_SUCCESS and hands you the attribute info in info. otherwise it returns an error code, and you deal with it. 😭

---

✨ ERRORS ✨

• PFMLIB_ERR_NOINIT — library has not been initialized properly. ma'am, please initialize.
• PFMLIB_ERR_INVAL — the idx or attr arguments are invalid, or info is NULL, or size is not zero.
• PFM_ERR_NOTSUPP — the requested os layer has not been detected on the host system. it's not here, bestie, sorry.

---

✨ AUTHOR ✨

Stephane Eranian <eranian@gmail.com> — legend behavior, we thank you for your service 👑

---

and that's the whole page, bestie 💖 this manual page was dated December, 2009 and comes from LIBPFM(3) — the Linux Programmer's Manual. go forth and query your event attributes with confidence, periodt. ✨🎀🦋