pfm_find_event, pfm_find_event_byname,
pfm_find_event_bycode, pfm_find_event_bycode_next - search
for events
SYNOPSIS
#include <perfmon/pfmlib.h>
int pfm_find_event(char *str, int *desc);
int pfm_find_event_byname(char *v, int *desc);
int pfm_find_event_bycode(int code, int *desc);
int pfm_find_event_bycode_next(int desc, int code, int *desc);
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 set of functions described here allows to get an event
descriptor given either the name of the event or its code.
Several events can share the same code but have different
names. In the current implementation of the PMU, an event
code is composed of a base code (called event select) and
a umask. The combination of the two is guaranteed unique.
The umask is not an architected feature and as such is not
part of the generic interface of this library.
The pfm_find_event is a general purpose search routine.
Given a string it returns the descriptor of the corre
sponding event. The string can represent an event name or
an event code in ASCII form. Note that the code can be
represented in decimal or hexadecimal.
In contrast pfm_find_event_byname will search for an event
by interpreting the name argument as the name event only.
Similarly, pfm_find_event_bycode will search for an event
given the code argument given as an integer.
Because there can be several events with the same code,
search for other events with the same code. Given an event
e and a code, this function will look for the next event
with the same code. It is not necessary to have called
pfm_find_event_bycode prior to calling this function. This
function is fully threadsafe as it does not maintain any
state between calls.
RETURN
All functions return whether or not the call was success
ful. 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.
PFMLIB_ERR_NOTFOUND
no matching event was found.
AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
Man(1) output converted with
man2html