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__dummy_new(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__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