tools/lib/perf/Documentation/libperf.txt

   1 libperf(3)
   2 ==========
   3
   4 NAME
   5 ----
   6 libperf - Linux kernel perf event library
   7
   8
   9 SYNOPSIS
  10 --------
  11 *Generic API:*
  12
  13 [source,c]
  14 --
  15   #include <perf/core.h>
  16
  17   enum libperf_print_level {
  18           LIBPERF_ERR,
  19           LIBPERF_WARN,
  20           LIBPERF_INFO,
  21           LIBPERF_DEBUG,
  22           LIBPERF_DEBUG2,
  23           LIBPERF_DEBUG3,
  24   };
  25
  26   typedef int (*libperf_print_fn_t)(enum libperf_print_level level,
  27                                     const char *, va_list ap);
  28
  29   void libperf_init(libperf_print_fn_t fn);
  30 --
  31
  32 *API to handle CPU maps:*
  33
  34 [source,c]
  35 --
  36   #include <perf/cpumap.h>
  37
  38   struct perf_cpu_map;
  39
  40   struct perf_cpu_map *perf_cpu_map__new_any_cpu(void);
  41   struct perf_cpu_map *perf_cpu_map__new(const char *cpu_list);
  42   struct perf_cpu_map *perf_cpu_map__get(struct perf_cpu_map *map);
  43   struct perf_cpu_map *perf_cpu_map__merge(struct perf_cpu_map *orig,
  44                                            struct perf_cpu_map *other);
  45   void perf_cpu_map__put(struct perf_cpu_map *map);
  46   int perf_cpu_map__cpu(const struct perf_cpu_map *cpus, int idx);
  47   int perf_cpu_map__nr(const struct perf_cpu_map *cpus);
  48   bool perf_cpu_map__has_any_cpu_or_is_empty(const struct perf_cpu_map *map);
  49   int perf_cpu_map__max(struct perf_cpu_map *map);
  50   bool perf_cpu_map__has(const struct perf_cpu_map *map, int cpu);
  51
  52   #define perf_cpu_map__for_each_cpu(cpu, idx, cpus)
  53 --
  54
  55 *API to handle thread maps:*
  56
  57 [source,c]
  58 --
  59   #include <perf/threadmap.h>
  60
  61   struct perf_thread_map;
  62
  63   struct perf_thread_map *perf_thread_map__new_dummy(void);
  64   struct perf_thread_map *perf_thread_map__new_array(int nr_threads, pid_t *array);
  65
  66   void perf_thread_map__set_pid(struct perf_thread_map *map, int idx, pid_t pid);
  67   char *perf_thread_map__comm(struct perf_thread_map *map, int idx);
  68   int perf_thread_map__nr(struct perf_thread_map *threads);
  69   pid_t perf_thread_map__pid(struct perf_thread_map *map, int idx);
  70
  71   struct perf_thread_map *perf_thread_map__get(struct perf_thread_map *map);
  72   void perf_thread_map__put(struct perf_thread_map *map);
  73 --
  74
  75 *API to handle event lists:*
  76
  77 [source,c]
  78 --
  79   #include <perf/evlist.h>
  80
  81   struct perf_evlist;
  82
  83   void perf_evlist__add(struct perf_evlist *evlist,
  84                         struct perf_evsel *evsel);
  85   void perf_evlist__remove(struct perf_evlist *evlist,
  86                            struct perf_evsel *evsel);
  87   struct perf_evlist *perf_evlist__new(void);
  88   void perf_evlist__delete(struct perf_evlist *evlist);
  89   struct perf_evsel* perf_evlist__next(struct perf_evlist *evlist,
  90                                        struct perf_evsel *evsel);
  91   int perf_evlist__open(struct perf_evlist *evlist);
  92   void perf_evlist__close(struct perf_evlist *evlist);
  93   void perf_evlist__enable(struct perf_evlist *evlist);
  94   void perf_evlist__disable(struct perf_evlist *evlist);
  95
  96   #define perf_evlist__for_each_evsel(evlist, pos)
  97
  98   void perf_evlist__set_maps(struct perf_evlist *evlist,
  99                              struct perf_cpu_map *cpus,
 100                              struct perf_thread_map *threads);
 101   int perf_evlist__poll(struct perf_evlist *evlist, int timeout);
 102   int perf_evlist__filter_pollfd(struct perf_evlist *evlist,
 103                                  short revents_and_mask);
 104
 105   int perf_evlist__mmap(struct perf_evlist *evlist, int pages);
 106   void perf_evlist__munmap(struct perf_evlist *evlist);
 107
 108   struct perf_mmap *perf_evlist__next_mmap(struct perf_evlist *evlist,
 109                                            struct perf_mmap *map,
 110                                            bool overwrite);
 111
 112   #define perf_evlist__for_each_mmap(evlist, pos, overwrite)
 113 --
 114
 115 *API to handle events:*
 116
 117 [source,c]
 118 --
 119   #include <perf/evsel.h>*
 120
 121   struct perf_evsel;
 122
 123   struct perf_counts_values {
 124           union {
 125                   struct {
 126                           uint64_t val;
 127                           uint64_t ena;
 128                           uint64_t run;
 129                   };
 130                   uint64_t values[3];
 131           };
 132   };
 133
 134   struct perf_evsel *perf_evsel__new(struct perf_event_attr *attr);
 135   void perf_evsel__delete(struct perf_evsel *evsel);
 136   int perf_evsel__open(struct perf_evsel *evsel, struct perf_cpu_map *cpus,
 137                        struct perf_thread_map *threads);
 138   void perf_evsel__close(struct perf_evsel *evsel);
 139   void perf_evsel__close_cpu(struct perf_evsel *evsel, int cpu_map_idx);
 140   int perf_evsel__mmap(struct perf_evsel *evsel, int pages);
 141   void perf_evsel__munmap(struct perf_evsel *evsel);
 142   void *perf_evsel__mmap_base(struct perf_evsel *evsel, int cpu_map_idx, int thread);
 143   int perf_evsel__read(struct perf_evsel *evsel, int cpu_map_idx, int thread,
 144                        struct perf_counts_values *count);
 145   int perf_evsel__enable(struct perf_evsel *evsel);
 146   int perf_evsel__enable_cpu(struct perf_evsel *evsel, int cpu_map_idx);
 147   int perf_evsel__disable(struct perf_evsel *evsel);
 148   int perf_evsel__disable_cpu(struct perf_evsel *evsel, int cpu_map_idx);
 149   struct perf_cpu_map *perf_evsel__cpus(struct perf_evsel *evsel);
 150   struct perf_thread_map *perf_evsel__threads(struct perf_evsel *evsel);
 151   struct perf_event_attr *perf_evsel__attr(struct perf_evsel *evsel);
 152 --
 153
 154 *API to handle maps (perf ring buffers):*
 155
 156 [source,c]
 157 --
 158   #include <perf/mmap.h>
 159
 160   struct perf_mmap;
 161
 162   void perf_mmap__consume(struct perf_mmap *map);
 163   int perf_mmap__read_init(struct perf_mmap *map);
 164   void perf_mmap__read_done(struct perf_mmap *map);
 165   union perf_event *perf_mmap__read_event(struct perf_mmap *map);
 166 --
 167
 168 *Structures to access perf API events:*
 169
 170 [source,c]
 171 --
 172   #include <perf/event.h>
 173
 174   struct perf_record_mmap;
 175   struct perf_record_mmap2;
 176   struct perf_record_comm;
 177   struct perf_record_namespaces;
 178   struct perf_record_fork;
 179   struct perf_record_lost;
 180   struct perf_record_lost_samples;
 181   struct perf_record_read;
 182   struct perf_record_throttle;
 183   struct perf_record_ksymbol;
 184   struct perf_record_bpf_event;
 185   struct perf_record_sample;
 186   struct perf_record_switch;
 187   struct perf_record_header_attr;
 188   struct perf_record_record_cpu_map;
 189   struct perf_record_cpu_map_data;
 190   struct perf_record_cpu_map;
 191   struct perf_record_event_update_cpus;
 192   struct perf_record_event_update_scale;
 193   struct perf_record_event_update;
 194   struct perf_trace_event_type;
 195   struct perf_record_header_event_type;
 196   struct perf_record_header_tracing_data;
 197   struct perf_record_header_build_id;
 198   struct perf_record_id_index;
 199   struct perf_record_auxtrace_info;
 200   struct perf_record_auxtrace;
 201   struct perf_record_auxtrace_error;
 202   struct perf_record_aux;
 203   struct perf_record_itrace_start;
 204   struct perf_record_thread_map_entry;
 205   struct perf_record_thread_map;
 206   struct perf_record_stat_config_entry;
 207   struct perf_record_stat_config;
 208   struct perf_record_stat;
 209   struct perf_record_stat_round;
 210   struct perf_record_time_conv;
 211   struct perf_record_header_feature;
 212   struct perf_record_compressed;
 213 --
 214
 215 DESCRIPTION
 216 -----------
 217 The libperf library provides an API to access the linux kernel perf
 218 events subsystem.
 219
 220 Following objects are key to the libperf interface:
 221
 222 [horizontal]
 223
 224 struct perf_cpu_map:: Provides a CPU list abstraction.
 225
 226 struct perf_thread_map:: Provides a thread list abstraction.
 227
 228 struct perf_evsel:: Provides an abstraction for single a perf event.
 229
 230 struct perf_evlist:: Gathers several struct perf_evsel object and performs functions on all of them.
 231
 232 struct perf_mmap:: Provides an abstraction for accessing perf ring buffer.
 233
 234 The exported API functions bind these objects together.
 235
 236 REPORTING BUGS
 237 --------------
 238 Report bugs to <linux-perf-users@vger.kernel.org>.
 239
 240 LICENSE
 241 -------
 242 libperf is Free Software licensed under the GNU LGPL 2.1
 243
 244 RESOURCES
 245 ---------
 246 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
 247
 248 SEE ALSO
 249 --------
 250 libperf-sampling(7), libperf-counting(7)