|
Packit |
577717 |
.TH LIBPFM 3 "August, 2006" "" "Linux Programmer's Manual"
|
|
Packit |
577717 |
.SH NAME
|
|
Packit |
577717 |
pfm_find_event, pfm_find_full_event, pfm_find_event_bycode,
|
|
Packit |
577717 |
pfm_find_event_bycode_next, pfm_find_event_mask \- search for events and unit
|
|
Packit |
577717 |
masks
|
|
Packit |
577717 |
.SH SYNOPSIS
|
|
Packit |
577717 |
.nf
|
|
Packit |
577717 |
.B #include <perfmon/pfmlib.h>
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.BI "int pfm_find_event(const char *"str ", unsigned int *"desc ");"
|
|
Packit |
577717 |
.BI "int pfm_find_full_event(const char *"str ", pfmlib_event_t *"e ");"
|
|
Packit |
577717 |
.BI "int pfm_find_event_bycode(int "code ", unsigned int *"desc ");"
|
|
Packit |
577717 |
.BI "int pfm_find_event_bycode_next(unsigned int "desc1 ", int "code ", unsigned int *"desc ");"
|
|
Packit |
577717 |
.BI "int pfm_find_event_mask(unsigned int "idx ", const char *"str ", unsigned int *"mask_idx ");"
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
.SH DESCRIPTION
|
|
Packit |
577717 |
The PMU counters can be programmed to count the number of occurrences
|
|
Packit |
577717 |
of certain events. The number of events varies from one PMU model
|
|
Packit |
577717 |
to the other. Each event has a name and a code which is used to program
|
|
Packit |
577717 |
the actual PMU register. Some event may need to be further qualified
|
|
Packit |
577717 |
with unit masks.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The library does not directly expose the event code, nor unit mask code,
|
|
Packit |
577717 |
to user applications because it is not necessary. Instead applications
|
|
Packit |
577717 |
use names to query the library for particular information about events.
|
|
Packit |
577717 |
Given an event name, the library returns an opaque descriptor.
|
|
Packit |
577717 |
Each descriptor is unique and has no relationship to the event code.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The set of functions described here can be used to get an event descriptor
|
|
Packit |
577717 |
given either the name of the event or its code. Several events may
|
|
Packit |
577717 |
share the same code. An event name is a string structured as: event_name[:unit_mask1[:unit_mask2]].
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_find_event()\fR function is a general purpose search routine.
|
|
Packit |
577717 |
Given an event name in \fBstr\fR, it returns the descriptor for the
|
|
Packit |
577717 |
corresponding event. If unit masks are provided, they are not taken
|
|
Packit |
577717 |
into account. This function is being \fBdeprecated\fR in favor of
|
|
Packit |
577717 |
the \fBpfm_find_full_event()\fR function.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_find_full_event()\fR function is the general purpose search routine.
|
|
Packit |
577717 |
Given an event name in \fBstr\fR, it returns in \fBev\fR, the full event descriptor that
|
|
Packit |
577717 |
includes the event descriptor in \fBev->event\fR and the unit mask descriptors
|
|
Packit |
577717 |
in \fBev->unit_masks\fR. The number of unit masks descriptors returned is
|
|
Packit |
577717 |
indicated in \fBev->num_masks\fR. Unit masks are specified as a colon
|
|
Packit |
577717 |
separated list of unit mask names, exact values or value combinations.
|
|
Packit |
577717 |
For instance, if event A supports unit masks M1 (0x1) and M2 (0x40), and
|
|
Packit |
577717 |
both unit masks are to be measured, then the following values for
|
|
Packit |
577717 |
\fBstr\fR are valid: "A:M1:M2", "A:M1:0x40", "A:M2:0x1", "A:0x1:0x40", "A:0x41".
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_find_event_bycode()\fR function searches for an event given
|
|
Packit |
577717 |
its \fBcode\fR represented as an integer. It returns in \fBdesc\fR,
|
|
Packit |
577717 |
the event code. Unit masks are ignored.
|
|
Packit |
577717 |
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
Because there can be several events with the same code, the library
|
|
Packit |
577717 |
provides the \fBpfm_find_event_bycode_next()\fR function to search for other
|
|
Packit |
577717 |
events with the same code. Given an event \fBdesc1\fR and a \fBcode\fR,
|
|
Packit |
577717 |
this function will look for the next event with the same code. If
|
|
Packit |
577717 |
such an event exists, its descriptor will be stored into \fBdesc\fR.
|
|
Packit |
577717 |
It is not necessary to have called the \fBpfm_find_event_bycode()\fR function prior
|
|
Packit |
577717 |
to calling this function. This function is fully threadsafe as it does
|
|
Packit |
577717 |
not maintain any state between calls.
|
|
Packit |
577717 |
.sp
|
|
Packit |
577717 |
The \fBpfm_find_event_mask()\fR function is used to find the unit mask descriptor
|
|
Packit |
577717 |
based on its name or numerical value passed in \fBstr\fR for the event specified
|
|
Packit |
577717 |
in \fBidx\fR. The numeric value must be an exact match of an existing unit mask value,
|
|
Packit |
577717 |
i.e., all bits must match. Some events do not have unit masks, in which case this function
|
|
Packit |
577717 |
returns an error.
|
|
Packit |
577717 |
.SH RETURN
|
|
Packit |
577717 |
All functions return whether or not the call was successful.
|
|
Packit |
577717 |
A return value of \fBPFMLIB_SUCCESS\fR indicates success,
|
|
Packit |
577717 |
otherwise the value is the error code.
|
|
Packit |
577717 |
.SH ERRORS
|
|
Packit |
577717 |
.B PFMLIB_ERR_NOINIT
|
|
Packit |
577717 |
the library has not been initialized properly.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ERR_INVAL
|
|
Packit |
577717 |
the event descriptor is invalid, or the pointer argument is NULL.
|
|
Packit |
577717 |
.TP
|
|
Packit |
577717 |
.B PFMLIB_ERR_NOTFOUND
|
|
Packit |
577717 |
no matching event or unit mask was found.
|
|
Packit |
577717 |
.SH AUTHOR
|
|
Packit |
577717 |
Stephane Eranian <eranian@hpl.hp.com>
|
|
Packit |
577717 |
.PP
|