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