1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 pfm_get_event_attr_info - get event attribute information
7
9 #include <perfmon/pfmlib.h>
10 int pfm_get_event_attr_info(int idx, int attr, pfm_os_t os, pfm_event_attr_info_t *info);
12
15 This function returns in info information about the attribute desig‐
16 nated by attr for the event specified in idx and the os layer in os.
17 The pfm_os_t enumeration provides the following choices:
19 PFM_OS_NONE
21 The returned information pertains only to what the PMU hardware
22 exports. No operating system attributes is taken into account.
23 PFM_OS_PERF_EVENT
25 The returned information includes the actual PMU hardware and
26 the additional attributes exported by the perf_events kernel
27 interface. The perf_event attributes pertain only the PMU hard‐
28 ware. In case perf_events is not detected, an error is
29 returned.
30 PFM_OS_PERF_EVENT_EXT
32 The returned information includes all of what is already pro‐
33 vided by PFM_OS_PERF_EVENT plus all the software attributes con‐
34 trolled by perf_events, such as sampling period, precise sam‐
35 pling.
36 The pfm_event_attr_info_t structure is defined as follows:
38 typedef struct {
39 const char *name;
40 const char *desc;
41 const char *equiv;
42 size_t size;
43 uint64_t code;
44 pfm_attr_t type;
45 int idx;
46 pfm_attr_ctrl_t ctrl;
47 int reserved1;
48 struct {
49 int is_dfl:1;
50 int is_precise:1;
51 int reserved:30;
52 };
53 union {
54 uint64_t dfl_val64;
55 const char *dfl_str;
56 int dfl_bool;
57 int dfl_int;
58 };
59 } pfm_event_attr_info_t;
60 The fields of this structure are defined as follows:
62 name This is the name of the attribute. This is a read-only string.
64 desc This is the description of the attribute. This is a read-only
66 string. It may contain multiple sentences.
67 equiv Certain attributes may be just variations of other attributes
69 for the same event. They may be provided as handy shortcuts to
70 avoid supplying a long list of attributes. For those
71 attributes, this field is not NULL and contains the complete
72 equivalent attribute string. This string, once appended to the
73 event name, may be used library calls requiring an event string.
74 code This is the raw attribute code. For PFM_ATTR_UMASK, this is the
76 unit mask code. For all other attributes, this is an opaque
77 index.
78 type This is the type of the attribute. Attributes represent either
80 sub-events or extra filters that can be applied to the event.
81 Filters (also called modifiers) may be tied to the event or the
82 PMU register the event is programmed into. The type of an
83 attribute determines how it must be specified. The following
84 types are defined:
85 PFM_ATTR_UMASK
87 This is a unit mask, i.e., a sub-event. It is specified
88 using its name. Depending on the event, it may be possi‐
89 ble to specify multiple unit masks.
90 PFM_ATTR_MOD_BOOL
92 This is a boolean attribute. It has a value of 0, 1, y or
93 n. The value is specified after the equal sign, e.g.,
94 foo=1. As a convenience, the equal sign and value may be
95 omitted, in which case this is equivalent to =1.
96 PFM_ATTR_MOD_INTEGER
98 This is an integer attribute. It has a value which must
99 be passed after the equal sign. The range of valid values
100 depends on the attribute and is usually specified in its
101 description.
102 idx This is the attribute index. It is identical to the value of
104 attr passed to the call and is provided for completeness.
105 size This field contains the size of the struct passed. This field is
107 used to provide for extensibility of the struct without compro‐
108 mising backward compatibility. The value should be set to
109 sizeof(pfm_event_attr_info_t). If instead, a value of 0 is spec‐
110 ified, the library assumes the struct passed is identical to the
111 first ABI version which size is PFM_ATTR_INFO_ABI0. Thus, if
112 fields were added after the first ABI, they will not be set by
113 the library. The library does check that bytes beyond what is
114 implemented are zeroes.
115 is_dfl This field indicates whether or not this attribute is set by
117 default. This applies mostly for PFM_ATTR_UMASK. If a unit mask
118 is marked as default, and no unit mask is specified in the event
119 string, then the library uses it by default. Note that there may
120 be multiple defaults per event depending on how unit masks are
121 grouped.
122 is_precise
124 This field indicates whether or not this umask supports precise
125 sampling. Precise sampling is a hardware mechanism that avoids
126 instruction address skid when using interrupt-based sampling. On
127 Intel X86 processors, this field indicates that the umask sup‐
128 ports Precise Event-Based Sampling (PEBS).
129 dfl_val64, dfl_str, dfl_bool, dfl_int
131 This union contains the value of an attribute. For
132 PFM_ATTR_UMASK, the is the unit mask code, for all other types
133 this is the actual value of the attribute.
134 ctrl This field indicates which layer or source controls the
136 attribute. The following sources are defined:
137 PFM_ATTR_CTRL_UNKNOWN
139 The source controlling the attribute is not known.
140 PFM_ATTR_CTRL_PMU
142 The attribute is controlled by the PMU hardware.
143 PFM_ATTR_CTRL_PERF_EVENT
145 The attribute is controlled by the perf_events kernel
146 interface.
147 reserved
149 These fields must be set to zero.
150
152 If successful, the function returns PFM_SUCCESS and attribute informa‐
153 tion in info, otherwise it returns an error code.
154
156 PFMLIB_ERR_NOINIT
157 Library has not been initialized properly.
158 PFMLIB_ERR_INVAL
160 The idx or attr arguments are invalid or info is NULL or size is
161 not zero.
162 PFM_ERR_NOTSUPP
164 The requested os layer has not been detected on the host system.
165
167 Stephane Eranian <eranian@gmail.com>
168 December, 2009 LIBPFM(3)