1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 pfm_get_os_event_encoding - get event encoding for a specific operating
7 system
8
10 #include <perfmon/pfmlib.h>
11 int pfm_get_os_event_encoding(const char *str, int dfl_plm, pfm_os_t os, void *arg);
13
16 This is the key function to retrieve the encoding of an event for a
17 specific operating system interface. The event string passed in str is
18 parsed and encoded for the operating system specified by os. Only one
19 event per call can be encoded. As such, str can contain only one sym‐
20 bolic event name. The event is encoded to monitor at the privilege lev‐
21 els specified by the dfl_plm mask, if supported, otherwise this parame‐
22 ter is ignored. The operating system specific input and output argu‐
23 ments are passed in arg.
24 The event string, str, may contains sub-event masks (umask) and any
26 other supported modifiers. Only one event is parsed from the string.
27 For convenience, it is possible to pass a comma-separated list of
28 events in str but only the first event is encoded.
29 The following values are supported for os:
31 PFM_OS_NONE
33 This value causes the event to be encoded purely as specified by
34 the PMU hardware. The arg argument must be a pointer to a
35 pfm_raw_pmu_encode_arg_t structure which is defined as follows:
36 typedef struct {
38 uint64_t *codes;
39 char **fstr;
40 size_t size;
41 int count;
42 int idx;
43 } pfm_pmu_encode_arg_t;
44 The fields are defined as follows:
46 codes A pointer to an array of 64-bit values. On input, if
48 codes is NULL, then the library allocates whatever is
49 necessary to store the encoding of the event. If codes is
50 not NULL on input, then count must reflect its actual
51 number of elements. If count is big enough, the library
52 stores the encoding at the address provided. Otherwise,
53 an error is returned.
54 count On input, the field contains the maximum number of ele‐
56 ments in the array codes. Upon return, it contains the
57 number of actual entries in codes. If codes is NULL, then
58 count must be zero.
59 fstr If the caller is interested in retrieving the fully qual‐
61 ified event string where all used unit masks and all mod‐
62 ifiers are spelled out, this field must be set to a non-
63 null address of a pointer to a string (char **). Upon
64 return, if fstr was not NULL, then the string pointer
65 passed on entry points to the event string. The string is
66 dynamically allocated and must eventually be freed by the
67 caller. If fstr was NULL on entry, then nothing is re‐
68 turned in this field. The typical calling sequence looks
69 as follows:
70 char *fstr = NULL
71 pfm_pmu_encode_arg_t arg;
72 arg.fstr = &fstr;
73 ret = pfm_get_os_event_encoding("event",
74 PFM_PLM0|PFM_PLM3,
75 PFM_OS_NONE,
76 &e);
77 if (ret == PFM_SUCCESS) {
78 printf("fstr=%s\n", fstr);
79 free(fstr);
80 }
81 size This field contains the size of the struct passed. This
83 field is used to provide for extensibility of the struct
84 without compromising backward compatibility. The value
85 should be set to sizeof(pfm_pmu_encode_arg_t). If in‐
86 stead, a value of 0 is specified, the library assumes the
87 struct passed is identical to the first ABI version which
88 size is PFM_RAW_ENCODE_ABI0. Thus, if fields were added
89 after the first ABI, they will not be set by the library.
90 The library does check that bytes beyond what is imple‐
91 mented are zeroes.
92 idx Upon return, this field contains the opaque unique iden‐
94 tifier for the event described in str. This index can be
95 used to retrieve information about the event using
96 pfm_get_event_info(), for instance.
97 PFM_OS_PERF_EVENT, PFM_OS_PERF_EVENT_EXT
99 This value causes the event to be encoded for the perf_event
100 Linux kernel interface (available since 2.6.31). The arg must
101 be a pointer to a pfm_perf_encode_arg_t structure. The
102 PFM_OS_PERF_EVENT layer provides the modifiers exported by the
103 underlying PMU hardware, some of which may actually be overrid‐
104 den by the perf_event interface, such as the monitoring privi‐
105 lege levels. The PFM_OS_PERF_EVENT_EXT extends PFM_OS_EVENT to
106 add modifiers controlled only by the perf_event interface, such
107 as sampling period (period), frequency (freq) and exclusive re‐
108 source access (excl).
109 typedef struct {
111 struct perf_event_attr *attr;
112 char **fstr;
113 size_t size;
114 int idx;
115 int cpu;
116 int flags;
117 } pfm_perf_encode_arg_t;
118 The fields are defined as follows:
119 attr A pointer to a struct perf_event_attr as defined in
121 perf_event.h. This field cannot be NULL on entry. The
122 struct is not completely overwritten by the call. The li‐
123 brary only modifies the fields it knows about, thereby
124 allowing perf_event ABI mismatch between caller and li‐
125 brary.
126 fstr Same behavior as is described for PFM_OS_NONE above.
128 size This field contains the size of the struct passed. This
130 field is used to provide for extensibility of the struct
131 without compromising backward compatibility. The value
132 should be set to sizeof(pfm_perf_encode_arg_t). If in‐
133 stead, a value of 0 is specified, the library assumes the
134 struct passed is identical to the first ABI version which
135 size is PFM_PERF_ENCODE_ABI0. Thus, if fields were added
136 after the first ABI, they will not be set by the library.
137 The library does check that bytes beyond what is imple‐
138 mented are zeroes.
139 idx Upon return, this field contains the opaque unique iden‐
141 tifier for the event described in str. This index can be
142 used to retrieve information about the event using
143 pfm_get_event_info(), for instance.
144 cpu Not used yet.
146 flags Not used yet.
148 Here is a example of how this function could be used with PFM_OS_NONE:
150 #include <inttypes.h>
151 #include <err.h>
152 #include <perfmon/pfmlib.h>
153 int main(int argc, char **argv)
154 {
155 pfm_raw_pmu_encode_t raw;
156 int ret;
157 ret = pfm_initialize();
159 if (ret != PFMLIB_SUCCESS)
160 errx(1, "cannot initialize library %s", pfm_strerror(ret));
161 memset(&raw, 0, sizeof(raw));
163 ret = pfm_get_os_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, PFM_OS_NONE, &raw);
165 if (ret != PFM_SUCCESS)
166 err(1", cannot get encoding %s", pfm_strerror(ret));
167 for(i=0; i < raw.count; i++)
169 printf("count[%d]=0x%"PRIx64"\n", i, raw.codes[i]);
170 free(raw.codes);
172 return 0;
173 }
174
176 The function returns in arg the encoding of the event for the os passed
177 in os. The content of arg depends on the os argument. Upon success,
178 PFM_SUCCESS is returned otherwise a specific error code is returned.
179
181 PFM_ERR_TOOSMALL
182 The code argument is too small for the encoding.
183 PFM_ERR_INVAL
185 The code or count argument is NULL or the str contains more than
186 one symbolic event.
187 PFM_ERR_NOMEM
189 Not enough memory.
190 PFM_ERR_NOTFOUND
192 Event not found.
193 PFM_ERR_ATTR
195 Invalid event attribute (unit mask or modifier)
196 PFM_ERR_ATTR_VAL
198 Invalid modifier value.
199 PFM_ERR_ATTR_SET
201 attribute already set, cannot be changed.
202 PFM_ERR_ATTR_UMASK
204 Missing unit mask.
205 PFM_ERR_ATTR_FEATCOMB
207 Unit masks or features cannot be combined into a single event.
208
210 Stephane Eranian <eranian@gmail.com>
211 January, 2011 LIBPFM(3)