System Behavior Analysis with SEGGER SystemView

[中文]

SEGGER SystemView is a real-time recording and visualization tool that allows you to analyze the runtime behavior of an application (task scheduling, ISRs, system events). In the esp_trace model, SystemView is provided as an encoder: it formats FreeRTOS and application events into the SystemView protocol, and the data is carried to the host by a transport (typically apptrace over JTAG, or UART for real-time viewing).

See SystemView for the official tool.

Enabling SystemView

SystemView support is provided by the managed component espressif/esp_sysview. The SystemView menu becomes visible only after:

  1. Adding the component dependency in idf_component.yml:

    dependencies:
  espressif/esp_sysview: ^1

  2. Selecting the external library in menuconfig: Component config > ESP Trace Configuration > Trace library > External library from component registry.

After that, you can configure SystemView in Component config > SEGGER SystemView Configuration. This menu lets you choose the timestamp source (CONFIG_ESP_TRACE_TIMESTAMP_SOURCE), individually enable or disable collection of SystemView events (CONFIG_SEGGER_SYSVIEW_EVT_XXX), and select which CPU to trace when using the UART destination.

Note

For the full, up-to-date list of configuration options and host-side setup, see the component README: esp_sysview.

To trace over the UART interface in real-time, first select UART as the destination in Component config > ESP Trace Configuration > Application Level Tracing. Then select Pro or App CPU in Component config > ESP Trace Configuration > SEGGER SystemView.

OpenOCD SystemView Tracing Command Options

When tracing over JTAG, data is collected with a dedicated OpenOCD command. For OpenOCD/JTAG setup, see JTAG Debugging.

Command usage:

esp sysview [start <options>] | [stop] | [status]

Sub-commands:

start

Start tracing (continuous streaming).

stop

Stop tracing.

status

Get tracing status.

Start command syntax:

start <outfile1> [outfile2] [poll_period [trace_size [stop_tmo]]]

outfile1

Path to file to save data from PRO CPU. This argument should have the following format: file://path/to/file.

outfile2

Path to file to save data from APP CPU. This argument should have the following format: file://path/to/file.

poll_period

Data polling period (in ms) for available trace data. If greater than 0, then command runs in non-blocking mode. By default, 1 ms.

trace_size

Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is received. By default, -1 (trace size stop trigger is disabled).

stop_tmo

Idle timeout (in sec). Tracing is stopped if there is no data for specified period of time. By default, -1 (disable this stop trigger).

Note

If poll_period is 0, OpenOCD telnet command line will not be available until tracing is stopped. You must stop it manually by resetting the board or pressing Ctrl+C in the OpenOCD window (not the one with the telnet session). Another option is to set trace_size and wait until this size of data is collected. At this point, tracing stops automatically.

Command usage example:

esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat

The tracing data will be retrieved and saved in non-blocking mode. To stop this process, enter esp sysview stop command on the OpenOCD telnet prompt, optionally pressing Ctrl+C in the OpenOCD window.

Multi-Core SystemView Tracing Command

For SystemView version 3.60 and later, which supports multi-core tracing, use the esp sysview_mcore command. This command is identical to esp sysview but uses the official SEGGER SystemView multi-core format. Tracing data from all cores are saved in the same file, which can be opened in SEGGER SystemView v3.60 or later.

Command usage example:

esp sysview_mcore start file://heap_log_mcore.SVDat

For detailed command syntax and options, refer to the esp sysview command above, as esp sysview_mcore accepts the same parameters.

Data Visualization

After trace data are collected, use a special tool to visualize the results and inspect behavior of the program.

Good instructions on how to install, configure, and visualize data in Impulse from one core can be found here.

Note

ESP-IDF uses its own mapping for SystemView FreeRTOS events IDs, so users need to replace the original file mapping $SYSVIEW_INSTALL_DIR/Description/SYSVIEW_FreeRTOS.txt with $IDF_PATH/tools/esp_app_trace/SYSVIEW_FreeRTOS.txt. Also, contents of that ESP-IDF-specific file should be used when configuring SystemView serializer using the above link.

Application Examples

Was this page helpful?