1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 pfm_find_event, pfm_find_full_event, pfm_find_event_bycode,
7 pfm_find_event_bycode_next, pfm_find_event_mask - search for events and
8 unit masks
9
11 #include <perfmon/pfmlib.h>
12 int pfm_find_event(const char *str, unsigned int *desc);
14 int pfm_find_full_event(const char *str, pfmlib_event_t *e);
15 int pfm_find_event_bycode(int code, unsigned int *desc);
16 int pfm_find_event_bycode_next(unsigned int desc1, int code, unsigned int *desc);
17 int pfm_find_event_mask(unsigned int idx, const char *str, unsigned int *mask_idx);
18
22 The PMU counters can be programmed to count the number of occurrences
23 of certain events. The number of events varies from one PMU model to
24 the other. Each event has a name and a code which is used to program
25 the actual PMU register. Some event may need to be further qualified
26 with unit masks.
27 The library does not directly expose the event code, nor unit mask
29 code, to user applications because it is not necessary. Instead appli‐
30 cations use names to query the library for particular information about
31 events. Given an event name, the library returns an opaque descriptor.
32 Each descriptor is unique and has no relationship to the event code.
33 The set of functions described here can be used to get an event
35 descriptor given either the name of the event or its code. Several
36 events may share the same code. An event name is a string structured
37 as: event_name[:unit_mask1[:unit_mask2]].
38 The pfm_find_event() function is a general purpose search routine.
40 Given an event name in str, it returns the descriptor for the corre‐
41 sponding event. If unit masks are provided, they are not taken into
42 account. This function is being deprecated in favor of the
43 pfm_find_full_event() function.
44 The pfm_find_full_event() function is the general purpose search rou‐
46 tine. Given an event name in str, it returns in ev, the full event
47 descriptor that includes the event descriptor in ev->event and the unit
48 mask descriptors in ev->unit_masks. The number of unit masks descrip‐
49 tors returned is indicated in ev->num_masks. Unit masks are specified
50 as a colon separated list of unit mask names, exact values or value
51 combinations. For instance, if event A supports unit masks M1 (0x1)
52 and M2 (0x40), and both unit masks are to be measured, then the follow‐
53 ing values for str are valid: "A:M1:M2", "A:M1:0x40", "A:M2:0x1",
54 "A:0x1:0x40", "A:0x41".
55 The pfm_find_event_bycode() function searches for an event given its
57 code represented as an integer. It returns in desc, the event code.
58 Unit masks are ignored.
59 Because there can be several events with the same code, the library
62 provides the pfm_find_event_bycode_next() function to search for other
63 events with the same code. Given an event desc1 and a code, this func‐
64 tion will look for the next event with the same code. If such an event
65 exists, its descriptor will be stored into desc. It is not necessary
66 to have called the pfm_find_event_bycode() function prior to calling
67 this function. This function is fully threadsafe as it does not main‐
68 tain any state between calls.
69 The pfm_find_event_mask() function is used to find the unit mask
71 descriptor based on its name or numerical value passed in str for the
72 event specified in idx. The numeric value must be an exact match of an
73 existing unit mask value, i.e., all bits must match. Some events do not
74 have unit masks, in which case this function returns an error.
75
77 All functions return whether or not the call was successful. A return
78 value of PFMLIB_SUCCESS indicates success, otherwise the value is the
79 error code.
80
82 PFMLIB_ERR_NOINIT the library has not been initialized properly.
83 PFMLIB_ERR_INVAL
85 the event descriptor is invalid, or the pointer argument is
86 NULL.
87 PFMLIB_ERR_NOTFOUND
89 no matching event or unit mask was found.
90
92 Stephane Eranian <eranian@hpl.hp.com>
93 August, 2006 LIBPFM(3)