.. 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