chore: import upstream snapshot with attribution

examples/system/app_trace_basic/CMakeLists.txt

@@ -0,0 +1,8 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.22)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
+idf_build_set_property(MINIMAL_BUILD ON)
+project(app_trace_basic)

examples/system/app_trace_basic/README.md

@@ -0,0 +1,73 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | ESP32-S31 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | --------- |
+
+# Application Level Tracing Example (Basic)
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example demonstrates how to use the [Application Level Tracing Library](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#) (henceforth referred to as **App Trace**) to log messages to a host via JTAG instead of the normal method of logging via UART.
+
+UART logs are time consuming and can significantly slow down the function that calls it. Therefore, it is generally a bad idea to use UART logs in time-critical functions. Logging to host via JTAG is significantly faster and can be used in time-critical functions. For more details regarding logging to host via JTAG, refer to the [Logging to Host Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#app-trace-logging-to-host).
+
+### Hardware Required
+
+To run this example, you need a supported target dev board connected to a JTAG adapter, which can come in the following forms:
+
+* [ESP-WROVER-KIT](https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/esp-wrover-kit/index.html) which integrates an on-board JTAG adapter. Ensure that the [required jumpers to enable JTAG are connected](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/get-started-wrover-kit.html#setup-options) on the WROVER-KIT.
+* ESP32, ESP32-S2 or ESP32-C2 core board (e.g. ESP32-DevKitC, [ESP32-S2-Saola-1](https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32s2/esp32-s2-saola-1/index.html)) can also work as long as you connect it to an external JTAG adapter (e.g. FT2232H, J-LINK).
+
+This example will assume that an ESP-WROVER-KIT is used.
+
+#### Connections:
+
+1. Connect the JTAG interface to the target board. For details about how to set up JTAG interface, please see [JTAG Debugging](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html). Power up both the JTAG debugger and target board.
+
+2. After connecting JTAG interface, you need to [Run OpenOCD](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html#run-openocd).
+
+3. Open a separate terminal window and run telnet by entering the command below. The telnet terminal window is used to feed commands to OpenOCD:
+
+    ```bash
+    telnet localhost 4444
+    ```
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+
+* To enable application tracing, select the `(X) Trace memory` option under `Component config > Application Level Tracing`. This option should have been selected by default.
+
+### Build, Flash, and Run
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+**Start App Trace:** In the telnet session window, trigger OpenOCD to start App Trace on the target by entering the command below. This command will collect 9000 bytes of JTAG log data and save them to the file `file://apptrace.log` (note `file://` depends on
+where OpenOCD was started). Assuming that OpenOCD was started in this example's directory, `apptrace.log` will be saved here as well.
+
+
+```bash
+esp apptrace start file://apptrace.log 0 2000 3 0 0
+```
+
+**Note:** For more details on OpenOCD commands regarding App Trace, refer to the [OpenOCD Application Level Tracing Commands](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#openocd-application-level-tracing-commands)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Troubleshooting
+
+### Unable to flash when OpenOCD is connected to the target
+
+On ESP32 boards, one likely cause would be an incorrect SPI flash voltage when starting OpenOCD. Suppose a target board/module with a 3.3 V powered SPI flash is being used, but the configuration file (ex. `board/esp32-wrover.cfg` for ESP32) is selected when starting OpenOCD which can set the SPI flash voltage to 1.8 V. In this situation, the SPI flash will not work after OpenOCD connects to the target as OpenOCD has changed the SPI flash voltage. Therefore, you might not be able to flash to the target when OpenOCD is connected.
+
+To work around this issue, users are suggested to use `board/esp32-wrover.cfg` for ESP32 boards/modules operating with an SPI flash voltage of 1.8 V, and `board/esp-wroom-32.cfg` for 3.3 V. Refer to [ESP32 Dev Kits](https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32/index.html) and [Set SPI Flash Voltage](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/tips-and-quirks.html#why-to-set-spi-flash-voltage-in-openocd-configuration) for more details.
+
+(For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you as soon as possible.)

examples/system/app_trace_basic/main/CMakeLists.txt

@@ -0,0 +1,3 @@
+idf_component_register(SRCS "app_trace_basic_example_main.c"
+                       PRIV_REQUIRES esp_trace
+                       INCLUDE_DIRS ".")

examples/system/app_trace_basic/main/app_trace_basic_example_main.c

@@ -0,0 +1,64 @@
+/*
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+/* Application Trace Basic Example
+
+   This example code is in the Public Domain (or CC0 licensed, at your option.)
+
+   Unless required by applicable law or agreed to in writing, this
+   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+   CONDITIONS OF ANY KIND, either express or implied.
+*/
+
+#include <stdio.h>
+#include <string.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "soc/uart_pins.h"
+#include "esp_log.h"
+#include "esp_app_trace.h"
+
+static const char *TAG = "example";
+
+#if !CONFIG_APPTRACE_DEST_JTAG
+/* Override default uart config to use console pins as a uart channel */
+esp_apptrace_config_t esp_apptrace_get_user_params(void)
+{
+    esp_apptrace_config_t config = APPTRACE_UART_CONFIG_DEFAULT();
+    config.dest_cfg.uart.uart_num = 0;
+    config.dest_cfg.uart.tx_pin_num = U0TXD_GPIO_NUM;
+    config.dest_cfg.uart.rx_pin_num = U0RXD_GPIO_NUM;
+    return config;
+}
+#endif
+
+void app_main(void)
+{
+    if (esp_apptrace_get_destination() == ESP_APPTRACE_DEST_JTAG) {
+        ESP_LOGI(TAG, "Waiting for OpenOCD connection");
+
+        while (!esp_apptrace_host_is_connected()) {
+            vTaskDelay(1);
+        }
+    } else { // UART
+        // Before sending data, wait for the UART host to be ready
+        vTaskDelay(1000 / portTICK_PERIOD_MS);
+    }
+
+    ESP_LOGI(TAG, "Sending example data to the host...");
+
+    for (unsigned int cnt = 1; cnt < 51; ++cnt) {
+        char buf[32] = {0};
+        snprintf(buf, sizeof(buf), "Apptrace test data[%d]:%d\n", cnt, cnt * cnt);
+        esp_err_t res = esp_apptrace_write(buf, strlen(buf), ESP_APPTRACE_TMO_INFINITE);
+        if (res != ESP_OK) {
+            ESP_LOGE(TAG, "Failed to write data to host [0x%x] (%s)", res, esp_err_to_name(res));
+        }
+        esp_apptrace_flush(1000);
+        vTaskDelay(50 / portTICK_PERIOD_MS);
+    }
+
+    ESP_LOGI(TAG, "Done!");
+}

examples/system/app_trace_basic/pytest_app_trace_basic.py

@@ -0,0 +1,88 @@
+# SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Unlicense OR CC0-1.0
+import os.path
+import time
+import typing
+
+import pytest
+import serial
+from pytest_embedded_idf import IdfDut
+from pytest_embedded_idf.utils import idf_parametrize
+
+if typing.TYPE_CHECKING:
+    from conftest import OpenOCD
+
+
+def _test_examples_app_trace_basic(openocd_dut: 'OpenOCD', dut: IdfDut) -> None:
+    time.sleep(1)  # Wait for the USJ port to be ready
+    dut.expect_exact('example: Waiting for OpenOCD connection', timeout=5)
+    with openocd_dut.run() as openocd:
+        openocd.write('reset run')
+        dut.expect_exact('example: Waiting for OpenOCD connection', timeout=5)
+        time.sleep(1)  # wait for APPTRACE_INIT semihosting call
+        openocd.write('esp apptrace start file://apptrace.log 0 2000 3 0 0')
+        openocd.apptrace_wait_stop()
+
+        search_strings = ['Targets connected.', 'Disconnect targets...']
+        with open(openocd.log_file, encoding='utf-8') as oocd_log:  # pylint: disable=protected-access
+            cores = 1 if dut.app.sdkconfig.get('ESP_SYSTEM_SINGLE_CORE_MODE') is True else 2
+            search_strings.append(f'App trace params: from {cores} cores,')
+            for search_str in search_strings:
+                found = False
+                oocd_log.seek(0)
+                for line in oocd_log:
+                    if search_str in line:
+                        found = True
+                        break
+                if found is not True:
+                    raise RuntimeError(f'"{search_str}" could not be found in {openocd.log_file}')  # pylint: disable=protected-access
+
+        with open('apptrace.log', encoding='utf-8') as apptrace_log:
+            content = apptrace_log.read()
+            for sample_num in range(1, 51):
+                log_str = f'Apptrace test data[{sample_num}]:{sample_num * sample_num}'
+                if log_str not in content:
+                    raise RuntimeError('"{}" could not be found in {}'.format(log_str, 'apptrace.log'))
+
+
+@pytest.mark.jtag
+@idf_parametrize('config', ['apptrace_jtag'], indirect=['config'])
+@idf_parametrize('target', ['esp32', 'esp32c2', 'esp32s2'], indirect=['target'])
+def test_examples_app_trace_basic(openocd_dut: 'OpenOCD', dut: IdfDut) -> None:
+    _test_examples_app_trace_basic(openocd_dut, dut)
+
+
+@pytest.mark.usb_serial_jtag
+@idf_parametrize('config', ['apptrace_jtag'], indirect=['config'])
+@idf_parametrize(
+    'target', ['esp32s3', 'esp32c3', 'esp32c5', 'esp32c6', 'esp32c61', 'esp32h2', 'esp32p4'], indirect=['target']
+)
+def test_examples_app_trace_basic_usj(openocd_dut: 'OpenOCD', dut: IdfDut) -> None:
+    _test_examples_app_trace_basic(openocd_dut, dut)
+
+
+@pytest.mark.generic
+@idf_parametrize('config', ['apptrace_uart'], indirect=['config'])
+@idf_parametrize('target', ['supported_targets'], indirect=['target'])
+@pytest.mark.temp_skip_ci(targets=['esp32s31', 'esp32h4'], reason='bringup on this module is not done')
+def test_examples_app_trace_basic_uart(dut: IdfDut) -> None:
+    dut.serial.close()
+    with serial.Serial(dut.serial.port, baudrate=1000000, timeout=3) as ser:
+        apptrace_log = os.path.join(dut.logdir, 'apptrace_log_uart.txt')  # pylint: disable=protected-access
+        with open(apptrace_log, 'w+b') as f:
+            start_time = time.time()
+            while True:
+                try:
+                    if ser.in_waiting:
+                        f.write(ser.read(ser.in_waiting))
+                    if time.time() - start_time > 5:
+                        break
+                except serial.SerialTimeoutException:
+                    assert False, 'Timeout reached while reading from serial port, exiting...'
+
+            f.seek(0)
+            content = f.read().decode('utf-8', errors='ignore')
+            for sample_num in range(1, 51):
+                log_str = f'Apptrace test data[{sample_num}]:{sample_num * sample_num}'
+                if log_str not in content:
+                    raise RuntimeError('"{}" could not be found in {}'.format(log_str, 'apptrace_log_uart.txt'))

examples/system/app_trace_basic/sdkconfig.ci.apptrace_jtag

@@ -0,0 +1 @@
+CONFIG_APPTRACE_DEST_JTAG=y

examples/system/app_trace_basic/sdkconfig.ci.apptrace_uart

@@ -0,0 +1,3 @@
+CONFIG_ESP_CONSOLE_NONE=y
+# Destination can be selectable on runtime
+CONFIG_APPTRACE_DEST_ALL=y

examples/system/app_trace_basic/sdkconfig.defaults

@@ -0,0 +1,4 @@
+# Enable application tracing by default
+CONFIG_ESP_TRACE_ENABLE=y
+CONFIG_ESP_TRACE_LIB_NONE=y
+CONFIG_ESP_TRACE_TRANSPORT_APPTRACE=y