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_t maxlen);
15 int pfm_get_full_event_name(pfmlib_event_t *ev, char *name, size_t maxlen);
16 int pfm_get_event_mask_name(unsigned int e, unsigned int mask, char *name, size_t maxlen);
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 are
31 stored in the buffer. The buffer size must be large enough to store
32 the event name, otherwise an error is returned. This behavior is
33 required to avoid returning partial names with no way for the caller to
34 verify this is not the full name, except by failing other calls. The
35 buffer can be appropriately sized using the
36 pfm_get_max_event_name_len() function. The returned name is a null ter‐
37 minated string with all upper-case characters and no spaces.
38 The pfm_get_full_event_name() function returns in name the event name
40 given the full event description in ev. The description contains the
41 event code in ev->event and optional unit masks descriptors in
42 ev->unit_masks. The maxlen argument indicates the maximum length of the
43 buffer provided for name. If more than maxlen-1 characters are needed
44 to represent the event, an error is returned. Applications may use the
45 pfm_get_max_event_name_len() function to size the buffer correctly. In
46 case unit masks are provided, the final event name string is structured
47 as: event_name:unit_masks1[:unit_masks2]. Event names and unit masks
48 names are returned in all upper case.
49 The pfm_get_event_code() function returns the event code in code given
51 its opaque descriptor e.
52 On some PMU models, the code associated with an event is different
54 based on the counter it is programmed into. The
55 pfm_get_event_code_counter() function is used to retrieve the event
56 code in code when the event e is programmed into counter cnt. The
57 counter index cnt must correspond to of a counting PMD register.
58 Given an opaque event descriptor e, the pfm_get_event_counters() func‐
60 tion returns in counters a bitmask of type pfmlib_regmask_t where each
61 bit set represents a PMU config register which can be used to program
62 this event. The bitmask must be accessed using accessor macros defined
63 by the library.
64 The pfm_get_num_events() function returns in count the total number of
66 events available for the PMU model. On some PMU models, however, not
67 all events in the table may be useable due to processor stepping
68 changes. However, The library guarantees that no more that count events
69 are available.
70 It is possible to list all existing events for the detected host PMU
72 using accessor functions as the full table of events is not accessible
73 to the applications. The index of the first event is always zero, then
74 using the pfm_get_num_events() function you get the total number of
75 events. On some PMU models, e.g., AMD64, not all events are necessar‐
76 ily supported by the host PMU, therefore the count returned by this
77 calls may not be the actual number of available events. Event descrip‐
78 tors are contiguous therefore a simple loop will allow complete scan‐
79 ning. The typical scan loop is constructed as follows:
80 unsigned int i, count;
82 char name[256];
83 int ret;
84 pfm_get_num_events(&count);
85 for(i=0;i < count; i++)
86 {
87 ret = pfm_get_event_name(i, name, 256);
88 if (ret != PFMLIB_SUCCESS)
89 continue;
90 printf("%s\n", name);
91 }
92 The pfm_get_max_event_name_len() function returns in len the maximum
95 length in bytes for the name of the events or its unit masks, if any,
96 available on one PMU implementation. The value excludes the string ter‐
97 mination character ('\0').
98 The pfm_get_event_description() function returns in str the description
100 string associated with the event specified in ev. The description is
101 returned into a buffer that is allocated to hold the entire description
102 text. It is the responsibility of the caller to free the buffer when it
103 becomes useless by calling the free(3) function.
104 The pfm_get_event_mask_code() function must be used to retrieve the
106 actual unit mask value given a event descriptor in e and a unit mask
107 descriptor in mask. The value is returned in code.
108 The pfm_get_event_mask_name() function must be used to retrieve the
110 name associated with a unit mask specified in mask for event e. The
111 name is returned in the buffer specified in name. The maximum size of
112 the buffer must be specified in maxlen.
113 The pfm_get_event_mask_description() function returns in str the
115 description string associated with the unit mask specified in mask for
116 the event specified in ev. The description is returned into a buffer
117 that is allocated to hold the entire description text. It is the
118 responsibility of the caller to free the buffer when it becomes useless
119 by calling the free(3) function.
120
123 All functions return whether or not the call was successful. A return
124 value of PFMLIB_SUCCESS indicates success, otherwise the value is the
125 error code.
126
128 PFMLIB_ERR_NOINIT the library has not been initialized properly.
129 PFMLIB_ERR_FULL
131 the string buffer provided is too small
132 PFMLIB_ERR_INVAL
134 the event or unit mask descriptor, or the cnt argument is
135 invalid, or a pointer argument is NULL.
136
138 pfm_get_impl_counters(3), pfm_get_max_event_name_len(3), free(3)
139
141 Stephane Eranian <eranian@gmail.com>
142 August, 2006 LIBPFM(3)