libperf - Man Page
Linux kernel perf event library
Synopsis
Generic API:
#include <perf/core.h> enum libperf_print_level { LIBPERF_ERR, LIBPERF_WARN, LIBPERF_INFO, LIBPERF_DEBUG, LIBPERF_DEBUG2, LIBPERF_DEBUG3, }; typedef int (*libperf_print_fn_t)(enum libperf_print_level level, const char *, va_list ap); void libperf_init(libperf_print_fn_t fn);
API to handle CPU maps:
#include <perf/cpumap.h> struct perf_cpu_map; struct perf_cpu_map *perf_cpu_map__new_any_cpu(void); struct perf_cpu_map *perf_cpu_map__new(const char *cpu_list); struct perf_cpu_map *perf_cpu_map__read(FILE *file); struct perf_cpu_map *perf_cpu_map__get(struct perf_cpu_map *map); struct perf_cpu_map *perf_cpu_map__merge(struct perf_cpu_map *orig, struct perf_cpu_map *other); void perf_cpu_map__put(struct perf_cpu_map *map); int perf_cpu_map__cpu(const struct perf_cpu_map *cpus, int idx); int perf_cpu_map__nr(const struct perf_cpu_map *cpus); bool perf_cpu_map__has_any_cpu_or_is_empty(const struct perf_cpu_map *map); int perf_cpu_map__max(struct perf_cpu_map *map); bool perf_cpu_map__has(const struct perf_cpu_map *map, int cpu); #define perf_cpu_map__for_each_cpu(cpu, idx, cpus)
API to handle thread maps:
#include <perf/threadmap.h> struct perf_thread_map; struct perf_thread_map *perf_thread_map__new_dummy(void); struct perf_thread_map *perf_thread_map__new_array(int nr_threads, pid_t *array); void perf_thread_map__set_pid(struct perf_thread_map *map, int idx, pid_t pid); char *perf_thread_map__comm(struct perf_thread_map *map, int idx); int perf_thread_map__nr(struct perf_thread_map *threads); pid_t perf_thread_map__pid(struct perf_thread_map *map, int idx); struct perf_thread_map *perf_thread_map__get(struct perf_thread_map *map); void perf_thread_map__put(struct perf_thread_map *map);
API to handle event lists:
#include <perf/evlist.h> struct perf_evlist; void perf_evlist__add(struct perf_evlist *evlist, struct perf_evsel *evsel); void perf_evlist__remove(struct perf_evlist *evlist, struct perf_evsel *evsel); struct perf_evlist *perf_evlist__new(void); void perf_evlist__delete(struct perf_evlist *evlist); struct perf_evsel* perf_evlist__next(struct perf_evlist *evlist, struct perf_evsel *evsel); int perf_evlist__open(struct perf_evlist *evlist); void perf_evlist__close(struct perf_evlist *evlist); void perf_evlist__enable(struct perf_evlist *evlist); void perf_evlist__disable(struct perf_evlist *evlist); #define perf_evlist__for_each_evsel(evlist, pos) void perf_evlist__set_maps(struct perf_evlist *evlist, struct perf_cpu_map *cpus, struct perf_thread_map *threads); int perf_evlist__poll(struct perf_evlist *evlist, int timeout); int perf_evlist__filter_pollfd(struct perf_evlist *evlist, short revents_and_mask); int perf_evlist__mmap(struct perf_evlist *evlist, int pages); void perf_evlist__munmap(struct perf_evlist *evlist); struct perf_mmap *perf_evlist__next_mmap(struct perf_evlist *evlist, struct perf_mmap *map, bool overwrite); #define perf_evlist__for_each_mmap(evlist, pos, overwrite)
API to handle events:
#include <perf/evsel.h>* struct perf_evsel; struct perf_counts_values { union { struct { uint64_t val; uint64_t ena; uint64_t run; }; uint64_t values[3]; }; }; struct perf_evsel *perf_evsel__new(struct perf_event_attr *attr); void perf_evsel__delete(struct perf_evsel *evsel); int perf_evsel__open(struct perf_evsel *evsel, struct perf_cpu_map *cpus, struct perf_thread_map *threads); void perf_evsel__close(struct perf_evsel *evsel); void perf_evsel__close_cpu(struct perf_evsel *evsel, int cpu_map_idx); int perf_evsel__mmap(struct perf_evsel *evsel, int pages); void perf_evsel__munmap(struct perf_evsel *evsel); void *perf_evsel__mmap_base(struct perf_evsel *evsel, int cpu_map_idx, int thread); int perf_evsel__read(struct perf_evsel *evsel, int cpu_map_idx, int thread, struct perf_counts_values *count); int perf_evsel__enable(struct perf_evsel *evsel); int perf_evsel__enable_cpu(struct perf_evsel *evsel, int cpu_map_idx); int perf_evsel__disable(struct perf_evsel *evsel); int perf_evsel__disable_cpu(struct perf_evsel *evsel, int cpu_map_idx); struct perf_cpu_map *perf_evsel__cpus(struct perf_evsel *evsel); struct perf_thread_map *perf_evsel__threads(struct perf_evsel *evsel); struct perf_event_attr *perf_evsel__attr(struct perf_evsel *evsel);
API to handle maps (perf ring buffers):
#include <perf/mmap.h> struct perf_mmap; void perf_mmap__consume(struct perf_mmap *map); int perf_mmap__read_init(struct perf_mmap *map); void perf_mmap__read_done(struct perf_mmap *map); union perf_event *perf_mmap__read_event(struct perf_mmap *map);
Structures to access perf API events:
#include <perf/event.h> struct perf_record_mmap; struct perf_record_mmap2; struct perf_record_comm; struct perf_record_namespaces; struct perf_record_fork; struct perf_record_lost; struct perf_record_lost_samples; struct perf_record_read; struct perf_record_throttle; struct perf_record_ksymbol; struct perf_record_bpf_event; struct perf_record_sample; struct perf_record_switch; struct perf_record_header_attr; struct perf_record_record_cpu_map; struct perf_record_cpu_map_data; struct perf_record_cpu_map; struct perf_record_event_update_cpus; struct perf_record_event_update_scale; struct perf_record_event_update; struct perf_trace_event_type; struct perf_record_header_event_type; struct perf_record_header_tracing_data; struct perf_record_header_build_id; struct perf_record_id_index; struct perf_record_auxtrace_info; struct perf_record_auxtrace; struct perf_record_auxtrace_error; struct perf_record_aux; struct perf_record_itrace_start; struct perf_record_thread_map_entry; struct perf_record_thread_map; struct perf_record_stat_config_entry; struct perf_record_stat_config; struct perf_record_stat; struct perf_record_stat_round; struct perf_record_time_conv; struct perf_record_header_feature; struct perf_record_compressed;
Description
The libperf library provides an API to access the linux kernel perf events subsystem.
Following objects are key to the libperf interface:
struct perf_cpu_map | Provides a CPU list abstraction. |
struct perf_thread_map | Provides a thread list abstraction. |
struct perf_evsel | Provides an abstraction for single a perf event. |
struct perf_evlist | Gathers several struct perf_evsel object and performs functions on all of them. |
struct perf_mmap | Provides an abstraction for accessing perf ring buffer. |
The exported API functions bind these objects together.
Reporting Bugs
Report bugs to <linux-perf-users@vger.kernel.org[1]>.
License
libperf is Free Software licensed under the GNU LGPL 2.1
Resources
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
See Also
Notes
- 1.
linux-perf-users@vger.kernel.org
mailto:linux-perf-users@vger.kernel.org
Referenced By
libperf-counting(7), libperf-sampling(7).
09/27/2024 libperf Manual