NAME
pfm_get_event_name, pfm_get_full_event_name, pfm_get_event_mask_name,
pfm_get_event_code, pfm_get_event_mask_code, pfm_get_event_counters,
pfm_get_num_events, pfm_get_max_event_name_len,
pfm_get_event_description, pfm_get_event_mask_description - get event
information
SYNOPSIS
#include <perfmon/pfmlib.h>
int pfm_get_event_name(unsigned int e, char *name, size_tmaxlen);
int pfm_get_full_event_name(pfmlib_event_t *ev, char *name, size_tmaxlen);
int pfm_get_event_mask_name(unsigned int e, unsigned int mask, char *name, size_tmaxlen);
int pfm_get_event_code(unsigned int e, int *code);
int pfm_get_event_mask_code(unsigned int e, unsigned int mask, int *code);
int pfm_get_event_code_counter(unsigned int e, unsigned int cnt, int *code);
int pfm_get_event_counters(int e, pfmlib_regmask_t counters);
int pfm_get_num_events(unsigned int *count);
int pfm_get_max_event_name_len(size_t *len);
int pfm_get_event_description(unsigned int ev, char **str);
int pfm_get_event_mask_description(unsigned int ev, unsigned int mask, char **str);
DESCRIPTION
The pfm_get_event_name function returns in name the event name given
its opaque descriptor in e. The maxlen argument indicates the maximum
length of the buffer provided for name. Up to maxlen-1 characters will
be returned, not including the termination character. Event names are
returned in all upper case.
The pfm_get_full_event_name function returns in name the event name
given the full event description in ev. The description contains the
event code in ev->event and optional unit masks descriptors in
ev->unit_masks. The maxlen argument indicates the maximum length of the
buffer provided for name. If more than maxlen-1 characters are needed
to represent the event, an error is returned. In case unit masks are
provided, the final event name string is structured as:
event_name:unit_masks1[:unit_masks2]. Event names and unit masks names
are returned in all upper case.
The pfm_get_event_code function returns the event code in code given
its opaque descriptor e.
On some PMU models, the code associated with an event is different
based on the counter it is programmed into. The
pfm_get_event_code_counter function is used to retrieve the event code
in code when the event e is programmed into counter cnt. The counter
index cnt must correspond to of a counting PMD register.
Given an opaque event descriptor e, the pfm_get_event_counters function
returns in counters a bitmask of type pfmlib_regmask_t where each bit
set represents a PMU config register which can be used to program this
event. The bitmask must be accessed using accessor macros defined by
the library.
It is possible to list all existing events for the detected host PMU
using accessor functions as the full table of events is not accessible
to the applications. The index of the first event is always zero, then
using pfm_get_num_events you get the total number of events. Event
descriptors are contiguous therefore a simple loop will allow complete
scanning. The typical scan loop is constructed as follows:
unsigned int i, count;
char name[256];
pfm_get_num_events(&count);
for(i=0;i < count; i++)
{
pfm_get_event_name(i, name, 256);
printf("%s\n", name);
}
The pfm_get_num_events function returns in count the total number of
events supported by the host PMU.
The former pfm_get_first_event has been deprecated. You can simply
initialize your variable to 0 to point to the first event.
The former pfm_get_next_event has been deprecated. You need to retrieve
the total number of events for the host PMU and then increment your
loop variable until you reach that count.
The pfm_get_max_event_name_len function returns in len the maximum
length in bytes for the name of the events or its unit masks, if any,
available on one PMU implementation. The value excludes the string
termination character (’\0’).
The pfm_get_event_description function returns in str the description
string associated with the event specified in ev. The description is
returned into a buffer that is allocated to hold the entire description
text. It is the responsibility of the caller to free the buffer when it
becomes useless by calling the free(3) function.
The pfm_get_event_mask_code function must be used to retrieve the
actual unit mask value given a event descriptor in e and a unit mask
descriptor in mask. The value is returned in code.
The pfm_get_event_mask_name function must be used to retrieve the name
associated with a unit mask specified in mask for event e. The name is
returned in the buffer specified in name. The maximum size of the
buffer must be specified in maxlen.
The pfm_get_event_mask_description function returns in str the
description string associated with the unit mask specified in mask for
the event specified in ev. The description is returned into a buffer
that is allocated to hold the entire description text. It is the
responsibility of the caller to free the buffer when it becomes useless
by calling the free(3) function.
RETURN
All functions return whether or not the call was successful. A return
value of PFMLIB_SUCCESS indicates success, otherwise the value is the
error code.
ERRORS
PFMLIB_ERR_NOINIT the library has not been initialized properly.
PFMLIB_ERR_FULL
the string buffer provided is too small
PFMLIB_ERR_INVAL
the event or unit mask descriptor, or the cnt argument is
invalid, or a pointer argument is NULL.
SEE ALSO
pfm_get_impl_counters(3), free(3)
AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
August, 2006 LIBPFM(3)