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