NAME

       pfm_get_event_info - get event information

SYNOPSIS

       #include <perfmon/pfmlib.h>

       int pfm_get_event_info(int idx, pfm_os_t os, pfm_event_info_t *info);

DESCRIPTION

       This  function  returns  in  info  information  about  a  specific  event designated by its opaque unique
       identifier in idx for the operating system specified in os.

       The pfm_event_info_t structure is defined as follows:
       typedef struct {
               const char              *name;
               const char              *desc;
               const char              *equiv;
               size_t              size;
               uint64_t                code;
               pfm_pmu_t               pmu;
               pfm_dtype_t             dtype
               int                     idx;
               int                     nattrs;
               struct {
                 unsigned int is_precise:1;
                 unsigned int reserved_bits:31;
               };
       } pfm_event_info_t;

       The fields of this structure are defined as follows:

       name   This is the name of the event. This is a read-only string.

       desc   This is the description of the event.  This  is  a  read-only  string.  It  may  contain  multiple
              sentences.

       equiv  Certain events may be just variations of actual events. They may be provided as handy shortcuts to
              avoid  supplying  a long list of attributes. For those events, this field is not NULL and contains
              the complete equivalent event string.

       code   This is the raw event code. It should not be confused with the encoding of the event.  This  field
              represents only the event selection code, it does not include any unit mask or attribute settings.

       pmu    This  is the identification of the PMU model this event belongs to. It is of type pfm_pmu_t. Using
              this value and the pfm_get_pmu_info function, it is possible to get PMU information.

       dtype  This field returns the representation of the event data. By default, it is PFM_DATA_UINT64.

              idx This is the event unique opaque identifier. It is identical to the idx passed to the call  and
              is provided for completeness.

       nattrs This  is  the  number  of  attributes  supported  by  this  event. Attributes may be unit masks or
              modifiers. If the event has not attribute, then the value of this field is simply 0.

       size   This field contains the size of the struct passed. This field is used to provide for extensibility
              of  the  struct  without  compromising  backward  compatibility.   The  value  should  be  set  to
              sizeof(pfm_event_info_t).  If  instead,  a value of 0 is specified, the library assumes the struct
              passed is identical to the first ABI version which size is PFM_EVENT_INFO_ABI0.  Thus,  if  fields
              were  added  after the first ABI, they will not be set by the library. The library does check that
              bytes beyond what is implemented are zeroes.

       is_precise
              This bitfield indicates whether or not the event support precise sampling.  Precise sampling is  a
              hardware  mechanism that avoids instruction address skid when using interrupt-based sampling. When
              the event has umasks, this field means that at least one umask supports precise sampling. On Intel
              X86 processors, this indicates whether the event supports Precise Event-Based Sampling (PEBS).

       The pfm_os_t enumeration provides the following choices:

       PFM_OS_NONE
              The returned information pertains only to what the PMU  hardware  exports.   No  operating  system
              attributes is taken into account.

       PFM_OS_PERF_EVENT
              The  returned  information includes the actual PMU hardware and the additional attributes exported
              by the perf_events kernel interface.  The perf_event attributes pertain only the PMU hardware.  In
              case perf_events is not detected, an error is returned.

       PFM_OS_PERF_EVENT_EXT
              The returned information includes all of what is already provided by  PFM_OS_PERF_EVENT  plus  all
              the software attributes controlled by perf_events, such as sampling period, precise sampling.

RETURN

       If  successful,  the  function returns PFM_SUCCESS and event information in info, otherwise it returns an
       error code.

ERRORS

       PFMLIB_ERR_NOINIT
              Library has not been initialized properly.

       PFMLIB_ERR_INVAL
              The idx argument is invalid or info is NULL or size is not zero.

       PFMLIB_ERR_NOTSUPP
              The requested os is not detected or supported.

AUTHOR

       Stephane Eranian <eranian@gmail.com>

                                                 December, 2009                                        LIBPFM(3)