1.. _profiling-perf:
2
3Perf
4####
5
6Perf is a profiler tool based on stack tracing. It can be used for lightweight profiling
7with minimal code overhead.
8
9Work Principle
10**************
11
12The ``perf record`` shell command starts a timer with the perf tracer function.
13Timers are driven by interrupts, so the perf tracer function is called during an interruption.
14The Zephyr core saves the return address and frame pointer in the interrupt stack or ``callee_saved``
15structure before calling the interrupt handler. Thus, the perf trace function makes stack traces by
16using the return address and frame pointer.
17
18The :zephyr_file:`scripts/profiling/stackcollapse.py` script can be used to convert return addresses
19in the stack trace to function names using symbols from the ELF file, and to prints them in the
20format expected by `FlameGraph`_.
21
22Configuration
23*************
24
25You can configure this module using the following options:
26
27* :kconfig:option:`CONFIG_PROFILING_PERF`: Enables the module. This option adds
28  the ``perf`` command to the shell.
29
30* :kconfig:option:`CONFIG_PROFILING_PERF_BUFFER_SIZE`: Sets the size of the perf buffer
31  where samples are saved before printing.
32
33Usage
34*****
35
36Refer to the :zephyr:code-sample:`profiling-perf` sample for an example of how to use the perf tool.
37
38 .. _FlameGraph: https://github.com/brendangregg/FlameGraph/
39