181de3bf3SJiri Olsalibperf(3) 281de3bf3SJiri Olsa========== 381de3bf3SJiri Olsa 481de3bf3SJiri OlsaNAME 581de3bf3SJiri Olsa---- 681de3bf3SJiri Olsalibperf - Linux kernel perf event library 781de3bf3SJiri Olsa 881de3bf3SJiri Olsa 981de3bf3SJiri OlsaSYNOPSIS 1081de3bf3SJiri Olsa-------- 1181de3bf3SJiri Olsa*Generic API:* 1281de3bf3SJiri Olsa 1381de3bf3SJiri Olsa[source,c] 1481de3bf3SJiri Olsa-- 1581de3bf3SJiri Olsa #include <perf/core.h> 1681de3bf3SJiri Olsa 1781de3bf3SJiri Olsa enum libperf_print_level { 1881de3bf3SJiri Olsa LIBPERF_ERR, 1981de3bf3SJiri Olsa LIBPERF_WARN, 2081de3bf3SJiri Olsa LIBPERF_INFO, 2181de3bf3SJiri Olsa LIBPERF_DEBUG, 2281de3bf3SJiri Olsa LIBPERF_DEBUG2, 2381de3bf3SJiri Olsa LIBPERF_DEBUG3, 2481de3bf3SJiri Olsa }; 2581de3bf3SJiri Olsa 2681de3bf3SJiri Olsa typedef int (*libperf_print_fn_t)(enum libperf_print_level level, 2781de3bf3SJiri Olsa const char *, va_list ap); 2881de3bf3SJiri Olsa 2981de3bf3SJiri Olsa void libperf_init(libperf_print_fn_t fn); 3081de3bf3SJiri Olsa-- 3181de3bf3SJiri Olsa 32ce746d43SRob Herring*API to handle CPU maps:* 3381de3bf3SJiri Olsa 3481de3bf3SJiri Olsa[source,c] 3581de3bf3SJiri Olsa-- 3681de3bf3SJiri Olsa #include <perf/cpumap.h> 3781de3bf3SJiri Olsa 3881de3bf3SJiri Olsa struct perf_cpu_map; 3981de3bf3SJiri Olsa 4081de3bf3SJiri Olsa struct perf_cpu_map *perf_cpu_map__dummy_new(void); 4181de3bf3SJiri Olsa struct perf_cpu_map *perf_cpu_map__new(const char *cpu_list); 4281de3bf3SJiri Olsa struct perf_cpu_map *perf_cpu_map__read(FILE *file); 4381de3bf3SJiri Olsa struct perf_cpu_map *perf_cpu_map__get(struct perf_cpu_map *map); 4481de3bf3SJiri Olsa struct perf_cpu_map *perf_cpu_map__merge(struct perf_cpu_map *orig, 4581de3bf3SJiri Olsa struct perf_cpu_map *other); 4681de3bf3SJiri Olsa void perf_cpu_map__put(struct perf_cpu_map *map); 4781de3bf3SJiri Olsa int perf_cpu_map__cpu(const struct perf_cpu_map *cpus, int idx); 4881de3bf3SJiri Olsa int perf_cpu_map__nr(const struct perf_cpu_map *cpus); 4981de3bf3SJiri Olsa bool perf_cpu_map__empty(const struct perf_cpu_map *map); 5081de3bf3SJiri Olsa int perf_cpu_map__max(struct perf_cpu_map *map); 51dfc66befSIan Rogers bool perf_cpu_map__has(const struct perf_cpu_map *map, int cpu); 5281de3bf3SJiri Olsa 5381de3bf3SJiri Olsa #define perf_cpu_map__for_each_cpu(cpu, idx, cpus) 5481de3bf3SJiri Olsa-- 5581de3bf3SJiri Olsa 5681de3bf3SJiri Olsa*API to handle thread maps:* 5781de3bf3SJiri Olsa 5881de3bf3SJiri Olsa[source,c] 5981de3bf3SJiri Olsa-- 6081de3bf3SJiri Olsa #include <perf/threadmap.h> 6181de3bf3SJiri Olsa 6281de3bf3SJiri Olsa struct perf_thread_map; 6381de3bf3SJiri Olsa 6481de3bf3SJiri Olsa struct perf_thread_map *perf_thread_map__new_dummy(void); 65*56dce868STzvetomir Stoyanov (VMware) struct perf_thread_map *perf_thread_map__new_array(int nr_threads, pid_t *array); 6681de3bf3SJiri Olsa 6741415b8aSTzvetomir Stoyanov (VMware) void perf_thread_map__set_pid(struct perf_thread_map *map, int idx, pid_t pid); 6841415b8aSTzvetomir Stoyanov (VMware) char *perf_thread_map__comm(struct perf_thread_map *map, int idx); 6981de3bf3SJiri Olsa int perf_thread_map__nr(struct perf_thread_map *threads); 7041415b8aSTzvetomir Stoyanov (VMware) pid_t perf_thread_map__pid(struct perf_thread_map *map, int idx); 7181de3bf3SJiri Olsa 7281de3bf3SJiri Olsa struct perf_thread_map *perf_thread_map__get(struct perf_thread_map *map); 7381de3bf3SJiri Olsa void perf_thread_map__put(struct perf_thread_map *map); 7481de3bf3SJiri Olsa-- 7581de3bf3SJiri Olsa 7681de3bf3SJiri Olsa*API to handle event lists:* 7781de3bf3SJiri Olsa 7881de3bf3SJiri Olsa[source,c] 7981de3bf3SJiri Olsa-- 8081de3bf3SJiri Olsa #include <perf/evlist.h> 8181de3bf3SJiri Olsa 8281de3bf3SJiri Olsa struct perf_evlist; 8381de3bf3SJiri Olsa 8481de3bf3SJiri Olsa void perf_evlist__add(struct perf_evlist *evlist, 8581de3bf3SJiri Olsa struct perf_evsel *evsel); 8681de3bf3SJiri Olsa void perf_evlist__remove(struct perf_evlist *evlist, 8781de3bf3SJiri Olsa struct perf_evsel *evsel); 8881de3bf3SJiri Olsa struct perf_evlist *perf_evlist__new(void); 8981de3bf3SJiri Olsa void perf_evlist__delete(struct perf_evlist *evlist); 9081de3bf3SJiri Olsa struct perf_evsel* perf_evlist__next(struct perf_evlist *evlist, 9181de3bf3SJiri Olsa struct perf_evsel *evsel); 9281de3bf3SJiri Olsa int perf_evlist__open(struct perf_evlist *evlist); 9381de3bf3SJiri Olsa void perf_evlist__close(struct perf_evlist *evlist); 9481de3bf3SJiri Olsa void perf_evlist__enable(struct perf_evlist *evlist); 9581de3bf3SJiri Olsa void perf_evlist__disable(struct perf_evlist *evlist); 9681de3bf3SJiri Olsa 9781de3bf3SJiri Olsa #define perf_evlist__for_each_evsel(evlist, pos) 9881de3bf3SJiri Olsa 9981de3bf3SJiri Olsa void perf_evlist__set_maps(struct perf_evlist *evlist, 10081de3bf3SJiri Olsa struct perf_cpu_map *cpus, 10181de3bf3SJiri Olsa struct perf_thread_map *threads); 10281de3bf3SJiri Olsa int perf_evlist__poll(struct perf_evlist *evlist, int timeout); 10381de3bf3SJiri Olsa int perf_evlist__filter_pollfd(struct perf_evlist *evlist, 10481de3bf3SJiri Olsa short revents_and_mask); 10581de3bf3SJiri Olsa 10681de3bf3SJiri Olsa int perf_evlist__mmap(struct perf_evlist *evlist, int pages); 10781de3bf3SJiri Olsa void perf_evlist__munmap(struct perf_evlist *evlist); 10881de3bf3SJiri Olsa 10981de3bf3SJiri Olsa struct perf_mmap *perf_evlist__next_mmap(struct perf_evlist *evlist, 11081de3bf3SJiri Olsa struct perf_mmap *map, 11181de3bf3SJiri Olsa bool overwrite); 11281de3bf3SJiri Olsa 11381de3bf3SJiri Olsa #define perf_evlist__for_each_mmap(evlist, pos, overwrite) 11481de3bf3SJiri Olsa-- 11581de3bf3SJiri Olsa 11681de3bf3SJiri Olsa*API to handle events:* 11781de3bf3SJiri Olsa 11881de3bf3SJiri Olsa[source,c] 11981de3bf3SJiri Olsa-- 12081de3bf3SJiri Olsa #include <perf/evsel.h>* 12181de3bf3SJiri Olsa 12281de3bf3SJiri Olsa struct perf_evsel; 12381de3bf3SJiri Olsa 12481de3bf3SJiri Olsa struct perf_counts_values { 12581de3bf3SJiri Olsa union { 12681de3bf3SJiri Olsa struct { 12781de3bf3SJiri Olsa uint64_t val; 12881de3bf3SJiri Olsa uint64_t ena; 12981de3bf3SJiri Olsa uint64_t run; 13081de3bf3SJiri Olsa }; 13181de3bf3SJiri Olsa uint64_t values[3]; 13281de3bf3SJiri Olsa }; 13381de3bf3SJiri Olsa }; 13481de3bf3SJiri Olsa 13581de3bf3SJiri Olsa struct perf_evsel *perf_evsel__new(struct perf_event_attr *attr); 13681de3bf3SJiri Olsa void perf_evsel__delete(struct perf_evsel *evsel); 13781de3bf3SJiri Olsa int perf_evsel__open(struct perf_evsel *evsel, struct perf_cpu_map *cpus, 13881de3bf3SJiri Olsa struct perf_thread_map *threads); 13981de3bf3SJiri Olsa void perf_evsel__close(struct perf_evsel *evsel); 14091802e73SIan Rogers void perf_evsel__close_cpu(struct perf_evsel *evsel, int cpu_map_idx); 1416cd70754SRob Herring int perf_evsel__mmap(struct perf_evsel *evsel, int pages); 1426cd70754SRob Herring void perf_evsel__munmap(struct perf_evsel *evsel); 14391802e73SIan Rogers void *perf_evsel__mmap_base(struct perf_evsel *evsel, int cpu_map_idx, int thread); 14491802e73SIan Rogers int perf_evsel__read(struct perf_evsel *evsel, int cpu_map_idx, int thread, 14581de3bf3SJiri Olsa struct perf_counts_values *count); 14681de3bf3SJiri Olsa int perf_evsel__enable(struct perf_evsel *evsel); 14791802e73SIan Rogers int perf_evsel__enable_cpu(struct perf_evsel *evsel, int cpu_map_idx); 14881de3bf3SJiri Olsa int perf_evsel__disable(struct perf_evsel *evsel); 14991802e73SIan Rogers int perf_evsel__disable_cpu(struct perf_evsel *evsel, int cpu_map_idx); 15081de3bf3SJiri Olsa struct perf_cpu_map *perf_evsel__cpus(struct perf_evsel *evsel); 15181de3bf3SJiri Olsa struct perf_thread_map *perf_evsel__threads(struct perf_evsel *evsel); 15281de3bf3SJiri Olsa struct perf_event_attr *perf_evsel__attr(struct perf_evsel *evsel); 15381de3bf3SJiri Olsa-- 15481de3bf3SJiri Olsa 15581de3bf3SJiri Olsa*API to handle maps (perf ring buffers):* 15681de3bf3SJiri Olsa 15781de3bf3SJiri Olsa[source,c] 15881de3bf3SJiri Olsa-- 15981de3bf3SJiri Olsa #include <perf/mmap.h> 16081de3bf3SJiri Olsa 16181de3bf3SJiri Olsa struct perf_mmap; 16281de3bf3SJiri Olsa 16381de3bf3SJiri Olsa void perf_mmap__consume(struct perf_mmap *map); 16481de3bf3SJiri Olsa int perf_mmap__read_init(struct perf_mmap *map); 16581de3bf3SJiri Olsa void perf_mmap__read_done(struct perf_mmap *map); 16681de3bf3SJiri Olsa union perf_event *perf_mmap__read_event(struct perf_mmap *map); 16781de3bf3SJiri Olsa-- 16881de3bf3SJiri Olsa 16981de3bf3SJiri Olsa*Structures to access perf API events:* 17081de3bf3SJiri Olsa 17181de3bf3SJiri Olsa[source,c] 17281de3bf3SJiri Olsa-- 17381de3bf3SJiri Olsa #include <perf/event.h> 17481de3bf3SJiri Olsa 17581de3bf3SJiri Olsa struct perf_record_mmap; 17681de3bf3SJiri Olsa struct perf_record_mmap2; 17781de3bf3SJiri Olsa struct perf_record_comm; 17881de3bf3SJiri Olsa struct perf_record_namespaces; 17981de3bf3SJiri Olsa struct perf_record_fork; 18081de3bf3SJiri Olsa struct perf_record_lost; 18181de3bf3SJiri Olsa struct perf_record_lost_samples; 18281de3bf3SJiri Olsa struct perf_record_read; 18381de3bf3SJiri Olsa struct perf_record_throttle; 18481de3bf3SJiri Olsa struct perf_record_ksymbol; 18581de3bf3SJiri Olsa struct perf_record_bpf_event; 18681de3bf3SJiri Olsa struct perf_record_sample; 18781de3bf3SJiri Olsa struct perf_record_switch; 18881de3bf3SJiri Olsa struct perf_record_header_attr; 18981de3bf3SJiri Olsa struct perf_record_record_cpu_map; 19081de3bf3SJiri Olsa struct perf_record_cpu_map_data; 19181de3bf3SJiri Olsa struct perf_record_cpu_map; 19281de3bf3SJiri Olsa struct perf_record_event_update_cpus; 19381de3bf3SJiri Olsa struct perf_record_event_update_scale; 19481de3bf3SJiri Olsa struct perf_record_event_update; 19581de3bf3SJiri Olsa struct perf_trace_event_type; 19681de3bf3SJiri Olsa struct perf_record_header_event_type; 19781de3bf3SJiri Olsa struct perf_record_header_tracing_data; 19881de3bf3SJiri Olsa struct perf_record_header_build_id; 19981de3bf3SJiri Olsa struct perf_record_id_index; 20081de3bf3SJiri Olsa struct perf_record_auxtrace_info; 20181de3bf3SJiri Olsa struct perf_record_auxtrace; 20281de3bf3SJiri Olsa struct perf_record_auxtrace_error; 20381de3bf3SJiri Olsa struct perf_record_aux; 20481de3bf3SJiri Olsa struct perf_record_itrace_start; 20581de3bf3SJiri Olsa struct perf_record_thread_map_entry; 20681de3bf3SJiri Olsa struct perf_record_thread_map; 20781de3bf3SJiri Olsa struct perf_record_stat_config_entry; 20881de3bf3SJiri Olsa struct perf_record_stat_config; 20981de3bf3SJiri Olsa struct perf_record_stat; 21081de3bf3SJiri Olsa struct perf_record_stat_round; 21181de3bf3SJiri Olsa struct perf_record_time_conv; 21281de3bf3SJiri Olsa struct perf_record_header_feature; 21381de3bf3SJiri Olsa struct perf_record_compressed; 21481de3bf3SJiri Olsa-- 21581de3bf3SJiri Olsa 21681de3bf3SJiri OlsaDESCRIPTION 21781de3bf3SJiri Olsa----------- 21881de3bf3SJiri OlsaThe libperf library provides an API to access the linux kernel perf 21981de3bf3SJiri Olsaevents subsystem. 22081de3bf3SJiri Olsa 22181de3bf3SJiri OlsaFollowing objects are key to the libperf interface: 22281de3bf3SJiri Olsa 22381de3bf3SJiri Olsa[horizontal] 22481de3bf3SJiri Olsa 225ce746d43SRob Herringstruct perf_cpu_map:: Provides a CPU list abstraction. 22681de3bf3SJiri Olsa 22781de3bf3SJiri Olsastruct perf_thread_map:: Provides a thread list abstraction. 22881de3bf3SJiri Olsa 22981de3bf3SJiri Olsastruct perf_evsel:: Provides an abstraction for single a perf event. 23081de3bf3SJiri Olsa 23181de3bf3SJiri Olsastruct perf_evlist:: Gathers several struct perf_evsel object and performs functions on all of them. 23281de3bf3SJiri Olsa 23381de3bf3SJiri Olsastruct perf_mmap:: Provides an abstraction for accessing perf ring buffer. 23481de3bf3SJiri Olsa 23581de3bf3SJiri OlsaThe exported API functions bind these objects together. 23681de3bf3SJiri Olsa 23781de3bf3SJiri OlsaREPORTING BUGS 23881de3bf3SJiri Olsa-------------- 23981de3bf3SJiri OlsaReport bugs to <linux-perf-users@vger.kernel.org>. 24081de3bf3SJiri Olsa 24181de3bf3SJiri OlsaLICENSE 24281de3bf3SJiri Olsa------- 24381de3bf3SJiri Olsalibperf is Free Software licensed under the GNU LGPL 2.1 24481de3bf3SJiri Olsa 24581de3bf3SJiri OlsaRESOURCES 24681de3bf3SJiri Olsa--------- 24781de3bf3SJiri Olsahttps://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 24881de3bf3SJiri Olsa 24981de3bf3SJiri OlsaSEE ALSO 25081de3bf3SJiri Olsa-------- 25181de3bf3SJiri Olsalibperf-sampling(7), libperf-counting(7) 252