NAME | SYNOPSIS | DESCRIPTION | RETURN | ERRORS | AUTHOR | COLOPHON

LIBPFM(3)                 Linux Programmer's Manual                LIBPFM(3)

NAME         top

       pfm_get_event_attr_info - get event attribute information

SYNOPSIS         top

       #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         top

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

       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         top

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

ERRORS         top

       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         top

       Stephane Eranian <eranian@gmail.com>

COLOPHON         top

       This page is part of the perfmon2 (a performance monitoring library)
       project.  Information about the project can be found at 
       ⟨http://perfmon2.sourceforge.net/⟩.  If you have a bug report for this
       manual page, send it to perfmon2-devel@lists.sourceforge.net.  This
       page was obtained from the project's upstream Git repository 
       ⟨git://git.code.sf.net/p/perfmon2/libpfm4⟩ on 2017-07-05.  If you dis‐
       cover any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

                               December, 2009                      LIBPFM(3)