1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
7 #include <perfmon/pfmlib.h>
8 int pfm_find_event(const char *str);
10
13 This function is used to convert an event string passed in str into an
14 opaque event identifier, i.e., the return value.
15 Events are first manipulated a strings which contain the event name,
17 sub-event names and optional filters and modifiers. This function ana‐
18 lyzes the string and try to find the matching event.
19 The event string is a structured string and it is composed as follows:
21 [pmu_name::]event_name[:unit_mask][:modifier|:modifier=val]
23 The various components are separated by : or ::, they are defined as
25 follows:
26 pmu_name
29 This is an optional prefix to designate a specific PMU model.
30 With the prefix the event which matches the event_name is used.
31 In case multiple PMU models are activated, there may be conflict
32 with identical event names to mean the same or different things.
33 In that case, it is necessary to fully specify the event with a
34 pmu_name. That string corresponds to what is returned by
35 pfm_get_pmu_name().
36 event_name
38 This is the event name and is required. The library is not case
39 sensitive on event string. The event name must match completely
40 the actual event name; it cannot be a substring.
41 unit_mask
43 The optional unit mask which can be considered like a sub-event
44 of the major event. If a event has unit masks, and there is no
45 default, then at least one unit mask must be passed in the
46 string. Multiple unit masks may be specified for a single event.
47 modifier
49 A modifier is an optional filter which is provided by the hard‐
50 ware register hosting the event or by the underlying kernel in‐
51 frastructure. Typical modifiers include privilege level fil‐
52 ters. Some modifiers are simple boolean, in which case just
53 passing their names is equivalent to setting their value to
54 true. Other modifiers need a specific value, in which case it is
55 provided after the equal sign. No space is tolerate around the
56 equal sign. The list of modifiers depends on the host PMU and
57 underlying kernel API. They are documented in PMU-specific docu‐
58 mentation. Multiple modifiers may be passed. There is not order
59 between unit masks and modifiers.
60 The library uses the generic term attribute to designate both unit
62 masks and modifiers.
63 Here are a few examples of event strings:
65 amd64::RETIRED_INSTRUCTIONS:u
67 Event RETIRED_INSTRUCTION on AMD64 processor, measure at user
68 privilege level only
69 RS_UOPS_DISPATCHED:c=1:i:u
71 Event RS_UOPS_DISPATCHED measured at user privilege level only,
72 and with counter-mask set to 1
73 For the purpose of this function, only the pmu_name and event_name are
75 considered, everything else is parsed, thus must be valid, but is
76 ignored.
77 The function searches only for one event per call. As a convenience,
79 the function will identify the event up to the first comma. In other
80 words, if str is equal to "EVENTA,EVENTB", then the function will only
81 look at EVENTA and will not return an error because of invalid event
82 string. This is handy when parsing constant event strings containing
83 multiple, comma-separated, events.
84
87 The function returns the opaque event identifier that corresponds that
88 the event string. In case of error, a negative error code is returned
89 instead.
90
92 PFMLIB_ERR_NOINIT
93 The library has not been initialized properly.
94 PFMLIB_ERR_INVAL
96 The event string is NULL.
97 PFMLIB_ERR_NOMEM
99 The library ran out of memory.
100 PFMLIB_ERR_NOTFOUND
102 The event was not found
103 PFMLIB_ERR_ATTR
105 Invalid event attribute
106 PFMLIB_ERR_ATTR_VAL
108 Invalid event attribute value
109 PFMLIB_ERR_TOOMANY
111 Too many event attributes passed
112
114 Stephane Eranian <eranian@gmail.com>
115 September, 2009 LIBPFM(3)