1libperf(3)
2==========
3
4NAME
5----
6libperf - Linux kernel perf event library
7
8
9SYNOPSIS
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
216DESCRIPTION
217-----------
218The libperf library provides an API to access the linux kernel perf
219events subsystem.
220
221Following objects are key to the libperf interface:
222
223[horizontal]
224
225struct perf_cpu_map:: Provides a CPU list abstraction.
226
227struct perf_thread_map:: Provides a thread list abstraction.
228
229struct perf_evsel:: Provides an abstraction for single a perf event.
230
231struct perf_evlist:: Gathers several struct perf_evsel object and performs functions on all of them.
232
233struct perf_mmap:: Provides an abstraction for accessing perf ring buffer.
234
235The exported API functions bind these objects together.
236
237REPORTING BUGS
238--------------
239Report bugs to <linux-perf-users@vger.kernel.org>.
240
241LICENSE
242-------
243libperf is Free Software licensed under the GNU LGPL 2.1
244
245RESOURCES
246---------
247https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
248
249SEE ALSO
250--------
251libperf-sampling(7), libperf-counting(7)
252