pfm_get_event_attr_info(3) — Linux manual page


LIBPFM(3)                 Linux Programmer's Manual                LIBPFM(3)

NAME         top

       pfm_get_event_attr_info - get event attribute information

SYNOPSIS         top

       #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         top

       This function returns in info information about the attribute
       designated by attr for the event specified in idx and the os layer in

       The pfm_os_t enumeration provides the following choices:

              The returned information pertains only to what the PMU
              hardware exports.  No operating system attributes is taken
              into account.

              The returned information includes the actual PMU hardware and
              the additional attributes exported by the perf_events kernel
              interface.  The perf_event attributes pertain only the PMU
              hardware.  In case perf_events is not detected, an error is

              The returned information includes all of what is already
              provided by PFM_OS_PERF_EVENT plus all the software attributes
              controlled by perf_events, such as sampling period, precise

       The pfm_event_attr_info_t structure is defined as follows:
       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             reserved:28;
               union {
                       uint64_t        dfl_val64;
                       const char      *dfl_str;
                       int             dfl_bool;
                       int             dfl_int;
       } pfm_event_attr_info_t;

       The fields of this structure are defined as follows:

       name   This is the name of the attribute. This is a read-only string.

       desc   This is the description of the attribute. This is a read-only
              string.  It may contain multiple sentences.

       equiv  Certain attributes may be just variations of other attributes
              for the same event.  They may be provided as handy shortcuts
              to avoid supplying a long list of attributes.  For those
              attributes, this field is not NULL and contains the complete
              equivalent attribute string. This string, once appended to the
              event name, may be used library calls requiring an event

       code   This is the raw attribute code. For PFM_ATTR_UMASK, this is
              the unit mask code. For all other attributes, this is an
              opaque index.

       type   This is the type of the attribute. Attributes represent either
              sub-events or extra filters that can be applied to the event.
              Filters (also called modifiers)  may be tied to the event or
              the PMU register the event is programmed into. The type of an
              attribute determines how it must be specified. The following
              types are defined:

                     This is a unit mask, i.e., a sub-event. It is specified
                     using its name.  Depending on the event, it may be
                     possible to specify multiple unit masks.

                     This is a boolean attribute. It has a value of 0, 1, y
                     or n. The value is specified 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.

                     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.

       idx    This is the attribute index. It is identical to the value of
              attr passed to the call and is provided for completeness.

       size   This field contains the size of the struct passed. This field
              is used to provide for extensibility of the struct without
              compromising backward compatibility.  The value should be set
              to sizeof(pfm_event_attr_info_t). If instead, a value of 0 is
              specified, the library assumes the struct passed is identical
              to the first ABI version which size is PFM_ATTR_INFO_ABI0.
              Thus, if fields were added after the first ABI, they will not
              be set by the library. The library does check that bytes
              beyond what is implemented are zeroes.

       is_dfl This field indicates whether or not this attribute is set by
              default. This applies mostly for 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.

              This field indicates 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).

              This bitfield indicates whether or not the attribute includes
              occurrences happening during speculative execution for both
              wrong and correct paths. Given that this kind of event
              information is not always available from vendors, this field
              uses multiple bits. A value of PFM_EVENT_INFO_SPEC_NA
              indicates that speculation information is not available. A
              value of PFM_EVENT_INFO_SPEC_TRUE indicates that the attribute
              counts during speculative execution. A value of
              PFM_EVENT_INFO_SPEC_FALSE indicates that the attribute does
              not count during speculative execution.

       dfl_val64, dfl_str, dfl_bool, dfl_int
              This union contains the value of an attribute. For
              PFM_ATTR_UMASK, the is the unit mask code, for all other types
              this is the actual value of the attribute.

       ctrl   This field indicates which layer or source controls the
              attribute.  The following sources are defined:

                     The source controlling the attribute is not known.

                     The attribute is controlled by the PMU hardware.

                     The attribute is controlled by the perf_events kernel

              These fields must be set to zero.

RETURN         top

       If successful, the function returns PFM_SUCCESS and attribute
       information in info, otherwise it returns an error code.

ERRORS         top

              Library has not been initialized properly.

              The idx or attr arguments are invalid or info is NULL or size
              is not zero.

              The requested os layer has not been detected on the host

AUTHOR         top

       Stephane Eranian <>

COLOPHON         top

       This page is part of the perfmon2 (a performance monitoring library)
       project.  Information about the project can be found at 
       ⟨⟩.  If you have a bug report for this
       manual page, send it to  This
       page was obtained from the project's upstream Git repository
       ⟨git:// perfmon2-libpfm4⟩ on
       2020-09-18.  (At that time, the date of the most recent commit that
       was found in the repository was 2020-08-25.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

                               December, 2009                      LIBPFM(3)