1.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
  2
  3libperf tutorial
  4================
  5
  6Compile 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
 15Libperf object
 16==============
 17The libperf library provides several high level objects:
 18
 19struct perf_cpu_map
 20  Provides a cpu list abstraction.
 21
 22struct perf_thread_map
 23  Provides a thread list abstraction.
 24
 25struct perf_evsel
 26  Provides an abstraction for single a perf event.
 27
 28struct perf_evlist
 29  Gathers several struct perf_evsel object and performs functions on all of them.
 30
 31The exported API binds these objects together,
 32for full reference see the libperf.7 man page.
 33
 34Examples
 35========
 36Examples aim to explain libperf functionality on simple use cases.
 37They 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
 45ex-1-compile example
 46====================
 47This example shows the basic usage of *struct perf_cpu_map*,
 48how 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
 59The 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
 82First you need to include the proper header to have *struct perf_cpumap*
 83declaration and functions:
 84
 85.. code-block:: c
 86
 87   1 #include <perf/cpumap.h>
 88
 89
 90The *struct perf_cpumap* object is created by *perf_cpu_map__new* call.
 91The *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
 97This 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
103The iteration through the *struct perf_cpumap* CPUs is done using the *perf_cpu_map__for_each_cpu*
104macro 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
115ex-2-evsel-stat example
116=======================
117
118TBD
119
120ex-3-evlist-stat example
121========================
122
123TBD