1LIBPFM(3)                  Linux Programmer's Manual                 LIBPFM(3)
2
3
4

NAME

6       pfm_get_event_attr_info - get event attribute information
7

SYNOPSIS

9       #include <perfmon/pfmlib.h>
10
11       int pfm_get_event_attr_info(int idx, int attr, pfm_os_t os, pfm_event_attr_info_t *info);
12
13

DESCRIPTION

15       This  function  returns  in info information about the attribute desig‐
16       nated by attr for the event specified in idx and the os layer in os.
17
18       The pfm_os_t enumeration provides the following choices:
19
20       PFM_OS_NONE
21              The returned information pertains only to what the PMU  hardware
22              exports.  No operating system attributes is taken into account.
23
24       PFM_OS_PERF_EVENT
25              The  returned  information  includes the actual PMU hardware and
26              the additional attributes exported  by  the  perf_events  kernel
27              interface.  The perf_event attributes pertain only the PMU hard‐
28              ware.   In  case  perf_events  is  not  detected,  an  error  is
29              returned.
30
31       PFM_OS_PERF_EVENT_EXT
32              The  returned  information  includes all of what is already pro‐
33              vided by PFM_OS_PERF_EVENT plus all the software attributes con‐
34              trolled  by  perf_events,  such as sampling period, precise sam‐
35              pling.
36
37       The pfm_event_attr_info_t structure is defined as follows:
38       typedef struct {
39               const char              *name;
40               const char              *desc;
41               const char              *equiv;
42               size_t           size;
43               uint64_t                code;
44               pfm_attr_t              type;
45               int                     idx;
46               pfm_attr_ctrl_t         ctrl;
47               int                     reserved1;
48               struct {
49                       int             is_dfl:1;
50                       int             is_precise:1;
51                       int             reserved:30;
52               };
53               union {
54                       uint64_t        dfl_val64;
55                       const char      *dfl_str;
56                       int             dfl_bool;
57                       int             dfl_int;
58               };
59       } pfm_event_attr_info_t;
60
61       The fields of this structure are defined as follows:
62
63       name   This is the name of the attribute. This is a read-only string.
64
65       desc   This is the description of the attribute. This  is  a  read-only
66              string.  It may contain multiple sentences.
67
68       equiv  Certain  attributes  may  be just variations of other attributes
69              for the same event.  They may be provided as handy shortcuts  to
70              avoid   supplying   a   long  list  of  attributes.   For  those
71              attributes, this field is not NULL  and  contains  the  complete
72              equivalent  attribute  string. This string, once appended to the
73              event name, may be used library calls requiring an event string.
74
75       code   This is the raw attribute code. For PFM_ATTR_UMASK, this is  the
76              unit  mask  code.  For  all  other attributes, this is an opaque
77              index.
78
79       type   This is the type of the attribute. Attributes  represent  either
80              sub-events  or  extra  filters that can be applied to the event.
81              Filters (also called modifiers)  may be tied to the event or the
82              PMU  register  the  event  is  programmed  into.  The type of an
83              attribute determines how it must  be  specified.  The  following
84              types are defined:
85
86              PFM_ATTR_UMASK
87                     This  is  a unit mask, i.e., a sub-event. It is specified
88                     using its name.  Depending on the event, it may be possi‐
89                     ble to specify multiple unit masks.
90
91              PFM_ATTR_MOD_BOOL
92                     This is a boolean attribute. It has a value of 0, 1, y or
93                     n. The value is specified after  the  equal  sign,  e.g.,
94                     foo=1.  As a convenience, the equal sign and value may be
95                     omitted, in which case this is equivalent to =1.
96
97              PFM_ATTR_MOD_INTEGER
98                     This is an integer attribute. It has a value  which  must
99                     be passed after the equal sign. The range of valid values
100                     depends on the attribute and is usually specified in  its
101                     description.
102
103       idx    This  is  the  attribute  index. It is identical to the value of
104              attr passed to the call and is provided for completeness.
105
106       size   This field contains the size of the struct passed. This field is
107              used  to provide for extensibility of the struct without compro‐
108              mising backward compatibility.   The  value  should  be  set  to
109              sizeof(pfm_event_attr_info_t). If instead, a value of 0 is spec‐
110              ified, the library assumes the struct passed is identical to the
111              first  ABI  version  which  size is PFM_ATTR_INFO_ABI0. Thus, if
112              fields were added after the first ABI, they will not be  set  by
113              the  library.  The  library does check that bytes beyond what is
114              implemented are zeroes.
115
116       is_dfl This field indicates whether or not this  attribute  is  set  by
117              default.  This applies mostly for PFM_ATTR_UMASK. If a unit mask
118              is marked as default, and no unit mask is specified in the event
119              string, then the library uses it by default. Note that there may
120              be multiple defaults per event depending on how unit  masks  are
121              grouped.
122
123       is_precise
124              This  field indicates whether or not this umask supports precise
125              sampling.  Precise sampling is a hardware mechanism that  avoids
126              instruction address skid when using interrupt-based sampling. On
127              Intel X86 processors, this field indicates that the  umask  sup‐
128              ports Precise Event-Based Sampling (PEBS).
129
130       dfl_val64, dfl_str, dfl_bool, dfl_int
131              This   union   contains   the   value   of   an  attribute.  For
132              PFM_ATTR_UMASK, the is the unit mask code, for all  other  types
133              this is the actual value of the attribute.
134
135       ctrl   This   field  indicates  which  layer  or  source  controls  the
136              attribute.  The following sources are defined:
137
138              PFM_ATTR_CTRL_UNKNOWN
139                     The source controlling the attribute is not known.
140
141              PFM_ATTR_CTRL_PMU
142                     The attribute is controlled by the PMU hardware.
143
144              PFM_ATTR_CTRL_PERF_EVENT
145                     The attribute is controlled  by  the  perf_events  kernel
146                     interface.
147
148       reserved
149              These fields must be set to zero.
150

RETURN

152       If  successful, the function returns PFM_SUCCESS and attribute informa‐
153       tion in info, otherwise it returns an error code.
154

ERRORS

156       PFMLIB_ERR_NOINIT
157              Library has not been initialized properly.
158
159       PFMLIB_ERR_INVAL
160              The idx or attr arguments are invalid or info is NULL or size is
161              not zero.
162
163       PFM_ERR_NOTSUPP
164              The requested os layer has not been detected on the host system.
165

AUTHOR

167       Stephane Eranian <eranian@gmail.com>
168
169                                December, 2009                       LIBPFM(3)
Impressum