michaelh/zephyr
1
0
Fork 0
Code Releases Activity

profiling: doc: clean up grammar/spelling

Browse source 
Clean up documentation pages for the new perf tool
as they contained several typos, grammar errors, and
duplicated content between main doc page and sample
page

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This commit is contained in:
Benjamin Cabé 2024-08-14 11:49:27 +02:00 • committed by Fabio Baltieri
commit 3735ae94a1
3 changed files with 57 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

89
doc/services/profiling/perf.rst
View file

@ -1,91 +1,38 @@
.. _profiling-perf:
Perf
####
Perf is a profiler tool based on stack tracing. It can be used for lightweight profiling
with minimal code overhead.
Perf is a profiler tool, based on stack tracing. It can be used to light weight profiling
almost without any code overhead.
Work Principle
**************
Work principe
*************
The ``perf record`` shell command starts a timer with the perf tracer function.
Timers are driven by interrupts, so the perf tracer function is called during an interruption.
The Zephyr core saves the return address and frame pointer in the interrupt stack or ``callee_saved``
structure before calling the interrupt handler. Thus, the perf trace function makes stack traces by
using the return address and frame pointer.
``perf record`` shell-command starts timer with perf tracer function.
Timers are driven by inerrupts, so perf tracer function is calling during interruption.
Zephyr core save return address and frame pointer in interrupt stack or ``callee_saved``
struture before caling interrupt hundler. So perf trace function makes stack traces by
using return address and frame pointer.
Then stackcollapse.py script convert return addresses in stack trace to function names
by elf file and print them in required for FlameGraph format.
The :zephyr_file:`scripts/profiling/stackcollapse.py` script can be used to convert return addresses
in the stack trace to function names using symbols from the ELF file, and to prints them in the
format expected by `FlameGraph`_.
Configuration
*************
Configure this module using the following options.
You can configure this module using the following options:
* :kconfig:option:`CONFIG_PROFILING_PERF`: enable the module. This opion add
perf command in shell.
* :kconfig:option:`CONFIG_PROFILING_PERF`: Enables the module. This option adds
the ``perf`` command to the shell.
* :kconfig:option:`CONFIG_PROFILING_PERF_BUFFER_SIZE`: sets size of perf buffer,
* :kconfig:option:`CONFIG_PROFILING_PERF_BUFFER_SIZE`: Sets the size of the perf buffer
where samples are saved before printing.
Usage
*****
More specific example can be found in :zephyr:code-sample:`profiling-perf`.
Refer to the :zephyr:code-sample:`profiling-perf` sample for an example of how to use the perf tool.
#. Build with perf enabled and run.
#. Begin perf sampling by shell-command
.. code-block:: text
perf record <period> <frequency>
This command will start timer with perf sampler for *period* in seconds and
with *frequency* in hertz.
Wait for the completion message ``perf done!`` or ``perf buf override!``
(if perf buffer size is smaller than required).
#. Print made by perf samles in terminal by shell-command
.. code-block:: text
perf printbuf
Output exaple:
.. code-block:: text
Perf buf length 1985
0000000000000004
0000000080004e58
00000000800071ca
0000000080000964
aaaaaaaaaaaaaaaa
0000000000000002
....
00000000800163e0
Copy gotten output in some file, for example *perf_buf*.
#. Translate perf samples by stackcollapse script to format, required by FlameGraph
.. code-block:: bash
python zephyr/scripts/perf/stackcollapse.py perf_buf <build_dir>/zephyr/zephyr.elf > perf_buf.folded
And turn into .svg FlameGraph (for example *graph.svg*)
.. code-block:: bash
./FlameGraph/flamegraph.pl perf_buf.folded > graph.svg
All this step can be done by one command
.. code-block:: bash
python zephyr/scripts/perf/stackcollapse.py perf_buf <build_dir>/zephyr/zephyr.elf | ./FlameGraph/flamegraph.pl > graph.svg
.. _FlameGraph: https://github.com/brendangregg/FlameGraph/