Provided by: libpfm4-dev_4.13.0+git32-g0d4ed0e-1_amd64 bug

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             reserved:28;
               };
               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.

       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.

AUTHOR

       Stephane Eranian <eranian@gmail.com>

                                          December, 2009                                LIBPFM(3)