pfm_get_event_name,                    pfm_get_event_code,
       pfm_get_event_counters,               pfm_get_first_event,
       pfm_get_next_event - get event information


SYNOPSIS

       #include <perfmon/pfmlib.h>

       int pfm_get_event_name(int e, char **name);
       int pfm_get_event_code(int e, int *code);
       int pfm_get_event_counters(int e, unsigned long counters[4]);
       int pfm_get_first_event(void);
       int pfm_get_next_event(int e);


DESCRIPTION

       The  PMU  counters can be programmed to measure the number
       of occurrences of certain events.  The  number  of  events
       varies  from  one  implementation to the other. Each event
       has a name and a code which is used to program the  actual
       PMU  register. Not all event can necessarily be programmed
       on any of the available  counters  due  to  hardware  con­
       straints.

       The  library  does  not  directly expose the event code to
       user applications because it  is  not  necessary.  Instead
       applications  used names to query the library for particu­
       lar information about events. Given a  name,  the  library
       returns  an  opaque  descriptor to the applications.  Each
       descriptor is unique and has no relationship to the  event
       code.   All  functions requires the library to be properly
       initialized.

       The pfm_get_event_name function returns in name the  event
       name  given its opaque descriptor e. The string represent­
       ing the name must be considered as read only.

       The pfm_get_event_code function returns the event code  in
       code given its opaque descriptor e.

       Given     an    opaque    event    descriptor    e,    the
       pfm_get_event_counters function returns a bitmask  in  the
       counters array where each bit set represents a PMU counter
       which can be used to program this event. A PMU counter  is
       defined  as  a  matching  pair  of  PMC  and  PMD, such as
       PMC4/PMD4.

       It is  possible  to  list  all  existing  events  for  the
       detected host PMU using access functions as the full table
       of events is  not  accessible  to  the  applications.  The
       pfm_get_first_event  returns the opaque descriptor for the
       first event, then pfm_get_next_event is used to go to  the
       next  event  given  a  descriptor e. After the last event,
       this function will return -1. The  typical  scan  loop  is


       char **name;
       int i;
       i = pfm_get_first_event();
       for(;i != -1; i = pfm_get_next_event(i))
       {
          pfm_get_event_name(i, &name);
          printf("%s\n", name);
       }


RETURN

       The  pfm_get_first_event  returns the opaque descriptor of
       the first event. The  pfm_get_next_event  function  return
       the  descriptor  for  the  next  event.  A  value of -1 is
       returned if the last event is passed as argument or if  an
       invalid event descriptor is given.

       All  other  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.


AUTHOR

       Stephane Eranian <eranian@hpl.hp.com>


Man(1) output converted with man2html