Man Linux: Main Page and Category List

NAME

       pfm_get_event_name,  pfm_get_full_event_name,  pfm_get_event_mask_name,
       pfm_get_event_code,  pfm_get_event_mask_code,   pfm_get_event_counters,
       pfm_get_num_events,                         pfm_get_max_event_name_len,
       pfm_get_event_description, pfm_get_event_mask_description -  get  event
       information

SYNOPSIS

       #include <perfmon/pfmlib.h>

       int pfm_get_event_name(unsigned int e, char *name, size_tmaxlen);
       int pfm_get_full_event_name(pfmlib_event_t *ev, char *name, size_tmaxlen);
       int pfm_get_event_mask_name(unsigned int e, unsigned int mask, char *name, size_tmaxlen);
       int pfm_get_event_code(unsigned int e, int *code);
       int pfm_get_event_mask_code(unsigned int e, unsigned int mask, int *code);
       int pfm_get_event_code_counter(unsigned int e, unsigned int cnt, int *code);
       int pfm_get_event_counters(int e, pfmlib_regmask_t counters);
       int pfm_get_num_events(unsigned int *count);
       int pfm_get_max_event_name_len(size_t *len);
       int pfm_get_event_description(unsigned int ev, char **str);
       int pfm_get_event_mask_description(unsigned int ev, unsigned int mask, char **str);

DESCRIPTION

       The  pfm_get_event_name  function  returns in name the event name given
       its opaque descriptor in e. The maxlen argument indicates  the  maximum
       length of the buffer provided for name.  Up to maxlen-1 characters will
       be returned, not including the termination character. Event  names  are
       returned in all upper case.

       The  pfm_get_full_event_name  function  returns  in name the event name
       given the full event description in ev. The  description  contains  the
       event  code  in  ev->event  and  optional  unit  masks  descriptors  in
       ev->unit_masks. The maxlen argument indicates the maximum length of the
       buffer  provided for name.  If more than maxlen-1 characters are needed
       to represent the event, an error is returned.  In case unit  masks  are
       provided,   the   final   event   name   string   is   structured   as:
       event_name:unit_masks1[:unit_masks2]. Event names and unit masks  names
       are returned in all upper case.

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

       On some PMU models, the code associated  with  an  event  is  different
       based    on    the    counter    it    is    programmed    into.    The
       pfm_get_event_code_counter function is used to retrieve the event  code
       in  code  when  the event e is programmed into counter cnt. The counter
       index cnt must correspond to of a counting PMD register.

       Given an opaque event descriptor e, the pfm_get_event_counters function
       returns  in  counters a bitmask of type pfmlib_regmask_t where each bit
       set represents a PMU config register which can be used to program  this
       event.  The  bitmask  must be accessed using accessor macros defined by
       the library.

       It is possible to list all existing events for the  detected  host  PMU
       using  accessor functions as the full table of events is not accessible
       to the applications. The index of the first event is always zero,  then
       using  pfm_get_num_events  you  get  the total number of events.  Event
       descriptors are contiguous therefore a simple loop will allow  complete
       scanning. The typical scan loop is constructed as follows:

       unsigned int i, count;
       char name[256];
       pfm_get_num_events(&count);
       for(i=0;i < count; i++)
       {
          pfm_get_event_name(i, name, 256);
          printf("%s\n", name);
       }

       The  pfm_get_num_events  function  returns in count the total number of
       events supported by the host PMU.

       The former pfm_get_first_event has  been  deprecated.  You  can  simply
       initialize your variable to 0 to point to the first event.

       The former pfm_get_next_event has been deprecated. You need to retrieve
       the total number of events for the host PMU  and  then  increment  your
       loop variable until you reach that count.

       The  pfm_get_max_event_name_len  function  returns  in  len the maximum
       length in bytes for the name of the events or its unit masks,  if  any,
       available  on  one  PMU  implementation.  The value excludes the string
       termination character (’\0’).

       The pfm_get_event_description function returns in str  the  description
       string  associated  with the event specified in ev.  The description is
       returned into a buffer that is allocated to hold the entire description
       text. It is the responsibility of the caller to free the buffer when it
       becomes useless by calling the free(3) function.

       The pfm_get_event_mask_code function  must  be  used  to  retrieve  the
       actual  unit  mask  value given a event descriptor in e and a unit mask
       descriptor in mask. The value is returned in code.

       The pfm_get_event_mask_name function must be used to retrieve the  name
       associated  with a unit mask specified in mask for event e. The name is
       returned in the buffer specified in  name.  The  maximum  size  of  the
       buffer must be specified in maxlen.

       The   pfm_get_event_mask_description   function   returns  in  str  the
       description string associated with the unit mask specified in mask  for
       the  event  specified  in ev. The description is returned into a buffer
       that is allocated to hold  the  entire  description  text.  It  is  the
       responsibility of the caller to free the buffer when it becomes useless
       by calling the free(3) function.

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_FULL
              the string buffer provided is too small

       PFMLIB_ERR_INVAL
              the event or unit  mask  descriptor,  or  the  cnt  argument  is
              invalid, or a pointer argument is NULL.

SEE ALSO

       pfm_get_impl_counters(3), free(3)

AUTHOR

       Stephane Eranian <eranian@hpl.hp.com>

                                 August, 2006                        LIBPFM(3)