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); 6581de3bf3SJiri Olsa 66*41415b8aSTzvetomir Stoyanov (VMware) void perf_thread_map__set_pid(struct perf_thread_map *map, int idx, pid_t pid); 67*41415b8aSTzvetomir Stoyanov (VMware) char *perf_thread_map__comm(struct perf_thread_map *map, int idx); 6881de3bf3SJiri Olsa int perf_thread_map__nr(struct perf_thread_map *threads); 69*41415b8aSTzvetomir Stoyanov (VMware) pid_t perf_thread_map__pid(struct perf_thread_map *map, int idx); 7081de3bf3SJiri Olsa 7181de3bf3SJiri Olsa struct perf_thread_map *perf_thread_map__get(struct perf_thread_map *map); 7281de3bf3SJiri Olsa void perf_thread_map__put(struct perf_thread_map *map); 7381de3bf3SJiri Olsa-- 7481de3bf3SJiri Olsa 7581de3bf3SJiri Olsa*API to handle event lists:* 7681de3bf3SJiri Olsa 7781de3bf3SJiri Olsa[source,c] 7881de3bf3SJiri Olsa-- 7981de3bf3SJiri Olsa #include <perf/evlist.h> 8081de3bf3SJiri Olsa 8181de3bf3SJiri Olsa struct perf_evlist; 8281de3bf3SJiri Olsa 8381de3bf3SJiri Olsa void perf_evlist__add(struct perf_evlist *evlist, 8481de3bf3SJiri Olsa struct perf_evsel *evsel); 8581de3bf3SJiri Olsa void perf_evlist__remove(struct perf_evlist *evlist, 8681de3bf3SJiri Olsa struct perf_evsel *evsel); 8781de3bf3SJiri Olsa struct perf_evlist *perf_evlist__new(void); 8881de3bf3SJiri Olsa void perf_evlist__delete(struct perf_evlist *evlist); 8981de3bf3SJiri Olsa struct perf_evsel* perf_evlist__next(struct perf_evlist *evlist, 9081de3bf3SJiri Olsa struct perf_evsel *evsel); 9181de3bf3SJiri Olsa int perf_evlist__open(struct perf_evlist *evlist); 9281de3bf3SJiri Olsa void perf_evlist__close(struct perf_evlist *evlist); 9381de3bf3SJiri Olsa void perf_evlist__enable(struct perf_evlist *evlist); 9481de3bf3SJiri Olsa void perf_evlist__disable(struct perf_evlist *evlist); 9581de3bf3SJiri Olsa 9681de3bf3SJiri Olsa #define perf_evlist__for_each_evsel(evlist, pos) 9781de3bf3SJiri Olsa 9881de3bf3SJiri Olsa void perf_evlist__set_maps(struct perf_evlist *evlist, 9981de3bf3SJiri Olsa struct perf_cpu_map *cpus, 10081de3bf3SJiri Olsa struct perf_thread_map *threads); 10181de3bf3SJiri Olsa int perf_evlist__poll(struct perf_evlist *evlist, int timeout); 10281de3bf3SJiri Olsa int perf_evlist__filter_pollfd(struct perf_evlist *evlist, 10381de3bf3SJiri Olsa short revents_and_mask); 10481de3bf3SJiri Olsa 10581de3bf3SJiri Olsa int perf_evlist__mmap(struct perf_evlist *evlist, int pages); 10681de3bf3SJiri Olsa void perf_evlist__munmap(struct perf_evlist *evlist); 10781de3bf3SJiri Olsa 10881de3bf3SJiri Olsa struct perf_mmap *perf_evlist__next_mmap(struct perf_evlist *evlist, 10981de3bf3SJiri Olsa struct perf_mmap *map, 11081de3bf3SJiri Olsa bool overwrite); 11181de3bf3SJiri Olsa 11281de3bf3SJiri Olsa #define perf_evlist__for_each_mmap(evlist, pos, overwrite) 11381de3bf3SJiri Olsa-- 11481de3bf3SJiri Olsa 11581de3bf3SJiri Olsa*API to handle events:* 11681de3bf3SJiri Olsa 11781de3bf3SJiri Olsa[source,c] 11881de3bf3SJiri Olsa-- 11981de3bf3SJiri Olsa #include <perf/evsel.h>* 12081de3bf3SJiri Olsa 12181de3bf3SJiri Olsa struct perf_evsel; 12281de3bf3SJiri Olsa 12381de3bf3SJiri Olsa struct perf_counts_values { 12481de3bf3SJiri Olsa union { 12581de3bf3SJiri Olsa struct { 12681de3bf3SJiri Olsa uint64_t val; 12781de3bf3SJiri Olsa uint64_t ena; 12881de3bf3SJiri Olsa uint64_t run; 12981de3bf3SJiri Olsa }; 13081de3bf3SJiri Olsa uint64_t values[3]; 13181de3bf3SJiri Olsa }; 13281de3bf3SJiri Olsa }; 13381de3bf3SJiri Olsa 13481de3bf3SJiri Olsa struct perf_evsel *perf_evsel__new(struct perf_event_attr *attr); 13581de3bf3SJiri Olsa void perf_evsel__delete(struct perf_evsel *evsel); 13681de3bf3SJiri Olsa int perf_evsel__open(struct perf_evsel *evsel, struct perf_cpu_map *cpus, 13781de3bf3SJiri Olsa struct perf_thread_map *threads); 13881de3bf3SJiri Olsa void perf_evsel__close(struct perf_evsel *evsel); 13991802e73SIan Rogers void perf_evsel__close_cpu(struct perf_evsel *evsel, int cpu_map_idx); 1406cd70754SRob Herring int perf_evsel__mmap(struct perf_evsel *evsel, int pages); 1416cd70754SRob Herring void perf_evsel__munmap(struct perf_evsel *evsel); 14291802e73SIan Rogers void *perf_evsel__mmap_base(struct perf_evsel *evsel, int cpu_map_idx, int thread); 14391802e73SIan Rogers int perf_evsel__read(struct perf_evsel *evsel, int cpu_map_idx, int thread, 14481de3bf3SJiri Olsa struct perf_counts_values *count); 14581de3bf3SJiri Olsa int perf_evsel__enable(struct perf_evsel *evsel); 14691802e73SIan Rogers int perf_evsel__enable_cpu(struct perf_evsel *evsel, int cpu_map_idx); 14781de3bf3SJiri Olsa int perf_evsel__disable(struct perf_evsel *evsel); 14891802e73SIan Rogers int perf_evsel__disable_cpu(struct perf_evsel *evsel, int cpu_map_idx); 14981de3bf3SJiri Olsa struct perf_cpu_map *perf_evsel__cpus(struct perf_evsel *evsel); 15081de3bf3SJiri Olsa struct perf_thread_map *perf_evsel__threads(struct perf_evsel *evsel); 15181de3bf3SJiri Olsa struct perf_event_attr *perf_evsel__attr(struct perf_evsel *evsel); 15281de3bf3SJiri Olsa-- 15381de3bf3SJiri Olsa 15481de3bf3SJiri Olsa*API to handle maps (perf ring buffers):* 15581de3bf3SJiri Olsa 15681de3bf3SJiri Olsa[source,c] 15781de3bf3SJiri Olsa-- 15881de3bf3SJiri Olsa #include <perf/mmap.h> 15981de3bf3SJiri Olsa 16081de3bf3SJiri Olsa struct perf_mmap; 16181de3bf3SJiri Olsa 16281de3bf3SJiri Olsa void perf_mmap__consume(struct perf_mmap *map); 16381de3bf3SJiri Olsa int perf_mmap__read_init(struct perf_mmap *map); 16481de3bf3SJiri Olsa void perf_mmap__read_done(struct perf_mmap *map); 16581de3bf3SJiri Olsa union perf_event *perf_mmap__read_event(struct perf_mmap *map); 16681de3bf3SJiri Olsa-- 16781de3bf3SJiri Olsa 16881de3bf3SJiri Olsa*Structures to access perf API events:* 16981de3bf3SJiri Olsa 17081de3bf3SJiri Olsa[source,c] 17181de3bf3SJiri Olsa-- 17281de3bf3SJiri Olsa #include <perf/event.h> 17381de3bf3SJiri Olsa 17481de3bf3SJiri Olsa struct perf_record_mmap; 17581de3bf3SJiri Olsa struct perf_record_mmap2; 17681de3bf3SJiri Olsa struct perf_record_comm; 17781de3bf3SJiri Olsa struct perf_record_namespaces; 17881de3bf3SJiri Olsa struct perf_record_fork; 17981de3bf3SJiri Olsa struct perf_record_lost; 18081de3bf3SJiri Olsa struct perf_record_lost_samples; 18181de3bf3SJiri Olsa struct perf_record_read; 18281de3bf3SJiri Olsa struct perf_record_throttle; 18381de3bf3SJiri Olsa struct perf_record_ksymbol; 18481de3bf3SJiri Olsa struct perf_record_bpf_event; 18581de3bf3SJiri Olsa struct perf_record_sample; 18681de3bf3SJiri Olsa struct perf_record_switch; 18781de3bf3SJiri Olsa struct perf_record_header_attr; 18881de3bf3SJiri Olsa struct perf_record_record_cpu_map; 18981de3bf3SJiri Olsa struct perf_record_cpu_map_data; 19081de3bf3SJiri Olsa struct perf_record_cpu_map; 19181de3bf3SJiri Olsa struct perf_record_event_update_cpus; 19281de3bf3SJiri Olsa struct perf_record_event_update_scale; 19381de3bf3SJiri Olsa struct perf_record_event_update; 19481de3bf3SJiri Olsa struct perf_trace_event_type; 19581de3bf3SJiri Olsa struct perf_record_header_event_type; 19681de3bf3SJiri Olsa struct perf_record_header_tracing_data; 19781de3bf3SJiri Olsa struct perf_record_header_build_id; 19881de3bf3SJiri Olsa struct perf_record_id_index; 19981de3bf3SJiri Olsa struct perf_record_auxtrace_info; 20081de3bf3SJiri Olsa struct perf_record_auxtrace; 20181de3bf3SJiri Olsa struct perf_record_auxtrace_error; 20281de3bf3SJiri Olsa struct perf_record_aux; 20381de3bf3SJiri Olsa struct perf_record_itrace_start; 20481de3bf3SJiri Olsa struct perf_record_thread_map_entry; 20581de3bf3SJiri Olsa struct perf_record_thread_map; 20681de3bf3SJiri Olsa struct perf_record_stat_config_entry; 20781de3bf3SJiri Olsa struct perf_record_stat_config; 20881de3bf3SJiri Olsa struct perf_record_stat; 20981de3bf3SJiri Olsa struct perf_record_stat_round; 21081de3bf3SJiri Olsa struct perf_record_time_conv; 21181de3bf3SJiri Olsa struct perf_record_header_feature; 21281de3bf3SJiri Olsa struct perf_record_compressed; 21381de3bf3SJiri Olsa-- 21481de3bf3SJiri Olsa 21581de3bf3SJiri OlsaDESCRIPTION 21681de3bf3SJiri Olsa----------- 21781de3bf3SJiri OlsaThe libperf library provides an API to access the linux kernel perf 21881de3bf3SJiri Olsaevents subsystem. 21981de3bf3SJiri Olsa 22081de3bf3SJiri OlsaFollowing objects are key to the libperf interface: 22181de3bf3SJiri Olsa 22281de3bf3SJiri Olsa[horizontal] 22381de3bf3SJiri Olsa 224ce746d43SRob Herringstruct perf_cpu_map:: Provides a CPU list abstraction. 22581de3bf3SJiri Olsa 22681de3bf3SJiri Olsastruct perf_thread_map:: Provides a thread list abstraction. 22781de3bf3SJiri Olsa 22881de3bf3SJiri Olsastruct perf_evsel:: Provides an abstraction for single a perf event. 22981de3bf3SJiri Olsa 23081de3bf3SJiri Olsastruct perf_evlist:: Gathers several struct perf_evsel object and performs functions on all of them. 23181de3bf3SJiri Olsa 23281de3bf3SJiri Olsastruct perf_mmap:: Provides an abstraction for accessing perf ring buffer. 23381de3bf3SJiri Olsa 23481de3bf3SJiri OlsaThe exported API functions bind these objects together. 23581de3bf3SJiri Olsa 23681de3bf3SJiri OlsaREPORTING BUGS 23781de3bf3SJiri Olsa-------------- 23881de3bf3SJiri OlsaReport bugs to <linux-perf-users@vger.kernel.org>. 23981de3bf3SJiri Olsa 24081de3bf3SJiri OlsaLICENSE 24181de3bf3SJiri Olsa------- 24281de3bf3SJiri Olsalibperf is Free Software licensed under the GNU LGPL 2.1 24381de3bf3SJiri Olsa 24481de3bf3SJiri OlsaRESOURCES 24581de3bf3SJiri Olsa--------- 24681de3bf3SJiri Olsahttps://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git 24781de3bf3SJiri Olsa 24881de3bf3SJiri OlsaSEE ALSO 24981de3bf3SJiri Olsa-------- 25081de3bf3SJiri Olsalibperf-sampling(7), libperf-counting(7) 251