# pfm_get_event_attr_info

## NAME



           pfm_get_event_attr_info - get event attribute information
    


## SYNOPSIS



           **#include <perfmon/pfmlib.h>**
    
           **int pfm_get_event_attr_info(int** _idx_**, int** _attr_**, pfm_os_t** _os_**, pfm_event_attr_info_t ***_info_**);**
    


## DESCRIPTION



           This function returns in **info** information about the attribute
           designated by **attr** for the event specified in **idx** and the os layer
           in **os**.
    
           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.
    
           The **pfm_event_attr_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_attr_t              type;
                   int                     idx;
                   pfm_attr_ctrl_t         ctrl;
                   int                     reserved1;
                   struct {
                           int             is_dfl:1;
                           int             is_precise:1;
                           int             is_speculative:2;
                     int       support_hw_smpl:1;
                     int       support_no_mods:1;
                           int             reserved:26;
                   };
                   union {
                           uint64_t        dfl_val64;
                           const char      *dfl_str;
                           int             dfl_bool;
                           int             dfl_int;
                   };
           } pfm_event_attr_info_t;
    
           The fields of this structure are defined as follows:
    
           **name** This is the name of the attribute. This is a read-only
                  string.
    
           **desc** This is the description of the attribute. This is a read-
                  only string.  It may contain multiple sentences.
    
           **equiv** Certain attributes may be just variations of other
                  attributes for the same event.  They may be provided as
                  handy shortcuts to avoid supplying a long list of
                  attributes.  For those attributes, this field is not NULL
                  and contains the complete equivalent attribute string. This
                  string, once appended to the event name, may be used
                  library calls requiring an event string.
    
           **code** This is the raw attribute code. For PFM_ATTR_UMASK, this is
                  the unit mask code. For all other attributes, this is an
                  opaque index.
    
           **type** This is the type of the attribute. Attributes represent
                  either sub-events or extra filters that can be applied to
                  the event. Filters (also called modifiers)  may be tied to
                  the event or the PMU register the event is programmed into.
                  The type of an attribute determines how it must be
                  specified. The following types are defined:
    
                  **PFM_ATTR_UMASK**
                         This is a unit mask, i.e., a sub-event. It is
                         specified using its name.  Depending on the event,
                         it may be possible to specify multiple unit masks.
    
                  **PFM_ATTR_MOD_BOOL**
                         This is a boolean attribute. It has a value of 0, 1,
                         y or n. The value is specified after the equal sign,
                         e.g., foo=1. As a convenience, the equal sign and
                         value may be omitted, in which case this is
                         equivalent to =1.
    
                  **PFM_ATTR_MOD_INTEGER**
                         This is an integer attribute. It has a value which
                         must be passed after the equal sign. The range of
                         valid values depends on the attribute and is usually
                         specified in its description.
    
           **idx** This is the attribute index. It is identical to the value
                  of **attr** passed to the call and is provided for
                  completeness.
    
           **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_attr_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_ATTR_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_dfl** This field indicates whether or not this attribute is set
                  by default. This applies mostly for PFM_ATTR_UMASK. If a
                  unit mask is marked as default, and no unit mask is
                  specified in the event string, then the library uses it by
                  default. Note that there may be multiple defaults per event
                  depending on how unit masks are grouped.
    
           **is_precise**
                  This field indicates whether or not this umask supports
                  precise sampling.  Precise sampling is a hardware mechanism
                  that avoids instruction address skid when using interrupt-
                  based sampling. On Intel X86 processors, this field
                  indicates that the umask supports Precise Event-Based
                  Sampling (PEBS).
    
           **is_speculative**
                  This bitfield indicates whether or not the attribute
                  includes occurrences happening during speculative execution
                  for both wrong and correct paths. 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 attribute
                  counts during speculative execution. A value of
                  **PFM_EVENT_INFO_SPEC_FALSE** indicates that the attribute does
                  not count during speculative execution.
    
           **support_hw_smpl**
                  This boolean field indicates that the attribute (in this
                  case a umask) supports hardware sampling.  That means the
                  hardware can sample this event+umasks without involving the
                  kernel at each sample.
    
           **support_no_mods**
                  This boolean field indicates that the attribute (in this
                  case a umask) does not support any hardware or software
                  modifiers, such as privilege level filters, sampling,
                  precise sampling, and such. This is necessary when select
                  umasks of an event have more restrictions than others,
                  e.g., the event and most umasks support modifiers except a
                  few umasks.
    
           **dfl_val64, dfl_str, dfl_bool, dfl_int**
                  This union contains the value of an attribute. For
                  PFM_ATTR_UMASK, the is the unit mask code, for all other
                  types this is the actual value of the attribute.
    
           **ctrl** This field indicates which layer or source controls the
                  attribute.  The following sources are defined:
    
                  **PFM_ATTR_CTRL_UNKNOWN**
                         The source controlling the attribute is not known.
    
                  **PFM_ATTR_CTRL_PMU**
                         The attribute is controlled by the PMU hardware.
    
                  **PFM_ATTR_CTRL_PERF_EVENT**
                         The attribute is controlled by the perf_events
                         kernel interface.
    
           **reserved**
                  These fields must be set to zero.
    


## RETURN



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


## ERRORS



           **PFMLIB_ERR_NOINIT**
                  Library has not been initialized properly.
    
           **PFMLIB_ERR_INVAL**
                  The **idx** or **attr** arguments are invalid or **info** is **NULL** or
                  **size** is not zero.
    
           **PFM_ERR_NOTSUPP**
                  The requested os layer has not been detected on the host
                  system.
    


* * *