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 in‐
27 terface. The perf_event attributes pertain only the PMU hard‐
28 ware. In case perf_events is not detected, an error is re‐
29 turned.
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 is_speculative:2;
52 int reserved:28;
53 };
54 union {
55 uint64_t dfl_val64;
56 const char *dfl_str;
57 int dfl_bool;
58 int dfl_int;
59 };
60 } pfm_event_attr_info_t;
61 The fields of this structure are defined as follows:
63 name This is the name of the attribute. This is a read-only string.
65 desc This is the description of the attribute. This is a read-only
67 string. It may contain multiple sentences.
68 equiv Certain attributes may be just variations of other attributes
70 for the same event. They may be provided as handy shortcuts to
71 avoid supplying a long list of attributes. For those at‐
72 tributes, this field is not NULL and contains the complete
73 equivalent attribute string. This string, once appended to the
74 event name, may be used library calls requiring an event string.
75 code This is the raw attribute code. For PFM_ATTR_UMASK, this is the
77 unit mask code. For all other attributes, this is an opaque in‐
78 dex.
79 type This is the type of the attribute. Attributes represent either
81 sub-events or extra filters that can be applied to the event.
82 Filters (also called modifiers) may be tied to the event or the
83 PMU register the event is programmed into. The type of an attri‐
84 bute determines how it must be specified. The following types
85 are defined:
86 PFM_ATTR_UMASK
88 This is a unit mask, i.e., a sub-event. It is specified
89 using its name. Depending on the event, it may be possi‐
90 ble to specify multiple unit masks.
91 PFM_ATTR_MOD_BOOL
93 This is a boolean attribute. It has a value of 0, 1, y or
94 n. The value is specified after the equal sign, e.g.,
95 foo=1. As a convenience, the equal sign and value may be
96 omitted, in which case this is equivalent to =1.
97 PFM_ATTR_MOD_INTEGER
99 This is an integer attribute. It has a value which must
100 be passed after the equal sign. The range of valid values
101 depends on the attribute and is usually specified in its
102 description.
103 idx This is the attribute index. It is identical to the value of
105 attr passed to the call and is provided for completeness.
106 size This field contains the size of the struct passed. This field is
108 used to provide for extensibility of the struct without compro‐
109 mising backward compatibility. The value should be set to
110 sizeof(pfm_event_attr_info_t). If instead, a value of 0 is spec‐
111 ified, the library assumes the struct passed is identical to the
112 first ABI version which size is PFM_ATTR_INFO_ABI0. Thus, if
113 fields were added after the first ABI, they will not be set by
114 the library. The library does check that bytes beyond what is
115 implemented are zeroes.
116 is_dfl This field indicates whether or not this attribute is set by de‐
118 fault. This applies mostly for PFM_ATTR_UMASK. If a unit mask is
119 marked as default, and no unit mask is specified in the event
120 string, then the library uses it by default. Note that there may
121 be multiple defaults per event depending on how unit masks are
122 grouped.
123 is_precise
125 This field indicates whether or not this umask supports precise
126 sampling. Precise sampling is a hardware mechanism that avoids
127 instruction address skid when using interrupt-based sampling. On
128 Intel X86 processors, this field indicates that the umask sup‐
129 ports Precise Event-Based Sampling (PEBS).
130 is_speculative
132 This bitfield indicates whether or not the attribute includes
133 occurrences happening during speculative execution for both
134 wrong and correct paths. Given that this kind of event informa‐
135 tion is not always available from vendors, this field uses mul‐
136 tiple bits. A value of PFM_EVENT_INFO_SPEC_NA indicates that
137 speculation information is not available. A value of
138 PFM_EVENT_INFO_SPEC_TRUE indicates that the attribute counts
139 during speculative execution. A value of
140 PFM_EVENT_INFO_SPEC_FALSE indicates that the attribute does not
141 count during speculative execution.
142 dfl_val64, dfl_str, dfl_bool, dfl_int
144 This union contains the value of an attribute. For
145 PFM_ATTR_UMASK, the is the unit mask code, for all other types
146 this is the actual value of the attribute.
147 ctrl This field indicates which layer or source controls the attri‐
149 bute. The following sources are defined:
150 PFM_ATTR_CTRL_UNKNOWN
152 The source controlling the attribute is not known.
153 PFM_ATTR_CTRL_PMU
155 The attribute is controlled by the PMU hardware.
156 PFM_ATTR_CTRL_PERF_EVENT
158 The attribute is controlled by the perf_events kernel in‐
159 terface.
160 reserved
162 These fields must be set to zero.
163
165 If successful, the function returns PFM_SUCCESS and attribute informa‐
166 tion in info, otherwise it returns an error code.
167
169 PFMLIB_ERR_NOINIT
170 Library has not been initialized properly.
171 PFMLIB_ERR_INVAL
173 The idx or attr arguments are invalid or info is NULL or size is
174 not zero.
175 PFM_ERR_NOTSUPP
177 The requested os layer has not been detected on the host system.
178
180 Stephane Eranian <eranian@gmail.com>
181 December, 2009 LIBPFM(3)