1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 pfm_get_perf_event_encoding - encode event for perf_event API
7
9 #include <perfmon/pfmlib_perf_event.h>
10 int pfm_get_perf_event_encoding(const char *str, int dfl_plm, struct perf_event_attr *attr, char **fstr, int *idx);
12
15 This function can be used in conjunction with the perf_events Linux
16 kernel API which provides access to hardware performance counters, ker‐
17 nel software counters and tracepoints. The function takes an event
18 string in str and a default privilege level mask in dfl_plm and fills
19 out the relevant parts of the perf_events specific data structure in
20 attr.
21 This function is deprecated. It is superseded by
23 pfm_get_os_event_encoding() with the OS argument set to either
24 PFM_OS_PERF_EVENT or PFM_OS_PERF_EVENT_EXT. Using this function pro‐
25 vides extended support for perf_events. Certain perf_event configura‐
26 tion option are only available through this new interface.
27 The following examples illustrates the transition:
29 struct perf_event_attr attr;
31 int i, count = 0;
32 uint64_t *codes;
33 memset(&attr, 0, sizeof(attr));
35 ret = pfm_get_perf_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, &attrs, NULL, NULL);
37 if (ret != PFM_SUCCESS)
38 err(1", cannot get encoding %s", pfm_strerror(ret));
39 is equivalent to:
42 #include <perfmon/pfmlib_perf_event.h>
44 struct perf_event_attr attr;
45 pfm_perf_encode_arg_t arg;
46 memset(&arg, 0, sizeof(arg));
48 arg.size = sizeof(arg);
49 arg.attr = &attr;
50 ret = pfm_get_os_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, PFM_OS_PERF, &arg);
52 if (ret != PFM_SUCCESS)
53 err(1", cannot get encoding %s", pfm_strerror(ret));
54 The dfl_plm cannot be zero, though it may not necessarily be used by the event.
58 Depending on the event, combination of the following privilege levels may be used:
59 PFM_PLM3
61 Measure at privilege level 3. This usually corresponds to user level. On X86, it corresponds
62 to privilege levels 3, 2, 1. Check the PMU specific man page to verify if this level
63 is supported by your PMU model.
64 PFM_PLM2
66 Measure at privilege level 2. Check the PMU specific man page to verify if this level
67 is supported by your PMU model.
68 PFM_PLM1
70 Measure at privilege level 1. Check the PMU specific man page to verify if this level
71 is supported by your PMU model.
72 PFM_PLM0
74 Measure at privilege level 0. This usually corresponds to kernel level. Check the PMU
75 specific man page to verify if this level is supported by your PMU model.
76 PFM_PLMH
78 Measure at hypervisor privilege level. This is used in conjunction with hardware virtualization.
79 Check the PMU specific man page to verify if this level is supported by your PMU model.
80 If fstr is not NULL, the function will make it point to the fully qualified event string,
82 i.e., a string with the event name, all unit masks set, and the value of all modifiers.
83 The library will allocate memory to store the event string but it is the responsibility of the
84 caller to eventually free that string using free().
85 If idx is not NULL, it returns the corresponding unique event identifier.
87 Only select fields are modified by the function, the others are untouched.
89 The following fields in attr are modified:
90 type The type of the event
92 config The encoding of the event
94 exclude_user
96 Whether or not user level execution should be excluded from monitoring. The definition
97 of user is PMU model specific.
98 exclude_kernel
100 Whether or not kernel level execution should be excluded from monitoring. The definition
101 of kernel is PMU model specific.
102 exclude_hv
104 Whether or not hypervisor level execution should be excluded from monitoring. The definition
105 of hypervisor is PMU model specific.
106 By default, if no privilege level modifier is specified in the event string, the library clears
108 exclude_user, exclude_kernel and exclude_hv, resulting in the event being
109 measured at all levels subject to hardware support.
110 The function is able to work on only one event at a time. For convenience, it accepts
112 event strings with commas. In that case, it will translate the first event up to the
113 first comma. This is handy in case tools gets passed events as a comma-separated list.
114
117 The function returns in attr the perf_event encoding which corresponds
118 to the event string. If idx is not NULL, then it will contain the
119 unique event identifier upon successful return. The value PFM_SUCCESS
120 is returned if successful, otherwise a negative error code is returned.
121
124 PFM_ERR_TOOSMALL
125 The code argument is too small for the encoding.
126 PFM_ERR_INVAL
128 The attr argument is NULL.
129 PFM_ERR_NOMEM
131 Not enough memory.
132 PFM_ERR_NOTFOUND
134 Event not found.
135 PFM_ERR_ATTR
137 Invalid event attribute (unit mask or modifier)
138 PFM_ERR_ATTR_VAL
140 Invalid modifier value.
141 PFM_ERR_ATTR_SET
143 attribute already set, cannot be changed.
144 PFM_ERR_ATTR_UMASK
146 Missing unit mask.
147 PFM_ERR_ATTR_FEATCOMB
149 Unit masks or features cannot be combined into a single event.
150
152 Stephane Eranian <eranian@gmail.com>
153
155 pfm_get_os_event_encoding(3)
156 September, 2009 LIBPFM(3)