1 libperf(3) 1 libperf(3)
2 ========== 2 ==========
3 3
4 NAME 4 NAME
5 ---- 5 ----
6 libperf - Linux kernel perf event library 6 libperf - Linux kernel perf event library
7 7
8 8
9 SYNOPSIS 9 SYNOPSIS
10 -------- 10 --------
11 *Generic API:* 11 *Generic API:*
12 12
13 [source,c] 13 [source,c]
14 -- 14 --
15 #include <perf/core.h> 15 #include <perf/core.h>
16 16
17 enum libperf_print_level { 17 enum libperf_print_level {
18 LIBPERF_ERR, 18 LIBPERF_ERR,
19 LIBPERF_WARN, 19 LIBPERF_WARN,
20 LIBPERF_INFO, 20 LIBPERF_INFO,
21 LIBPERF_DEBUG, 21 LIBPERF_DEBUG,
22 LIBPERF_DEBUG2, 22 LIBPERF_DEBUG2,
23 LIBPERF_DEBUG3, 23 LIBPERF_DEBUG3,
24 }; 24 };
25 25
26 typedef int (*libperf_print_fn_t)(enum libpe 26 typedef int (*libperf_print_fn_t)(enum libperf_print_level level,
27 const char 27 const char *, va_list ap);
28 28
29 void libperf_init(libperf_print_fn_t fn); 29 void libperf_init(libperf_print_fn_t fn);
30 -- 30 --
31 31
32 *API to handle CPU maps:* 32 *API to handle CPU maps:*
33 33
34 [source,c] 34 [source,c]
35 -- 35 --
36 #include <perf/cpumap.h> 36 #include <perf/cpumap.h>
37 37
38 struct perf_cpu_map; 38 struct perf_cpu_map;
39 39
40 struct perf_cpu_map *perf_cpu_map__new_any_c 40 struct perf_cpu_map *perf_cpu_map__new_any_cpu(void);
41 struct perf_cpu_map *perf_cpu_map__new(const 41 struct perf_cpu_map *perf_cpu_map__new(const char *cpu_list);
42 struct perf_cpu_map *perf_cpu_map__read(FILE 42 struct perf_cpu_map *perf_cpu_map__read(FILE *file);
43 struct perf_cpu_map *perf_cpu_map__get(struc 43 struct perf_cpu_map *perf_cpu_map__get(struct perf_cpu_map *map);
44 struct perf_cpu_map *perf_cpu_map__merge(str 44 struct perf_cpu_map *perf_cpu_map__merge(struct perf_cpu_map *orig,
45 str 45 struct perf_cpu_map *other);
46 void perf_cpu_map__put(struct perf_cpu_map * 46 void perf_cpu_map__put(struct perf_cpu_map *map);
47 int perf_cpu_map__cpu(const struct perf_cpu_ 47 int perf_cpu_map__cpu(const struct perf_cpu_map *cpus, int idx);
48 int perf_cpu_map__nr(const struct perf_cpu_m 48 int perf_cpu_map__nr(const struct perf_cpu_map *cpus);
49 bool perf_cpu_map__has_any_cpu_or_is_empty(c 49 bool perf_cpu_map__has_any_cpu_or_is_empty(const struct perf_cpu_map *map);
50 int perf_cpu_map__max(struct perf_cpu_map *m 50 int perf_cpu_map__max(struct perf_cpu_map *map);
51 bool perf_cpu_map__has(const struct perf_cpu 51 bool perf_cpu_map__has(const struct perf_cpu_map *map, int cpu);
52 52
53 #define perf_cpu_map__for_each_cpu(cpu, idx, 53 #define perf_cpu_map__for_each_cpu(cpu, idx, cpus)
54 -- 54 --
55 55
56 *API to handle thread maps:* 56 *API to handle thread maps:*
57 57
58 [source,c] 58 [source,c]
59 -- 59 --
60 #include <perf/threadmap.h> 60 #include <perf/threadmap.h>
61 61
62 struct perf_thread_map; 62 struct perf_thread_map;
63 63
64 struct perf_thread_map *perf_thread_map__new 64 struct perf_thread_map *perf_thread_map__new_dummy(void);
65 struct perf_thread_map *perf_thread_map__new 65 struct perf_thread_map *perf_thread_map__new_array(int nr_threads, pid_t *array);
66 66
67 void perf_thread_map__set_pid(struct perf_th 67 void perf_thread_map__set_pid(struct perf_thread_map *map, int idx, pid_t pid);
68 char *perf_thread_map__comm(struct perf_thre 68 char *perf_thread_map__comm(struct perf_thread_map *map, int idx);
69 int perf_thread_map__nr(struct perf_thread_m 69 int perf_thread_map__nr(struct perf_thread_map *threads);
70 pid_t perf_thread_map__pid(struct perf_threa 70 pid_t perf_thread_map__pid(struct perf_thread_map *map, int idx);
71 71
72 struct perf_thread_map *perf_thread_map__get 72 struct perf_thread_map *perf_thread_map__get(struct perf_thread_map *map);
73 void perf_thread_map__put(struct perf_thread 73 void perf_thread_map__put(struct perf_thread_map *map);
74 -- 74 --
75 75
76 *API to handle event lists:* 76 *API to handle event lists:*
77 77
78 [source,c] 78 [source,c]
79 -- 79 --
80 #include <perf/evlist.h> 80 #include <perf/evlist.h>
81 81
82 struct perf_evlist; 82 struct perf_evlist;
83 83
84 void perf_evlist__add(struct perf_evlist *ev 84 void perf_evlist__add(struct perf_evlist *evlist,
85 struct perf_evsel *evs 85 struct perf_evsel *evsel);
86 void perf_evlist__remove(struct perf_evlist 86 void perf_evlist__remove(struct perf_evlist *evlist,
87 struct perf_evsel * 87 struct perf_evsel *evsel);
88 struct perf_evlist *perf_evlist__new(void); 88 struct perf_evlist *perf_evlist__new(void);
89 void perf_evlist__delete(struct perf_evlist 89 void perf_evlist__delete(struct perf_evlist *evlist);
90 struct perf_evsel* perf_evlist__next(struct 90 struct perf_evsel* perf_evlist__next(struct perf_evlist *evlist,
91 struct 91 struct perf_evsel *evsel);
92 int perf_evlist__open(struct perf_evlist *ev 92 int perf_evlist__open(struct perf_evlist *evlist);
93 void perf_evlist__close(struct perf_evlist * 93 void perf_evlist__close(struct perf_evlist *evlist);
94 void perf_evlist__enable(struct perf_evlist 94 void perf_evlist__enable(struct perf_evlist *evlist);
95 void perf_evlist__disable(struct perf_evlist 95 void perf_evlist__disable(struct perf_evlist *evlist);
96 96
97 #define perf_evlist__for_each_evsel(evlist, 97 #define perf_evlist__for_each_evsel(evlist, pos)
98 98
99 void perf_evlist__set_maps(struct perf_evlis 99 void perf_evlist__set_maps(struct perf_evlist *evlist,
100 struct perf_cpu_m 100 struct perf_cpu_map *cpus,
101 struct perf_threa 101 struct perf_thread_map *threads);
102 int perf_evlist__poll(struct perf_evlist *ev 102 int perf_evlist__poll(struct perf_evlist *evlist, int timeout);
103 int perf_evlist__filter_pollfd(struct perf_e 103 int perf_evlist__filter_pollfd(struct perf_evlist *evlist,
104 short revents 104 short revents_and_mask);
105 105
106 int perf_evlist__mmap(struct perf_evlist *ev 106 int perf_evlist__mmap(struct perf_evlist *evlist, int pages);
107 void perf_evlist__munmap(struct perf_evlist 107 void perf_evlist__munmap(struct perf_evlist *evlist);
108 108
109 struct perf_mmap *perf_evlist__next_mmap(str 109 struct perf_mmap *perf_evlist__next_mmap(struct perf_evlist *evlist,
110 str 110 struct perf_mmap *map,
111 boo 111 bool overwrite);
112 112
113 #define perf_evlist__for_each_mmap(evlist, p 113 #define perf_evlist__for_each_mmap(evlist, pos, overwrite)
114 -- 114 --
115 115
116 *API to handle events:* 116 *API to handle events:*
117 117
118 [source,c] 118 [source,c]
119 -- 119 --
120 #include <perf/evsel.h>* 120 #include <perf/evsel.h>*
121 121
122 struct perf_evsel; 122 struct perf_evsel;
123 123
124 struct perf_counts_values { 124 struct perf_counts_values {
125 union { 125 union {
126 struct { 126 struct {
127 uint64_t val; 127 uint64_t val;
128 uint64_t ena; 128 uint64_t ena;
129 uint64_t run; 129 uint64_t run;
130 }; 130 };
131 uint64_t values[3]; 131 uint64_t values[3];
132 }; 132 };
133 }; 133 };
134 134
135 struct perf_evsel *perf_evsel__new(struct pe 135 struct perf_evsel *perf_evsel__new(struct perf_event_attr *attr);
136 void perf_evsel__delete(struct perf_evsel *e 136 void perf_evsel__delete(struct perf_evsel *evsel);
137 int perf_evsel__open(struct perf_evsel *evse 137 int perf_evsel__open(struct perf_evsel *evsel, struct perf_cpu_map *cpus,
138 struct perf_thread_map 138 struct perf_thread_map *threads);
139 void perf_evsel__close(struct perf_evsel *ev 139 void perf_evsel__close(struct perf_evsel *evsel);
140 void perf_evsel__close_cpu(struct perf_evsel 140 void perf_evsel__close_cpu(struct perf_evsel *evsel, int cpu_map_idx);
141 int perf_evsel__mmap(struct perf_evsel *evse 141 int perf_evsel__mmap(struct perf_evsel *evsel, int pages);
142 void perf_evsel__munmap(struct perf_evsel *e 142 void perf_evsel__munmap(struct perf_evsel *evsel);
143 void *perf_evsel__mmap_base(struct perf_evse 143 void *perf_evsel__mmap_base(struct perf_evsel *evsel, int cpu_map_idx, int thread);
144 int perf_evsel__read(struct perf_evsel *evse 144 int perf_evsel__read(struct perf_evsel *evsel, int cpu_map_idx, int thread,
145 struct perf_counts_valu 145 struct perf_counts_values *count);
146 int perf_evsel__enable(struct perf_evsel *ev 146 int perf_evsel__enable(struct perf_evsel *evsel);
147 int perf_evsel__enable_cpu(struct perf_evsel 147 int perf_evsel__enable_cpu(struct perf_evsel *evsel, int cpu_map_idx);
148 int perf_evsel__disable(struct perf_evsel *e 148 int perf_evsel__disable(struct perf_evsel *evsel);
149 int perf_evsel__disable_cpu(struct perf_evse 149 int perf_evsel__disable_cpu(struct perf_evsel *evsel, int cpu_map_idx);
150 struct perf_cpu_map *perf_evsel__cpus(struct 150 struct perf_cpu_map *perf_evsel__cpus(struct perf_evsel *evsel);
151 struct perf_thread_map *perf_evsel__threads( 151 struct perf_thread_map *perf_evsel__threads(struct perf_evsel *evsel);
152 struct perf_event_attr *perf_evsel__attr(str 152 struct perf_event_attr *perf_evsel__attr(struct perf_evsel *evsel);
153 -- 153 --
154 154
155 *API to handle maps (perf ring buffers):* 155 *API to handle maps (perf ring buffers):*
156 156
157 [source,c] 157 [source,c]
158 -- 158 --
159 #include <perf/mmap.h> 159 #include <perf/mmap.h>
160 160
161 struct perf_mmap; 161 struct perf_mmap;
162 162
163 void perf_mmap__consume(struct perf_mmap *ma 163 void perf_mmap__consume(struct perf_mmap *map);
164 int perf_mmap__read_init(struct perf_mmap *m 164 int perf_mmap__read_init(struct perf_mmap *map);
165 void perf_mmap__read_done(struct perf_mmap * 165 void perf_mmap__read_done(struct perf_mmap *map);
166 union perf_event *perf_mmap__read_event(stru 166 union perf_event *perf_mmap__read_event(struct perf_mmap *map);
167 -- 167 --
168 168
169 *Structures to access perf API events:* 169 *Structures to access perf API events:*
170 170
171 [source,c] 171 [source,c]
172 -- 172 --
173 #include <perf/event.h> 173 #include <perf/event.h>
174 174
175 struct perf_record_mmap; 175 struct perf_record_mmap;
176 struct perf_record_mmap2; 176 struct perf_record_mmap2;
177 struct perf_record_comm; 177 struct perf_record_comm;
178 struct perf_record_namespaces; 178 struct perf_record_namespaces;
179 struct perf_record_fork; 179 struct perf_record_fork;
180 struct perf_record_lost; 180 struct perf_record_lost;
181 struct perf_record_lost_samples; 181 struct perf_record_lost_samples;
182 struct perf_record_read; 182 struct perf_record_read;
183 struct perf_record_throttle; 183 struct perf_record_throttle;
184 struct perf_record_ksymbol; 184 struct perf_record_ksymbol;
185 struct perf_record_bpf_event; 185 struct perf_record_bpf_event;
186 struct perf_record_sample; 186 struct perf_record_sample;
187 struct perf_record_switch; 187 struct perf_record_switch;
188 struct perf_record_header_attr; 188 struct perf_record_header_attr;
189 struct perf_record_record_cpu_map; 189 struct perf_record_record_cpu_map;
190 struct perf_record_cpu_map_data; 190 struct perf_record_cpu_map_data;
191 struct perf_record_cpu_map; 191 struct perf_record_cpu_map;
192 struct perf_record_event_update_cpus; 192 struct perf_record_event_update_cpus;
193 struct perf_record_event_update_scale; 193 struct perf_record_event_update_scale;
194 struct perf_record_event_update; 194 struct perf_record_event_update;
195 struct perf_trace_event_type; 195 struct perf_trace_event_type;
196 struct perf_record_header_event_type; 196 struct perf_record_header_event_type;
197 struct perf_record_header_tracing_data; 197 struct perf_record_header_tracing_data;
198 struct perf_record_header_build_id; 198 struct perf_record_header_build_id;
199 struct perf_record_id_index; 199 struct perf_record_id_index;
200 struct perf_record_auxtrace_info; 200 struct perf_record_auxtrace_info;
201 struct perf_record_auxtrace; 201 struct perf_record_auxtrace;
202 struct perf_record_auxtrace_error; 202 struct perf_record_auxtrace_error;
203 struct perf_record_aux; 203 struct perf_record_aux;
204 struct perf_record_itrace_start; 204 struct perf_record_itrace_start;
205 struct perf_record_thread_map_entry; 205 struct perf_record_thread_map_entry;
206 struct perf_record_thread_map; 206 struct perf_record_thread_map;
207 struct perf_record_stat_config_entry; 207 struct perf_record_stat_config_entry;
208 struct perf_record_stat_config; 208 struct perf_record_stat_config;
209 struct perf_record_stat; 209 struct perf_record_stat;
210 struct perf_record_stat_round; 210 struct perf_record_stat_round;
211 struct perf_record_time_conv; 211 struct perf_record_time_conv;
212 struct perf_record_header_feature; 212 struct perf_record_header_feature;
213 struct perf_record_compressed; 213 struct perf_record_compressed;
214 -- 214 --
215 215
216 DESCRIPTION 216 DESCRIPTION
217 ----------- 217 -----------
218 The libperf library provides an API to access 218 The libperf library provides an API to access the linux kernel perf
219 events subsystem. 219 events subsystem.
220 220
221 Following objects are key to the libperf inter 221 Following objects are key to the libperf interface:
222 222
223 [horizontal] 223 [horizontal]
224 224
225 struct perf_cpu_map:: Provides a CPU list abst 225 struct perf_cpu_map:: Provides a CPU list abstraction.
226 226
227 struct perf_thread_map:: Provides a thread lis 227 struct perf_thread_map:: Provides a thread list abstraction.
228 228
229 struct perf_evsel:: Provides an abstraction fo 229 struct perf_evsel:: Provides an abstraction for single a perf event.
230 230
231 struct perf_evlist:: Gathers several struct pe 231 struct perf_evlist:: Gathers several struct perf_evsel object and performs functions on all of them.
232 232
233 struct perf_mmap:: Provides an abstraction for 233 struct perf_mmap:: Provides an abstraction for accessing perf ring buffer.
234 234
235 The exported API functions bind these objects 235 The exported API functions bind these objects together.
236 236
237 REPORTING BUGS 237 REPORTING BUGS
238 -------------- 238 --------------
239 Report bugs to <linux-perf-users@vger.kernel.or 239 Report bugs to <linux-perf-users@vger.kernel.org>.
240 240
241 LICENSE 241 LICENSE
242 ------- 242 -------
243 libperf is Free Software licensed under the GN 243 libperf is Free Software licensed under the GNU LGPL 2.1
244 244
245 RESOURCES 245 RESOURCES
246 --------- 246 ---------
247 https://git.kernel.org/pub/scm/linux/kernel/gi 247 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
248 248
249 SEE ALSO 249 SEE ALSO
250 -------- 250 --------
251 libperf-sampling(7), libperf-counting(7) 251 libperf-sampling(7), libperf-counting(7)
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.