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