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