README.rst
1.. zephyr:code-sample:: instrumentation
2 :name: Instrumentation
3 :relevant-api: instrumentation_api
4
5 Demonstrate the instrumentation subsystem tracing and profiling features.
6
7Overview
8********
9
10This sample shows the instrumentation subsystem tracing and profiling
11features. It basically consists of two threads in a ping-pong mode, taking
12turns to execute loops that spend some CPU cycles.
13
14Requirements
15************
16
17A Linux host and a UART console is required to run this sample.
18
19Building and Running
20********************
21
22Build and flash the sample as follows, changing ``mps2/an385`` for your
23board.
24
25.. zephyr-app-commands::
26 :zephyr-app: samples/subsys/instrumentation
27 :host-os: unix
28 :board: mps2/an385
29 :goals: build flash
30 :compact:
31
32Alternatively you can run this using QEMU:
33
34.. zephyr-app-commands::
35 :zephyr-app: samples/subsys/instrumentation
36 :host-os: unix
37 :board: mps2/an385
38 :goals: run
39 :gen-args: '-DQEMU_SOCKET=y'
40 :compact:
41
42After the sample is flashed to the target (or QEMU is running), it must be possible to
43collect and visualize traces and profiling info using the instrumentation CLI
44tool, :zephyr_file:`scripts/instrumentation/zaru.py`.
45
46.. note::
47 Please note, that this subsystem uses the ``retained_mem`` driver, hence it's necessary
48 to add the proper devicetree overlay for the target board. See
49 :zephyr_file:`./samples/subsys/instrumentation/boards/mps2_an385.overlay` for an example.
50
51Connect the board's UART port to the host device and
52run the :zephyr_file:`scripts/instrumentation/zaru.py` script on the host.
53
54Source the :zephyr_file:`zephyr-env.sh` file to set the ``ZEPHYR_BASE`` variable and get
55:zephyr_file:`scripts/instrumentation/zaru.py` in your PATH:
56
57.. code-block:: console
58
59 . zephyr-env.sh
60
61Check instrumentation status:
62
63.. code-block:: console
64
65 zaru.py status
66
67Set the tracing/profiling trigger; in this sample the function
68``get_sem_and_exec_function`` is the one interesting to allow the observation
69of context switches:
70
71.. code-block:: console
72
73 zaru.py trace -v -c get_sem_and_exec_function
74
75Reboot target so tracing/profiling at the location is effective:
76
77.. code-block:: console
78
79 zaru.py reboot
80
81Wait ~2 seconds so the sample finishes 2 rounds of ping-pong between ``main``
82and ``thread_A``, and get the traces:
83
84.. code-block:: console
85
86 zaru.py trace -v
87
88Get the profile:
89
90.. code-block:: console
91
92 zaru.py profile -v -n 10
93
94Or alternatively, export the traces to Perfetto (it's necessary
95to reboot because ``zaru.py trace`` dumped the buffer and it's now empty):
96
97.. code-block:: console
98
99 zaru.py reboot
100 zaru.py trace -v --perfetto --output perfetto_zephyr.json
101
102Then, go to http://perfetto.dev, Trace Viewer, and load ``perfetto_zephyr.json``.
103
