1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 pfm_get_event_name, pfm_get_full_event_name, pfm_get_event_mask_name,
7 pfm_get_event_code, pfm_get_event_mask_code, pfm_get_event_counters,
8 pfm_get_num_events, pfm_get_max_event_name_len, pfm_get_event_descrip‐
9 tion, pfm_get_event_mask_description - get event information
10
12 #include <perfmon/pfmlib.h>
13 int pfm_get_event_name(unsigned int e, char *name, size_tmaxlen);
15 int pfm_get_full_event_name(pfmlib_event_t *ev, char *name, size_tmaxlen);
16 int pfm_get_event_mask_name(unsigned int e, unsigned int mask, char *name, size_tmaxlen);
17 int pfm_get_event_code(unsigned int e, int *code);
18 int pfm_get_event_mask_code(unsigned int e, unsigned int mask, int *code);
19 int pfm_get_event_code_counter(unsigned int e, unsigned int cnt, int *code);
20 int pfm_get_event_counters(int e, pfmlib_regmask_t counters);
21 int pfm_get_num_events(unsigned int *count);
22 int pfm_get_max_event_name_len(size_t *len);
23 int pfm_get_event_description(unsigned int ev, char **str);
24 int pfm_get_event_mask_description(unsigned int ev, unsigned int mask, char **str);
25
28 The pfm_get_event_name function returns in name the event name given
29 its opaque descriptor in e. The maxlen argument indicates the maximum
30 length of the buffer provided for name. Up to maxlen-1 characters will
31 be returned, not including the termination character. Event names are
32 returned in all upper case.
33 The pfm_get_full_event_name function returns in name the event name
35 given the full event description in ev. The description contains the
36 event code in ev->event and optional unit masks descriptors in
37 ev->unit_masks. The maxlen argument indicates the maximum length of the
38 buffer provided for name. If more than maxlen-1 characters are needed
39 to represent the event, an error is returned. In case unit masks are
40 provided, the final event name string is structured as:
41 event_name:unit_masks1[:unit_masks2]. Event names and unit masks names
42 are returned in all upper case.
43 The pfm_get_event_code function returns the event code in code given
45 its opaque descriptor e.
46 On some PMU models, the code associated with an event is different
48 based on the counter it is programmed into. The
49 pfm_get_event_code_counter function is used to retrieve the event code
50 in code when the event e is programmed into counter cnt. The counter
51 index must correspond to the index of a counting PMC register.
52 Given an opaque event descriptor e, the pfm_get_event_counters function
54 returns counters a bitmask of type pfmlib_regmask_t where each bit set
55 represents a PMU counter which can be used to program this event. The
56 bitmask must be accessed accessor macros defined by the library.
57 It is possible to list all existing events for the detected host PMU
59 using accessor functions as the full table of events is not accessible
60 to the applications. The index of the first event is always zero, then
61 using pfm_get_num_events you get the total number of events. Event
62 descriptors are contiguous therefore a simple loop will allow complete
63 scanning. The typical scan loop is constructed as follows:
64 unsigned int i, count;
66 char name[256];
67 pfm_get_num_events(&count);
68 for(i=0;i < count; i++)
69 {
70 pfm_get_event_name(i, name, 256);
71 printf("%s\n", name);
72 }
73 The pfm_get_num_events function returns in count the total number of
76 events supported by the host PMU.
77 The former pfm_get_first_event has been deprecated. You can simply ini‐
79 tialize your variable to 0 to point to the first event.
80 The former pfm_get_next_event has been deprecated. You need to retrieve
82 the total number of events for the host PMU and then increment your
83 loop variable until you reach that count.
84 The pfm_get_max_event_name_len function returns in len the maximum
86 length in bytes for the name of the events or its unit masks, if any,
87 available on one PMU implementation. The value excludes the string ter‐
88 mination character ('\0').
89 The pfm_get_event_description function returns in str the description
91 string associated with the event specified in ev. The description is
92 returned into a buffer that is allocated to hold the entire description
93 text. It is the responsibility of the caller to free the buffer when it
94 becomes useless by calling the free(3) function.
95 The pfm_get_event_mask_code function must be used to retrieve the
97 actual unit mask value given a event descriptor in e and a unit mask
98 descriptor in mask. The value is returned in code.
99 The pfm_get_event_mask_name function must be used to retrieve the name
101 associated with a unit mask specified in mask for event e. The name is
102 returned in the buffer specified in name. The maximum size of the buf‐
103 fer must be specified in maxlen.
104 The pfm_get_event_mask_description function returns in str the
106 description string associated with the unit mask specified in mask for
107 the event specified in ev. The description is returned into a buffer
108 that is allocated to hold the entire description text. It is the
109 responsibility of the caller to free the buffer when it becomes useless
110 by calling the free(3) function.
111
114 All functions return whether or not the call was successful. A return
115 value of PFMLIB_SUCCESS indicates success, otherwise the value is the
116 error code.
117
119 PFMLIB_ERR_NOINIT the library has not been initialized properly.
120 PFMLIB_ERR_FULL
122 the string buffer provided is too small
123 PFMLIB_ERR_INVAL
125 the event or unit mask descriptor, or the cnt argument is
126 invalid, or a pointer argument is NULL.
127
129 pfm_get_impl_counters(3), free(3)
130
132 Stephane Eranian <eranian@hpl.hp.com>
133 August, 2006 LIBPFM(3)