1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 pfm_get_event_info - get event information
7
9 #include <perfmon/pfmlib.h>
10 int pfm_get_event_info(int idx, pfm_os_t os, pfm_event_info_t *info);
12
15 This function returns in info information about a specific event desig‐
16 nated by its opaque unique identifier in idx for the operating system
17 specified in os.
18 The pfm_event_info_t structure is defined as follows:
20 typedef struct {
21 const char *name;
22 const char *desc;
23 const char *equiv;
24 size_t size;
25 uint64_t code;
26 pfm_pmu_t pmu;
27 pfm_dtype_t dtype
28 int idx;
29 int nattrs;
30 struct {
31 unsigned int is_precise:1;
32 unsigned int reserved_bits:31;
33 };
34 } pfm_event_info_t;
35 The fields of this structure are defined as follows:
37 name This is the name of the event. This is a read-only string.
39 desc This is the description of the event. This is a read-only
41 string. It may contain multiple sentences.
42 equiv Certain events may be just variations of actual events. They may
44 be provided as handy shortcuts to avoid supplying a long list of
45 attributes. For those events, this field is not NULL and con‐
46 tains the complete equivalent event string.
47 code This is the raw event code. It should not be confused with the
49 encoding of the event. This field represents only the event se‐
50 lection code, it does not include any unit mask or attribute
51 settings.
52 pmu This is the identification of the PMU model this event belongs
54 to. It is of type pfm_pmu_t. Using this value and the
55 pfm_get_pmu_info function, it is possible to get PMU informa‐
56 tion.
57 dtype This field returns the representation of the event data. By de‐
59 fault, it is PFM_DATA_UINT64.
60 idx This is the event unique opaque identifier. It is identical
62 to the idx passed to the call and is provided for completeness.
63 nattrs This is the number of attributes supported by this event. At‐
65 tributes may be unit masks or modifiers. If the event has not
66 attribute, then the value of this field is simply 0.
67 size This field contains the size of the struct passed. This field is
69 used to provide for extensibility of the struct without compro‐
70 mising backward compatibility. The value should be set to
71 sizeof(pfm_event_info_t). If instead, a value of 0 is specified,
72 the library assumes the struct passed is identical to the first
73 ABI version which size is PFM_EVENT_INFO_ABI0. Thus, if fields
74 were added after the first ABI, they will not be set by the li‐
75 brary. The library does check that bytes beyond what is imple‐
76 mented are zeroes.
77 is_precise
79 This bitfield indicates whether or not the event support precise
80 sampling. Precise sampling is a hardware mechanism that avoids
81 instruction address skid when using interrupt-based sampling.
82 When the event has umasks, this field means that at least one
83 umask supports precise sampling. On Intel X86 processors, this
84 indicates whether the event supports Precise Event-Based Sam‐
85 pling (PEBS).
86 is_speculative
88 This bitfield indicates whether or not the event includes occur‐
89 rences happening during speculative execution for both wrong and
90 correct path. Given that this kind of event information is not
91 always available from vendors, this field uses multiple bits. A
92 value of PFM_EVENT_INFO_SPEC_NA indicates that speculation in‐
93 formation is not available. A value of PFM_EVENT_INFO_SPEC_TRUE
94 indicates that the event count during speculative execution. A
95 value of PFM_EVENT_INFO_SPEC_FALS indicates that the event does
96 not count during speculative execution.
97 The pfm_os_t enumeration provides the following choices:
99 PFM_OS_NONE
101 The returned information pertains only to what the PMU hardware
102 exports. No operating system attributes is taken into account.
103 PFM_OS_PERF_EVENT
105 The returned information includes the actual PMU hardware and
106 the additional attributes exported by the perf_events kernel in‐
107 terface. The perf_event attributes pertain only the PMU hard‐
108 ware. In case perf_events is not detected, an error is re‐
109 turned.
110 PFM_OS_PERF_EVENT_EXT
112 The returned information includes all of what is already pro‐
113 vided by PFM_OS_PERF_EVENT plus all the software attributes con‐
114 trolled by perf_events, such as sampling period, precise sam‐
115 pling.
116
118 If successful, the function returns PFM_SUCCESS and event information
119 in info, otherwise it returns an error code.
120
122 PFMLIB_ERR_NOINIT
123 Library has not been initialized properly.
124 PFMLIB_ERR_INVAL
126 The idx argument is invalid or info is NULL or size is not zero.
127 PFMLIB_ERR_NOTSUPP
129 The requested os is not detected or supported.
130
132 Stephane Eranian <eranian@gmail.com>
133 December, 2009 LIBPFM(3)