pfm_get_event_name, pfm_get_event_code,
pfm_get_event_counters, pfm_get_first_event,
pfm_get_next_event - get event information
SYNOPSIS
#include <perfmon/pfmlib.h>
int pfm_get_event_name(int e, char **name);
int pfm_get_event_code(int e, int *code);
int pfm_get_event_counters(int e, unsigned long counters[4]);
int pfm_get_first_event(void);
int pfm_get_next_event(int e);
DESCRIPTION
The PMU counters can be programmed to measure the number
of occurrences of certain events. The number of events
varies from one implementation to the other. Each event
has a name and a code which is used to program the actual
PMU register. Not all event can necessarily be programmed
on any of the available counters due to hardware con
straints.
The library does not directly expose the event code to
user applications because it is not necessary. Instead
applications used names to query the library for particu
lar information about events. Given a name, the library
returns an opaque descriptor to the applications. Each
descriptor is unique and has no relationship to the event
code. All functions requires the library to be properly
initialized.
The pfm_get_event_name function returns in name the event
name given its opaque descriptor e. The string represent
ing the name must be considered as read only.
The pfm_get_event_code function returns the event code in
code given its opaque descriptor e.
Given an opaque event descriptor e, the
pfm_get_event_counters function returns a bitmask in the
counters array where each bit set represents a PMU counter
which can be used to program this event. A PMU counter is
defined as a matching pair of PMC and PMD, such as
PMC4/PMD4.
It is possible to list all existing events for the
detected host PMU using access functions as the full table
of events is not accessible to the applications. The
pfm_get_first_event returns the opaque descriptor for the
first event, then pfm_get_next_event is used to go to the
next event given a descriptor e. After the last event,
this function will return -1. The typical scan loop is
char **name;
int i;
i = pfm_get_first_event();
for(;i != -1; i = pfm_get_next_event(i))
{
pfm_get_event_name(i, &name);
printf("%s\n", name);
}
RETURN
The pfm_get_first_event returns the opaque descriptor of
the first event. The pfm_get_next_event function return
the descriptor for the next event. A value of -1 is
returned if the last event is passed as argument or if an
invalid event descriptor is given.
All other 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_INVAL
the event descriptor is invalid, or the pointer
argument is NULL.
AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
Man(1) output converted with
man2html