252 lines
7.6 KiB
Plaintext
252 lines
7.6 KiB
Plaintext
|
libperf(3)
|
||
|
|
==========
|
||
|
|
|
||
|
|
NAME
|
||
|
|
----
|
||
|
|
libperf - Linux kernel perf event library
|
||
|
|
|
||
|
|
|
||
|
|
SYNOPSIS
|
||
|
|
--------
|
||
|
|
*Generic API:*
|
||
|
|
|
||
|
|
[source,c]
|
||
|
|
--
|
||
|
|
#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:*
|
||
|
|
|
||
|
|
[source,c]
|
||
|
|
--
|
||
|
|
#include <perf/cpumap.h>
|
||
|
|
|
||
|
|
struct perf_cpu_map;
|
||
|
|
|
||
|
|
struct perf_cpu_map *perf_cpu_map__dummy_new(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__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:*
|
||
|
|
|
||
|
|
[source,c]
|
||
|
|
--
|
||
|
|
#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:*
|
||
|
|
|
||
|
|
[source,c]
|
||
|
|
--
|
||
|
|
#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:*
|
||
|
|
|
||
|
|
[source,c]
|
||
|
|
--
|
||
|
|
#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):*
|
||
|
|
|
||
|
|
[source,c]
|
||
|
|
--
|
||
|
|
#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:*
|
||
|
|
|
||
|
|
[source,c]
|
||
|
|
--
|
||
|
|
#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:
|
||
|
|
|
||
|
|
[horizontal]
|
||
|
|
|
||
|
|
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>.
|
||
|
|
|
||
|
|
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
|
||
|
|
--------
|
||
|
|
libperf-sampling(7), libperf-counting(7)
|