124 lines
2.8 KiB
ReStructuredText
124 lines
2.8 KiB
ReStructuredText
.. 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
|