Man Linux: Main Page and Category List

NAME

       pfm_get_cycle_event,   pfm_get_inst_retired_event  -  get  basic  event
       descriptors

SYNOPSIS

       #include <perfmon/pfmlib.h>

       int pfm_get_cycle_event(pfmlib_event_t *ev);
       int pfm_get_inst_retired_event(pfmlib_event_t *ev);

DESCRIPTION

       In order to build very simple geenric examples that work across all PMU
       models,  the  library  provides a way to retrieve information about two
       basic  events  that  are  present  in  most  PMU  models:  cycles   and
       instruction  retired.  The  first  event,  cycles, counts the number of
       elapsed cycles. The  second  event,  instruction  retired,  counts  the
       number  of  instructions  that  have  executed  and  retired  from  the
       processor pipeline. Depending on the PMU model, there may be variations
       in  the  exact  definition  of  those events. The library provides this
       information on a best effort  basis.  User  must  refer  to  PMU  model
       specific documentation to validate the event definition.

       The  pfm_get_cycle_event  function returns in ev the event and optional
       unit mask  descriptors  for  the  event  that  counts  elapsed  cycles.
       Depending  on  the  PMU  model,  there may be unit mask(s) necessary to
       count  cycles.  Application  must   check   the   value   returned   in
       ev->num_masks.

       The  pfm_get_inst_retired_event  function  returns  in ev the event and
       optional unit mask descriptors for the event that counts the number  of
       retured  instruction.  Depending  on  the  PMU model, there may be unit
       mask(s) necessary to count retired instructions. Application must check
       the value returned in ev->num_masks.

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 ev parameter is NULL.

       PFMLIB_ERR_NOTSUPP
              the  host  PMU  does  not  define  an  event  to count cycles or
              instructions retired.

       AUTHOR Stephane Eranian <eranian@hpl.hp.com>

                                September, 2006                      LIBPFM(3)