tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
libperf: Initial documentation
Add initial drafts of documentation files, hugely unfinished.
Signed-off-by: Jiri Olsa <jolsa@kernel.org>
Cc: Alexander Shishkin <alexander.shishkin@linux.intel.com>
Cc: Alexey Budankov <alexey.budankov@linux.intel.com>
Cc: Andi Kleen <ak@linux.intel.com>
Cc: Michael Petlan <mpetlan@redhat.com>
Cc: Namhyung Kim <namhyung@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Link: http://lkml.kernel.org/r/20190721112506.12306-80-jolsa@kernel.org
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
authored by
Jiri Olsa
and committed by
Arnaldo Carvalho de Melo
f4f48e9c
02266a2d
+230
+7
tools/perf/lib/Documentation/Makefile
+7
tools/perf/lib/Documentation/Makefile
+100
tools/perf/lib/Documentation/man/libperf.rst
+100
tools/perf/lib/Documentation/man/libperf.rst
···
1
+
.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
2
+
3
+
libperf
4
+
5
+
The libperf library provides an API to access the linux kernel perf
6
+
events subsystem. It provides the following high level objects:
7
+
8
+
- struct perf_cpu_map
9
+
- struct perf_thread_map
10
+
- struct perf_evlist
11
+
- struct perf_evsel
12
+
13
+
reference
14
+
=========
15
+
Function reference by header files:
16
+
17
+
perf/core.h
18
+
-----------
19
+
.. code-block:: c
20
+
21
+
typedef int (\*libperf_print_fn_t)(enum libperf_print_level level,
22
+
const char \*, va_list ap);
23
+
24
+
void libperf_set_print(libperf_print_fn_t fn);
25
+
26
+
perf/cpumap.h
27
+
-------------
28
+
.. code-block:: c
29
+
30
+
struct perf_cpu_map \*perf_cpu_map__dummy_new(void);
31
+
struct perf_cpu_map \*perf_cpu_map__new(const char \*cpu_list);
32
+
struct perf_cpu_map \*perf_cpu_map__read(FILE \*file);
33
+
struct perf_cpu_map \*perf_cpu_map__get(struct perf_cpu_map \*map);
34
+
void perf_cpu_map__put(struct perf_cpu_map \*map);
35
+
int perf_cpu_map__cpu(const struct perf_cpu_map \*cpus, int idx);
36
+
int perf_cpu_map__nr(const struct perf_cpu_map \*cpus);
37
+
perf_cpu_map__for_each_cpu(cpu, idx, cpus)
38
+
39
+
perf/threadmap.h
40
+
----------------
41
+
.. code-block:: c
42
+
43
+
struct perf_thread_map \*perf_thread_map__new_dummy(void);
44
+
void perf_thread_map__set_pid(struct perf_thread_map \*map, int thread, pid_t pid);
45
+
char \*perf_thread_map__comm(struct perf_thread_map \*map, int thread);
46
+
struct perf_thread_map \*perf_thread_map__get(struct perf_thread_map \*map);
47
+
void perf_thread_map__put(struct perf_thread_map \*map);
48
+
49
+
perf/evlist.h
50
+
-------------
51
+
.. code-block::
52
+
53
+
void perf_evlist__init(struct perf_evlist \*evlist);
54
+
void perf_evlist__add(struct perf_evlist \*evlist,
55
+
struct perf_evsel \*evsel);
56
+
void perf_evlist__remove(struct perf_evlist \*evlist,
57
+
struct perf_evsel \*evsel);
58
+
struct perf_evlist \*perf_evlist__new(void);
59
+
void perf_evlist__delete(struct perf_evlist \*evlist);
60
+
struct perf_evsel\* perf_evlist__next(struct perf_evlist \*evlist,
61
+
struct perf_evsel \*evsel);
62
+
int perf_evlist__open(struct perf_evlist \*evlist);
63
+
void perf_evlist__close(struct perf_evlist \*evlist);
64
+
void perf_evlist__enable(struct perf_evlist \*evlist);
65
+
void perf_evlist__disable(struct perf_evlist \*evlist);
66
+
perf_evlist__for_each_evsel(evlist, pos)
67
+
void perf_evlist__set_maps(struct perf_evlist \*evlist,
68
+
struct perf_cpu_map \*cpus,
69
+
struct perf_thread_map \*threads);
70
+
71
+
perf/evsel.h
72
+
------------
73
+
.. code-block:: c
74
+
75
+
struct perf_counts_values {
76
+
union {
77
+
struct {
78
+
uint64_t val;
79
+
uint64_t ena;
80
+
uint64_t run;
81
+
};
82
+
uint64_t values[3];
83
+
};
84
+
};
85
+
86
+
void perf_evsel__init(struct perf_evsel \*evsel,
87
+
struct perf_event_attr \*attr);
88
+
struct perf_evsel \*perf_evsel__new(struct perf_event_attr \*attr);
89
+
void perf_evsel__delete(struct perf_evsel \*evsel);
90
+
int perf_evsel__open(struct perf_evsel \*evsel, struct perf_cpu_map \*cpus,
91
+
struct perf_thread_map \*threads);
92
+
void perf_evsel__close(struct perf_evsel \*evsel);
93
+
int perf_evsel__read(struct perf_evsel \*evsel, int cpu, int thread,
94
+
struct perf_counts_values \*count);
95
+
int perf_evsel__enable(struct perf_evsel \*evsel);
96
+
int perf_evsel__disable(struct perf_evsel \*evsel);
97
+
int perf_evsel__apply_filter(struct perf_evsel \*evsel, const char \*filter);
98
+
struct perf_cpu_map \*perf_evsel__cpus(struct perf_evsel \*evsel);
99
+
struct perf_thread_map \*perf_evsel__threads(struct perf_evsel \*evsel);
100
+
struct perf_event_attr \*perf_evsel__attr(struct perf_evsel \*evsel);
+123
tools/perf/lib/Documentation/tutorial/tutorial.rst
+123
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