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