0001 libperf(3)
0002 ==========
0003
0004 NAME
0005 ----
0006 libperf - Linux kernel perf event library
0007
0008
0009 SYNOPSIS
0010 --------
0011 *Generic API:*
0012
0013 [source,c]
0014 --
0015 #include <perf/core.h>
0016
0017 enum libperf_print_level {
0018 LIBPERF_ERR,
0019 LIBPERF_WARN,
0020 LIBPERF_INFO,
0021 LIBPERF_DEBUG,
0022 LIBPERF_DEBUG2,
0023 LIBPERF_DEBUG3,
0024 };
0025
0026 typedef int (*libperf_print_fn_t)(enum libperf_print_level level,
0027 const char *, va_list ap);
0028
0029 void libperf_init(libperf_print_fn_t fn);
0030 --
0031
0032 *API to handle CPU maps:*
0033
0034 [source,c]
0035 --
0036 #include <perf/cpumap.h>
0037
0038 struct perf_cpu_map;
0039
0040 struct perf_cpu_map *perf_cpu_map__dummy_new(void);
0041 struct perf_cpu_map *perf_cpu_map__new(const char *cpu_list);
0042 struct perf_cpu_map *perf_cpu_map__read(FILE *file);
0043 struct perf_cpu_map *perf_cpu_map__get(struct perf_cpu_map *map);
0044 struct perf_cpu_map *perf_cpu_map__merge(struct perf_cpu_map *orig,
0045 struct perf_cpu_map *other);
0046 void perf_cpu_map__put(struct perf_cpu_map *map);
0047 int perf_cpu_map__cpu(const struct perf_cpu_map *cpus, int idx);
0048 int perf_cpu_map__nr(const struct perf_cpu_map *cpus);
0049 bool perf_cpu_map__empty(const struct perf_cpu_map *map);
0050 int perf_cpu_map__max(struct perf_cpu_map *map);
0051 bool perf_cpu_map__has(const struct perf_cpu_map *map, int cpu);
0052
0053 #define perf_cpu_map__for_each_cpu(cpu, idx, cpus)
0054 --
0055
0056 *API to handle thread maps:*
0057
0058 [source,c]
0059 --
0060 #include <perf/threadmap.h>
0061
0062 struct perf_thread_map;
0063
0064 struct perf_thread_map *perf_thread_map__new_dummy(void);
0065 struct perf_thread_map *perf_thread_map__new_array(int nr_threads, pid_t *array);
0066
0067 void perf_thread_map__set_pid(struct perf_thread_map *map, int idx, pid_t pid);
0068 char *perf_thread_map__comm(struct perf_thread_map *map, int idx);
0069 int perf_thread_map__nr(struct perf_thread_map *threads);
0070 pid_t perf_thread_map__pid(struct perf_thread_map *map, int idx);
0071
0072 struct perf_thread_map *perf_thread_map__get(struct perf_thread_map *map);
0073 void perf_thread_map__put(struct perf_thread_map *map);
0074 --
0075
0076 *API to handle event lists:*
0077
0078 [source,c]
0079 --
0080 #include <perf/evlist.h>
0081
0082 struct perf_evlist;
0083
0084 void perf_evlist__add(struct perf_evlist *evlist,
0085 struct perf_evsel *evsel);
0086 void perf_evlist__remove(struct perf_evlist *evlist,
0087 struct perf_evsel *evsel);
0088 struct perf_evlist *perf_evlist__new(void);
0089 void perf_evlist__delete(struct perf_evlist *evlist);
0090 struct perf_evsel* perf_evlist__next(struct perf_evlist *evlist,
0091 struct perf_evsel *evsel);
0092 int perf_evlist__open(struct perf_evlist *evlist);
0093 void perf_evlist__close(struct perf_evlist *evlist);
0094 void perf_evlist__enable(struct perf_evlist *evlist);
0095 void perf_evlist__disable(struct perf_evlist *evlist);
0096
0097 #define perf_evlist__for_each_evsel(evlist, pos)
0098
0099 void perf_evlist__set_maps(struct perf_evlist *evlist,
0100 struct perf_cpu_map *cpus,
0101 struct perf_thread_map *threads);
0102 int perf_evlist__poll(struct perf_evlist *evlist, int timeout);
0103 int perf_evlist__filter_pollfd(struct perf_evlist *evlist,
0104 short revents_and_mask);
0105
0106 int perf_evlist__mmap(struct perf_evlist *evlist, int pages);
0107 void perf_evlist__munmap(struct perf_evlist *evlist);
0108
0109 struct perf_mmap *perf_evlist__next_mmap(struct perf_evlist *evlist,
0110 struct perf_mmap *map,
0111 bool overwrite);
0112
0113 #define perf_evlist__for_each_mmap(evlist, pos, overwrite)
0114 --
0115
0116 *API to handle events:*
0117
0118 [source,c]
0119 --
0120 #include <perf/evsel.h>*
0121
0122 struct perf_evsel;
0123
0124 struct perf_counts_values {
0125 union {
0126 struct {
0127 uint64_t val;
0128 uint64_t ena;
0129 uint64_t run;
0130 };
0131 uint64_t values[3];
0132 };
0133 };
0134
0135 struct perf_evsel *perf_evsel__new(struct perf_event_attr *attr);
0136 void perf_evsel__delete(struct perf_evsel *evsel);
0137 int perf_evsel__open(struct perf_evsel *evsel, struct perf_cpu_map *cpus,
0138 struct perf_thread_map *threads);
0139 void perf_evsel__close(struct perf_evsel *evsel);
0140 void perf_evsel__close_cpu(struct perf_evsel *evsel, int cpu_map_idx);
0141 int perf_evsel__mmap(struct perf_evsel *evsel, int pages);
0142 void perf_evsel__munmap(struct perf_evsel *evsel);
0143 void *perf_evsel__mmap_base(struct perf_evsel *evsel, int cpu_map_idx, int thread);
0144 int perf_evsel__read(struct perf_evsel *evsel, int cpu_map_idx, int thread,
0145 struct perf_counts_values *count);
0146 int perf_evsel__enable(struct perf_evsel *evsel);
0147 int perf_evsel__enable_cpu(struct perf_evsel *evsel, int cpu_map_idx);
0148 int perf_evsel__disable(struct perf_evsel *evsel);
0149 int perf_evsel__disable_cpu(struct perf_evsel *evsel, int cpu_map_idx);
0150 struct perf_cpu_map *perf_evsel__cpus(struct perf_evsel *evsel);
0151 struct perf_thread_map *perf_evsel__threads(struct perf_evsel *evsel);
0152 struct perf_event_attr *perf_evsel__attr(struct perf_evsel *evsel);
0153 --
0154
0155 *API to handle maps (perf ring buffers):*
0156
0157 [source,c]
0158 --
0159 #include <perf/mmap.h>
0160
0161 struct perf_mmap;
0162
0163 void perf_mmap__consume(struct perf_mmap *map);
0164 int perf_mmap__read_init(struct perf_mmap *map);
0165 void perf_mmap__read_done(struct perf_mmap *map);
0166 union perf_event *perf_mmap__read_event(struct perf_mmap *map);
0167 --
0168
0169 *Structures to access perf API events:*
0170
0171 [source,c]
0172 --
0173 #include <perf/event.h>
0174
0175 struct perf_record_mmap;
0176 struct perf_record_mmap2;
0177 struct perf_record_comm;
0178 struct perf_record_namespaces;
0179 struct perf_record_fork;
0180 struct perf_record_lost;
0181 struct perf_record_lost_samples;
0182 struct perf_record_read;
0183 struct perf_record_throttle;
0184 struct perf_record_ksymbol;
0185 struct perf_record_bpf_event;
0186 struct perf_record_sample;
0187 struct perf_record_switch;
0188 struct perf_record_header_attr;
0189 struct perf_record_record_cpu_map;
0190 struct perf_record_cpu_map_data;
0191 struct perf_record_cpu_map;
0192 struct perf_record_event_update_cpus;
0193 struct perf_record_event_update_scale;
0194 struct perf_record_event_update;
0195 struct perf_trace_event_type;
0196 struct perf_record_header_event_type;
0197 struct perf_record_header_tracing_data;
0198 struct perf_record_header_build_id;
0199 struct perf_record_id_index;
0200 struct perf_record_auxtrace_info;
0201 struct perf_record_auxtrace;
0202 struct perf_record_auxtrace_error;
0203 struct perf_record_aux;
0204 struct perf_record_itrace_start;
0205 struct perf_record_thread_map_entry;
0206 struct perf_record_thread_map;
0207 struct perf_record_stat_config_entry;
0208 struct perf_record_stat_config;
0209 struct perf_record_stat;
0210 struct perf_record_stat_round;
0211 struct perf_record_time_conv;
0212 struct perf_record_header_feature;
0213 struct perf_record_compressed;
0214 --
0215
0216 DESCRIPTION
0217 -----------
0218 The libperf library provides an API to access the linux kernel perf
0219 events subsystem.
0220
0221 Following objects are key to the libperf interface:
0222
0223 [horizontal]
0224
0225 struct perf_cpu_map:: Provides a CPU list abstraction.
0226
0227 struct perf_thread_map:: Provides a thread list abstraction.
0228
0229 struct perf_evsel:: Provides an abstraction for single a perf event.
0230
0231 struct perf_evlist:: Gathers several struct perf_evsel object and performs functions on all of them.
0232
0233 struct perf_mmap:: Provides an abstraction for accessing perf ring buffer.
0234
0235 The exported API functions bind these objects together.
0236
0237 REPORTING BUGS
0238 --------------
0239 Report bugs to <linux-perf-users@vger.kernel.org>.
0240
0241 LICENSE
0242 -------
0243 libperf is Free Software licensed under the GNU LGPL 2.1
0244
0245 RESOURCES
0246 ---------
0247 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
0248
0249 SEE ALSO
0250 --------
0251 libperf-sampling(7), libperf-counting(7)
