Man Linux: Main Page and Category List

NAME

       pfm_find_event,       pfm_find_full_event,       pfm_find_event_bycode,
       pfm_find_event_bycode_next, pfm_find_event_mask - search for events and
       unit masks

SYNOPSIS

       #include <perfmon/pfmlib.h>

       int pfm_find_event(const char *str, unsigned int *desc);
       int pfm_find_full_event(const char *str, pfmlib_event_t *e);
       int pfm_find_event_bycode(int code, unsigned int *desc);
       int pfm_find_event_bycode_next(unsigned int desc1, int code, unsigned int *desc);
       int pfm_find_event_mask(unsigned int *idx, const char *str, unsigned int *mask_idx);

DESCRIPTION

       The  PMU  counters can be programmed to count the number of occurrences
       of certain events. The number of events varies from one  PMU  model  to
       the  other.  Each  event has a name and a code which is used to program
       the actual PMU register. Some event may need to  be  further  qualified
       with unit masks.

       The  library  does  not  directly  expose the event code, nor unit mask
       code, to  user  applications  because  it  is  not  necessary.  Instead
       applications  use names to query the library for particular information
       about events.  Given an event  name,  the  library  returns  an  opaque
       descriptor.   Each  descriptor is unique and has no relationship to the
       event code.

       The set of functions described  here  can  be  used  to  get  an  event
       descriptor  given  either  the  name  of the event or its code. Several
       events may share the same code. An event name is  a  string  structured
       as: event_name[:unit_mask1[:unit_mask2]].

       The pfm_find_event function is a general purpose search routine.  Given
       an event name in str, it returns the descriptor for  the  corresponding
       event.   If  unit  masks are provided, they are not taken into account.
       This function is being deprecated in favor of pfm_find_full_event_name.

       The  pfm_find_full_event  function is a general purpose search routine.
       Given an event name, it returns in ev, the full event  descriptor  that
       includes   the   event  descriptor  in  ev->event  and  the  unit  mask
       descriptors in ev->unit_masks. The number  of  unit  masks  descriptors
       returned  is indicated in ev->num_masks. This function is the preferred
       search function.

       The  pfm_find_event_bycode  searches  for  an  event  given  its   code
       represented  as  an  integer.  It returns in desc, the event code. Unit
       masks are ignored.

       Because there can be several events with the  same  code,  the  library
       provides the pfm_find_event_bycode_next to search for other events with
       the same code. Given an event desc1 and a code, this function will look
       for  the  next  event  with the same code. If such an event exists, its
       descriptor will be stored into desc.   It  is  not  necessary  to  have
       called  pfm_find_event_bycode  prior  to  calling  this  function. This
       function is fully threadsafe as it does not maintain any state  between
       calls.

       The  pfm_find_event_mask  function  is  used  to  find  the  unit  mask
       descriptor based on its name passed in str for the event  specified  in
       idx.  Some  events  do not have unit masks, in which case this function
       returns an error.

RETURN

       All functions return whether or not the call was successful.  A  return
       value  of  PFMLIB_SUCCESS indicates success, otherwise the value is the
       error code.

ERRORS

       PFMLIB_ERR_NOINIT the library has not been initialized properly.

       PFMLIB_ERR_INVAL
              the event descriptor is invalid,  or  the  pointer  argument  is
              NULL.

       PFMLIB_ERR_NOTFOUND
              no matching event or unit mask was found.

AUTHOR

       Stephane Eranian <eranian@hpl.hp.com>

                                 August, 2006                        LIBPFM(3)