pfm_get_event_info(3) — Linux manual page


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

NAME         top

       pfm_get_event_info - get event information

SYNOPSIS         top

       #include <perfmon/pfmlib.h>

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

DESCRIPTION         top

       This function returns in info information about a specific event
       designated by its opaque unique identifier in idx for the operating
       system specified in os.

       The pfm_event_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_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;

       The fields of this structure are defined as follows:

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

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

       equiv  Certain events may be just variations of actual events. They
              may be provided as handy shortcuts to avoid supplying a long
              list of attributes. For those events, this field is not NULL
              and contains the complete equivalent event string.

       code   This is the raw event code. It should not be confused with the
              encoding of the event. This field represents only the event
              selection code, it does not include any unit mask or attribute

       pmu    This is the identification of the PMU model this event belongs
              to. It is of type pfm_pmu_t. Using this value and the
              pfm_get_pmu_info function, it is possible to get PMU

       dtype  This field returns the representation of the event data. By
              default, it is PFM_DATA_UINT64.

              idx This is the event unique opaque identifier. It is
              identical to the idx passed to the call and is provided for

       nattrs This is the number of attributes supported by this event.
              Attributes may be unit masks or modifiers. If the event has
              not attribute, then the value of this field is simply 0.

       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_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_EVENT_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.

              This bitfield indicates whether or not the event support
              precise sampling.  Precise sampling is a hardware mechanism
              that avoids instruction address skid when using interrupt-
              based sampling. When the event has umasks, this field means
              that at least one umask supports precise sampling. On Intel
              X86 processors, this indicates whether the event supports
              Precise Event-Based Sampling (PEBS).

              This bitfield indicates whether or not the event includes
              occurrences happening during speculative execution for both
              wrong and correct path. 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 event
              count during speculative execution. A value of
              PFM_EVENT_INFO_SPEC_FALS indicates that the event does not
              count during speculative execution.

       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

RETURN         top

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

ERRORS         top

              Library has not been initialized properly.

              The idx argument is invalid or info is NULL or size is not

              The requested os is not detected or supported.

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)