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.

AUTHOR

Stephane Eranian <[email protected]>