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

NAME

6       pfm_get_os_event_encoding - get event encoding for a specific operating
7       system
8

SYNOPSIS

10       #include <perfmon/pfmlib.h>
11
12       int pfm_get_os_event_encoding(const char *str, int dfl_plm, pfm_os_t os,  void *arg);
13
14

DESCRIPTION

16       This is the key function to retrieve the encoding of  an  event  for  a
17       specific  operating system interface. The event string passed in str is
18       parsed and encoded for the operating system specified by os. The  event
19       is  encoded to monitor at the privilege levels specified by the dfl_plm
20       mask, if supported, otherwise this parameter is ignored. The  operating
21       system specific input and output arguments are passed in arg.
22
23       The  event  string,  str,  may contains sub-event masks (umask) and any
24       other supported modifiers. Only one event is parsed  from  the  string.
25       For  convenience,  it  is  possible  to  pass a comma-separated list of
26       events in str but only the first event is encoded.
27
28       The following values are supported for os:
29
30       PFM_OS_NONE
31              This value causes the event to be encoded purely as specified by
32              the  PMU  hardware.  The  arg  argument  must  be a pointer to a
33              pfm_raw_pmu_encode_arg_t structure which is defined as follows:
34
35              typedef struct {
36                  uint64_t    *codes;
37                  char        **fstr;
38                  size_t      size;
39                  int         count;
40                  int         idx;
41              } pfm_pmu_encode_arg_t;
42
43              The fields are defined as follows:
44
45              codes  A pointer to an array of  64-bit  values.  On  input,  if
46                     codes  is  NULL,  then  the library allocates whatever is
47                     necessary to store the encoding of the event. If codes is
48                     not  NULL  on  input,  then count must reflect its actual
49                     number of elements. If count is big enough,  the  library
50                     stores  the encoding at the address provided.  Otherwise,
51                     an error is returned.
52
53              count  On input, the field contains the maximum number  of  ele‐
54                     ments  in  the  array codes. Upon return, it contains the
55                     number of actual entries in codes. If codes is NULL, then
56                     count must be zero.
57
58              fstr   If the caller is interested in retrieving the fully qual‐
59                     ified event string where all used unit masks and all mod‐
60                     ifiers  are spelled out, this field must be set to a non-
61                     null address of a pointer to a string  (char  **).   Upon
62                     return,  if  fstr  was  not NULL, then the string pointer
63                     passed on entry points to the event string. The string is
64                     dynamically allocated and must eventually be freed by the
65                     caller. If fstr  was  NULL  on  entry,  then  nothing  is
66                     returned  in  this  field.  The  typical calling sequence
67                     looks as follows:
68                        char *fstr = NULL
69                        pfm_pmu_encode_arg_t arg;
70                        arg.fstr = &fstr;
71                        ret = pfm_get_os_event_encoding("event",
72                                                        PFM_PLM0|PFM_PLM3,
73                                                        PFM_OS_NONE,
74                                                        &e);
75                        if (ret == PFM_SUCCESS) {
76                           printf("fstr=%s0, fstr);
77                           free(fstr);
78                        }
79
80              size   This field contains the size of the struct  passed.  This
81                     field  is used to provide for extensibility of the struct
82                     without compromising backward compatibility.   The  value
83                     should   be   set   to  sizeof(pfm_pmu_encode_arg_t).  If
84                     instead, a value of 0 is specified, the  library  assumes
85                     the  struct  passed is identical to the first ABI version
86                     which size is PFM_RAW_ENCODE_ABI0. Thus, if  fields  were
87                     added  after  the  first ABI, they will not be set by the
88                     library. The library does check that bytes beyond what is
89                     implemented are zeroes.
90
91              idx    Upon  return, this field contains the opaque unique iden‐
92                     tifier for the event described in str.  This index can be
93                     used  to  retrieve  information  about  the  event  using
94                     pfm_get_event_info(), for instance.
95
96       PFM_OS_PERF_EVENT, PFM_OS_PERF_EVENT_EXT
97              This value causes the event to be  encoded  for  the  perf_event
98              Linux  kernel  interface (available since 2.6.31).  The arg must
99              be  a  pointer  to  a   pfm_perf_encode_arg_t   structure.   The
100              PFM_OS_PERF_EVENT  layer  provides the modifiers exported by the
101              underlying PMU hardware, some of which may actually be  overrid‐
102              den  by  the perf_event interface, such as the monitoring privi‐
103              lege levels. The PFM_OS_PERF_EVENT_EXT extends  PFM_OS_EVENT  to
104              add  modifiers controlled only by the perf_event interface, such
105              as sampling period  (period),  frequency  (freq)  and  exclusive
106              resource access (excl).
107
108              typedef struct {
109                  struct perf_event_attr *attr;
110                  char **fstr;
111                  size_t size;
112                  int idx;
113                  int cpu;
114                  int flags;
115              } pfm_perf_encode_arg_t;
116              The fields are defined as follows:
117
118              attr   A  pointer  to  a  struct  perf_event_attr  as defined in
119                     perf_event.h. This field cannot be  NULL  on  entry.  The
120                     struct  is  not  completely  overwritten by the call. The
121                     library only modifies the fields it knows about,  thereby
122                     allowing  perf_event  ABI  mismatch  between  caller  and
123                     library.
124
125              fstr   Same behavior as is described for PFM_OS_NONE above.
126
127              size   This field contains the size of the struct  passed.  This
128                     field  is used to provide for extensibility of the struct
129                     without compromising backward compatibility.   The  value
130                     should   be   set  to  sizeof(pfm_perf_encode_arg_t).  If
131                     instead, a value of 0 is specified, the  library  assumes
132                     the  struct  passed is identical to the first ABI version
133                     which size is PFM_PERF_ENCODE_ABI0. Thus, if fields  were
134                     added  after  the  first ABI, they will not be set by the
135                     library. The library does check that bytes beyond what is
136                     implemented are zeroes.
137
138              idx    Upon  return, this field contains the opaque unique iden‐
139                     tifier for the event described in str.  This index can be
140                     used  to  retrieve  information  about  the  event  using
141                     pfm_get_event_info(), for instance.
142
143              cpu    Not used yet.
144
145              flags  Not used yet.
146
147       Here is a example of how this function could be used with PFM_OS_NONE:
148       #include <inttypes.h>
149       #include <err.h>
150       #include <perfmon/pfmlib.h>
151       int main(int argc, char **argv)
152       {
153          pfm_raw_pmu_encode_t raw;
154          int ret;
155
156          ret = pfm_initialize();
157          if (ret != PFMLIB_SUCCESS)
158             errx(1, "cannot initialize library %s", pfm_strerror(ret));
159
160          memset(&raw, 0, sizeof(raw));
161
162          ret = pfm_get_os_event_encoding("RETIRED_INSTRUCTIONS", PFM_PLM3, PFM_OS_NONE, &raw);
163          if (ret != PFM_SUCCESS)
164             err(1", cannot get encoding %s", pfm_strerror(ret));
165
166          for(i=0; i < raw.count; i++)
167             printf("count[%d]=0x%"PRIx64"\n", i, raw.codes[i]);
168
169          free(raw.codes);
170          return 0;
171       }
172

RETURN

174       The function returns in arg the encoding of the event for the os passed
175       in  os.  The  content  of arg depends on the os argument. Upon success,
176       PFM_SUCCESS is returned otherwise a specific error code is returned.
177

ERRORS

179       PFM_ERR_TOOSMALL
180              The code argument is too small for the encoding.
181
182       PFM_ERR_INVAL
183              The code or count argument is NULL.
184
185       PFM_ERR_NOMEM
186              Not enough memory.
187
188       PFM_ERR_NOTFOUND
189              Event not found.
190
191       PFM_ERR_ATTR
192              Invalid event attribute (unit mask or modifier)
193
194       PFM_ERR_ATTR_VAL
195              Invalid modifier value.
196
197       PFM_ERR_ATTR_SET
198              attribute already set, cannot be changed.
199
200       PFM_ERR_ATTR_UMASK
201              Missing unit mask.
202
203       PFM_ERR_ATTR_FEATCOMB
204              Unit masks or features cannot be combined into a single event.
205

AUTHOR

207       Stephane Eranian <eranian@gmail.com>
208
209                                 January, 2011                       LIBPFM(3)
Impressum