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 #define perf_cpu_map__for_each_cpu(cpu, idx, cpus)
46 API to handle thread maps:
48 #include <perf/threadmap.h>
50 struct perf_thread_map;
52 struct perf_thread_map *perf_thread_map__new_dummy(void);
54 void perf_thread_map__set_pid(struct perf_thread_map *map, int thread, pid_t pid);
56 char *perf_thread_map__comm(struct perf_thread_map *map, int thread);
57 int perf_thread_map__nr(struct perf_thread_map *threads);
58 pid_t perf_thread_map__pid(struct perf_thread_map *map, int thread);
59 struct perf_thread_map *perf_thread_map__get(struct perf_thread_map *map);
61 void perf_thread_map__put(struct perf_thread_map *map);
62 API to handle event lists:
64 #include <perf/evlist.h>
66 struct perf_evlist;
68 void perf_evlist__add(struct perf_evlist *evlist,
70 struct perf_evsel *evsel);
71 void perf_evlist__remove(struct perf_evlist *evlist,
72 struct perf_evsel *evsel);
73 struct perf_evlist *perf_evlist__new(void);
74 void perf_evlist__delete(struct perf_evlist *evlist);
75 struct perf_evsel* perf_evlist__next(struct perf_evlist *evlist,
76 struct perf_evsel *evsel);
77 int perf_evlist__open(struct perf_evlist *evlist);
78 void perf_evlist__close(struct perf_evlist *evlist);
79 void perf_evlist__enable(struct perf_evlist *evlist);
80 void perf_evlist__disable(struct perf_evlist *evlist);
81 #define perf_evlist__for_each_evsel(evlist, pos)
83 void perf_evlist__set_maps(struct perf_evlist *evlist,
85 struct perf_cpu_map *cpus,
86 struct perf_thread_map *threads);
87 int perf_evlist__poll(struct perf_evlist *evlist, int timeout);
88 int perf_evlist__filter_pollfd(struct perf_evlist *evlist,
89 short revents_and_mask);
90 int perf_evlist__mmap(struct perf_evlist *evlist, int pages);
92 void perf_evlist__munmap(struct perf_evlist *evlist);
93 struct perf_mmap *perf_evlist__next_mmap(struct perf_evlist *evlist,
95 struct perf_mmap *map,
96 bool overwrite);
97 #define perf_evlist__for_each_mmap(evlist, pos, overwrite)
99 API to handle events:
101 #include <perf/evsel.h>*
103 struct perf_evsel;
105 struct perf_counts_values {
107 union {
108 struct {
109 uint64_t val;
110 uint64_t ena;
111 uint64_t run;
112 };
113 uint64_t values[3];
114 };
115 };
116 struct perf_evsel *perf_evsel__new(struct perf_event_attr *attr);
118 void perf_evsel__delete(struct perf_evsel *evsel);
119 int perf_evsel__open(struct perf_evsel *evsel, struct perf_cpu_map *cpus,
120 struct perf_thread_map *threads);
121 void perf_evsel__close(struct perf_evsel *evsel);
122 void perf_evsel__close_cpu(struct perf_evsel *evsel, int cpu);
123 int perf_evsel__mmap(struct perf_evsel *evsel, int pages);
124 void perf_evsel__munmap(struct perf_evsel *evsel);
125 void *perf_evsel__mmap_base(struct perf_evsel *evsel, int cpu, int thread);
126 int perf_evsel__read(struct perf_evsel *evsel, int cpu, int thread,
127 struct perf_counts_values *count);
128 int perf_evsel__enable(struct perf_evsel *evsel);
129 int perf_evsel__enable_cpu(struct perf_evsel *evsel, int cpu);
130 int perf_evsel__disable(struct perf_evsel *evsel);
131 int perf_evsel__disable_cpu(struct perf_evsel *evsel, int cpu);
132 struct perf_cpu_map *perf_evsel__cpus(struct perf_evsel *evsel);
133 struct perf_thread_map *perf_evsel__threads(struct perf_evsel *evsel);
134 struct perf_event_attr *perf_evsel__attr(struct perf_evsel *evsel);
135 API to handle maps (perf ring buffers):
137 #include <perf/mmap.h>
139 struct perf_mmap;
141 void perf_mmap__consume(struct perf_mmap *map);
143 int perf_mmap__read_init(struct perf_mmap *map);
144 void perf_mmap__read_done(struct perf_mmap *map);
145 union perf_event *perf_mmap__read_event(struct perf_mmap *map);
146 Structures to access perf API events:
148 #include <perf/event.h>
150 struct perf_record_mmap;
152 struct perf_record_mmap2;
153 struct perf_record_comm;
154 struct perf_record_namespaces;
155 struct perf_record_fork;
156 struct perf_record_lost;
157 struct perf_record_lost_samples;
158 struct perf_record_read;
159 struct perf_record_throttle;
160 struct perf_record_ksymbol;
161 struct perf_record_bpf_event;
162 struct perf_record_sample;
163 struct perf_record_switch;
164 struct perf_record_header_attr;
165 struct perf_record_record_cpu_map;
166 struct perf_record_cpu_map_data;
167 struct perf_record_cpu_map;
168 struct perf_record_event_update_cpus;
169 struct perf_record_event_update_scale;
170 struct perf_record_event_update;
171 struct perf_trace_event_type;
172 struct perf_record_header_event_type;
173 struct perf_record_header_tracing_data;
174 struct perf_record_header_build_id;
175 struct perf_record_id_index;
176 struct perf_record_auxtrace_info;
177 struct perf_record_auxtrace;
178 struct perf_record_auxtrace_error;
179 struct perf_record_aux;
180 struct perf_record_itrace_start;
181 struct perf_record_thread_map_entry;
182 struct perf_record_thread_map;
183 struct perf_record_stat_config_entry;
184 struct perf_record_stat_config;
185 struct perf_record_stat;
186 struct perf_record_stat_round;
187 struct perf_record_time_conv;
188 struct perf_record_header_feature;
189 struct perf_record_compressed;
190
192 The libperf library provides an API to access the linux kernel perf
193 events subsystem.
194 Following objects are key to the libperf interface:
196 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/22/2021 LIBPERF(3)