252 lines · plain
1libperf(3)2==========3 4NAME5----6libperf - Linux kernel perf event library7 8 9SYNOPSIS10--------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 216DESCRIPTION217-----------218The libperf library provides an API to access the linux kernel perf219events 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 BUGS238--------------239Report bugs to <linux-perf-users@vger.kernel.org>.240 241LICENSE242-------243libperf is Free Software licensed under the GNU LGPL 2.1244 245RESOURCES246---------247https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git248 249SEE ALSO250--------251libperf-sampling(7), libperf-counting(7)252