pfm_get_event_info - get event information
#include <perfmon/pfmlib.h>
int pfm_get_event_info(int idx, pfm_os_t os, pfm_event_info_t *info);
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 settings.
- 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 information.
- 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
completeness.
- 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.
- is_precise
- 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).
- is_speculative
- 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:
- PFM_OS_NONE
- The returned information pertains only to what the PMU hardware exports.
No operating system attributes is taken into account.
- PFM_OS_PERF_EVENT
- 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 returned.
- PFM_OS_PERF_EVENT_EXT
- 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 sampling.
If successful, the function returns PFM_SUCCESS and event
information in info, otherwise it returns an error code.
Stephane Eranian <eranian@gmail.com>