NAME pfm_find_event - search for an event masks

SYNOPSIS

       #include <perfmon/pfmlib.h>

       int pfm_find_event(const char *str);

DESCRIPTION

       This function is used to convert an event string passed in str 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:

       [pmu_name::]event_name[:unit_mask][:modifier|:modifier=val]

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

       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
              pfm_get_pmu_name().

       event_name
              This  is  the  event  name and is required. The library is not case sensitive on event string. The
              event name must match completely the actual event name; it cannot be a substring.

       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.

       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 true. 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.

       The library uses the generic term attribute to designate both unit masks and modifiers.

       Here are a few examples of event strings:

       amd64::RETIRED_INSTRUCTIONS:u
              Event RETIRED_INSTRUCTION on AMD64 processor, measure at user privilege level only

       RS_UOPS_DISPATCHED:c=1:i:u
              Event RS_UOPS_DISPATCHED measured at user privilege level only, and with counter-mask set to 1

       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 str 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.

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.

ERRORS

       PFMLIB_ERR_NOINIT
              The library has not been initialized properly.

       PFMLIB_ERR_INVAL
              The event string is NULL.

       PFMLIB_ERR_NOMEM
              The library ran out of memory.

       PFMLIB_ERR_NOTFOUND
              The event was not found

       PFMLIB_ERR_ATTR
              Invalid event attribute

       PFMLIB_ERR_ATTR_VAL
              Invalid event attribute value

       PFMLIB_ERR_TOOMANY
              Too many event attributes passed

AUTHOR

       Stephane Eranian <eranian@gmail.com>

                                                 September, 2009                                       LIBPFM(3)