doc: Added Percepio Tracealyzer guide on Tracing page
The Tracing page did not cover the Percepio Tracealyzer support. Added a guide for Tracealyzer with a screenshot (like SystemView has). Moved the three tools to a common subsection for better overview. (Updated with kartben patch.) Signed-off-by: Johan Kraft <johan.kraft@percepio.com>
This commit is contained in:
Johan Kraft
Carles Cufí
parent
9a5f145c7a
commit
e8c3154ee1
2 changed files with 269 additions and 17 deletions
|
|
@ -7,7 +7,7 @@ Overview
|
|||
********
|
||||
|
||||
The tracing feature provides hooks that permits you to collect data from
|
||||
your application and allows tools running on a host to visualize the inner-working of
|
||||
your application and allows :ref:`tools` running on a host to visualize the inner-working of
|
||||
the kernel and various subsystems.
|
||||
|
||||
Every system has application-specific events to trace out. Historically,
|
||||
|
|
@ -92,6 +92,262 @@ The CTF top layer is enabled using the configuration option
|
|||
:kconfig:option:`CONFIG_TRACING_CTF` and can be used with the different transport
|
||||
backends both in synchronous and asynchronous modes.
|
||||
|
||||
.. _tools:
|
||||
|
||||
Tracing Tools
|
||||
*************
|
||||
|
||||
Zephyr includes support for several popular tracing tools, presented below in alphabetical order.
|
||||
|
||||
Percepio Tracealyzer Support
|
||||
============================
|
||||
|
||||
Zephyr includes support for `Percepio Tracealyzer`_ that offers trace visualization for
|
||||
simplified analysis, report generation and other analysis features. Tracealyzer allows for trace
|
||||
streaming over various interfaces and also snapshot tracing, where the events are kept in a RAM
|
||||
buffer.
|
||||
|
||||
.. _Percepio Tracealyzer: https://percepio.com/tracealyzer
|
||||
|
||||
.. figure:: percepio_tracealyzer.png
|
||||
:align: center
|
||||
:alt: Percepio Tracealyzer
|
||||
:figclass: align-center
|
||||
:width: 80%
|
||||
|
||||
Zephyr kernel events are captured automatically when Tracealyzer tracing is enabled.
|
||||
Tracealyzer also provides extensive support for application logging, where you call the tracing
|
||||
library from your application code. This lets you visualize kernel events and application events
|
||||
together, for example as data plots or state diagrams on logged variables.
|
||||
Learn more in the Tracealyzer User Manual provided with the application.
|
||||
|
||||
Percepio TraceRecorder and Stream Ports
|
||||
---------------------------------------
|
||||
The tracing library for Tracealyzer (TraceRecorder) is included in the Zephyr manifest and
|
||||
provided under the same license (Apache 2.0). This is enabled by adding the following
|
||||
configuration options in your prj.conf:
|
||||
|
||||
.. code-block:: cfg
|
||||
|
||||
CONFIG_TRACING=y
|
||||
CONFIG_PERCEPIO_TRACERECORDER=y
|
||||
|
||||
Or using menuconfig:
|
||||
|
||||
* Enable :menuselection:`Subsystems and OS Services --> Tracing Support`
|
||||
* Under :menuselection:`Subsystems and OS Services --> Tracing Support --> Tracing Format`, select
|
||||
:guilabel:`Percepio Tracealyzer`
|
||||
|
||||
Some additional settings are needed to configure TraceRecorder. The most important configuration
|
||||
is to select the right "stream port". This specifies how to output the trace data.
|
||||
As of July 2024, the following stream ports are available in the Zephyr configuration system:
|
||||
|
||||
* **Ring Buffer**: The trace data is kept in a circular RAM buffer.
|
||||
* **RTT**: Trace streaming via Segger RTT on J-Link debug probes.
|
||||
* **ITM**: Trace streaming via the ITM function on Arm Cortex-M devices.
|
||||
* **Semihost**: For tracing on QEMU. Streams the trace data to a host file.
|
||||
|
||||
Select the stream port in menuconfig under
|
||||
:menuselection:`Modules --> percepio --> TraceRecorder --> Stream Port`.
|
||||
|
||||
Or simply add one of the following options in your prj.conf:
|
||||
|
||||
.. code-block:: cfg
|
||||
|
||||
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RINGBUFFER=y
|
||||
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT=y
|
||||
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_ITM=y
|
||||
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_ZEPHYR_SEMIHOST=y
|
||||
|
||||
Make sure to only include ONE of these configuration options.
|
||||
|
||||
The stream port modules have individual configuration options. In menuconfig these are found
|
||||
under :menuselection:`Modules --> percepio --> TraceRecorder --> (Stream Port) Config`.
|
||||
The most important options for each stream port are described below.
|
||||
|
||||
Tracealyzer Snapshot Tracing (Ring Buffer)
|
||||
------------------------------------------
|
||||
|
||||
The "Ring Buffer" stream port keeps the trace data in a RAM buffer on the device.
|
||||
By default, this is a circular buffer, meaning that it always contains the most recent data.
|
||||
This is used to dump "snapshots" of the trace data, e.g. by using the debugger. This usually only
|
||||
allows for short traces, unless you have megabytes of RAM to spare, so it is not suitable for
|
||||
profiling. However, it can be quite useful for debugging in combination with breakpoints.
|
||||
For example, if you set a breakpoint in an error handler, a snapshot trace can show the sequence
|
||||
of events leading up to the error. Snapshot tracing is also easy to begin with, since it doesn't
|
||||
depend on any particular debug probe or other development tool.
|
||||
|
||||
To use the Ring Buffer option, make sure to have the following configuration options in your
|
||||
prj.cnf:
|
||||
|
||||
.. code-block:: cfg
|
||||
|
||||
CONFIG_TRACING=y
|
||||
CONFIG_PERCEPIO_TRACERECORDER=y
|
||||
CONFIG_PERCEPIO_TRC_START_MODE_START=y
|
||||
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RINGBUFFER=y
|
||||
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RINGBUFFER_SIZE=<size in bytes>
|
||||
|
||||
Or if using menuconfig:
|
||||
|
||||
* Enable :menuselection:`Subsystems and OS Services --> Tracing Support`
|
||||
* Under :menuselection:`Subsystems and OS Services --> Tracing Support --> Tracing Format`, select
|
||||
:guilabel:`Percepio Tracealyzer`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> Recorder Start Mode`, select
|
||||
:guilabel:`Start`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> Stream Port`, select
|
||||
:guilabel:`Ring Buffer`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> Ring Buffer Config --> Buffer Size`,
|
||||
set the buffer size in bytes.
|
||||
|
||||
The default buffer size can be reduced if you are tight on RAM, or increased if you have RAM to
|
||||
spare and want longer traces. You may also optimize the Tracing Configuration settings to get
|
||||
longer traces by filtering out less important events.
|
||||
In menuconfig, see
|
||||
:menuselection:`Subsystems and OS Services --> Tracing Support --> Tracing Configuration`.
|
||||
|
||||
To view the trace data, the easiest way is to start your debugger (west debug) and run the
|
||||
following GDB command::
|
||||
|
||||
dump binary value trace.bin *RecorderDataPtr
|
||||
|
||||
The resulting file is typically found in the root of the build folder, unless a different path is
|
||||
specified. Open this file in Tracealyzer by selecting :menuselection:`File --> Open --> Open File`.
|
||||
|
||||
Tracealyzer Streaming with SEGGER RTT
|
||||
-------------------------------------
|
||||
|
||||
Tracealyzer has built-in support for SEGGER RTT to receive trace data using a J-Link probe.
|
||||
This allows for recording very long traces. To configure Zephyr for RTT streaming to Tracealyzer,
|
||||
add the following configuration options in your prj.cnf:
|
||||
|
||||
.. code-block:: cfg
|
||||
|
||||
CONFIG_TRACING=y
|
||||
CONFIG_PERCEPIO_TRACERECORDER=y
|
||||
CONFIG_PERCEPIO_TRC_START_MODE_START_FROM_HOST=y
|
||||
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT=y
|
||||
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT_UP_BUFFER_SIZE=<size in bytes>
|
||||
|
||||
Or if using menuconfig:
|
||||
|
||||
* Enable :menuselection:`Subsystems and OS Services --> Tracing Support`
|
||||
* Under :menuselection:`Subsystems and OS Services --> Tracing Support --> Tracing Format`, select
|
||||
:guilabel:`Percepio Tracealyzer`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> Recorder Start Mode`, select
|
||||
:guilabel:`Start From Host`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> Stream Port`, select
|
||||
:guilabel:`RTT`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> RTT Config`, set the size of the
|
||||
RTT "up" buffer in bytes.
|
||||
|
||||
The setting :guilabel:`RTT buffer size up` sets the size of the RTT transmission buffer. This is important
|
||||
for throughput. By default this buffer is quite large, 5000 bytes, to give decent performance
|
||||
also on onboard J-Link debuggers (they are not as fast as the stand-alone probes).
|
||||
If you are tight on RAM, you may consider reducing this setting. If using a regular J-Link probe
|
||||
it is often sufficient with a much smaller buffer, e.g. 1 KB or less.
|
||||
|
||||
Learn more about RTT streaming in the Tracealyzer User Manual.
|
||||
See Creating and Loading Traces -> Percepio TraceRecorder -> Using TraceRecorder v4.6 or later ->
|
||||
Stream ports (or search for RTT).
|
||||
|
||||
Tracealyzer Streaming with Arm ITM
|
||||
----------------------------------
|
||||
|
||||
This stream port is for Arm Cortex-M devices featuring the ITM unit. It is recommended to use a
|
||||
fast debug probe that allows for SWO speeds of 10 MHz or higher. To use this stream port,
|
||||
apply the following configuration options:
|
||||
|
||||
.. code-block:: cfg
|
||||
|
||||
CONFIG_TRACING=y
|
||||
CONFIG_PERCEPIO_TRACERECORDER=y
|
||||
CONFIG_PERCEPIO_TRC_START_MODE_START=y
|
||||
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_ITM=y
|
||||
CONFIG_PERCEPIO_TRC_CFG_ITM_PORT=1
|
||||
|
||||
Or if using menuconfig:
|
||||
|
||||
* Enable :menuselection:`Subsystems and OS Services --> Tracing Support`
|
||||
* Under :menuselection:`Subsystems and OS Services --> Tracing Support --> Tracing Format`, select
|
||||
:guilabel:`Percepio Tracealyzer`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> Recorder Start Mode`, select
|
||||
:guilabel:`Start`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> Stream Port`, select
|
||||
:guilabel:`ITM`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> ITM Config`, set the ITM port to
|
||||
1.
|
||||
|
||||
The main setting for the ITM stream port is the ITM port (0-31). A dedicated channel is needed
|
||||
for Tracealyzer. Port 0 is usually reserved for printf logging, so channel 1 is used by default.
|
||||
|
||||
The option :guilabel:`Use internal buffer` should typically remain disabled. It buffers the data in RAM
|
||||
before transmission and defers the data transmission to the periodic TzCtrl thread.
|
||||
|
||||
The host-side setup depends on what debug probe you are using. Learn more in the Tracealyzer
|
||||
User Manual.
|
||||
See :menuselection:`Creating and Loading Traces --> Percepio TraceRecorder --> Using TraceRecorder v4.6 or later --> Stream ports (or search for ITM)`.
|
||||
|
||||
Tracealyzer Streaming from QEMU (Semihost)
|
||||
------------------------------------------
|
||||
|
||||
This stream port is designed for Zephyr tracing in QEMU. This can be an easy way to get started
|
||||
with tracing and try out streaming trace without needing a fast debug probe. The data is streamed
|
||||
to a host file using semihosting. To use this option, apply the following configuration options:
|
||||
|
||||
.. code-block:: cfg
|
||||
|
||||
CONFIG_SEMIHOST=y
|
||||
CONFIG_TRACING=y
|
||||
CONFIG_PERCEPIO_TRACERECORDER=y
|
||||
CONFIG_PERCEPIO_TRC_START_MODE_START=y
|
||||
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_ZEPHYR_SEMIHOST=y
|
||||
|
||||
Using menuconfig
|
||||
|
||||
* Enable :menuselection:`General Architecture Options --> Semihosting support for Arm and RISC-V targets`
|
||||
* Enable :menuselection:`Subsystems and OS Services --> Tracing Support`
|
||||
* Under :menuselection:`Subsystems and OS Services --> Tracing Support --> Tracing Format`, select
|
||||
:guilabel:`Percepio Tracealyzer`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> Recorder Start Mode`, select
|
||||
:guilabel:`Start`
|
||||
* Under :menuselection:`Modules --> percepio --> TraceRecorder --> Stream Port`, select
|
||||
:guilabel:`Semihost`
|
||||
|
||||
By default, the resulting trace file is found in :file:`./trace.psf` in the root of the build folder,
|
||||
unless a different path is specified. Open this file in `Percepio Tracealyzer`_ by selecting
|
||||
:menuselection:`File --> Open --> Open File`.
|
||||
|
||||
Recorder Start Mode
|
||||
-------------------
|
||||
|
||||
You may have noticed the :guilabel:`Recorder Start Mode` option in the Tracealyzer examples above.
|
||||
This decides when the tracing starts. With the option :guilabel:`Start`, the tracing begins directly
|
||||
at startup, once the TraceRecorder library has been initialized. This is recommended when using the
|
||||
Ring Buffer and Semihost stream ports.
|
||||
|
||||
For streaming via RTT or ITM you may also use :guilabel:`Start From Host` or
|
||||
:guilabel:`Start Await Host`. Both listens for start commands from the Tracealyzer application. The
|
||||
latter option, :guilabel:`Start Await Host`, causes the TraceRecorder initialization to block until
|
||||
the start command is received from the Tracealyzer application.
|
||||
|
||||
Custom Stream Ports for Tracealyzer
|
||||
-----------------------------------
|
||||
|
||||
The stream ports are small modules within TraceRecorder that define what functions to call to
|
||||
output the trace data and (optionally) how to read start/stop commands from Tracealyzer.
|
||||
It is fairly easy to make custom stream ports to implement your own data transport and
|
||||
Tracealyzer can receive trace streams over various interfaces, including files, sockets,
|
||||
COM ports, named pipes and more. Note that additional stream port modules are available in the
|
||||
TraceRecorder repo (e.g. lwIP), although they might require modifications to work with Zephyr.
|
||||
|
||||
Learning More
|
||||
-------------
|
||||
|
||||
Learn more about how to get started in the `Tracealyzer Getting Started Guides`_.
|
||||
|
||||
.. _Tracealyzer Getting Started Guides: https://percepio.com/tracealyzer/gettingstarted/
|
||||
|
||||
|
||||
SEGGER SystemView Support
|
||||
=========================
|
||||
|
|
@ -141,6 +397,18 @@ builtin table::
|
|||
# On Linux and MacOS
|
||||
cp $ZEPHYR_BASE/subsys/tracing/sysview/SYSVIEW_Zephyr.txt ~/.config/SEGGER/
|
||||
|
||||
TraceCompass
|
||||
=============
|
||||
|
||||
TraceCompass is an open source tool that visualizes CTF events such as thread
|
||||
scheduling and interrupts, and is helpful to find unintended interactions and
|
||||
resource conflicts on complex systems.
|
||||
|
||||
See also the presentation by Ericsson,
|
||||
`Advanced Trouble-shooting Of Real-time Systems
|
||||
<https://wiki.eclipse.org/images/0/0e/TechTalkOnlineDemoFeb2017_v1.pdf>`_.
|
||||
|
||||
|
||||
User-Defined Tracing
|
||||
====================
|
||||
|
||||
|
|
@ -226,22 +494,6 @@ to an host computer::
|
|||
The resulting channel0_0 file have to be placed in a directory with the ``metadata``
|
||||
file like the other backend.
|
||||
|
||||
Visualisation Tools
|
||||
*******************
|
||||
|
||||
TraceCompass
|
||||
=============
|
||||
|
||||
TraceCompass is an open source tool that visualizes CTF events such as thread
|
||||
scheduling and interrupts, and is helpful to find unintended interactions and
|
||||
resource conflicts on complex systems.
|
||||
|
||||
See also the presentation by Ericsson,
|
||||
`Advanced Trouble-shooting Of Real-time Systems
|
||||
<https://wiki.eclipse.org/images/0/0e/TechTalkOnlineDemoFeb2017_v1.pdf>`_.
|
||||
|
||||
|
||||
|
||||
Future LTTng Inspiration
|
||||
************************
|
||||
|
||||
|
|
|
|||
BIN
doc/services/tracing/percepio_tracealyzer.png
Normal file
BIN
doc/services/tracing/percepio_tracealyzer.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 222 KiB |
Loading…
Add table
Add a link
Reference in a new issue