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
21 The PMU counters can be programmed to count the number of occurrences
22 of certain events. The number of events varies from one PMU model to
23 the other. Each event has a name and a code which is used to program
24 the actual PMU register. Some event may need to be further qualified
25 with unit masks.
26 The library does not directly expose the event code, nor unit mask
28 code, to user applications because it is not necessary. Instead appli‐
29 cations use names to query the library for particular information about
30 events. Given an event name, the library returns an opaque descriptor.
31 Each descriptor is unique and has no relationship to the event code.
32 The set of functions described here can be used to get an event
34 descriptor given either the name of the event or its code. Several
35 events may share the same code. An event name is a string structured
36 as: event_name[:unit_mask1[:unit_mask2]].
37 The pfm_find_event function is a general purpose search routine. Given
39 an event name in str, it returns the descriptor for the corresponding
40 event. If unit masks are provided, they are not taken into account.
41 This function is being deprecated in favor of pfm_find_full_event_name.
42 The pfm_find_full_event function is a general purpose search routine.
44 Given an event name, it returns in ev, the full event descriptor that
45 includes the event descriptor in ev->event and the unit mask descrip‐
46 tors in ev->unit_masks. The number of unit masks descriptors returned
47 is indicated in ev->num_masks. This function is the preferred search
48 function.
49 The pfm_find_event_bycode searches for an event given its code repre‐
52 sented as an integer. It returns in desc, the event code. Unit masks
53 are ignored.
54 Because there can be several events with the same code, the library
57 provides the pfm_find_event_bycode_next to search for other events with
58 the same code. Given an event desc1 and a code, this function will look
59 for the next event with the same code. If such an event exists, its
60 descriptor will be stored into desc. It is not necessary to have
61 called pfm_find_event_bycode prior to calling this function. This func‐
62 tion is fully threadsafe as it does not maintain any state between
63 calls.
64 The pfm_find_event_mask function is used to find the unit mask descrip‐
66 tor based on its name passed in str for the event specified in idx.
67 Some events do not have unit masks, in which case this function returns
68 an error.
69
71 All functions return whether or not the call was successful. A return
72 value of PFMLIB_SUCCESS indicates success, otherwise the value is the
73 error code.
74
76 PFMLIB_ERR_NOINIT the library has not been initialized properly.
77 PFMLIB_ERR_INVAL
79 the event descriptor is invalid, or the pointer argument is
80 NULL.
81 PFMLIB_ERR_NOTFOUND
83 no matching event or unit mask was found.
84
86 Stephane Eranian <eranian@hpl.hp.com>
87 August, 2006 LIBPFM(3)