Skip to content

Commit 0c7669a

Browse files
gerekongerekon
committed
Adds example for ESP-IDF component
1 parent 7607807 commit 0c7669a

File tree

7 files changed

+319
-0
lines changed

7 files changed

+319
-0
lines changed

‎examples/ESP-IDF/tracing/CMakeLists.txt

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# The following lines of boilerplate have to be in your project's CMakeLists
2+
# in this exact order for cmake to work correctly
3+
cmake_minimum_required(VERSION 3.16)
4+
5+
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
6+
# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
7+
idf_build_set_property(MINIMAL_BUILD OFF)
8+
project(tracealyzer)

‎examples/ESP-IDF/tracing/README.md

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
2+
| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- |
3+
# Example: Application Level Tracing - Percepio Tracealyzer Traces (tracealyzer)
4+
5+
This test code shows how to perform system-wide behavioral analysis of the program using [Percepio Tracealyzer tool](https://www.segger.com/products/development-tools/systemview/).
6+
7+
For description of [SystemView tracing](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#system-behaviour-analysis-with-segger-systemview) please refer to **ESP32 Programming Guide**, section **Application Level Tracing library**. The following example provides practical implementation of this functionality.
8+
9+
10+
## Use Case
11+
12+
To find the reason of program's misbehaviour it is often necessary to have the whole picture of interacting components (scheduler, IRQs, tasks, semaphores etc.) in the system. In such cases tools which allow to trace the behaviour of the system as a whole can be very useful.
13+
Consider the following situation. User program have a timer and a task. Upon every tick the timer sends an event to the task. When task receives event it prints a message. Timer should notify the task 10 times.
14+
There can be a problem which causes the task to lose some events.
15+
Below is the timer's ISR code:
16+
17+
```
18+
static void example_timer_isr(void *arg)
19+
{
20+
example_event_data_t *tim_arg = (example_event_data_t *)arg;
21+
22+
if (tim_arg->thnd != NULL) {
23+
if (tim_arg->count++ < 10) {
24+
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
25+
if (xTaskNotifyFromISR(tim_arg->thnd, tim_arg->count, eSetValueWithOverwrite, &xHigherPriorityTaskWoken) != pdPASS) {
26+
ESP_EARLY_LOGE(TAG, "Failed to notify task %p", tim_arg->thnd);
27+
} else {
28+
if (xHigherPriorityTaskWoken == pdTRUE) {
29+
portYIELD_FROM_ISR();
30+
}
31+
}
32+
}
33+
}
34+
// re-start timer
35+
example_timer_rearm(tim_arg->group, tim_arg->timer);
36+
}
37+
```
38+
39+
Below is the task's code:
40+
41+
```
42+
static void example_task(void *p)
43+
{
44+
example_event_data_t *arg = (example_event_data_t *) p;
45+
timer_isr_handle_t inth;
46+
47+
ESP_LOGI(TAG, "%p: run task", xTaskGetCurrentTaskHandle());
48+
49+
esp_err_t res = timer_isr_register(arg->group, arg->timer, example_timer_isr, arg, 0, &inth);
50+
if (res != ESP_OK) {
51+
ESP_LOGE(TAG, "%p: failed to register timer ISR", xTaskGetCurrentTaskHandle());
52+
}
53+
else {
54+
res = timer_start(arg->group, arg->timer);
55+
if (res != ESP_OK) {
56+
ESP_LOGE(TAG, "%p: failed to start timer", xTaskGetCurrentTaskHandle());
57+
}
58+
}
59+
60+
while (1) {
61+
uint32_t event_val;
62+
xTaskNotifyWait(0, 0, &event_val, portMAX_DELAY);
63+
ESP_LOGI(TAG, "Task[%p]: received event %d", xTaskGetCurrentTaskHandle(), event_val);
64+
}
65+
}
66+
```
67+
68+
Potential problem can arise in such program because task and timer has no any mechanism to acknowledge the events transfer. Task needs some time to process an event before waiting for the next one. In this case call to `ESP_LOGI` will be the most time consuming part of event processing. Therefore when timer's ISR is called at some rate it can happen that `xTaskNotifyFromISR` gets called several times before task calls `xTaskNotifyWait`. In these conditions some events will be lost. Possible solution for this is to increase timer's tick period or to use some events acknowledgement mechanism.
69+
70+
Check the full example code [sysview_tracing](main/sysview_tracing.c) that when compiled in dual core mode reproduces the described problem on both cores. Below is the output of example compiled in single core mode. It shows that task misses several events:
71+
72+
```
73+
I (295) example: 0x3ffb6c10: run task
74+
I (297) example: Task[0x3ffb6c10]: received event 1
75+
I (300) example: Task[0x3ffb6c10]: received event 2
76+
I (306) example: Task[0x3ffb6c10]: received event 5
77+
I (311) example: Task[0x3ffb6c10]: received event 8
78+
I (317) example: Task[0x3ffb6c10]: received event 10
79+
```
80+
81+
82+
## Detecting The Reason Of The Problem
83+
84+
Besides built-in functionality to trace FreeRTOS internal operations SystemView also provides user with means to define its own trace messages and transfer problem-specific data to the host. In this example we extend SystemView with user-defined tracing module in order to
85+
make the root cause of the problem more clear in the gathered trace.
86+
87+
There are two ways to send user-defined info to SystemView:
88+
1. Using built-in SystemView messages. This method uses `SEGGER_SYSVIEW_OnUserStart` and `SEGGER_SYSVIEW_OnUserStop` API to indicate that some user event started or stopped. Disadvantge of this way is that those API do not carry any other data except for user event ID. Advantage is that you do not need to write any additional code to use these functions. In SystemView messages sent by means of that API will be shown as `User Start` or `User Stop` with user event ID as only parameter: 0 - for timer and 1 - for task in this example.
89+
2. Using custom SystemView messages. This is more flexible way. It implies extending SystemView with user module having its own set of events with any number of parameters (data) in each. For more details on extending see [code of this example](main/sysview_tracing.c) and [SystemView User Manual](https://www.segger.com/downloads/jlink/UM08027).
90+
91+
To run the example and find out the reason of the problem:
92+
93+
1. Connect JTAG interface to ESP32 board, power up both JTAG and ESP32. For details how to setup JTAG interface see [JTAG Debugging](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html).
94+
95+
2. [Run OpenOCD](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html#run-openocd). If you are using the [binary distribution of OpenOCD](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html#jtag-debugging-setup-openocd) and one of versions of [ESP-WROVER-KIT](https://docs.espressif.com/projects/esp-idf/en/latest/hw-reference/modules-and-boards.html#esp-wrover-kit-v3), respective command line will look as follows:
96+
97+
```
98+
cd ~/esp/openocd-esp32
99+
bin/openocd -s share/openocd/scripts -f board/esp32-wrover-kit-3.3v.cfg
100+
```
101+
NOTE: In order to run this example you need OpenOCD version `v0.10.0-esp32-20181105` or later.
102+
103+
3. Compile and load the example. Note to enable application tracing in menuconfig by going to `Component config > Application Level Tracing` and selecting `(X) Trace memory`. Also in order to generate SystemView trace data you need to enable this in `Component config > Application Level Tracing > FreeRTOS SystemView Tracing` by checking `(X) SystemView Tracing Enable`. Also ensure that all SystemView events are enabled there.
104+
105+
4. If you are going to use custom events enable them by checking `Example Configuration > Use custom SystemView event IDs`. By default SystemView shows only numeric values of IDs and parameters for custom messages in `Events` view. To make them pretty-looking you need to define for them parsing templates in `SYSVIEW_FreeRTOS.txt` which is resided in SystemView installation directory. For this example you can use `SYSVIEW_FreeRTOS.txt` from the project's root directory.
106+
107+
5. It is useful to use GDB to start and/or stop tracing automatically. To do this you need to prepare special `gdbinit` file:
108+
109+
```
110+
target remote :3333
111+
mon reset halt
112+
b app_main
113+
commands
114+
mon esp sysview start file:///tmp/sysview_example.svdat
115+
# For dual-core mode uncomment the line below and comment the line above
116+
# mon esp sysview start file:///tmp/sysview_example0.svdat file:///tmp/sysview_example1.svdat
117+
c
118+
end
119+
c
120+
```
121+
122+
Using this file GDB will connect to the target, reset it, and start tracing when it hit breakpoint at `app_main`. Trace data will be saved to `/tmp/sysview_example.svdat`.
123+
124+
6. Run GDB using the following command from the project root directory:
125+
126+
```
127+
xtensa-esp32-elf-gdb -x gdbinit build/sysview_tracing.elf
128+
```
129+
130+
**Note:** Replace `xtensa-esp32-elf-gdb` with the related gdb tool (e.g. `xtensa-esp32s2-elf-gdb`, `xtensa-esp32s3-elf-gdb` or `riscv32-esp-elf-gdb`) if running the example on different chip.
131+
132+
7. When program prints the last message, interrupt its execution (e.g. by pressing `CTRL+C`) and type the following command in GDB console to stop tracing:
133+
134+
```
135+
mon esp sysview stop
136+
```
137+
138+
You can also use another breakpoint to stop tracing and add respective lines to `gdbinit` at step 5.
139+
140+
8. Open trace data file in SystemView tool.
141+
142+
9. Right-click on any event in `Events` view and select:
143+
144+
- `Show User Events only` if you compiled example to use only built-in event.
145+
- `Show APIs only` if you compiled example to use custom events.
146+
147+
10. Now you can navigate over user-defined messages and see when timer `TG1_T0_LEVEL` sends events (`SYSVIEW_EXAMPLE_SEND_EVENT_START/STOP` or `User Start/Stop(0)`) and when task `svtrace0` reads them (`SYSVIEW_EXAMPLE_WAIT_EVENT_START/STOP` or `User Start/Stop(1)`).
148+
If you compiled example to use custom events you will also be able to see the values sent by timer and ones actually received by tasks.

‎examples/ESP-IDF/tracing/gdbinit

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
set pagination off
2+
target remote :3333
3+
4+
mon reset halt
5+
maintenance flush register-cache
6+
7+
b app_main
8+
commands
9+
mon esp apptrace start "file:///tmp/tracealyzer_example.psf" 0 -1 -1 0 0
10+
c
11+
end
12+
13+
c

‎examples/ESP-IDF/tracing/main/CMakeLists.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
idf_component_register(SRCS "tracealyzer.c"
2+
PRIV_REQUIRES esp_driver_gptimer app_trace
3+
INCLUDE_DIRS ".")

‎examples/ESP-IDF/tracing/main/idf_component.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
## IDF Component Manager Manifest File
2+
dependencies:
3+
## Required IDF version
4+
idf:
5+
version: ">=4.2.0"
6+
percepio/tracerecorder:
7+
version: "*"

‎examples/ESP-IDF/tracing/main/tracealyzer.c

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
/*
2+
* SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
3+
*
4+
* SPDX-License-Identifier: Unlicense OR CC0-1.0
5+
*/
6+
/* Application Trace to Host Example
7+
8+
This example code is in the Public Domain (or CC0 licensed, at your option.)
9+
10+
Unless required by applicable law or agreed to in writing, this
11+
software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
12+
CONDITIONS OF ANY KIND, either express or implied.
13+
*/
14+
15+
#include "sdkconfig.h"
16+
#include <stdio.h>
17+
#include <string.h>
18+
#include <stdlib.h>
19+
#include <inttypes.h>
20+
#include "esp_log.h"
21+
#include "freertos/FreeRTOS.h"
22+
#include "freertos/task.h"
23+
#include "driver/gptimer.h"
24+
25+
static const char *TAG = "example";
26+
27+
typedef struct {
28+
gptimer_handle_t gptimer;
29+
int count;
30+
TaskHandle_t thnd;
31+
uint64_t period;
32+
char task_name[32];
33+
} example_event_data_t;
34+
35+
static bool example_timer_alarm_cb(gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_ctx)
36+
{
37+
example_event_data_t *tim_arg = (example_event_data_t *)user_ctx;
38+
bool need_yield = false;
39+
40+
if (tim_arg->thnd != NULL) {
41+
if (tim_arg->count++ < 10000) {
42+
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
43+
if (xTaskNotifyFromISR(tim_arg->thnd, tim_arg->count, eSetValueWithOverwrite, &xHigherPriorityTaskWoken) != pdPASS) {
44+
ESP_EARLY_LOGE(TAG, "Failed to notify task %p", tim_arg->thnd);
45+
} else {
46+
if (xHigherPriorityTaskWoken == pdTRUE) {
47+
need_yield = true;
48+
}
49+
}
50+
}
51+
}
52+
return need_yield;
53+
}
54+
55+
static void example_task(void *p)
56+
{
57+
uint32_t event_val;
58+
example_event_data_t *arg = (example_event_data_t *) p;
59+
ESP_LOGI(TAG, "%p: run task", xTaskGetCurrentTaskHandle());
60+
gptimer_alarm_config_t alarm_config = {
61+
.reload_count = 0,
62+
.alarm_count = arg->period,
63+
.flags.auto_reload_on_alarm = true,
64+
};
65+
// This task is pinned to a specific core, to the interrupt will also be install to that core
66+
gptimer_event_callbacks_t cbs = {
67+
.on_alarm = example_timer_alarm_cb,
68+
};
69+
70+
traceString MyChannel = xTraceRegisterString(xPortGetCoreID() == 0 ? "DataCh0" : "DataCh1");
71+
72+
ESP_ERROR_CHECK(gptimer_register_event_callbacks(arg->gptimer, &cbs, arg));
73+
ESP_ERROR_CHECK(gptimer_set_alarm_action(arg->gptimer, &alarm_config));
74+
ESP_ERROR_CHECK(gptimer_enable(arg->gptimer));
75+
ESP_ERROR_CHECK(gptimer_start(arg->gptimer));
76+
while (1) {
77+
xTaskNotifyWait(0, 0, &event_val, portMAX_DELAY);
78+
ESP_LOGI(TAG, "Task[%p]: received event %"PRIu32, xTaskGetCurrentTaskHandle(), event_val);
79+
vTracePrintF(MyChannel, "Sensor Data = %d", event_val);
80+
}
81+
}
82+
83+
void app_main(void)
84+
{
85+
static example_event_data_t event_data[CONFIG_FREERTOS_NUMBER_OF_CORES];
86+
87+
for (int i = 0; i < CONFIG_FREERTOS_NUMBER_OF_CORES; i++) {
88+
gptimer_config_t timer_config = {
89+
.clk_src = GPTIMER_CLK_SRC_DEFAULT,
90+
.direction = GPTIMER_COUNT_UP,
91+
.resolution_hz = 1000000,
92+
};
93+
ESP_ERROR_CHECK(gptimer_new_timer(&timer_config, &event_data[i].gptimer));
94+
event_data[i].period = 100000 * (i + 1);
95+
}
96+
97+
for (int i = 0; i < CONFIG_FREERTOS_NUMBER_OF_CORES; i++) {
98+
sprintf(event_data->task_name, "trace%d", i);
99+
xTaskCreatePinnedToCore(example_task, event_data->task_name, 4096, &event_data[i], 3, &event_data[i].thnd, i);
100+
ESP_LOGI(TAG, "Created task %p", event_data[i].thnd);
101+
}
102+
}

‎examples/ESP-IDF/tracing/sdkconfig.defaults

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Enable application tracing by default
2+
CONFIG_APPTRACE_DEST_JTAG=y
3+
CONFIG_APPTRACE_ENABLE=y
4+
5+
# Enable Percepio TraceRecorder
6+
CONFIG_PERCEPIO_RECORDER_TRC_RECORDER_MODE_STREAMING=y
7+
CONFIG_PERCEPIO_TRACERECORDER_ENABLED=y
8+
CONFIG_PERCEPIO_RECORDER_CFG_START_MODE_START_FROM_HOST=y
9+
# CONFIG_PERCEPIO_RECORDER_CFG_START_MODE_START is not set
10+
# CONFIG_PERCEPIO_RECORDER_CFG_START_MODE_START_AWAIT_HOST is not set
11+
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_ESP_IDF_APPTRACE=y
12+
# CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RINGBUFFER is not set
13+
# CONFIG_PERCEPIO_RECORDER_CFG_TRAX_MODE_BLOCK_IF_FIFO_FULL is not set
14+
CONFIG_PERCEPIO_RECORDER_CFG_TRAX_MODE_NO_BLOCK_SKIP=y
15+
# CONFIG_PERCEPIO_RECORDER_CFG_SCHEDULING_ONLY is not set
16+
CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_MEMMANG_EVENTS=y
17+
CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_USER_EVENTS=y
18+
CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_ISR_TRACING=y
19+
CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_READY_EVENTS=y
20+
CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_OSTICK_EVENTS=y
21+
CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_EVENT_GROUP_EVENTS=y
22+
CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_TIMER_EVENTS=y
23+
CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_PEND_FUNC_CALL_EVENTS=y
24+
CONFIG_PERCEPIO_RECORDER_CFG_INCLUDE_STREAM_BUFFER_EVENTS=y
25+
CONFIG_PERCEPIO_RECORDER_CFG_ENABLE_STACK_MONITOR=y
26+
CONFIG_PERCEPIO_RECORDER_CFG_STACK_MONITOR_MAX_TASKS=15
27+
CONFIG_PERCEPIO_RECORDER_CFG_STACK_MONITOR_MAX_REPORTS=1
28+
CONFIG_PERCEPIO_RECORDER_CFG_CTRL_TASK_PRIORITY=1
29+
CONFIG_PERCEPIO_RECORDER_CFG_CTRL_TASK_DELAY=10
30+
CONFIG_PERCEPIO_RECORDER_CFG_CTRL_TASK_STACK_SIZE=1024
31+
CONFIG_PERCEPIO_RECORDER_TRC_RECORDER_BUFFER_ALLOCATION_STATIC=y
32+
# CONFIG_PERCEPIO_RECORDER_TRC_RECORDER_BUFFER_ALLOCATION_DYNAMIC is not set
33+
# CONFIG_PERCEPIO_RECORDER_TRC_RECORDER_BUFFER_ALLOCATION_CUSTOM is not set
34+
CONFIG_PERCEPIO_RECORDER_CFG_MAX_ISR_NESTING=8
35+
CONFIG_PERCEPIO_RECORDER_TRC_CFG_ENTRY_TABLE_SLOTS=40
36+
CONFIG_PERCEPIO_RECORDER_TRC_CFG_ENTRY_SYMBOL_MAX_LENGTH=25
37+
# CONFIG_PERCEPIO_RECORDER_TRC_STREAM_PORT_USE_INTERNAL_BUFFER is not set
38+
CONFIG_PERCEPIO_RECORDER_TRC_CFG_ISR_TAILCHAINING_THRESHOLD_STREAMING=0

0 commit comments

Comments
 (0)