1.. zephyr:code-sample:: profiling-perf
2   :name: Perf tool
3
4    Send perf samples to the host with console support
5
6This application can be used to understand how to use the :ref:`profiling-perf`
7tool.
8
9Requirements
10************
11
12The Perf tool is currently implemented only for RISC-V and x86_64 architectures.
13
14Usage example
15*************
16
17* Build and run the sample with:
18
19  .. zephyr-app-commands::
20     :zephyr-app: samples/subsys/profiling/perf
21     :board: qemu_riscv64
22     :goals: run
23     :compact:
24
25* After the sample has started, enter the shell command:
26
27  .. code-block:: console
28
29     uart:~$ perf record <duration> <frequency>
30
31  This command will start a timer for *duration* milliseconds at *frequency* Hz.
32
33* Wait for the completion message ``perf done!``, or ``perf buf override!`` if
34  the perf buffer size is smaller than required.
35
36* Print the samples captured by perf in the terminal with the shell command:
37
38  .. code-block:: console
39
40     uart:~$ perf printbuf
41
42  The output should be similar to:
43
44  .. code-block:: console
45
46     Perf buf length 2046
47     0000000000000004
48     00000000001056b2
49     0000000000108192
50     000000000010052f
51     0000000000000000
52       ....
53     000000000010052f
54     0000000000000000
55
56* Copy the output into a file, for example :file:`perf_buf`.
57
58* Generate :file:`graph.svg` with
59  :zephyr_file:`scripts/profiling/stackcollapse.py` and `FlameGraph`_:
60
61  .. _FlameGraph: https://github.com/brendangregg/FlameGraph/
62
63  .. code-block:: shell
64
65     python scripts/profiling/stackcollapse.py perf_buf build/zephyr/zephyr.elf | <flamegraph_dir_path>/flamegraph.pl > graph.svg
66
67Graph example
68=============
69
70.. image:: images/graph_example.svg
71   :align: center
72   :alt: graph example
73