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