1LIBPERF(3)                      libperf Manual                      LIBPERF(3)
2
3
4

NAME

6       libperf - Linux kernel perf event library
7

SYNOPSIS

9       Generic API:
10
11         #include <perf/core.h>
12
13         enum libperf_print_level {
14                 LIBPERF_ERR,
15                 LIBPERF_WARN,
16                 LIBPERF_INFO,
17                 LIBPERF_DEBUG,
18                 LIBPERF_DEBUG2,
19                 LIBPERF_DEBUG3,
20         };
21
22         typedef int (*libperf_print_fn_t)(enum libperf_print_level level,
23                                           const char *, va_list ap);
24
25         void libperf_init(libperf_print_fn_t fn);
26
27       API to handle CPU maps:
28
29         #include <perf/cpumap.h>
30
31         struct perf_cpu_map;
32
33         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
46         #define perf_cpu_map__for_each_cpu(cpu, idx, cpus)
47
48       API to handle thread maps:
49
50         #include <perf/threadmap.h>
51
52         struct perf_thread_map;
53
54         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
57         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
62         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
65       API to handle event lists:
66
67         #include <perf/evlist.h>
68
69         struct perf_evlist;
70
71         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
84         #define perf_evlist__for_each_evsel(evlist, pos)
85
86         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
93         int perf_evlist__mmap(struct perf_evlist *evlist, int pages);
94         void perf_evlist__munmap(struct perf_evlist *evlist);
95
96         struct perf_mmap *perf_evlist__next_mmap(struct perf_evlist *evlist,
97                                                  struct perf_mmap *map,
98                                                  bool overwrite);
99
100         #define perf_evlist__for_each_mmap(evlist, pos, overwrite)
101
102       API to handle events:
103
104         #include <perf/evsel.h>*
105
106         struct perf_evsel;
107
108         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
119         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
138       API to handle maps (perf ring buffers):
139
140         #include <perf/mmap.h>
141
142         struct perf_mmap;
143
144         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
149       Structures to access perf API events:
150
151         #include <perf/event.h>
152
153         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

DESCRIPTION

194       The libperf library provides an API to access the linux kernel perf
195       events subsystem.
196
197       Following objects are key to the libperf interface:
198
199
200       struct perf_cpu_map      Provides a CPU list
201                                abstraction.
202
203       struct perf_thread_map   Provides a thread list
204                                abstraction.
205
206       struct perf_evsel        Provides an abstraction
207                                for single a perf event.
208
209       struct perf_evlist       Gathers several struct
210                                perf_evsel object and
211                                performs functions on all
212                                of them.
213
214       struct perf_mmap         Provides an abstraction
215                                for accessing perf ring
216                                buffer.
217
218
219       The exported API functions bind these objects together.
220

REPORTING BUGS

222       Report bugs to <linux-perf-users@vger.kernel.org[1]>.
223

LICENSE

225       libperf is Free Software licensed under the GNU LGPL 2.1
226

RESOURCES

228       https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
229

SEE ALSO

231       libperf-sampling(7), libperf-counting(7)
232

NOTES

234        1. linux-perf-users@vger.kernel.org
235           mailto:linux-perf-users@vger.kernel.org
236
237
238
239libperf                           11/28/2023                        LIBPERF(3)
Impressum