pfm_find_event(3) — Linux manual page

NAME \| SYNOPSIS \| DESCRIPTION \| RETURN \| ERRORS \| AUTHOR \| COLOPHON

LIBPFM(3)               Linux Programmer's Manual              LIBPFM(3)

NAME top

       pfm_find_event - search for an event masks

SYNOPSIS top

       #include <perfmon/pfmlib.h>

       int pfm_find_event(const char *str);

DESCRIPTION top

       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 top

       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 top

       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 top

       Stephane Eranian <[email protected]>

COLOPHON top

       This page is part of the perfmon2 (a performance monitoring
       library) project.  Information about the project can be found at
       ⟨http://perfmon2.sourceforge.net/⟩.  If you have a bug report for
       this manual page, send it to
       [email protected].  This page was obtained
       from the project's upstream Git repository
       ⟨git://git.code.sf.net/p/perfmon2/libpfm4 perfmon2-libpfm4⟩ on
       2024-06-14.  (At that time, the date of the most recent commit
       that was found in the repository was 2024-04-24.)  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for
       the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original
       manual page), send a mail to [email protected]

                             September, 2009                   LIBPFM(3)

Pages that refer to this page: pfm_get_event_next(3)