.TH LIBPFM 3  "September, 2009" "" "Linux Programmer's Manual"
.SH NAME pfm_find_event \- search for an event masks
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.sp
.BI "int pfm_find_event(const char *"str ");"
.sp
.SH DESCRIPTION
This function is used to convert an event string passed in \fBstr\fR into an opaque
event identifier, i.e., the return value.

Events are first manipulated a strings which contain the event name, sub-event
names and optional filters and modifiers. This function analyzes the string
and try to find the matching event.

The event string is a structured string and it is composed as follows:
.TP
.B [pmu_name::]event_name[:unit_mask][:modifier|:modifier=val]
.PP

The various components are separated by \fB:\fR or \fB::\fR, they
are defined as follows:

.TP
.B pmu_name
This is an optional prefix to designate a specific PMU model. With the
prefix the event which matches the event_name is used. In case multiple
PMU models are activated, there may be conflict with identical event
names to mean the same or different things. In that case, it is necessary
to fully specify the event with a pmu_name. That string corresponds to
what is returned by \fBpfm_get_pmu_name()\fR.
.TP
.B event_name
This is the event name and is required. The library is not case sensitive
on event string. The event name must match \fBcompletely\fR the actual
event name; it cannot be a substring.
.TP
.B unit_mask
The optional unit mask which can be considered like a sub-event of the
major event. If a event has unit masks, and there is no default, then
at least one unit mask must be passed in the string. Multiple unit
masks may be specified for a single event.
.TP
.B modifier
A modifier is an optional filter which is provided by the hardware
register hosting the event or by the underlying kernel infrastructure.
Typical modifiers include privilege level filters. Some modifiers
are simple boolean, in which case just passing their names is equivalent
to setting their value to \fBtrue\fR. Other modifiers need a specific
value, in which case it is provided after the equal sign. No space is
tolerate around the equal sign. The list of modifiers depends on the
host PMU and underlying kernel API. They are documented in PMU-specific
documentation. Multiple modifiers may be passed. There is not order
between unit masks and modifiers.
.PP

The library uses the generic term \fBattribute\fR to designate both
unit masks and modifiers.

Here are a few examples of event strings:
.TP
.B amd64::RETIRED_INSTRUCTIONS:u
Event RETIRED_INSTRUCTION on AMD64 processor, measure at user privilege level only
.TP
.B RS_UOPS_DISPATCHED:c=1:i:u
Event RS_UOPS_DISPATCHED measured at user privilege level only, and with counter-mask set to 1
.PP
For the purpose of this function, only the pmu_name and event_name
are considered, everything else is parsed, thus must be valid, but is ignored.

The function searches only for one event per call. As a convenience, the function will
identify the event up to the first comma. In other words, if \fBstr\fR is equal to
"EVENTA,EVENTB", then the function will only look at EVENTA and will not return an
error because of invalid event string. This is handy when parsing constant event
strings containing multiple, comma-separated, events.

.SH RETURN
The function returns the opaque event identifier that corresponds
that the event string. In case of error, a negative error code
is returned instead.
.SH ERRORS
.TP
.B PFMLIB_ERR_NOINIT
The library has not been initialized properly.
.TP
.B PFMLIB_ERR_INVAL
The event string is NULL.
.TP
.B PFMLIB_ERR_NOMEM
The library ran out of memory.
.TP
.B PFMLIB_ERR_NOTFOUND
The event was not found
.TP
.B PFMLIB_ERR_ATTR
Invalid event attribute
.TP
.B PFMLIB_ERR_ATTR_VAL
Invalid event attribute value
.TP
.B PFMLIB_ERR_TOOMANY
Too many event attributes passed
.SH AUTHOR
Stephane Eranian <eranian@gmail.com>
.PP