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 124