LIBPFM(3) Linux Programmer's Manual LIBPFM(3)NAMEpfm_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
This function returns in info information about the attribute desig‐
nated by attr for the event specified in idx and the os layer in os.
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 hard‐
ware. 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 pro‐
vided by PFM_OS_PERF_EVENT plus all the software attributes con‐
trolled by perf_events, such as sampling period, precise sam‐
pling.
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 reserved:30;
};
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 string.
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:
PFM_ATTR_UMASK
This is a unit mask, i.e., a sub-event. It is specified
using its name. Depending on the event, it may be possi‐
ble to specify multiple unit masks.
PFM_ATTR_MOD_BOOL
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.
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.
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 compro‐
mising backward compatibility. The value should be set to
sizeof(pfm_event_attr_info_t). If instead, a value of 0 is spec‐
ified, 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.
is_precise
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 sup‐
ports Precise Event-Based Sampling (PEBS).
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:
PFM_ATTR_CTRL_UNKNOWN
The source controlling the attribute is not known.
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.
RETURN
If successful, the function returns PFM_SUCCESS and attribute informa‐
tion in info, otherwise it returns an error code.
ERRORS
PFMLIB_ERR_NOINIT
Library has not been initialized properly.
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.
AUTHOR
Stephane Eranian <eranian@gmail.com>
December, 2009 LIBPFM(3)
