tools/perf/lib/Documentation/tutorial/tutorial.rst

   1 .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
   2
   3 libperf tutorial
   4 ================
   5
   6 Compile and install libperf from kernel sources
   7 ===============================================
   8 .. code-block:: bash
   9
  10   git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
  11   cd linux/tools/perf/lib
  12   make
  13   sudo make install prefix=/usr
  14
  15 Libperf object
  16 ==============
  17 The libperf library provides several high level objects:
  18
  19 struct perf_cpu_map
  20   Provides a cpu list abstraction.
  21
  22 struct perf_thread_map
  23   Provides a thread list abstraction.
  24
  25 struct perf_evsel
  26   Provides an abstraction for single a perf event.
  27
  28 struct perf_evlist
  29   Gathers several struct perf_evsel object and performs functions on all of them.
  30
  31 The exported API binds these objects together,
  32 for full reference see the libperf.7 man page.
  33
  34 Examples
  35 ========
  36 Examples aim to explain libperf functionality on simple use cases.
  37 They are based in on a checked out linux kernel git tree:
  38
  39 .. code-block:: bash
  40
  41   $ cd tools/perf/lib/Documentation/tutorial/
  42   $ ls -d  ex-*
  43   ex-1-compile  ex-2-evsel-stat  ex-3-evlist-stat
  44
  45 ex-1-compile example
  46 ====================
  47 This example shows the basic usage of *struct perf_cpu_map*,
  48 how to create it and display its cpus:
  49
  50 .. code-block:: bash
  51
  52   $ cd ex-1-compile/
  53   $ make
  54   gcc -o test test.c -lperf
  55   $ ./test
  56   0 1 2 3 4 5 6 7
  57
  58
  59 The full code listing is here:
  60
  61 .. code-block:: c
  62
  63    1 #include <perf/cpumap.h>
  64    2
  65    3 int main(int argc, char **Argv)
  66    4 {
  67    5         struct perf_cpu_map *cpus;
  68    6         int cpu, tmp;
  69    7
  70    8         cpus = perf_cpu_map__new(NULL);
  71    9
  72   10         perf_cpu_map__for_each_cpu(cpu, tmp, cpus)
  73   11                 fprintf(stdout, "%d ", cpu);
  74   12
  75   13         fprintf(stdout, "\n");
  76   14
  77   15         perf_cpu_map__put(cpus);
  78   16         return 0;
  79   17 }
  80
  81
  82 First you need to include the proper header to have *struct perf_cpumap*
  83 declaration and functions:
  84
  85 .. code-block:: c
  86
  87    1 #include <perf/cpumap.h>
  88
  89
  90 The *struct perf_cpumap* object is created by *perf_cpu_map__new* call.
  91 The *NULL* argument asks it to populate the object with the current online CPUs list:
  92
  93 .. code-block:: c
  94
  95    8         cpus = perf_cpu_map__new(NULL);
  96
  97 This is paired with a *perf_cpu_map__put*, that drops its reference at the end, possibly deleting it.
  98
  99 .. code-block:: c
 100
 101   15         perf_cpu_map__put(cpus);
 102
 103 The iteration through the *struct perf_cpumap* CPUs is done using the *perf_cpu_map__for_each_cpu*
 104 macro which requires 3 arguments:
 105
 106 - cpu  - the cpu numer
 107 - tmp  - iteration helper variable
 108 - cpus - the *struct perf_cpumap* object
 109
 110 .. code-block:: c
 111
 112   10         perf_cpu_map__for_each_cpu(cpu, tmp, cpus)
 113   11                 fprintf(stdout, "%d ", cpu);
 114
 115 ex-2-evsel-stat example
 116 =======================
 117
 118 TBD
 119
 120 ex-3-evlist-stat example
 121 ========================
 122
 123 TBD