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][:modifer|:modifier=val]

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

       pmu_name
              This is an optional prefix to designte 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)