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 66 void perf_thread_map__set_pid(struct perf_thread_map *map, int thread, pid_t pid); 67 char *perf_thread_map__comm(struct perf_thread_map *map, int thread); 68 int perf_thread_map__nr(struct perf_thread_map *threads); 69 pid_t perf_thread_map__pid(struct perf_thread_map *map, int thread); 70 71 struct perf_thread_map *perf_thread_map__get(struct perf_thread_map *map); 72 void perf_thread_map__put(struct perf_thread_map *map); 73-- 74 75*API to handle event lists:* 76 77[source,c] 78-- 79 #include <perf/evlist.h> 80 81 struct perf_evlist; 82 83 void perf_evlist__add(struct perf_evlist *evlist, 84 struct perf_evsel *evsel); 85 void perf_evlist__remove(struct perf_evlist *evlist, 86 struct perf_evsel *evsel); 87 struct perf_evlist *perf_evlist__new(void); 88 void perf_evlist__delete(struct perf_evlist *evlist); 89 struct perf_evsel* perf_evlist__next(struct perf_evlist *evlist, 90 struct perf_evsel *evsel); 91 int perf_evlist__open(struct perf_evlist *evlist); 92 void perf_evlist__close(struct perf_evlist *evlist); 93 void perf_evlist__enable(struct perf_evlist *evlist); 94 void perf_evlist__disable(struct perf_evlist *evlist); 95 96 #define perf_evlist__for_each_evsel(evlist, pos) 97 98 void perf_evlist__set_maps(struct perf_evlist *evlist, 99 struct perf_cpu_map *cpus, 100 struct perf_thread_map *threads); 101 int perf_evlist__poll(struct perf_evlist *evlist, int timeout); 102 int perf_evlist__filter_pollfd(struct perf_evlist *evlist, 103 short revents_and_mask); 104 105 int perf_evlist__mmap(struct perf_evlist *evlist, int pages); 106 void perf_evlist__munmap(struct perf_evlist *evlist); 107 108 struct perf_mmap *perf_evlist__next_mmap(struct perf_evlist *evlist, 109 struct perf_mmap *map, 110 bool overwrite); 111 112 #define perf_evlist__for_each_mmap(evlist, pos, overwrite) 113-- 114 115*API to handle events:* 116 117[source,c] 118-- 119 #include <perf/evsel.h>* 120 121 struct perf_evsel; 122 123 struct perf_counts_values { 124 union { 125 struct { 126 uint64_t val; 127 uint64_t ena; 128 uint64_t run; 129 }; 130 uint64_t values[3]; 131 }; 132 }; 133 134 struct perf_evsel *perf_evsel__new(struct perf_event_attr *attr); 135 void perf_evsel__delete(struct perf_evsel *evsel); 136 int perf_evsel__open(struct perf_evsel *evsel, struct perf_cpu_map *cpus, 137 struct perf_thread_map *threads); 138 void perf_evsel__close(struct perf_evsel *evsel); 139 void perf_evsel__close_cpu(struct perf_evsel *evsel, int cpu_map_idx); 140 int perf_evsel__mmap(struct perf_evsel *evsel, int pages); 141 void perf_evsel__munmap(struct perf_evsel *evsel); 142 void *perf_evsel__mmap_base(struct perf_evsel *evsel, int cpu_map_idx, int thread); 143 int perf_evsel__read(struct perf_evsel *evsel, int cpu_map_idx, int thread, 144 struct perf_counts_values *count); 145 int perf_evsel__enable(struct perf_evsel *evsel); 146 int perf_evsel__enable_cpu(struct perf_evsel *evsel, int cpu_map_idx); 147 int perf_evsel__disable(struct perf_evsel *evsel); 148 int perf_evsel__disable_cpu(struct perf_evsel *evsel, int cpu_map_idx); 149 struct perf_cpu_map *perf_evsel__cpus(struct perf_evsel *evsel); 150 struct perf_thread_map *perf_evsel__threads(struct perf_evsel *evsel); 151 struct perf_event_attr *perf_evsel__attr(struct perf_evsel *evsel); 152-- 153 154*API to handle maps (perf ring buffers):* 155 156[source,c] 157-- 158 #include <perf/mmap.h> 159 160 struct perf_mmap; 161 162 void perf_mmap__consume(struct perf_mmap *map); 163 int perf_mmap__read_init(struct perf_mmap *map); 164 void perf_mmap__read_done(struct perf_mmap *map); 165 union perf_event *perf_mmap__read_event(struct perf_mmap *map); 166-- 167 168*Structures to access perf API events:* 169 170[source,c] 171-- 172 #include <perf/event.h> 173 174 struct perf_record_mmap; 175 struct perf_record_mmap2; 176 struct perf_record_comm; 177 struct perf_record_namespaces; 178 struct perf_record_fork; 179 struct perf_record_lost; 180 struct perf_record_lost_samples; 181 struct perf_record_read; 182 struct perf_record_throttle; 183 struct perf_record_ksymbol; 184 struct perf_record_bpf_event; 185 struct perf_record_sample; 186 struct perf_record_switch; 187 struct perf_record_header_attr; 188 struct perf_record_record_cpu_map; 189 struct perf_record_cpu_map_data; 190 struct perf_record_cpu_map; 191 struct perf_record_event_update_cpus; 192 struct perf_record_event_update_scale; 193 struct perf_record_event_update; 194 struct perf_trace_event_type; 195 struct perf_record_header_event_type; 196 struct perf_record_header_tracing_data; 197 struct perf_record_header_build_id; 198 struct perf_record_id_index; 199 struct perf_record_auxtrace_info; 200 struct perf_record_auxtrace; 201 struct perf_record_auxtrace_error; 202 struct perf_record_aux; 203 struct perf_record_itrace_start; 204 struct perf_record_thread_map_entry; 205 struct perf_record_thread_map; 206 struct perf_record_stat_config_entry; 207 struct perf_record_stat_config; 208 struct perf_record_stat; 209 struct perf_record_stat_round; 210 struct perf_record_time_conv; 211 struct perf_record_header_feature; 212 struct perf_record_compressed; 213-- 214 215DESCRIPTION 216----------- 217The libperf library provides an API to access the linux kernel perf 218events subsystem. 219 220Following objects are key to the libperf interface: 221 222[horizontal] 223 224struct perf_cpu_map:: Provides a CPU list abstraction. 225 226struct perf_thread_map:: Provides a thread list abstraction. 227 228struct perf_evsel:: Provides an abstraction for single a perf event. 229 230struct perf_evlist:: Gathers several struct perf_evsel object and performs functions on all of them. 231 232struct perf_mmap:: Provides an abstraction for accessing perf ring buffer. 233 234The exported API functions bind these objects together. 235 236REPORTING BUGS 237-------------- 238Report bugs to <linux-perf-users@vger.kernel.org>. 239 240LICENSE 241------- 242libperf is Free Software licensed under the GNU LGPL 2.1 243 244RESOURCES 245--------- 246https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 247 248SEE ALSO 249-------- 250libperf-sampling(7), libperf-counting(7) 251