README.rst
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/perf/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
