# pfm_get_event_info

## 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).
    
           **is_speculative**
                  This bitfield indicates whether or not the event includes
                  occurrences happening during speculative execution for both
                  wrong and correct path. Given that this kind of event
                  information is not always available from vendors, this
                  field uses multiple bits. A value of **PFM_EVENT_INFO_SPEC_NA**
                  indicates that speculation information is not available. A
                  value of **PFM_EVENT_INFO_SPEC_TRUE** indicates that the event
                  count during speculative execution. A value of
                  **PFM_EVENT_INFO_SPEC_FALS** indicates that the event does not
                  count during speculative execution.
    
           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.
    


* * *