mirror of
https://github.com/espressif/esp-idf.git
synced 2026-09-22 13:01:16 +03:00
docs(esp_trace): restructure tracing docs with esp_trace as master
Reorganize the tracing documentation so esp_trace is the master
component, with app_trace, SystemView, and Gcov referenced from it.
(cherry picked from commit 6c6490d54c)
This commit is contained in:
Erhan Kurubas
@@ -422,5 +422,5 @@ For detailed usage instructions, see:
|
||||
Examples demonstrating trace usage can be found in:
|
||||
- `examples/system/app_trace_basic/` - Basic application tracing
|
||||
- `examples/system/sysview_tracing/` - SystemView tracing example
|
||||
- `examples/system/esp_trace/` - Minimal template for integrating an external trace library (encoder + FreeRTOS hooks + vtable lock)
|
||||
- `examples/system/esp_trace_custom_library/` - Minimal template for integrating an external trace library (encoder + FreeRTOS hooks + vtable lock)
|
||||
- `examples/system/sysview_tracing_heap_log/` - SystemView heap and log tracing example
|
||||
|
||||
@@ -5,6 +5,9 @@
|
||||
*/
|
||||
#pragma once
|
||||
|
||||
#include <stdbool.h>
|
||||
#include <stddef.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
@@ -36,9 +39,10 @@ typedef struct {
|
||||
/**
|
||||
* @brief Encoder name (required)
|
||||
*
|
||||
* Must match a registered encoder name. Built-in encoders:
|
||||
* - "sysview" - SEGGER SystemView protocol for FreeRTOS tracing
|
||||
* - "raw" - Pass-through for raw binary data
|
||||
* Must match the name of an encoder registered via ESP_TRACE_REGISTER_ENCODER().
|
||||
* The esp_trace component ships no encoder itself; encoders are provided by
|
||||
* external components (for example, espressif/esp_sysview registers a SystemView
|
||||
* encoder).
|
||||
*/
|
||||
const char *encoder_name;
|
||||
|
||||
@@ -55,6 +59,7 @@ typedef struct {
|
||||
*
|
||||
* Must match a registered transport name. Built-in transports:
|
||||
* - "apptrace" - Uses app_trace for JTAG or UART communication
|
||||
* - "usb_serial_jtag" - Streams trace data over the USB Serial JTAG peripheral
|
||||
*
|
||||
*/
|
||||
const char *transport_name;
|
||||
@@ -142,7 +147,7 @@ esp_trace_link_types_t esp_trace_get_link_type(esp_trace_handle_t handle);
|
||||
/**
|
||||
* @brief Panic flush the trace handle. This function is called from panic handler.
|
||||
*
|
||||
* @param handle The trace handle
|
||||
* @param info Panic info passed from the panic handler
|
||||
*/
|
||||
void esp_trace_panic_handler(const void *info);
|
||||
|
||||
|
||||
@@ -1,27 +1,38 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
|
||||
* SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
#pragma once
|
||||
|
||||
#include <stdint.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief Core trace system configuration.
|
||||
*
|
||||
* Reserved for future core-level trace configuration.
|
||||
*/
|
||||
typedef struct esp_trace_config {
|
||||
// Reserved for future use
|
||||
int reserved;
|
||||
int reserved; ///< Reserved for future use.
|
||||
} esp_trace_config_t;
|
||||
|
||||
/**
|
||||
* @brief Trace transport link type.
|
||||
*/
|
||||
typedef enum {
|
||||
ESP_TRACE_LINK_UNKNOWN = 0,
|
||||
ESP_TRACE_LINK_DEBUG_PROBE,
|
||||
ESP_TRACE_LINK_UART,
|
||||
ESP_TRACE_LINK_USB_SERIAL_JTAG,
|
||||
ESP_TRACE_LINK_UNKNOWN = 0, ///< Unknown or unavailable link type.
|
||||
ESP_TRACE_LINK_DEBUG_PROBE, ///< Debug probe link, for example JTAG through OpenOCD.
|
||||
ESP_TRACE_LINK_UART, ///< UART link.
|
||||
ESP_TRACE_LINK_USB_SERIAL_JTAG, ///< USB Serial JTAG link.
|
||||
} esp_trace_link_types_t;
|
||||
|
||||
/* Timeout constants for trace operations */
|
||||
/**
|
||||
* @brief Infinite timeout for trace operations.
|
||||
*/
|
||||
#define ESP_TRACE_TMO_INFINITE (UINT32_MAX)
|
||||
|
||||
#ifdef __cplusplus
|
||||
|
||||
@@ -22,6 +22,10 @@ PROJECT_NAME = "IDF Programming Guide"
|
||||
|
||||
INPUT = \
|
||||
$(PROJECT_PATH)/components/app_trace/include/esp_app_trace.h \
|
||||
$(PROJECT_PATH)/components/esp_trace/include/esp_trace.h \
|
||||
$(PROJECT_PATH)/components/esp_trace/include/esp_trace_types.h \
|
||||
$(PROJECT_PATH)/components/esp_trace/include/esp_trace_port_encoder.h \
|
||||
$(PROJECT_PATH)/components/esp_trace/include/esp_trace_port_transport.h \
|
||||
$(PROJECT_PATH)/components/app_update/include/esp_ota_ops.h \
|
||||
$(PROJECT_PATH)/components/bootloader_support/include/bootloader_random.h \
|
||||
$(PROJECT_PATH)/components/bootloader_support/include/esp_app_format.h \
|
||||
|
||||
@@ -5,7 +5,6 @@ API Guides
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
app_trace
|
||||
startup
|
||||
:SOC_BT_SUPPORTED: bt-architecture/index
|
||||
:SOC_BT_CLASSIC_SUPPORTED: classic-bt/index
|
||||
@@ -44,6 +43,7 @@ API Guides
|
||||
stdio
|
||||
thread-local-storage
|
||||
tools/index
|
||||
tracing/index
|
||||
unit-tests
|
||||
host-apps
|
||||
:SOC_USB_OTG_SUPPORTED and not esp32p4 and not esp32h4: usb-otg-console
|
||||
|
||||
@@ -353,11 +353,10 @@ Related Documents
|
||||
debugging-examples
|
||||
semihosting
|
||||
tips-and-quirks
|
||||
../app_trace
|
||||
|
||||
- :doc:`using-debugger`
|
||||
- :doc:`debugging-examples`
|
||||
- :doc:`semihosting`
|
||||
- :doc:`tips-and-quirks`
|
||||
- :doc:`../app_trace`
|
||||
- :doc:`../tracing/index`
|
||||
- `Introduction to ESP-Prog Board <https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html>`__
|
||||
|
||||
@@ -63,7 +63,7 @@ Executing the target multiple times can help average out factors, e.g., RTOS con
|
||||
External Tracing
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
The :doc:`/api-guides/app_trace` allows measuring code execution with minimal impact on the code itself.
|
||||
The :doc:`/api-guides/tracing/transports` allows measuring code execution with minimal impact on the code itself.
|
||||
|
||||
Tasks
|
||||
^^^^^
|
||||
|
||||
111
docs/en/api-guides/tracing/architecture.rst
Normal file
111
docs/en/api-guides/tracing/architecture.rst
Normal file
@@ -0,0 +1,111 @@
|
||||
Tracing Architecture
|
||||
====================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This document explains the high-level design of the ESP-IDF tracing system.
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Applications use ``esp_trace`` to collect runtime information from the target and send it to a host tool for analysis. This supports use cases such as FreeRTOS task and ISR analysis with SEGGER SystemView, source code coverage with Gcov, and application-specific data collection over apptrace.
|
||||
|
||||
ESP-IDF provides common tracing formats and transports, and the same framework can be extended for new ones, such as a custom trace format or a transport over SPI or UDP.
|
||||
|
||||
The ESP-IDF tracing system follows a **Port & Adapter** design. Applications call the public ``esp_trace`` API, while the tracing core connects the selected encoder with the selected transport.
|
||||
|
||||
This design provides:
|
||||
|
||||
- A stable application-facing API.
|
||||
- Independent selection of trace format and host link.
|
||||
- Adapter-specific details kept outside the core tracing code.
|
||||
- Startup and panic handling owned by the tracing system.
|
||||
|
||||
.. mermaid::
|
||||
|
||||
flowchart TB
|
||||
app["Application<br/>FreeRTOS tasks, ISRs, esp_trace_write(), trace macros"]
|
||||
api["Public interface<br/>esp_trace API"]
|
||||
core["Core tracing code<br/>esp_trace component<br/>session, multi-core init, adapter coordination"]
|
||||
registry["Runtime registry<br/>maps configured names to adapters"]
|
||||
host["Host link<br/>OpenOCD over JTAG, UART, or USB Serial JTAG"]
|
||||
|
||||
subgraph PORTS["Ports"]
|
||||
direction LR
|
||||
enc_port["Encoder port"]
|
||||
transport_port["Transport port"]
|
||||
end
|
||||
|
||||
subgraph ADAPTERS["Adapters"]
|
||||
direction LR
|
||||
encoder["Encoder adapter<br/>external component, for example espressif/esp_sysview<br/>formats recorder events"]
|
||||
transport["Transport adapter<br/>esp_trace component<br/>apptrace over JTAG/UART, USB Serial JTAG"]
|
||||
end
|
||||
|
||||
app --> api --> core
|
||||
core --- registry
|
||||
core --> enc_port
|
||||
core --> transport_port
|
||||
enc_port --> encoder
|
||||
transport_port --> transport
|
||||
encoder -.-> transport
|
||||
transport --> host
|
||||
|
||||
Components
|
||||
----------
|
||||
|
||||
Core Tracing Code
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``esp_trace`` component contains the public API and maintains the active trace session. It creates the encoder/transport pair during startup, coordinates multi-core initialization, and forwards API calls to the selected adapters.
|
||||
|
||||
Encoder Port
|
||||
^^^^^^^^^^^^
|
||||
|
||||
The encoder port interface (:component_file:`esp_trace_port_encoder.h <esp_trace/include/esp_trace_port_encoder.h>`) defines how a trace library plugs into ``esp_trace``. An encoder receives trace writes or trace-hook events and converts them to a recorder-specific format, such as the SystemView protocol. ``esp_trace`` defines this interface but does not ship an encoder; encoders are provided by external components, for example ``espressif/esp_sysview``. See :doc:`custom-trace-library`.
|
||||
|
||||
Transport Port
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
The transport port interface (:component_file:`esp_trace_port_transport.h <esp_trace/include/esp_trace_port_transport.h>`) defines how encoded trace data leaves the target. A transport writes bytes to a host-facing link and handles link-specific operations such as flushing, host-connection checks, and panic-time output. ``esp_trace`` provides built-in apptrace over JTAG/UART and USB Serial JTAG transport adapters. See :doc:`transports`.
|
||||
|
||||
Each trace session pairs one encoder with one transport. The encoder can pass encoded trace data to the transport selected for the session, and trace writes do not allocate memory while they are running.
|
||||
|
||||
Initialization
|
||||
--------------
|
||||
|
||||
``esp_trace`` initializes automatically during system startup based on the encoder and transport selected in project configuration. Applications normally do not need to call a separate initialization function before using the public tracing API. Adapter-specific initialization requirements are covered in :doc:`custom-trace-library`.
|
||||
|
||||
Data Flow
|
||||
---------
|
||||
|
||||
A typical write flows from the public API to the encoder, then to the transport:
|
||||
|
||||
.. mermaid::
|
||||
|
||||
flowchart TD
|
||||
write["esp_trace_write(handle, data, size, tmo)"]
|
||||
validate["Core validates the handle"]
|
||||
encode["Encoder writes formatted data<br/>for example SystemView protocol"]
|
||||
send["Transport sends encoded bytes<br/>JTAG, UART, or USB Serial JTAG"]
|
||||
status["Status returns to the caller"]
|
||||
|
||||
write --> validate --> encode --> send --> status
|
||||
|
||||
Panic Handling
|
||||
--------------
|
||||
|
||||
During a panic, interrupts are disabled and normal locking cannot be used. The core calls optional panic callbacks on the active encoder and transport. Each adapter can then flush its own buffers without taking normal locks. Panic flushing can still drop data because it must not block or use normal locking.
|
||||
|
||||
Registry
|
||||
--------
|
||||
|
||||
Adapters register themselves at link time with ``ESP_TRACE_REGISTER_ENCODER()`` and ``ESP_TRACE_REGISTER_TRANSPORT()``. During initialization, the core looks up the configured encoder and transport by name. Only adapters linked into the application are available, and adding a new adapter does not require changes to the core.
|
||||
|
||||
Related Documentation
|
||||
---------------------
|
||||
|
||||
- :doc:`custom-trace-library`: the adapter author contract (encoder and transport function tables, registration, locking and reentrancy rules)
|
||||
- :doc:`transports`: the apptrace transport and standalone apptrace usage
|
||||
- :doc:`sysview`: SEGGER SystemView usage
|
||||
- :doc:`/api-reference/system/esp_trace`: ESP Trace API reference
|
||||
72
docs/en/api-guides/tracing/custom-trace-library.rst
Normal file
72
docs/en/api-guides/tracing/custom-trace-library.rst
Normal file
@@ -0,0 +1,72 @@
|
||||
.. _app_trace-integrating-a-custom-trace-library:
|
||||
|
||||
Integrating a Custom Trace Library
|
||||
==================================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The :doc:`esp_trace <index>` component lets a third-party trace recorder plug into ESP-IDF without patching the framework. External encoders, such as SEGGER SystemView, use this path. For the high-level design, see :doc:`architecture`.
|
||||
|
||||
An external component provides:
|
||||
|
||||
- An **encoder adapter**, registered via ``ESP_TRACE_REGISTER_ENCODER()``, which formats trace data into the recorder's protocol.
|
||||
- An ``esp_trace_freertos_impl.h`` header that defines the FreeRTOS trace hooks needed by the recorder.
|
||||
|
||||
The encoder is independent from the host link. It can use any registered :doc:`transport <transports>`, such as apptrace over JTAG/UART, USB Serial JTAG, or a custom transport.
|
||||
|
||||
Encoder Port
|
||||
------------
|
||||
|
||||
An encoder implements :cpp:struct:`esp_trace_encoder_vtable_t`.
|
||||
|
||||
- ``init`` and ``write`` are the only required callbacks.
|
||||
- ``start`` / ``stop`` / ``flush`` are dispatched from :cpp:func:`esp_trace_start`, :cpp:func:`esp_trace_stop`, and :cpp:func:`esp_trace_flush`.
|
||||
- ``panic_handler`` is called from the panic path so the adapter can flush without taking normal locks.
|
||||
- ``take_lock`` / ``give_lock`` provide the encoder's cross-core serialization; the core adds no locking of its own.
|
||||
|
||||
The encoder instance (:cpp:struct:`esp_trace_encoder`) holds its function table, the transport bound for the active trace session, and any encoder-specific state. See the struct reference for the exact fields.
|
||||
|
||||
If the encoder needs transport-specific settings, configure its bound transport from ``init`` using typed configuration keys, for example ``ESP_TRACE_TRANSPORT_CFG_HEADER_SIZE`` to set the transport header size.
|
||||
|
||||
Register the encoder at link time; the core looks it up by the configured name:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
ESP_TRACE_REGISTER_ENCODER("sysview", &s_sysview_vt);
|
||||
|
||||
Transport Port
|
||||
--------------
|
||||
|
||||
A transport implements :cpp:struct:`esp_trace_transport_vtable_t`.
|
||||
|
||||
Register it with ``ESP_TRACE_REGISTER_TRANSPORT("name", &vtable)``. Most projects only need a custom encoder and can use an existing transport. Implement a transport only when you need a new host link. See :doc:`transports` for the apptrace transport.
|
||||
|
||||
Locking and Reentrancy
|
||||
----------------------
|
||||
|
||||
Runtime callbacks such as ``write``, ``flush`` / ``flush_nolock``, ``read``, ``take_lock`` / ``give_lock``, and ``panic_handler`` can run from FreeRTOS trace hooks. Some of them can also run from ISR context, and some are called while the encoder lock is held.
|
||||
|
||||
.. warning::
|
||||
|
||||
Do not call FreeRTOS or IDF APIs that themselves emit trace hooks from these callbacks. Anything that triggers a ``trace*()`` macro re-enters the tracing path and can recurse into your encoder, deadlock on the encoder's non-recursive spinlock, or call a task-only API from ISR context.
|
||||
|
||||
Specifically avoid these APIs from runtime callbacks:
|
||||
|
||||
- Task APIs that yield (``vTaskDelay``, ``vTaskSuspend``, ``xTaskNotify*``)
|
||||
- Queue / semaphore / mutex APIs (``xQueueSend`` / ``xQueueReceive``, ``xSemaphoreTake`` / ``xSemaphoreGive``)
|
||||
- Stream and message buffer APIs
|
||||
- Heap allocations that may take an internal mutex
|
||||
|
||||
Use lock-free or spinlock-only primitives (``esp_trace_lock_*``, ``esp_trace_rb_*``), low-level register access, atomics, and ``esp_rom_*`` helpers in runtime callbacks. Do heavier work, such as FreeRTOS API calls or allocations, only in ``init()`` before tracing starts.
|
||||
|
||||
For transports that need a complex driver or network stack, keep the runtime callback as a producer only. Copy the trace data into a preallocated, trace-safe buffer, such as an ``esp_trace_rb_*`` ring buffer, and return quickly. A worker task created during ``init()`` consumes that buffer and calls APIs such as SPI master, sockets, StreamBuffer, or other FreeRTOS facilities outside the trace callback path and outside the encoder lock. Because the callback must not block or wake a task through yielding APIs, have the worker poll the buffer (or wake on a transport-level event) and drop data when the buffer is full rather than pushing backpressure onto the callback.
|
||||
|
||||
FreeRTOS Trace Hooks
|
||||
--------------------
|
||||
|
||||
To capture FreeRTOS events, the external component implementing a trace encoder should provide an ``esp_trace_freertos_impl.h`` header, defining the desired trace macros (``traceTASK_SWITCHED_IN()``, ``traceISR_ENTER()``, and so on). ``esp_trace`` includes this header when :ref:`CONFIG_ESP_TRACE_LIB_EXTERNAL <CONFIG_ESP_TRACE_LIB_EXTERNAL>` is enabled.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
- :example:`system/esp_trace_custom_library` is a minimal template that wires up an external encoder, demonstrates the FreeRTOS trace-hook include chain, and shows cross-core serialization through the encoder lock.
|
||||
26
docs/en/api-guides/tracing/gcov.rst
Normal file
26
docs/en/api-guides/tracing/gcov.rst
Normal file
@@ -0,0 +1,26 @@
|
||||
.. _app_trace-gcov-source-code-coverage:
|
||||
|
||||
Gcov (Source Code Coverage)
|
||||
===========================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Gcov is a source code coverage analysis tool. In ESP-IDF, coverage data generated on the target is dumped to the host over apptrace (JTAG or UART), where it is turned into standard ``.gcda`` files and processed with the usual host-side tools.
|
||||
|
||||
Report generation also needs the ``.gcno`` notes files that the compiler generates at build time for each source compiled with ``--coverage``. The host-side tools combine the runtime ``.gcda`` counts with the ``.gcno`` files and the original sources to produce the coverage report.
|
||||
|
||||
Gcov uses the tracing infrastructure for host data transfer, but it does not yet fully follow the :doc:`esp_trace <index>` encoder/transport model. In particular, it is tied to the apptrace transport (JTAG or UART) and does not support selecting a custom transport.
|
||||
|
||||
Coverage support is provided by the managed component `espressif/esp_gcov <https://components.espressif.com/components/espressif/esp_gcov>`_. Add it to your project's ``idf_component.yml``:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
dependencies:
|
||||
espressif/esp_gcov: ^1
|
||||
|
||||
Coverage data can be dumped either at a hard-coded point in your application (over apptrace via JTAG or UART) or on demand from the host via the OpenOCD ``esp gcov`` command (JTAG only). For the full setup, configuration options, and command usage, see README of the component linked above.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
- :example:`system/gcov` demonstrates how to add code coverage to a project and collect coverage data over JTAG.
|
||||
108
docs/en/api-guides/tracing/index.rst
Normal file
108
docs/en/api-guides/tracing/index.rst
Normal file
@@ -0,0 +1,108 @@
|
||||
Tracing
|
||||
===========
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP-IDF provides a tracing system for program behavior analysis and debugging. It lets you collect runtime data from {IDF_TARGET_NAME} and send it to a host computer with minimal overhead.
|
||||
|
||||
The system is centered on the **esp_trace** component. It owns the public tracing API, manages the active trace session, and connects trace encoders with trace transports. Other tracing features, such as SEGGER SystemView, Gcov, and the apptrace transport, plug into this model.
|
||||
|
||||
The ``esp_trace`` component supports common trace formats and transports, and is designed to be extensible. New trace formats and transports can be added without modifying ESP-IDF. For more information about the design, see :doc:`architecture`.
|
||||
|
||||
- **Trace formats**: SEGGER SystemView for industry-standard FreeRTOS analysis (see :doc:`sysview`), or your own recorder (see :doc:`custom-trace-library`).
|
||||
- **Transports**:
|
||||
|
||||
.. list::
|
||||
|
||||
- the :doc:`apptrace transport <transports>` (``app_trace`` component) over JTAG or UART
|
||||
:SOC_USB_SERIAL_JTAG_SUPPORTED: - the USB Serial JTAG transport
|
||||
|
||||
Choosing Your Path
|
||||
------------------
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 40 60
|
||||
|
||||
* - Goal
|
||||
- Where to look
|
||||
* - Analyze FreeRTOS task/ISR behavior
|
||||
- :doc:`SEGGER SystemView <sysview>`
|
||||
* - Send/receive arbitrary application data, or log to host
|
||||
- :doc:`Application Level Tracing transport <transports>`
|
||||
* - Collect source code coverage
|
||||
- :doc:`Gcov <gcov>`
|
||||
* - Integrate a third-party trace recorder
|
||||
- :doc:`Custom trace library <custom-trace-library>`
|
||||
|
||||
Choosing a Transport
|
||||
--------------------
|
||||
|
||||
The trace format and the transport are selected independently. Pick the host link based on your available hardware:
|
||||
|
||||
.. list::
|
||||
|
||||
- **apptrace over JTAG**: Highest throughput and host-initiated control (start / stop / dump). Requires a JTAG adapter and OpenOCD on the host. Best for SystemView and on-demand Gcov dumps.
|
||||
- **apptrace over UART**: Uses a spare UART instead of a debug probe, at lower throughput than JTAG. Pick a UART that is not used by the console.
|
||||
:SOC_USB_SERIAL_JTAG_SUPPORTED: - **USB Serial JTAG**: Uses the chip's built-in USB peripheral over a single USB cable, with no external adapter. Trace data flows over the peripheral's serial (CDC) interface, not its JTAG interface. Available when USB Serial JTAG is not already taken by the console.
|
||||
|
||||
Key Features
|
||||
------------
|
||||
|
||||
- **Automatic initialization**: Tracing is configured automatically at startup
|
||||
- **Multi-core support**: Works on single and dual-core chips
|
||||
- **Extensible**: Add custom trace formats or transports; see :doc:`architecture`
|
||||
|
||||
Quick Start: SystemView Tracing
|
||||
-------------------------------
|
||||
|
||||
To enable SEGGER SystemView tracing for FreeRTOS system analysis:
|
||||
|
||||
1. Add the ``espressif/esp_sysview`` dependency to your project's ``idf_component.yml``.
|
||||
|
||||
2. Select the external trace library by enabling :ref:`CONFIG_ESP_TRACE_LIB_EXTERNAL <CONFIG_ESP_TRACE_LIB_EXTERNAL>`.
|
||||
|
||||
3. Select the apptrace transport by enabling :ref:`CONFIG_ESP_TRACE_TRANSPORT_APPTRACE <CONFIG_ESP_TRACE_TRANSPORT_APPTRACE>`.
|
||||
|
||||
4. Set the data destination to JTAG by enabling :ref:`CONFIG_APPTRACE_DEST_JTAG <CONFIG_APPTRACE_DEST_JTAG>`.
|
||||
|
||||
5. Build and flash your application:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py build flash
|
||||
|
||||
For detailed SystemView usage, OpenOCD setup, and host-side visualization, see :doc:`sysview`.
|
||||
|
||||
Detailed Guides
|
||||
---------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
architecture
|
||||
transports
|
||||
sysview
|
||||
gcov
|
||||
custom-trace-library
|
||||
|
||||
Related Documentation
|
||||
---------------------
|
||||
|
||||
- :doc:`/api-reference/system/esp_trace`: ESP Trace API reference
|
||||
- :doc:`/api-reference/system/app_trace`: Application Level Tracing (transport) API reference
|
||||
- :doc:`/api-guides/jtag-debugging/index`: JTAG debugging setup and hardware configuration
|
||||
- `SEGGER SystemView <https://www.segger.com/products/development-tools/systemview/>`_: Official SystemView tool and documentation
|
||||
- `OpenOCD <https://openocd.org/>`_: Open On-Chip Debugger
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
- :example:`system/app_trace_basic`: Basic application tracing
|
||||
- :example:`system/sysview_tracing`: SystemView tracing example
|
||||
- :example:`system/sysview_tracing_heap_log`: Heap tracing with SystemView
|
||||
- :example:`system/gcov`: Source code coverage over JTAG
|
||||
- :example:`system/esp_trace_custom_library`: External trace library integration template
|
||||
140
docs/en/api-guides/tracing/sysview.rst
Normal file
140
docs/en/api-guides/tracing/sysview.rst
Normal file
@@ -0,0 +1,140 @@
|
||||
.. _app_trace-system-behaviour-analysis-with-segger-systemview:
|
||||
|
||||
System Behavior Analysis with SEGGER SystemView
|
||||
===============================================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
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 :doc:`esp_trace <index>` 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 :doc:`transport <transports>` (typically apptrace over JTAG, or UART for real-time viewing).
|
||||
|
||||
See `SystemView <https://www.segger.com/products/development-tools/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``:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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 (:ref:`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 <https://components.espressif.com/components/espressif/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 :doc:`JTAG Debugging </api-guides/jtag-debugging/index>`.
|
||||
|
||||
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:
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
::
|
||||
|
||||
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, users can use a special tool to visualize the results and inspect behavior of the program.
|
||||
|
||||
.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES
|
||||
|
||||
**Multi-Core Tracing**
|
||||
|
||||
SystemView version 3.60 and later supports tracing from multiple cores. For multi-core tracing, use the ``esp sysview_mcore`` command to generate a single file compatible with SystemView multi-core format. This command will create a single trace file that can be loaded directly into SystemView 3.60+ for multi-core visualization.
|
||||
|
||||
**Note:** SystemView versions before 3.60 do not support multi-core tracing. For older versions, when tracing from {IDF_TARGET_NAME} with JTAG interfaces in the dual-core mode, two separate files are generated: one for PRO CPU and another for APP CPU. Users can load each file into separate instances of the tool. For tracing over UART, after selecting the external library in menuconfig, users can select ``Component config`` > ``SEGGER SystemView Configuration`` to choose which CPU (Pro or App) has to be traced.
|
||||
|
||||
For older SystemView versions, analyzing data for every core in separate instances can be awkward. An alternative is to use the Eclipse plugin called *Impulse*, which can load several trace files, making it possible to inspect events from both cores in one view. This plugin also has no limitation of 1,000,000 events as compared to the free version of SystemView.
|
||||
|
||||
Good instructions on how to install, configure, and visualize data in Impulse from one core can be found `here <https://mcuoneclipse.com/2016/07/31/impulse-segger-systemview-in-eclipse/>`_.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES
|
||||
|
||||
Configure Impulse for Dual Core Traces
|
||||
""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
After installing Impulse and ensuring that it can successfully load trace files for each core in separate tabs, users can add special Multi Adapter port and load both files into one view. To do this, users need to do the following steps in Eclipse:
|
||||
|
||||
1. Open the ``Signal Ports`` view. Go to ``Windows`` > ``Show View`` > ``Other menu``. Find the ``Signal Ports`` view in Impulse folder and double-click it.
|
||||
2. In the ``Signal Ports`` view, right-click ``Ports`` and select ``Add`` > ``New Multi Adapter Port``.
|
||||
3. In the open dialog box, click ``Add`` and select ``New Pipe/File``.
|
||||
4. In the open dialog box, select ``SystemView Serializer`` as Serializer and set path to PRO CPU trace file. Click ``OK``.
|
||||
5. Repeat the steps 3-4 for APP CPU trace file.
|
||||
6. Double-click the created port. View for this port should open.
|
||||
7. Click the ``Start/Stop Streaming`` button. Data should be loaded.
|
||||
8. Use the ``Zoom Out``, ``Zoom In`` and ``Zoom Fit`` buttons to inspect data.
|
||||
9. For settings measurement cursors and other features, please see `Impulse documentation <https://toem.de/index.php/products/impulse>`_).
|
||||
|
||||
.. note::
|
||||
|
||||
If you have problems with visualization (no data is shown or strange behaviors of zoom action are observed), you can try to delete current signal hierarchy and double-click on the necessary file or port. Eclipse will ask you to create a new signal hierarchy.
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
- :example:`system/sysview_tracing` demonstrates how to trace FreeRTOS task and system events using SEGGER SystemView.
|
||||
- :example:`system/sysview_tracing_heap_log` demonstrates heap allocation tracing alongside SystemView events.
|
||||
@@ -1,23 +1,27 @@
|
||||
Application Level Tracing Library
|
||||
=================================
|
||||
Application Level Tracing Transport (apptrace)
|
||||
==============================================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The **Application Level Tracing** library (the ``app_trace`` component) is the default transport used by the :doc:`esp_trace <index>` tracing system. It transfers arbitrary data between the host and {IDF_TARGET_NAME} via the JTAG or UART interface with small overhead on program execution. It is possible to use the JTAG and UART interfaces simultaneously. The UART interface is mostly used for connection with the SEGGER SystemView tool (see :doc:`sysview`). Tracing over the USB Serial JTAG peripheral is provided by a separate transport, not by apptrace.
|
||||
|
||||
This page documents the transport itself: how to configure it, how to send and receive arbitrary application data through it, and the host-side OpenOCD commands used to collect that data. Higher-level features built on top of this transport are documented separately:
|
||||
|
||||
- System behavior analysis with SEGGER SystemView: see :doc:`sysview`.
|
||||
- Source code coverage with Gcov: see :doc:`gcov`.
|
||||
- Plugging in your own trace recorder: see :doc:`custom-trace-library`.
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
ESP-IDF provides a useful feature for program behavior analysis: application level tracing. It is implemented in the corresponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and {IDF_TARGET_NAME} via JTAG, UART, or USB interfaces with small overhead on program execution. It is possible to use JTAG and UART interfaces simultaneously. The UART interface is mostly used for connection with SEGGER SystemView tool (see `SystemView <https://www.segger.com/products/development-tools/systemview/>`_).
|
||||
|
||||
Developers can use this library to send application-specific state of execution to the host and receive commands or other types of information from the opposite direction at runtime. The main use cases of this library are:
|
||||
Developers can use this library to send application-specific state of execution to the host and receive commands or other types of information from the opposite direction at runtime. The main standalone use cases of this library are:
|
||||
|
||||
1. Collecting application-specific data. See :ref:`app_trace-application-specific-tracing`.
|
||||
2. Lightweight logging to the host. See :ref:`app_trace-logging-to-host`.
|
||||
3. System behavior analysis. See :ref:`app_trace-system-behaviour-analysis-with-segger-systemview`.
|
||||
4. Source code coverage. See :ref:`app_trace-gcov-source-code-coverage`.
|
||||
|
||||
Tracing components used when working over JTAG interface are shown in the figure below.
|
||||
Tracing components used when working over the JTAG interface are shown in the figure below.
|
||||
|
||||
.. figure:: ../../_static/app_trace-overview.jpg
|
||||
.. figure:: ../../../_static/app_trace-overview.jpg
|
||||
:align: center
|
||||
:alt: Tracing Components When Working Over JTAG
|
||||
|
||||
@@ -39,7 +43,7 @@ Configuration Options and Dependencies
|
||||
|
||||
Using of this feature depends on two components:
|
||||
|
||||
1. **Host side:** Application tracing is done over JTAG, so it needs OpenOCD to be set up and running on host machine. For instructions on how to set it up, please see :doc:`JTAG Debugging <../api-guides/jtag-debugging/index>` for details.
|
||||
1. **Host side:** Application tracing is done over JTAG, so it needs OpenOCD to be set up and running on host machine. For instructions on how to set it up, please see :doc:`JTAG Debugging </api-guides/jtag-debugging/index>` for details.
|
||||
|
||||
2. **Target side:** Application tracing functionality can be enabled in menuconfig. **Important:** You must first enable application tracing by going to ``Component config`` > ``ESP Trace Configuration`` > ``Trace transport`` and selecting ``ESP-IDF apptrace``. After that, configuration can be done at ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing``. Here you can configure the destination for the trace data. For UART interfaces, users have to define port number, baud rate, TX and RX pins numbers, and additional UART-related parameters. When any trace library is selected (for example SEGGER SystemView), these settings will be used for the library as well.
|
||||
|
||||
@@ -94,7 +98,7 @@ Quick Start Summary
|
||||
|
||||
.. note::
|
||||
|
||||
Application tracing can also work as a transport adapter to the esp_trace library. In this case, the Application Level Tracing library will not be used directly, but rather through the selected esp_trace library with new APIs.
|
||||
Application tracing can also work as a transport adapter to the esp_trace library. In this case, the Application Level Tracing library will not be used directly, but rather through the selected esp_trace library with new APIs. See :doc:`index`.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -226,13 +230,13 @@ In general, users should decide what type of data should be transferred in every
|
||||
|
||||
3. The next step is to build the program image and download it to the target as described in the :ref:`Getting Started Guide <get-started-build>`.
|
||||
|
||||
4. Run OpenOCD (see :doc:`JTAG Debugging <../api-guides/jtag-debugging/index>`).
|
||||
4. Run OpenOCD (see :doc:`JTAG Debugging </api-guides/jtag-debugging/index>`).
|
||||
|
||||
5. Connect to OpenOCD telnet server. It can be done using the following command in terminal ``telnet <oocd_host> 4444``. If telnet session is opened on the same machine which runs OpenOCD, you can use ``localhost`` as ``<oocd_host>`` in the command above.
|
||||
|
||||
6. Start trace data collection using special OpenOCD command. This command will transfer tracing data and redirect them to the specified file or socket. For description of the corresponding commands, see `OpenOCD Application Level Tracing Commands`_.
|
||||
|
||||
7. The final step is to process received data. Since the format of data is defined by users, the processing stage is out of the scope of this document. Good starting points for data processor are python scripts in ``$IDF_PATH/tools/esp_app_trace``: ``apptrace_proc.py`` (used for feature tests) and ``logtrace_proc.py`` (see more details in section `Logging to Host`_).
|
||||
7. The final step is to process received data. Since the format of data is defined by users, the processing stage is out of the scope of this document. Good starting points for data processor are python scripts in ``$IDF_PATH/tools/esp_app_trace``: ``sysviewtrace_proc.py`` (used for feature tests) and ``logtrace_proc.py`` (see more details in section `Logging to Host`_).
|
||||
|
||||
|
||||
OpenOCD Application Level Tracing Commands
|
||||
@@ -389,195 +393,13 @@ Optional arguments:
|
||||
Do not print errors.
|
||||
|
||||
|
||||
.. _app_trace-system-behaviour-analysis-with-segger-systemview:
|
||||
|
||||
System Behavior Analysis with SEGGER SystemView
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Another useful ESP-IDF feature built on top of application tracing library is the system level tracing which produces traces compatible with SEGGER SystemView tool (see `SystemView <https://www.segger.com/products/development-tools/systemview/>`_). SEGGER SystemView is a real-time recording and visualization tool that allows to analyze runtime behavior of an application. It is possible to view events in real-time through the UART interface.
|
||||
|
||||
|
||||
How To Use It
|
||||
"""""""""""""
|
||||
|
||||
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``:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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``. For full, up-to-date instructions, see the component README: `esp_sysview <https://components.espressif.com/components/espressif/esp_sysview>`_.
|
||||
|
||||
There are several other options enabled under the same menu:
|
||||
|
||||
1. {IDF_TARGET_NAME} timer to use as SystemView timestamp source: (:ref:`CONFIG_ESP_TRACE_TIMESTAMP_SOURCE`) selects the source of timestamps for SystemView events. In the single core mode, timestamps are generated using {IDF_TARGET_NAME} internal cycle counter running at maximum frequency. (:ref:`CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ`) In the dual-core mode, external timer is used to generate timestamps. It's frequency is 1/2 of the CPU frequency.
|
||||
|
||||
2. Individually enabled or disabled collection of SystemView events (``CONFIG_SEGGER_SYSVIEW_EVT_XXX``):
|
||||
|
||||
- Trace Buffer Overflow Event
|
||||
- ISR Enter Event
|
||||
- ISR Exit Event
|
||||
- ISR Exit to Scheduler Event
|
||||
- Task Start Execution Event
|
||||
- Task Stop Execution Event
|
||||
- Task Start Ready State Event
|
||||
- Task Stop Ready State Event
|
||||
- Task Create Event
|
||||
- Task Terminate Event
|
||||
- System Idle Event
|
||||
- Timer Enter Event
|
||||
- Timer Exit Event
|
||||
|
||||
ESP-IDF has all the code required to produce SystemView compatible traces.
|
||||
|
||||
3. 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
|
||||
""""""""""""""""""""""""""""""""""""""""""
|
||||
|
||||
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 examples:
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
1. Collect SystemView tracing data to files ``pro-cpu.SVDat`` and ``app-cpu.SVDat``. The files will be saved in ``openocd-esp32`` directory.
|
||||
|
||||
::
|
||||
|
||||
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 OpenOCD telnet prompt, optionally pressing Ctrl+C in the OpenOCD window.
|
||||
|
||||
2. Retrieve tracing data and save them indefinitely.
|
||||
|
||||
::
|
||||
|
||||
esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat 0 -1 -1
|
||||
|
||||
OpenOCD telnet command line prompt will not be available until tracing is stopped. To stop tracing, press 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:
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
::
|
||||
|
||||
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, users can use a special tool to visualize the results and inspect behavior of the program.
|
||||
|
||||
.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES
|
||||
|
||||
**Multi-Core Tracing**
|
||||
|
||||
SystemView version 3.60 and later supports tracing from multiple cores. For multi-core tracing, use the ``esp sysview_mcore`` command to generate a single file compatible with SystemView multi-core format:
|
||||
|
||||
::
|
||||
|
||||
esp sysview_mcore start file://heap_log_mcore.SVDat
|
||||
|
||||
This command will create a single trace file that can be loaded directly into SystemView 3.60+ for multi-core visualization.
|
||||
|
||||
**Note:** SystemView versions before 3.60 do not support multi-core tracing. For older versions, when tracing from {IDF_TARGET_NAME} with JTAG interfaces in the dual-core mode, two separate files are generated: one for PRO CPU and another for APP CPU. Users can load each file into separate instances of the tool. For tracing over UART, after selecting the external library in menuconfig, users can select ``Component config`` > ``SEGGER SystemView Configuration`` to choose which CPU (Pro or App) has to be traced.
|
||||
|
||||
For older SystemView versions, analyzing data for every core in separate instances can be awkward. An alternative is to use the Eclipse plugin called *Impulse*, which can load several trace files, making it possible to inspect events from both cores in one view. This plugin also has no limitation of 1,000,000 events as compared to the free version of SystemView.
|
||||
|
||||
Good instructions on how to install, configure, and visualize data in Impulse from one core can be found `here <https://mcuoneclipse.com/2016/07/31/impulse-segger-systemview-in-eclipse/>`_.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES
|
||||
|
||||
Configure Impulse for Dual Core Traces
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
After installing Impulse and ensuring that it can successfully load trace files for each core in separate tabs, users can add special Multi Adapter port and load both files into one view. To do this, users need to do the following steps in Eclipse:
|
||||
|
||||
1. Open the ``Signal Ports`` view. Go to ``Windows`` > ``Show View`` > ``Other menu``. Find the ``Signal Ports`` view in Impulse folder and double-click it.
|
||||
2. In the ``Signal Ports`` view, right-click ``Ports`` and select ``Add`` > ``New Multi Adapter Port``.
|
||||
3. In the open dialog box, click ``Add`` and select ``New Pipe/File``.
|
||||
4. In the open dialog box, select ``SystemView Serializer`` as Serializer and set path to PRO CPU trace file. Click ``OK``.
|
||||
5. Repeat the steps 3-4 for APP CPU trace file.
|
||||
6. Double-click the created port. View for this port should open.
|
||||
7. Click the ``Start/Stop Streaming`` button. Data should be loaded.
|
||||
8. Use the ``Zoom Out``, ``Zoom In`` and ``Zoom Fit`` buttons to inspect data.
|
||||
9. For settings measurement cursors and other features, please see `Impulse documentation <https://toem.de/index.php/products/impulse>`_).
|
||||
|
||||
.. note::
|
||||
|
||||
If you have problems with visualization (no data is shown or strange behaviors of zoom action are observed), you can try to delete current signal hierarchy and double-click on the necessary file or port. Eclipse will ask you to create a new signal hierarchy.
|
||||
|
||||
Application Examples
|
||||
""""""""""""""""""""
|
||||
--------------------
|
||||
|
||||
- :example:`system/sysview_tracing` demonstrates how to trace FreeRTOS task and system events using SEGGER SystemView.
|
||||
- :example:`system/sysview_tracing_heap_log` demonstrates heap allocation tracing alongside SystemView events.
|
||||
- :example:`system/app_trace_basic` demonstrates how to use the Application Level Tracing Library to log messages to a host via JTAG, providing a faster alternative to UART logs.
|
||||
- :example:`system/app_trace_to_plot` demonstrates how to send and plot dummy sensor data to a host via JTAG.
|
||||
|
||||
.. _app_trace-gcov-source-code-coverage:
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
Gcov (Source Code Coverage)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In ESP-IDF projects, code coverage analysis using gcov can be done with the help of `espressif/esp_gcov <https://components.espressif.com/components/espressif/esp_gcov>`_ managed component.
|
||||
|
||||
.. _app_trace-integrating-a-custom-trace-library:
|
||||
|
||||
Integrating a Custom Trace Library
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``esp_trace`` component exposes a stable extension point (``CONFIG_ESP_TRACE_LIB_EXTERNAL``) for plugging in a third-party trace recorder without patching ESP-IDF. An external component provides an encoder adapter (registered via ``ESP_TRACE_REGISTER_ENCODER()``) and a slim ``esp_trace_freertos_impl.h`` that injects the desired FreeRTOS trace hooks. The encoder vtable also offers optional ``start`` / ``stop`` / ``flush`` and ``take_lock`` / ``give_lock`` entries dispatched from the public :cpp:func:`esp_trace_start`, :cpp:func:`esp_trace_stop`, :cpp:func:`esp_trace_flush` API.
|
||||
|
||||
Application Examples
|
||||
""""""""""""""""""""
|
||||
|
||||
- :example:`system/esp_trace` is a minimal copy-paste template that wires up an external encoder, demonstrates the FreeRTOS trace-hook include-chain contract, and covers cross-core serialization through the encoder lock.
|
||||
For the transport API, see :doc:`/api-reference/system/app_trace`. For the high-level ``esp_trace`` API, see :doc:`/api-reference/system/esp_trace`.
|
||||
70
docs/en/api-reference/system/esp_trace.rst
Normal file
70
docs/en/api-reference/system/esp_trace.rst
Normal file
@@ -0,0 +1,70 @@
|
||||
ESP Trace
|
||||
=========
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The ``esp_trace`` component is the entry point for ESP-IDF tracing. It provides the public tracing API, manages the active trace session, and connects the selected encoder, such as SEGGER SystemView, with the selected transport, such as apptrace.
|
||||
|
||||
For a conceptual overview, architecture, and usage guides, see :doc:`/api-guides/tracing/index`.
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
- :example:`system/esp_trace_custom_library` demonstrates how to integrate an external trace library (encoder) with the ``esp_trace`` core.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
Types
|
||||
^^^^^
|
||||
|
||||
.. doxygentypedef:: esp_trace_handle_t
|
||||
|
||||
.. doxygenstruct:: esp_trace_open_params_t
|
||||
:members:
|
||||
|
||||
.. doxygenstruct:: esp_trace_config
|
||||
:members:
|
||||
|
||||
.. doxygenenum:: esp_trace_link_types_t
|
||||
|
||||
Adapter Types
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
.. doxygenstruct:: esp_trace_encoder_vtable_t
|
||||
:members:
|
||||
|
||||
.. doxygenstruct:: esp_trace_encoder
|
||||
:members:
|
||||
|
||||
.. doxygenenum:: esp_trace_transport_cfg_key_t
|
||||
|
||||
.. doxygenstruct:: esp_trace_transport_vtable_t
|
||||
:members:
|
||||
|
||||
.. doxygenstruct:: esp_trace_transport
|
||||
:members:
|
||||
|
||||
Functions
|
||||
^^^^^^^^^
|
||||
|
||||
.. doxygenfunction:: esp_trace_get_user_params
|
||||
|
||||
.. doxygenfunction:: esp_trace_get_active_handle
|
||||
|
||||
.. doxygenfunction:: esp_trace_write
|
||||
|
||||
.. doxygenfunction:: esp_trace_start
|
||||
|
||||
.. doxygenfunction:: esp_trace_stop
|
||||
|
||||
.. doxygenfunction:: esp_trace_flush
|
||||
|
||||
.. doxygenfunction:: esp_trace_is_host_connected
|
||||
|
||||
.. doxygenfunction:: esp_trace_get_link_type
|
||||
|
||||
.. doxygenfunction:: esp_trace_panic_handler
|
||||
@@ -9,6 +9,7 @@ System API
|
||||
app_image_format
|
||||
bootloader_image_format
|
||||
app_trace
|
||||
esp_trace
|
||||
esp_function_with_shared_stack
|
||||
chip_revision
|
||||
console
|
||||
|
||||
@@ -231,7 +231,7 @@ The ``app_trace`` component is now a sub-component of ``esp_trace`` and will be
|
||||
Initialization Flow Changes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
For runtime configuration override, a new callback system is available. See the :doc:`Application Tracing documentation <../../../api-guides/app_trace>` for details on ``esp_apptrace_get_user_params()`` and ``esp_trace_get_user_params()``.
|
||||
For runtime configuration override, a new callback system is available. See the :doc:`Application Tracing documentation <../../../api-guides/tracing/transports>` for details on ``esp_apptrace_get_user_params()`` and ``esp_trace_get_user_params()``.
|
||||
|
||||
API Changes
|
||||
^^^^^^^^^^^
|
||||
|
||||
@@ -66,6 +66,7 @@ get-started-cmake/get-started-pico-kit hw-reference/esp32/get-started-p
|
||||
get-started-cmake/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3
|
||||
|
||||
api-guides/build-system-cmake api-guides/build-system
|
||||
api-guides/app_trace api-guides/tracing/index
|
||||
api-guides/freertos-smp api-reference/system/freertos_idf
|
||||
api-guides/ulp-cmake api-guides/ulp
|
||||
api-guides/unit-tests-cmake api-guides/unit-tests
|
||||
|
||||
@@ -5,7 +5,6 @@ API 指南
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
app_trace
|
||||
startup
|
||||
:SOC_BT_SUPPORTED: bt-architecture/index
|
||||
:SOC_BT_CLASSIC_SUPPORTED: classic-bt/index
|
||||
@@ -44,6 +43,7 @@ API 指南
|
||||
stdio
|
||||
thread-local-storage
|
||||
tools/index
|
||||
tracing/index
|
||||
unit-tests
|
||||
host-apps
|
||||
:SOC_USB_OTG_SUPPORTED and not esp32p4 and not esp32h4: usb-otg-console
|
||||
|
||||
@@ -354,11 +354,10 @@ semihosting
|
||||
debugging-examples
|
||||
semihosting
|
||||
tips-and-quirks
|
||||
../app_trace
|
||||
|
||||
- :doc:`using-debugger`
|
||||
- :doc:`debugging-examples`
|
||||
- :doc:`semihosting`
|
||||
- :doc:`tips-and-quirks`
|
||||
- :doc:`../app_trace`
|
||||
- :doc:`../tracing/index`
|
||||
- `ESP-Prog 调试板介绍 <https://docs.espressif.com/projects/espressif-esp-iot-solution/zh_CN/latest/hw-reference/ESP-Prog_guide.html>`__
|
||||
|
||||
@@ -63,7 +63,7 @@
|
||||
外部跟踪
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
:doc:`/api-guides/app_trace` 可以在几乎不影响代码执行的情况下测量其执行速度。
|
||||
:doc:`/api-guides/tracing/transports` 可以在几乎不影响代码执行的情况下测量其执行速度。
|
||||
|
||||
任务
|
||||
^^^^^^^
|
||||
|
||||
111
docs/zh_CN/api-guides/tracing/architecture.rst
Normal file
111
docs/zh_CN/api-guides/tracing/architecture.rst
Normal file
@@ -0,0 +1,111 @@
|
||||
跟踪架构
|
||||
========
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本文档介绍 ESP-IDF 跟踪系统的高层设计。
|
||||
|
||||
概述
|
||||
----
|
||||
|
||||
应用程序可以使用 ``esp_trace`` 从目标设备收集运行时信息，并发送到主机工具进行分析。这支持多种场景，例如使用 SEGGER SystemView 分析 FreeRTOS 任务和中断、使用 Gcov 获取源代码覆盖率，以及通过 apptrace 收集应用程序自定义数据。
|
||||
|
||||
ESP-IDF 提供常用的跟踪格式和传输方式，同一框架也可以扩展到新的格式或传输，例如自定义跟踪格式、SPI 传输或 UDP 传输。
|
||||
|
||||
ESP-IDF 跟踪系统采用 **端口与适配器（Port & Adapter）** 设计。应用程序调用公共的 ``esp_trace`` API，跟踪核心则将所选编码器与所选传输连接起来。
|
||||
|
||||
该设计提供：
|
||||
|
||||
- 稳定的应用程序侧 API。
|
||||
- 跟踪格式和主机链路的独立选择。
|
||||
- 适配器相关细节不进入核心跟踪代码。
|
||||
- 由跟踪系统负责启动和 Panic 处理。
|
||||
|
||||
.. mermaid::
|
||||
|
||||
flowchart TB
|
||||
app["应用程序<br/>FreeRTOS 任务、ISR、esp_trace_write()、跟踪宏"]
|
||||
api["公共接口<br/>esp_trace API"]
|
||||
core["核心跟踪代码<br/>esp_trace 组件<br/>会话、多核初始化、适配器协调"]
|
||||
registry["运行时注册表<br/>将配置名称映射到适配器"]
|
||||
host["主机链路<br/>通过 JTAG 的 OpenOCD、UART 或 USB Serial JTAG"]
|
||||
|
||||
subgraph PORTS["端口"]
|
||||
direction LR
|
||||
enc_port["编码器端口"]
|
||||
transport_port["传输端口"]
|
||||
end
|
||||
|
||||
subgraph ADAPTERS["适配器"]
|
||||
direction LR
|
||||
encoder["编码器适配器<br/>外部组件，例如 espressif/esp_sysview<br/>格式化记录器事件"]
|
||||
transport["传输适配器<br/>esp_trace 组件<br/>JTAG/UART 上的 apptrace、USB Serial JTAG"]
|
||||
end
|
||||
|
||||
app --> api --> core
|
||||
core --- registry
|
||||
core --> enc_port
|
||||
core --> transport_port
|
||||
enc_port --> encoder
|
||||
transport_port --> transport
|
||||
encoder -.-> transport
|
||||
transport --> host
|
||||
|
||||
组件
|
||||
----
|
||||
|
||||
核心跟踪代码
|
||||
^^^^^^^^^^^^
|
||||
|
||||
``esp_trace`` 组件包含公共 API，并维护活动跟踪会话。它在启动期间创建编码器/传输配对，协调多核初始化，并将 API 调用转发给所选适配器。
|
||||
|
||||
编码器端口
|
||||
^^^^^^^^^^
|
||||
|
||||
编码器端口接口（:component_file:`esp_trace_port_encoder.h <esp_trace/include/esp_trace_port_encoder.h>`）定义跟踪库如何接入 ``esp_trace``。编码器接收跟踪写入或跟踪钩子事件，并将其转换为记录器特定格式，例如 SystemView 协议。``esp_trace`` 定义该接口，但自身不提供编码器；编码器由外部组件提供，例如 ``espressif/esp_sysview``。参见 :doc:`custom-trace-library`。
|
||||
|
||||
传输端口
|
||||
^^^^^^^^
|
||||
|
||||
传输端口接口（:component_file:`esp_trace_port_transport.h <esp_trace/include/esp_trace_port_transport.h>`）定义编码后的跟踪数据如何离开目标设备。传输负责将字节写入面向主机的链路，并处理链路相关操作，例如刷新、主机连接检查和 Panic 时输出。``esp_trace`` 提供内置的 apptrace（JTAG/UART）和 USB Serial JTAG 传输适配器。参见 :doc:`transports`。
|
||||
|
||||
每个跟踪会话都将一个编码器与一个传输配对。编码器可以将编码后的跟踪数据交给当前会话选择的传输，且跟踪写入期间不进行动态分配。
|
||||
|
||||
初始化
|
||||
------
|
||||
|
||||
``esp_trace`` 会根据项目配置中选择的编码器和传输，在系统启动期间自动初始化。应用程序在使用公共跟踪 API 前通常不需要调用单独的初始化函数。适配器相关的初始化要求参见 :doc:`custom-trace-library`。
|
||||
|
||||
数据流
|
||||
------
|
||||
|
||||
一次典型写入会从公共 API 流向编码器，再流向传输：
|
||||
|
||||
.. mermaid::
|
||||
|
||||
flowchart TD
|
||||
write["esp_trace_write(handle, data, size, tmo)"]
|
||||
validate["核心校验句柄"]
|
||||
encode["编码器写入格式化后的数据<br/>例如 SystemView 协议"]
|
||||
send["传输发送编码后的字节<br/>JTAG、UART 或 USB Serial JTAG"]
|
||||
status["状态返回给调用方"]
|
||||
|
||||
write --> validate --> encode --> send --> status
|
||||
|
||||
Panic 处理
|
||||
----------
|
||||
|
||||
发生 Panic 时，中断已禁用，常规加锁机制不可用。核心会调用活动编码器和传输的可选 Panic 回调。每个适配器随后可以在不使用常规锁的情况下刷新自己的缓冲区。由于 Panic 刷新不得阻塞或使用常规加锁机制，因此仍可能丢弃部分数据。
|
||||
|
||||
注册表
|
||||
------
|
||||
|
||||
适配器在链接时通过 ``ESP_TRACE_REGISTER_ENCODER()`` 和 ``ESP_TRACE_REGISTER_TRANSPORT()`` 自行注册。初始化期间，核心按名称查找所配置的编码器和传输。只有实际链接进应用程序的适配器才可用，且添加新适配器无需改动核心。
|
||||
|
||||
相关文档
|
||||
--------
|
||||
|
||||
- :doc:`custom-trace-library`：适配器作者契约（编码器与传输函数表、注册、加锁与重入规则）
|
||||
- :doc:`transports`：apptrace 传输及独立的 apptrace 用法
|
||||
- :doc:`sysview`：SEGGER SystemView 用法
|
||||
- :doc:`/api-reference/system/esp_trace`：ESP Trace API 参考
|
||||
72
docs/zh_CN/api-guides/tracing/custom-trace-library.rst
Normal file
72
docs/zh_CN/api-guides/tracing/custom-trace-library.rst
Normal file
@@ -0,0 +1,72 @@
|
||||
.. _app_trace-integrating-a-custom-trace-library:
|
||||
|
||||
集成自定义跟踪库
|
||||
================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
:doc:`esp_trace <index>` 组件允许第三方跟踪记录器在不修改 ESP-IDF 的情况下接入框架。SEGGER SystemView 等外部编码器正是通过这种方式集成到跟踪系统中。有关高层设计，请参阅 :doc:`architecture`。
|
||||
|
||||
外部组件需提供：
|
||||
|
||||
- 一个 **编码器适配器**，通过 ``ESP_TRACE_REGISTER_ENCODER()`` 注册，用于将跟踪数据格式化为该记录器的协议。
|
||||
- 一个 ``esp_trace_freertos_impl.h`` 头文件，用于定义记录器所需的 FreeRTOS 跟踪钩子。
|
||||
|
||||
编码器独立于主机链路。它可以使用任何已注册的 :doc:`传输 <transports>`，例如 JTAG/UART 上的 apptrace、USB Serial JTAG 或自定义传输。
|
||||
|
||||
编码器端口
|
||||
----------
|
||||
|
||||
编码器实现 :cpp:struct:`esp_trace_encoder_vtable_t`。
|
||||
|
||||
- 只有 ``init`` 和 ``write`` 为必需回调。
|
||||
- ``start`` / ``stop`` / ``flush`` 由 :cpp:func:`esp_trace_start`、:cpp:func:`esp_trace_stop`、:cpp:func:`esp_trace_flush` 调度。
|
||||
- ``panic_handler`` 在 Panic 路径上被调用，使适配器可以在不使用常规锁的情况下刷新。
|
||||
- ``take_lock`` / ``give_lock`` 提供编码器的多核序列化；核心自身不添加任何加锁。
|
||||
|
||||
编码器实例（:cpp:struct:`esp_trace_encoder`）保存其函数表、当前活动跟踪会话所绑定的传输以及编码器特定状态。具体字段请参阅该结构体的参考文档。
|
||||
|
||||
如果编码器需要设置传输参数，请在 ``init`` 中通过带类型的配置键配置所绑定的传输，例如使用 ``ESP_TRACE_TRANSPORT_CFG_HEADER_SIZE`` 设置传输数据头大小。
|
||||
|
||||
在链接时注册编码器；核心按所配置的名称查找：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
ESP_TRACE_REGISTER_ENCODER("sysview", &s_sysview_vt);
|
||||
|
||||
传输端口
|
||||
--------
|
||||
|
||||
传输实现 :cpp:struct:`esp_trace_transport_vtable_t`。
|
||||
|
||||
使用 ``ESP_TRACE_REGISTER_TRANSPORT("name", &vtable)`` 注册。大多数项目只需要自定义编码器，并可使用已有传输。仅当需要新的主机链路时才需要实现传输。apptrace 传输参见 :doc:`transports`。
|
||||
|
||||
加锁与重入
|
||||
----------
|
||||
|
||||
``write``、``flush`` / ``flush_nolock``、``read``、``take_lock`` / ``give_lock``、``panic_handler`` 等运行时回调可能从 FreeRTOS 跟踪钩子中调用。其中一些回调也可能从 ISR 上下文调用，另一些回调会在持有编码器锁时调用。
|
||||
|
||||
.. warning::
|
||||
|
||||
不要从这些回调中调用本身会触发跟踪钩子的 FreeRTOS 或 IDF API。任何会触发 ``trace*()`` 宏的操作都会重新进入跟踪路径，可能递归进入你的编码器、在编码器的非递归自旋锁上死锁，或在 ISR 上下文中调用仅限任务的 API。
|
||||
|
||||
在运行时回调中应特别避免：
|
||||
|
||||
- 会让出的任务 API（``vTaskDelay``、``vTaskSuspend``、``xTaskNotify*``）
|
||||
- 队列 / 信号量 / 互斥量 API（``xQueueSend`` / ``xQueueReceive``、``xSemaphoreTake`` / ``xSemaphoreGive``）
|
||||
- 流缓冲区和消息缓冲区 API
|
||||
- 可能获取内部互斥量的堆分配
|
||||
|
||||
在运行时回调中，应使用无锁或仅自旋锁的原语（``esp_trace_lock_*``、``esp_trace_rb_*``）、底层寄存器访问、原子操作以及 ``esp_rom_*`` 辅助函数。较重的工作（例如 FreeRTOS API 调用或内存分配）只应在 ``init()`` 中、跟踪开始前完成。
|
||||
|
||||
对于需要复杂驱动或网络协议栈的传输，运行时回调应只作为生产者使用。将跟踪数据复制到预分配且适合跟踪路径使用的缓冲区中，例如 ``esp_trace_rb_*`` 环形缓冲区，然后尽快返回。由 ``init()`` 创建的工作任务从该缓冲区取出数据，并在跟踪回调路径和编码器锁之外调用 SPI master、socket、StreamBuffer 或其他 FreeRTOS API。由于回调不能阻塞，也不能通过会让出的 API 唤醒任务，工作任务应轮询缓冲区（或在传输层事件上唤醒）；当缓冲区已满时应丢弃数据，而不是把背压传导回回调。
|
||||
|
||||
FreeRTOS 跟踪钩子
|
||||
-----------------
|
||||
|
||||
为捕获 FreeRTOS 事件，外部组件需提供 ``esp_trace_freertos_impl.h`` 头文件，其中定义所需的跟踪宏（``traceTASK_SWITCHED_IN()``、``traceISR_ENTER()`` 等）。当 ``CONFIG_ESP_TRACE_LIB_EXTERNAL=y`` 时，``esp_trace`` 会包含该头文件。所需的 CMake 配置（用于适配器注册的 ``WHOLE_ARCHIVE``，以及使头文件对 ``esp_trace`` 可见）参见 :component_file:`esp_trace 组件 README <esp_trace/README.md>`。
|
||||
|
||||
应用示例
|
||||
--------
|
||||
|
||||
- :example:`system/esp_trace_custom_library` 是一个最简模板，演示如何接入外部编码器、说明 FreeRTOS 跟踪钩子头文件的包含链，以及通过编码器锁实现多核序列化。
|
||||
26
docs/zh_CN/api-guides/tracing/gcov.rst
Normal file
26
docs/zh_CN/api-guides/tracing/gcov.rst
Normal file
@@ -0,0 +1,26 @@
|
||||
.. _app_trace-gcov-source-code-coverage:
|
||||
|
||||
Gcov（源代码覆盖率）
|
||||
====================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
Gcov 是一种源代码覆盖率分析工具。在 ESP-IDF 中，目标设备上生成的覆盖率数据通过 apptrace（JTAG 或 UART）转储到主机，在主机端被转换为标准的 ``.gcda`` 文件，并使用常规的主机端工具进行处理。
|
||||
|
||||
生成覆盖率报告还需要 ``.gcno`` 注释文件，编译器会在构建时为每个使用 ``--coverage`` 编译的源文件生成该文件。主机端工具将运行时的 ``.gcda`` 计数与 ``.gcno`` 文件以及原始源代码相结合，从而生成覆盖率报告。
|
||||
|
||||
Gcov 使用跟踪基础设施进行主机数据传输，但尚未完全遵循 :doc:`esp_trace <index>` 的编码器/传输模型。特别是，它固定使用 apptrace 传输（JTAG 或 UART），不支持选择自定义传输。
|
||||
|
||||
覆盖率功能由托管组件 `espressif/esp_gcov <https://components.espressif.com/components/espressif/esp_gcov>`_ 提供。在项目的 ``idf_component.yml`` 中添加该组件：
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
dependencies:
|
||||
espressif/esp_gcov: ^1
|
||||
|
||||
覆盖率数据既可以在应用程序中的硬编码位置转储（通过 apptrace 经 JTAG 或 UART），也可以通过 OpenOCD ``esp gcov`` 命令从主机端按需转储（仅限 JTAG）。完整的设置、配置选项以及命令用法，请参阅上面链接的组件 README。
|
||||
|
||||
应用示例
|
||||
--------
|
||||
|
||||
- :example:`system/gcov` 演示如何为项目添加代码覆盖率，并通过 JTAG 收集覆盖率数据。
|
||||
108
docs/zh_CN/api-guides/tracing/index.rst
Normal file
108
docs/zh_CN/api-guides/tracing/index.rst
Normal file
@@ -0,0 +1,108 @@
|
||||
ESP 跟踪
|
||||
========
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
----
|
||||
|
||||
ESP-IDF 提供了一套跟踪系统，用于程序行为分析和调试。它允许用户以较小开销从 {IDF_TARGET_NAME} 收集运行时数据，并将数据发送到主机。
|
||||
|
||||
该系统以 **esp_trace** 组件为中心。它提供公共跟踪 API，管理活动跟踪会话，并将跟踪编码器与跟踪传输连接起来。SEGGER SystemView、Gcov 和 apptrace 传输等跟踪功能都接入这一模型。
|
||||
|
||||
``esp_trace`` 组件支持常用的跟踪格式和传输方式，并设计为可扩展。新的跟踪格式和传输可以在不修改 ESP-IDF 的情况下添加。有关设计的更多信息，请参阅 :doc:`architecture`。
|
||||
|
||||
- **跟踪格式**：SEGGER SystemView，用于业界标准的 FreeRTOS 分析（参见 :doc:`sysview`）；或你自己的记录器（参见 :doc:`custom-trace-library`）。
|
||||
- **传输**：
|
||||
|
||||
.. list::
|
||||
|
||||
- :doc:`apptrace 传输 <transports>`\ （``app_trace`` 组件），可通过 JTAG 或 UART
|
||||
:SOC_USB_SERIAL_JTAG_SUPPORTED: - USB Serial JTAG 传输
|
||||
|
||||
选择适合你的路径
|
||||
----------------
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 40 60
|
||||
|
||||
* - 目标
|
||||
- 参考文档
|
||||
* - 分析 FreeRTOS 任务/中断行为
|
||||
- :doc:`SEGGER SystemView <sysview>`
|
||||
* - 发送/接收任意应用程序数据，或记录日志到主机
|
||||
- :doc:`应用层跟踪传输 <transports>`
|
||||
* - 收集源代码覆盖率
|
||||
- :doc:`Gcov <gcov>`
|
||||
* - 集成第三方跟踪记录器
|
||||
- :doc:`自定义跟踪库 <custom-trace-library>`
|
||||
|
||||
选择传输
|
||||
--------
|
||||
|
||||
跟踪格式与传输可独立选择。请根据可用硬件选择主机链路：
|
||||
|
||||
.. list::
|
||||
|
||||
- **apptrace（JTAG）**：吞吐量最高，并支持由主机发起的控制（start / stop / dump）。需要 JTAG 适配器以及主机上运行的 OpenOCD。适用于 SystemView 以及按需的 Gcov 转储。
|
||||
- **apptrace（UART）**：使用空闲的 UART 而非调试探针，吞吐量低于 JTAG。请选择未被控制台占用的 UART。
|
||||
:SOC_USB_SERIAL_JTAG_SUPPORTED: - **USB Serial JTAG**：使用芯片内置的 USB 外设，仅需一根 USB 线，无需外部适配器。跟踪数据通过该外设的串行（CDC）接口传输，而非其 JTAG 接口。当 USB Serial JTAG 未被控制台占用时可用。
|
||||
|
||||
主要特性
|
||||
--------
|
||||
|
||||
- **自动初始化**：跟踪在启动时自动配置
|
||||
- **多核支持**：适用于单核和双核芯片
|
||||
- **可扩展**：添加自定义跟踪格式或传输；参见 :doc:`architecture`
|
||||
|
||||
快速入门：SystemView 跟踪
|
||||
-------------------------
|
||||
|
||||
启用 SEGGER SystemView 跟踪以进行 FreeRTOS 系统分析：
|
||||
|
||||
1. 在项目的 ``idf_component.yml`` 中添加 ``espressif/esp_sysview`` 依赖。
|
||||
|
||||
2. 启用 :ref:`CONFIG_ESP_TRACE_LIB_EXTERNAL <CONFIG_ESP_TRACE_LIB_EXTERNAL>` 以选择外部跟踪库。
|
||||
|
||||
3. 启用 :ref:`CONFIG_ESP_TRACE_TRANSPORT_APPTRACE <CONFIG_ESP_TRACE_TRANSPORT_APPTRACE>` 以选择 apptrace 传输。
|
||||
|
||||
4. 启用 :ref:`CONFIG_APPTRACE_DEST_JTAG <CONFIG_APPTRACE_DEST_JTAG>` 以将数据目标设为 JTAG。
|
||||
|
||||
5. 构建并烧录应用程序：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py build flash
|
||||
|
||||
有关 SystemView 的详细用法、OpenOCD 设置和主机端可视化，请参阅 :doc:`sysview`。
|
||||
|
||||
详细指南
|
||||
--------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
architecture
|
||||
transports
|
||||
sysview
|
||||
gcov
|
||||
custom-trace-library
|
||||
|
||||
相关文档
|
||||
--------
|
||||
|
||||
- :doc:`/api-reference/system/esp_trace`：ESP Trace API 参考
|
||||
- :doc:`/api-reference/system/app_trace`：应用层跟踪（传输）API 参考
|
||||
- :doc:`/api-guides/jtag-debugging/index`：JTAG 调试设置与硬件配置
|
||||
- `SEGGER SystemView <https://www.segger.com/products/development-tools/systemview/>`_：官方 SystemView 工具和文档
|
||||
- `OpenOCD <https://openocd.org/>`_：开源片上调试器
|
||||
|
||||
示例
|
||||
----
|
||||
|
||||
- :example:`system/app_trace_basic`：基础应用程序跟踪
|
||||
- :example:`system/sysview_tracing`：SystemView 跟踪示例
|
||||
- :example:`system/sysview_tracing_heap_log`：基于 SystemView 的堆跟踪
|
||||
- :example:`system/gcov`：通过 JTAG 获取源代码覆盖率
|
||||
- :example:`system/esp_trace_custom_library`：外部跟踪库集成模板
|
||||
140
docs/zh_CN/api-guides/tracing/sysview.rst
Normal file
140
docs/zh_CN/api-guides/tracing/sysview.rst
Normal file
@@ -0,0 +1,140 @@
|
||||
.. _app_trace-system-behaviour-analysis-with-segger-systemview:
|
||||
|
||||
基于 SEGGER SystemView 的系统行为分析
|
||||
=====================================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
SEGGER SystemView 是一款实时记录和可视化工具，用于分析应用程序运行时的行为（任务调度、中断、系统事件）。在 :doc:`esp_trace <index>` 模型中，SystemView 以 **编码器** 的形式提供：它将 FreeRTOS 和应用程序事件格式化为 SystemView 协议，数据则由 :doc:`传输 <transports>` 层（通常为 JTAG 上的 apptrace，或用于实时查看的 UART）传送到主机。
|
||||
|
||||
工具详情请参阅 `SystemView <https://www.segger.com/products/development-tools/systemview/>`_。
|
||||
|
||||
启用 SystemView
|
||||
---------------
|
||||
|
||||
SystemView 功能由托管组件 ``espressif/esp_sysview`` 提供。完成以下步骤后才会显示 SystemView 配置菜单：
|
||||
|
||||
1. 在 ``idf_component.yml`` 中添加组件依赖：
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
dependencies:
|
||||
espressif/esp_sysview: ^1
|
||||
|
||||
2. 在 menuconfig 中选择外部库：``Component config`` > ``ESP Trace Configuration`` > ``Trace library`` > ``External library from component registry``。
|
||||
|
||||
之后，可通过 ``Component config`` > ``SEGGER SystemView Configuration`` 配置 SystemView。该菜单可用于选择时间戳源 (:ref:`CONFIG_ESP_TRACE_TIMESTAMP_SOURCE`)、单独启用或禁用 SystemView 事件集合 (``CONFIG_SEGGER_SYSVIEW_EVT_XXX``)，以及在使用 UART 目标时选择要跟踪的 CPU。
|
||||
|
||||
.. note::
|
||||
|
||||
完整的最新配置选项和主机端设置，请参阅组件 README：`esp_sysview <https://components.espressif.com/components/espressif/esp_sysview>`_。
|
||||
|
||||
想要通过 UART 接口进行实时跟踪，请首先在 ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing`` 中选择 UART 作为目标传输方式。然后在 ``Component config`` > ``ESP Trace Configuration`` > ``SEGGER SystemView`` 中选择 Pro 或 App CPU。
|
||||
|
||||
OpenOCD SystemView 跟踪命令选项
|
||||
-------------------------------
|
||||
|
||||
通过 JTAG 跟踪时，使用专用的 OpenOCD 命令收集数据。OpenOCD/JTAG 设置请参阅 :doc:`JTAG 调试 </api-guides/jtag-debugging/index>`。
|
||||
|
||||
命令用法：
|
||||
|
||||
``esp sysview [start <options>] | [stop] | [status]``
|
||||
|
||||
子命令：
|
||||
|
||||
``start``
|
||||
开启跟踪（连续流模式）。
|
||||
``stop``
|
||||
停止跟踪。
|
||||
``status``
|
||||
获取跟踪状态。
|
||||
|
||||
Start 子命令语法：
|
||||
|
||||
``start <outfile1> [outfile2] [poll_period [trace_size [stop_tmo]]]``
|
||||
|
||||
``outfile1``
|
||||
保存 PRO CPU 数据的文件路径。此参数需要具有如下格式：``file://path/to/file``。
|
||||
``outfile2``
|
||||
保存 APP CPU 数据的文件路径。此参数需要具有如下格式：``file://path/to/file``。
|
||||
``poll_period``
|
||||
跟踪数据的轮询周期（单位：毫秒）。如果该值大于 0，则命令以非阻塞的模式运行。默认为 1 毫秒。
|
||||
``trace_size``
|
||||
最多要收集的数据量（单位：字节）。当收到指定数量的数据后，将停止跟踪。默认值是 -1（禁用跟踪大小停止触发器）。
|
||||
``stop_tmo``
|
||||
空闲超时（单位：秒）。如果指定的时间内没有数据，将停止跟踪。默认值是 -1（禁用跟踪超时停止触发器）。
|
||||
|
||||
.. note::
|
||||
|
||||
如果 ``poll_period`` 为 0，则在跟踪停止之前，OpenOCD 的 telnet 命令行将不可用。你需要复位板卡，或者在 OpenOCD 的窗口（非 telnet 会话窗口）输入 Ctrl+C 命令，手动停止跟踪。另一个办法是设置 ``trace_size``，等到收集满指定数量的数据后自动停止跟踪。
|
||||
|
||||
命令使用示例：
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
::
|
||||
|
||||
esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat
|
||||
|
||||
跟踪数据被检索并以非阻塞的方式保存。要停止此过程，需要在 OpenOCD 的 telnet 会话窗口输入 ``esp sysview stop`` 命令，也可以在 OpenOCD 窗口中按下快捷键 Ctrl+C。
|
||||
|
||||
多核 SystemView 跟踪命令
|
||||
""""""""""""""""""""""""""
|
||||
|
||||
对于支持多核跟踪的 SystemView 3.60 及更高版本，请使用 ``esp sysview_mcore`` 命令。此命令与 ``esp sysview`` 相同，但使用官方 SEGGER SystemView 多核格式。所有核心的跟踪数据都保存在同一文件中，可在 SEGGER SystemView v3.60 或更高版本中打开。
|
||||
|
||||
命令使用示例：
|
||||
|
||||
::
|
||||
|
||||
esp sysview_mcore start file://heap_log_mcore.SVDat
|
||||
|
||||
有关详细的命令语法和选项，请参考前文所述的 ``esp sysview`` 命令，因为 ``esp sysview_mcore`` 支持相同的参数。
|
||||
|
||||
数据可视化
|
||||
----------
|
||||
|
||||
收集到跟踪数据后，用户可以使用特殊的工具对结果进行可视化并分析程序行为。
|
||||
|
||||
.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES
|
||||
|
||||
**多核跟踪**
|
||||
|
||||
SystemView 3.60 及更高版本支持多核心进行跟踪。对于多核跟踪，使用 ``esp sysview_mcore`` 命令可以生成与 SystemView 多核格式兼容的单个文件。此命令将创建一个单独的跟踪文件，可以直接加载到 SystemView 3.60+ 中进行多核可视化。
|
||||
|
||||
**注意：** SystemView 3.60 之前的版本不支持多核跟踪。对于旧版本，当使用 JTAG 接口跟踪双核模式下的 {IDF_TARGET_NAME} 时会生成两个文件：一个用于 PRO CPU，另一个用于 APP CPU。用户可将每个文件载入不同的工具实例。使用 UART 进行跟踪时，在 menuconfig 中选择外部库后，用户可以选择 ``Component config`` > ``SEGGER SystemView Configuration`` 来指定需要跟踪的 CPU（Pro 或 App）。
|
||||
|
||||
对于旧版本的 SystemView，在不同的实例中分别分析每个核的数据可能较为不便。另一个选择是使用名为 *Impulse* 的 Eclipse 插件，该插件可同时加载多个跟踪文件，实现在同一视图中检查来自两个核心的事件。与 SystemView 免费版相比，此插件还不受 100 万事件数量的限制。
|
||||
|
||||
关于如何安装、配置 Impulse 并使用它来可视化来自单个核心的跟踪数据，请参阅 `官方教程 <https://mcuoneclipse.com/2016/07/31/impulse-segger-systemview-in-eclipse/>`_ 。
|
||||
|
||||
.. note::
|
||||
|
||||
ESP-IDF 使用自己的 SystemView FreeRTOS 事件 ID 映射，因此用户需要将 ``$SYSVIEW_INSTALL_DIR/Description/SYSVIEW_FreeRTOS.txt`` 替换成 ``$IDF_PATH/tools/esp_app_trace/SYSVIEW_FreeRTOS.txt``。在使用上述链接配置 SystemView 序列化程序时，也应该使用该特定文件的内容。
|
||||
|
||||
.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES
|
||||
|
||||
配置 Impulse 实现双核跟踪
|
||||
"""""""""""""""""""""""""
|
||||
|
||||
在安装好 Impulse 插件并确保 Impulse 能够在单独的选项卡中成功加载每个核心的跟踪文件后，用户可以添加特殊的 Multi Adapter 端口并将这两个文件加载到一个视图中。为此，用户需要在 Eclipse 中执行以下操作：
|
||||
|
||||
1. 打开 ``Signal Ports`` 视图，前往 ``Windows`` > ``Show View`` > ``Other`` 菜单，在 Impulse 文件夹中找到 ``Signal Ports`` 视图并双击。
|
||||
2. 在 ``Signal Ports`` 视图中，右键 ``Ports`` 并选择 ``Add``，然后选择 ``New Multi Adapter Port``。
|
||||
3. 在打开的对话框中按下 ``add`` 按钮，选择 ``New Pipe/File``。
|
||||
4. 在打开的对话框中选择 ``SystemView Serializer`` 并设置 PRO CPU 跟踪文件的路径，按下 ``OK`` 保存设置。
|
||||
5. 对 APP CPU 的跟踪文件重复步骤 3 和 4。
|
||||
6. 双击创建的端口，会打开此端口的视图。
|
||||
7. 单击 ``Start/Stop Streaming`` 按钮，数据将会被加载。
|
||||
8. 使用 ``Zoom Out``，``Zoom In`` 和 ``Zoom Fit`` 按钮来查看数据。
|
||||
9. 有关设置测量光标和其他的功能，请参阅 `Impulse 官方文档 <https://toem.de/index.php/products/impulse>`_ 。
|
||||
|
||||
.. note::
|
||||
|
||||
如果你在可视化方面遇到了问题（未显示数据或者缩放操作异常），可以尝试删除当前的信号层次结构，再双击必要的文件或端口。Eclipse 会请求创建新的信号层次结构。
|
||||
|
||||
应用示例
|
||||
--------
|
||||
|
||||
- :example:`system/sysview_tracing` 演示如何使用 SEGGER SystemView 记录 FreeRTOS 任务与系统事件。
|
||||
- :example:`system/sysview_tracing_heap_log` 演示如何在记录 SystemView 事件的同时，对堆内存分配进行跟踪。
|
||||
@@ -1,23 +1,27 @@
|
||||
应用层跟踪库
|
||||
============
|
||||
应用层跟踪传输 (apptrace)
|
||||
=========================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
**应用层跟踪** 库（``app_trace`` 组件）是 :doc:`esp_trace <index>` 跟踪系统默认使用的传输方式。它允许用户在程序运行开销很小的前提下，通过 JTAG 或 UART 接口在主机和 {IDF_TARGET_NAME} 之间传输任意数据。用户也可同时使用 JTAG 和 UART 接口。UART 接口主要用于连接 SEGGER SystemView 工具（参见 :doc:`sysview`）。基于 USB Serial JTAG 外设的跟踪由一个独立的传输提供，而非 apptrace。
|
||||
|
||||
本页介绍该传输本身：如何配置它、如何通过它发送和接收任意应用程序数据，以及用于在主机端收集数据的 OpenOCD 命令。基于该传输构建的高级功能在其他页面中单独介绍：
|
||||
|
||||
- 基于 SEGGER SystemView 的系统行为分析：参见 :doc:`sysview`。
|
||||
- 使用 Gcov 获取源代码覆盖率：参见 :doc:`gcov`。
|
||||
- 接入你自己的跟踪记录器：参见 :doc:`custom-trace-library`。
|
||||
|
||||
概述
|
||||
----
|
||||
|
||||
ESP-IDF 中提供了应用层跟踪功能，用于分析应用程序的行为。这一功能在相应的库中实现，可以通过 menuconfig 开启。此功能允许用户在程序运行开销很小的前提下，通过 JTAG、UART 或 USB 接口在主机和 {IDF_TARGET_NAME} 之间传输任意数据。用户也可同时使用 JTAG 和 UART 接口。UART 接口主要用于连接 SEGGER SystemView 工具（参见 `SystemView <https://www.segger.com/products/development-tools/systemview/>`_)。
|
||||
|
||||
开发人员可以使用这一功能库将应用程序的运行状态发送给主机，在运行时接收来自主机的命令或者其他类型的信息。该库的主要使用场景有：
|
||||
开发人员可以使用这一功能库将应用程序的运行状态发送给主机，在运行时接收来自主机的命令或者其他类型的信息。该库独立使用时的主要使用场景有：
|
||||
|
||||
1. 收集来自特定应用程序的数据。具体请参阅 :ref:`app_trace-application-specific-tracing`。
|
||||
2. 记录到主机的轻量级日志。具体请参阅 :ref:`app_trace-logging-to-host`。
|
||||
3. 系统行为分析。具体请参阅 :ref:`app_trace-system-behaviour-analysis-with-segger-systemview`。
|
||||
4. 获取源代码覆盖率。具体请参阅 :ref:`app_trace-gcov-source-code-coverage`。
|
||||
|
||||
使用 JTAG 接口的跟踪组件工作示意图如下所示：
|
||||
|
||||
.. figure:: ../../_static/app_trace-overview.jpg
|
||||
.. figure:: ../../../_static/app_trace-overview.jpg
|
||||
:align: center
|
||||
:alt: Tracing Components when Working Over JTAG
|
||||
|
||||
@@ -39,7 +43,7 @@ ESP-IDF 中提供了应用层跟踪功能，用于分析应用程序的行为。
|
||||
|
||||
使用此功能需要在主机端和目标端进行以下配置：
|
||||
|
||||
1. **主机端：** 应用程序跟踪通过 JTAG 来完成，因此需要在主机上安装并运行 OpenOCD。详细信息请参阅 :doc:`JTAG 调试 <../api-guides/jtag-debugging/index>`。
|
||||
1. **主机端：** 应用程序跟踪通过 JTAG 来完成，因此需要在主机上安装并运行 OpenOCD。详细信息请参阅 :doc:`JTAG 调试 </api-guides/jtag-debugging/index>`。
|
||||
|
||||
2. **目标端：** 在 menuconfig 中开启应用程序跟踪功能。**重要提示：** 须首先通过 ``Component config`` > ``ESP Trace Configuration`` > ``Trace transport`` 并选择 ``ESP-IDF apptrace`` 启用应用程序跟踪。之后，可以在 ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing`` 中进行详细配置，例如配置跟踪数据的传输目标。对于 UART 接口，需定义端口号、波特率、TX 和 RX 管脚及其他相关参数。当选择任何跟踪库（例如 SEGGER SystemView）时，这些配置也将同步用于该库。
|
||||
|
||||
@@ -57,7 +61,7 @@ ESP-IDF 中提供了应用层跟踪功能，用于分析应用程序的行为。
|
||||
|
||||
4. *UART RX/TX ring buffer size* (:ref:`CONFIG_APPTRACE_UART_TX_BUFF_SIZE`)。缓冲区的大小取决于通过 UART 传输的数据量。
|
||||
|
||||
5. *UART TX message size* (:ref:`CONFIG_APPTRACE_UART_TX_MSG_size`)。要传输的单条消息的最大尺寸。
|
||||
5. *UART TX message size* (:ref:`CONFIG_APPTRACE_UART_TX_MSG_SIZE`)。要传输的单条消息的最大尺寸。
|
||||
|
||||
|
||||
如何使用此库
|
||||
@@ -94,7 +98,7 @@ ESP-IDF 中提供了应用层跟踪功能，用于分析应用程序的行为。
|
||||
|
||||
.. note::
|
||||
|
||||
应用程序跟踪也可作为 esp_trace 库的传输适配器。在这种情况下，应用层跟踪库不会被直接使用，而是通过已选择的 esp_trace 库及其 API 间接使用。
|
||||
应用程序跟踪也可作为 esp_trace 库的传输适配器。在这种情况下，应用层跟踪库不会被直接使用，而是通过已选择的 esp_trace 库及其 API 间接使用。参见 :doc:`index`。
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -226,13 +230,13 @@ ESP-IDF 中提供了应用层跟踪功能，用于分析应用程序的行为。
|
||||
|
||||
3. 下一步是编译应用程序的镜像，并将其下载到目标板上。这一步可以参考文档 :ref:`构建并烧写 <get-started-build>`。
|
||||
|
||||
4. 运行 OpenOCD（参见 :doc:`JTAG 调试 <../api-guides/jtag-debugging/index>`）。
|
||||
4. 运行 OpenOCD（参见 :doc:`JTAG 调试 </api-guides/jtag-debugging/index>`）。
|
||||
|
||||
5. 连接到 OpenOCD 的 telnet 服务器。用户可在终端执行命令 ``telnet <oocd_host> 4444``。如果用户是在运行 OpenOCD 的同一台机器上打开 telnet 会话，可以使用 ``localhost`` 替换上面命令中的 ``<oocd_host>``。
|
||||
|
||||
6. 使用特殊的 OpenOCD 命令开始收集待跟踪的命令。此命令将传输跟踪数据并将其重定向到指定的文件或套接字。相关命令的说明，请参阅 `OpenOCD 应用程序跟踪命令`_。
|
||||
|
||||
7. 最后，处理接收到的数据。由于数据格式由用户自己定义，本文档中省略数据处理的具体流程。数据处理的范例可以参考位于 ``$IDF_PATH/tools/esp_app_trace`` 下的 Python 脚本 ``apptrace_proc.py`` （用于功能测试）和 ``logtrace_proc.py`` （请参阅 :ref:`app_trace-logging-to-host` 章节中的详细信息）。
|
||||
7. 最后，处理接收到的数据。由于数据格式由用户自己定义，本文档中省略数据处理的具体流程。数据处理的范例可以参考位于 ``$IDF_PATH/tools/esp_app_trace`` 下的 Python 脚本 ``sysviewtrace_proc.py`` （用于功能测试）和 ``logtrace_proc.py`` （请参阅 :ref:`app_trace-logging-to-host` 章节中的详细信息）。
|
||||
|
||||
|
||||
OpenOCD 应用程序跟踪命令
|
||||
@@ -389,195 +393,13 @@ Log Trace Processor 命令选项
|
||||
不打印错误信息。
|
||||
|
||||
|
||||
.. _app_trace-system-behaviour-analysis-with-segger-systemview:
|
||||
|
||||
基于 SEGGER SystemView 的系统行为分析
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
ESP-IDF 中另一个基于应用层跟踪库的实用功能是系统级跟踪，它会生成与 `SEGGER SystemView 工具 <https://www.segger.com/products/development-tools/systemview/>`_ 相兼容的跟踪信息。SEGGER SystemView 是一款实时记录和可视化工具，用来分析应用程序运行时的行为，可通过 UART 接口实时查看事件。
|
||||
|
||||
|
||||
如何使用
|
||||
""""""""
|
||||
|
||||
SystemView 功能由托管组件 ``espressif/esp_sysview`` 提供。完成以下步骤后才会显示 SystemView 配置菜单：
|
||||
|
||||
1. 在 ``idf_component.yml`` 中添加组件依赖：
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
dependencies:
|
||||
espressif/esp_sysview: ^1
|
||||
|
||||
2. 在 menuconfig 中选择外部库：``Component config`` > ``ESP Trace Configuration`` > ``Trace library`` > ``External library from component registry``。
|
||||
|
||||
之后，可通过 ``Component config`` > ``SEGGER SystemView Configuration`` 配置 SystemView。完整的最新使用指南，请参阅 `esp_sysview README <https://components.espressif.com/components/espressif/esp_sysview>`_。
|
||||
|
||||
此配置菜单还包含以下选项：
|
||||
|
||||
1. {IDF_TARGET_NAME} 用作 SystemView 时间戳源的定时器选择：（:ref:`CONFIG_ESP_TRACE_TIMESTAMP_SOURCE`）用于选择 SystemView 事件的时间戳源。在单核模式下，时间戳由以最大频率运行的 {IDF_TARGET_NAME} 内部周期计数器生成。（:ref:`CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ`）在双核模式下，使用外部定时器生成时间戳，其频率为 CPU 频率的 1/2。
|
||||
|
||||
2. 可以单独启用或禁用的 SystemView 事件集合 (``CONFIG_SEGGER_SYSVIEW_EVT_XXX``)：
|
||||
|
||||
- Trace Buffer Overflow Event
|
||||
- ISR Enter Event
|
||||
- ISR Exit Event
|
||||
- ISR Exit to Scheduler Event
|
||||
- Task Start Execution Event
|
||||
- Task Stop Execution Event
|
||||
- Task Start Ready State Event
|
||||
- Task Stop Ready State Event
|
||||
- Task Create Event
|
||||
- Task Terminate Event
|
||||
- System Idle Event
|
||||
- Timer Enter Event
|
||||
- Timer Exit Event
|
||||
|
||||
ESP-IDF 中已经包含了所有用于生成兼容 SystemView 跟踪信息的代码。
|
||||
|
||||
3. 想要通过 UART 接口进行实时跟踪，请首先在 ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing`` 中选择 UART 作为目标传输方式。然后在 ``Component config`` > ``ESP Trace Configuration`` > ``SEGGER SystemView`` 中选择 Pro 或 App CPU。
|
||||
|
||||
OpenOCD SystemView 跟踪命令选项
|
||||
"""""""""""""""""""""""""""""""
|
||||
|
||||
命令用法：
|
||||
|
||||
``esp sysview [start <options>] | [stop] | [status]``
|
||||
|
||||
子命令：
|
||||
|
||||
``start``
|
||||
开启跟踪（连续流模式）。
|
||||
``stop``
|
||||
停止跟踪。
|
||||
``status``
|
||||
获取跟踪状态。
|
||||
|
||||
Start 子命令语法：
|
||||
|
||||
``start <outfile1> [outfile2] [poll_period [trace_size [stop_tmo]]]``
|
||||
|
||||
``outfile1``
|
||||
保存 PRO CPU 数据的文件路径。此参数需要具有如下格式：``file://path/to/file``。
|
||||
``outfile2``
|
||||
保存 APP CPU 数据的文件路径。此参数需要具有如下格式：``file://path/to/file``。
|
||||
``poll_period``
|
||||
跟踪数据的轮询周期（单位：毫秒）。如果该值大于 0，则命令以非阻塞的模式运行。默认为 1 毫秒。
|
||||
``trace_size``
|
||||
最多要收集的数据量（单位：字节）。当收到指定数量的数据后，将停止跟踪。默认值是 -1（禁用跟踪大小停止触发器）。
|
||||
``stop_tmo``
|
||||
空闲超时（单位：秒）。如果指定的时间内没有数据，将停止跟踪。默认值是 -1（禁用跟踪超时停止触发器）。
|
||||
|
||||
.. note::
|
||||
|
||||
如果 ``poll_period`` 为 0，则在跟踪停止之前，OpenOCD 的 telnet 命令行将不可用。你需要复位板卡，或者在 OpenOCD 的窗口（非 telnet 会话窗口）输入 Ctrl+C 命令，手动停止跟踪。另一个办法是设置 ``trace_size``，等到收集满指定数量的数据后自动停止跟踪。
|
||||
|
||||
命令使用示例：
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
1. 将 SystemView 跟踪数据收集到文件 ``pro-cpu.SVDat`` 和 ``pro-cpu.SVDat`` 中。这些文件会被保存在 ``openocd-esp32`` 目录中。
|
||||
|
||||
::
|
||||
|
||||
esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat
|
||||
|
||||
跟踪数据被检索并以非阻塞的方式保存。要停止此过程，需要在 OpenOCD 的 telnet 会话窗口输入 ``esp sysview stop`` 命令，也可以在 OpenOCD 窗口中按下快捷键 Ctrl+C。
|
||||
|
||||
2. 检索跟踪数据并无限保存。
|
||||
|
||||
::
|
||||
|
||||
esp32 sysview start file://pro-cpu.SVDat file://app-cpu.SVDat 0 -1 -1
|
||||
|
||||
OpenOCD 的 telnet 命令行在跟踪停止前会无法使用，要停止跟踪，请在 OpenOCD 窗口使用 Ctrl+C 快捷键。
|
||||
|
||||
|
||||
多核 SystemView 跟踪命令
|
||||
""""""""""""""""""""""""""
|
||||
|
||||
对于支持多核跟踪的 SystemView 3.60 及更高版本，请使用 ``esp sysview_mcore`` 命令。此命令与 ``esp sysview`` 相同，但使用官方 SEGGER SystemView 多核格式。所有核心的跟踪数据都保存在同一文件中，可在 SEGGER SystemView v3.60 或更高版本中打开。
|
||||
|
||||
命令使用示例：
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
::
|
||||
|
||||
esp sysview_mcore start file://heap_log_mcore.SVDat
|
||||
|
||||
有关详细的命令语法和选项，请参考前文所述的 ``esp sysview`` 命令，因为 ``esp sysview_mcore`` 支持相同的参数。
|
||||
|
||||
|
||||
数据可视化
|
||||
""""""""""
|
||||
|
||||
收集到跟踪数据后，用户可以使用特殊的工具对结果进行可视化并分析程序行为。
|
||||
|
||||
.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES
|
||||
|
||||
**多核跟踪**
|
||||
|
||||
SystemView 3.60 及更高版本支持多核心进行跟踪。对于多核跟踪，使用 ``esp sysview_mcore`` 命令可以生成与 SystemView 多核格式兼容的单个文件：
|
||||
|
||||
::
|
||||
|
||||
esp sysview_mcore start file://heap_log_mcore.SVDat
|
||||
|
||||
此命令将创建一个单独的跟踪文件，可以直接加载到 SystemView 3.60+ 中进行多核可视化。
|
||||
|
||||
**注意：** SystemView 3.60 之前的版本不支持多核跟踪。对于旧版本，当使用 JTAG 接口跟踪双核模式下的 {IDF_TARGET_NAME} 时会生成两个文件：一个用于 PRO CPU，另一个用于 APP CPU。用户可将每个文件载入不同的工具实例。使用 UART 进行跟踪时，在 menuconfig 中选择外部库后，用户可以选择 ``Component config`` > ``SEGGER SystemView Configuration`` 来指定需要跟踪的 CPU（Pro 或 App）。
|
||||
|
||||
对于旧版本的 SystemView，在不同的实例中分别分析每个核的数据可能较为不便。另一个选择是使用名为 *Impulse* 的 Eclipse 插件，该插件可同时加载多个跟踪文件，实现在同一视图中检查来自两个核心的事件。与 SystemView 免费版相比，此插件还不受 100 万事件数量的限制。
|
||||
|
||||
关于如何安装、配置 Impulse 并使用它来可视化来自单个核心的跟踪数据，请参阅 `官方教程 <https://mcuoneclipse.com/2016/07/31/impulse-segger-systemview-in-eclipse/>`_ 。
|
||||
|
||||
.. note::
|
||||
|
||||
ESP-IDF 使用自己的 SystemView FreeRTOS 事件 ID 映射，因此用户需要将 ``$SYSVIEW_INSTALL_DIR/Description/SYSVIEW_FreeRTOS.txt`` 替换成 ``$IDF_PATH/tools/esp_app_trace/SYSVIEW_FreeRTOS.txt``。在使用上述链接配置 SystemView 序列化程序时，也应该使用该特定文件的内容。
|
||||
|
||||
.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES
|
||||
|
||||
配置 Impulse 实现双核跟踪
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
在安装好 Impulse 插件并确保 Impulse 能够在单独的选项卡中成功加载每个核心的跟踪文件后，用户可以添加特殊的 Multi Adapter 端口并将这两个文件加载到一个视图中。为此，用户需要在 Eclipse 中执行以下操作：
|
||||
|
||||
1. 打开 ``Signal Ports`` 视图，前往 ``Windows`` > ``Show View`` > ``Other`` 菜单，在 Impulse 文件夹中找到 ``Signal Ports`` 视图并双击。
|
||||
2. 在 ``Signal Ports`` 视图中，右键 ``Ports`` 并选择 ``Add``，然后选择 ``New Multi Adapter Port``。
|
||||
3. 在打开的对话框中按下 ``add`` 按钮，选择 ``New Pipe/File``。
|
||||
4. 在打开的对话框中选择 ``SystemView Serializer`` 并设置 PRO CPU 跟踪文件的路径，按下 ``OK`` 保存设置。
|
||||
5. 对 APP CPU 的跟踪文件重复步骤 3 和 4。
|
||||
6. 双击创建的端口，会打开此端口的视图。
|
||||
7. 单击 ``Start/Stop Streaming`` 按钮，数据将会被加载。
|
||||
8. 使用 ``Zoom Out``，``Zoom In`` 和 ``Zoom Fit`` 按钮来查看数据。
|
||||
9. 有关设置测量光标和其他的功能，请参阅 `Impulse 官方文档 <https://toem.de/index.php/products/impulse>`_ 。
|
||||
|
||||
.. note::
|
||||
|
||||
如果你在可视化方面遇到了问题（未显示数据或者缩放操作异常），可以尝试删除当前的信号层次结构，再双击必要的文件或端口。Eclipse 会请求创建新的信号层次结构。
|
||||
|
||||
应用示例
|
||||
""""""""
|
||||
--------
|
||||
|
||||
- :example:`system/sysview_tracing` 演示如何使用 SEGGER SystemView 记录 FreeRTOS 任务与系统事件。
|
||||
- :example:`system/sysview_tracing_heap_log` 演示如何在记录 SystemView 事件的同时，对堆内存分配进行跟踪。
|
||||
- :example:`system/app_trace_basic` 演示如何使用应用层跟踪库通过 JTAG 将日志消息记录到主机，作为 UART 日志的更快替代方案。
|
||||
- :example:`system/app_trace_to_plot` 演示如何通过 JTAG 向主机发送并绘制虚拟传感器数据。
|
||||
|
||||
.. _app_trace-gcov-source-code-coverage:
|
||||
API 参考
|
||||
--------
|
||||
|
||||
Gcov（源代码覆盖率）
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
在 ESP-IDF 项目中，可以借助 `espressif/esp_gcov <https://components.espressif.com/components/espressif/esp_gcov>`_ 托管组件使用 gcov 进行代码覆盖率分析。
|
||||
|
||||
.. _app_trace-integrating-a-custom-trace-library:
|
||||
|
||||
集成自定义跟踪库
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
``esp_trace`` 组件提供了稳定的扩展点 (``CONFIG_ESP_TRACE_LIB_EXTERNAL``)，允许在不修改 ESP-IDF 的情况下接入第三方跟踪记录器。外部组件需提供一个编码器适配器（通过 ``ESP_TRACE_REGISTER_ENCODER()`` 注册）以及一个轻量的 ``esp_trace_freertos_impl.h``，用于注入所需的 FreeRTOS 跟踪钩子。编码器虚表还提供可选的 ``start`` / ``stop`` / ``flush`` 及 ``take_lock`` / ``give_lock`` 入口，由公共 API :cpp:func:`esp_trace_start`、:cpp:func:`esp_trace_stop`、:cpp:func:`esp_trace_flush` 调度。
|
||||
|
||||
应用示例
|
||||
""""""""
|
||||
|
||||
- :example:`system/esp_trace` 是一个最简的复制粘贴模板，演示如何接入外部编码器、说明 FreeRTOS 跟踪钩子头文件的包含链约束，以及通过编码器锁实现多核序列化。
|
||||
传输 API 请参阅 :doc:`/api-reference/system/app_trace`。高层 ``esp_trace`` API 请参阅 :doc:`/api-reference/system/esp_trace`。
|
||||
70
docs/zh_CN/api-reference/system/esp_trace.rst
Normal file
70
docs/zh_CN/api-reference/system/esp_trace.rst
Normal file
@@ -0,0 +1,70 @@
|
||||
ESP Trace
|
||||
=========
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
概述
|
||||
----
|
||||
|
||||
``esp_trace`` 组件是 ESP-IDF 跟踪的入口。它提供公共跟踪 API，管理活动跟踪会话，并将所选编码器（如 SEGGER SystemView）与所选传输（如 apptrace）连接起来。
|
||||
|
||||
有关概念概览、架构和使用指南，请参阅 :doc:`/api-guides/tracing/index`。
|
||||
|
||||
应用示例
|
||||
--------
|
||||
|
||||
- :example:`system/esp_trace_custom_library` 演示如何将外部跟踪库（编码器）与 ``esp_trace`` 核心集成。
|
||||
|
||||
API 参考
|
||||
--------
|
||||
|
||||
类型
|
||||
^^^^
|
||||
|
||||
.. doxygentypedef:: esp_trace_handle_t
|
||||
|
||||
.. doxygenstruct:: esp_trace_open_params_t
|
||||
:members:
|
||||
|
||||
.. doxygenstruct:: esp_trace_config
|
||||
:members:
|
||||
|
||||
.. doxygenenum:: esp_trace_link_types_t
|
||||
|
||||
适配器类型
|
||||
^^^^^^^^^^
|
||||
|
||||
.. doxygenstruct:: esp_trace_encoder_vtable_t
|
||||
:members:
|
||||
|
||||
.. doxygenstruct:: esp_trace_encoder
|
||||
:members:
|
||||
|
||||
.. doxygenenum:: esp_trace_transport_cfg_key_t
|
||||
|
||||
.. doxygenstruct:: esp_trace_transport_vtable_t
|
||||
:members:
|
||||
|
||||
.. doxygenstruct:: esp_trace_transport
|
||||
:members:
|
||||
|
||||
函数
|
||||
^^^^
|
||||
|
||||
.. doxygenfunction:: esp_trace_get_user_params
|
||||
|
||||
.. doxygenfunction:: esp_trace_get_active_handle
|
||||
|
||||
.. doxygenfunction:: esp_trace_write
|
||||
|
||||
.. doxygenfunction:: esp_trace_start
|
||||
|
||||
.. doxygenfunction:: esp_trace_stop
|
||||
|
||||
.. doxygenfunction:: esp_trace_flush
|
||||
|
||||
.. doxygenfunction:: esp_trace_is_host_connected
|
||||
|
||||
.. doxygenfunction:: esp_trace_get_link_type
|
||||
|
||||
.. doxygenfunction:: esp_trace_panic_handler
|
||||
@@ -9,6 +9,7 @@
|
||||
app_image_format
|
||||
bootloader_image_format
|
||||
app_trace
|
||||
esp_trace
|
||||
esp_function_with_shared_stack
|
||||
chip_revision
|
||||
console
|
||||
|
||||
@@ -231,7 +231,7 @@ App 追踪
|
||||
初始化流程更改
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
对于运行时配置覆盖，提供了新的回调系统。详细信息请参见 :doc:`应用程序跟踪文档 <../../../api-guides/app_trace>` 中关于 ``esp_apptrace_get_user_params()`` 和 ``esp_trace_get_user_params()`` 的说明。
|
||||
对于运行时配置覆盖，提供了新的回调系统。详细信息请参见 :doc:`应用程序跟踪文档 <../../../api-guides/tracing/transports>` 中关于 ``esp_apptrace_get_user_params()`` 和 ``esp_trace_get_user_params()`` 的说明。
|
||||
|
||||
API 更改
|
||||
^^^^^^^^^^^
|
||||
|
||||
@@ -32,7 +32,7 @@ Open the project configuration menu (`idf.py menuconfig`). Then go into `Example
|
||||
- Select where to save the pcap file in `Select destination to store pcap file` menu item.
|
||||
- `SD Card` means saving packets (pcap format) into the SD card you plug in. The default SD card work mode is set to SDMMC for target ESP32 and ESP32S3, but SPI is the only choice for other targets.
|
||||
- `Memory` means saving packets in memory and can parse packets in place.
|
||||
- `JTAG (App Trace)` means sending packets (pcap format) to host via JTAG interface. This feature depends on [app trace component](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html), Component config -> Application Level Tracing -> Data Destination -> JTAG should be enabled to choose `JTAG (App Trace)` as destination.
|
||||
- `JTAG (App Trace)` means sending packets (pcap format) to host via JTAG interface. This feature depends on [app trace component](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html), Component config -> Application Level Tracing -> Data Destination -> JTAG should be enabled to choose `JTAG (App Trace)` as destination.
|
||||
- Set the mount point in your filesystem in `SD card mount point in the filesystem` menu item. This configuration only takes effect when you choose to save packets into SD card.
|
||||
- Set max name length of pcap file in `Max name length of pcap file` menu item.
|
||||
- Set the length of sniffer work queue in `Length of sniffer work queue` menu item.
|
||||
@@ -303,7 +303,7 @@ I (130566) cmd_pcap: .pcap file close done
|
||||
2. Build & Flash with `idf.py -p PORT flash`
|
||||
3. Connect JTAG, run OpenOCD (for more information about how-to please refer to [JTAG Debugging](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/jtag-debugging/index.html)).
|
||||
4. Telnet to localhost with 4444 port: `telnet localhost 4444`.
|
||||
5. In the telnet session, run command like `esp32 apptrace start file://sniffer-esp32.pcap 1 -1 20` (more information about this command, please refer to [apptrace command](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/app_trace.html#openocd-application-level-tracing-commands)).
|
||||
5. In the telnet session, run command like `esp32 apptrace start file://sniffer-esp32.pcap 1 -1 20` (more information about this command, please refer to [apptrace command](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html#openocd-application-level-tracing-commands)).
|
||||
6. Run the example, start sniffer with `sniffer` command.
|
||||
7. Stop sniffer by entering command `sniffer --stop` in the example console.
|
||||
8. Stop tracing by entering command `esp32 apptrace stop` in the telnet session.
|
||||
|
||||
@@ -68,7 +68,7 @@ examples/system/esp_timer:
|
||||
- *common_components
|
||||
- esp_timer
|
||||
|
||||
examples/system/esp_trace:
|
||||
examples/system/esp_trace_custom_library:
|
||||
disable:
|
||||
- if: SOC_USB_SERIAL_JTAG_SUPPORTED != 1
|
||||
reason: example transport is USB Serial JTAG
|
||||
|
||||
@@ -5,9 +5,9 @@
|
||||
|
||||
(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.
|
||||
This example demonstrates how to use the [Application Level Tracing Library](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.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).
|
||||
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/tracing/transports.html#app-trace-logging-to-host).
|
||||
|
||||
### Hardware Required
|
||||
|
||||
@@ -56,7 +56,7 @@ where OpenOCD was started). Assuming that OpenOCD was started in this example's
|
||||
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)
|
||||
**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/tracing/transports.html#openocd-application-level-tracing-commands)
|
||||
|
||||
(To exit the serial monitor, type ``Ctrl-]``.)
|
||||
|
||||
|
||||
@@ -5,9 +5,9 @@
|
||||
|
||||
(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 send and plot dummy sensor data to a host via JTAG instead of the normal method of logging via UART.
|
||||
This example demonstrates how to use the [Application Level Tracing Library](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/transports.html) (henceforth referred to as **App Trace**) to send and plot dummy sensor data 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).
|
||||
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/tracing/transports.html#app-trace-logging-to-host).
|
||||
|
||||
### Hardware Required
|
||||
|
||||
@@ -65,7 +65,7 @@ idf.py openocd --openocd-commands "-f board/esp32-wrover-kit-3.3v.cfg -c 'init;r
|
||||
|
||||
**Note:** data.json file is an example for plot config file. It can be changed or modified.
|
||||
|
||||
**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)
|
||||
**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/tracing/transports.html#openocd-application-level-tracing-commands)
|
||||
|
||||
(To exit the serial monitor, type ``Ctrl-]``.)
|
||||
|
||||
|
||||
@@ -5,4 +5,4 @@ cmake_minimum_required(VERSION 3.16)
|
||||
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(esp_trace_example)
|
||||
project(esp_trace_custom_library)
|
||||
@@ -52,7 +52,7 @@ You should see the app start up and create a task. Whatever trace bytes your enc
|
||||
## Project Layout
|
||||
|
||||
```
|
||||
esp_trace/
|
||||
esp_trace_custom_library/
|
||||
├── CMakeLists.txt
|
||||
├── sdkconfig.defaults
|
||||
├── main/
|
||||
@@ -147,7 +147,7 @@ The example defaults to USB Serial JTAG. To use a different transport, edit `sdk
|
||||
| Transport | Config | Notes |
|
||||
| --- | --- | --- |
|
||||
| USB Serial JTAG | `CONFIG_ESP_TRACE_TRANSPORT_USB_SERIAL_JTAG=y` | Default. Requires `ESP_CONSOLE_SECONDARY_NONE=y`. |
|
||||
| apptrace over JTAG | `CONFIG_ESP_TRACE_TRANSPORT_APPTRACE=y` + `CONFIG_APPTRACE_DEST_JTAG=y` | Needs OpenOCD on the host to drain the buffer. |
|
||||
| apptrace over JTAG | `CONFIG_ESP_TRACE_TRANSPORT_APPTRACE=y` + `CONFIG_APPTRACE_DEST_JTAG=y` | Needs OpenOCD on the host to read out the buffer. |
|
||||
| apptrace over UART | `CONFIG_ESP_TRACE_TRANSPORT_APPTRACE=y` + `CONFIG_APPTRACE_DEST_UART=y` | Pick a UART different from the console. |
|
||||
| External transport | `CONFIG_ESP_TRACE_TRANSPORT_EXTERNAL=y` | Another component must register a transport with `ESP_TRACE_REGISTER_TRANSPORT(...)`. |
|
||||
| None | `CONFIG_ESP_TRACE_TRANSPORT_NONE=y` | Useful if your library streams data over its own channel and just needs the FreeRTOS hooks. |
|
||||
@@ -183,7 +183,7 @@ Because the transport is USB-Serial-JTAG and the console is on UART (`CONFIG_ESP
|
||||
esp_trace_start(); // resume emission (also resets the delta baseline)
|
||||
// ... do stuff ...
|
||||
esp_trace_stop(); // pause emission
|
||||
esp_trace_flush(); // drain transport buffers
|
||||
esp_trace_flush(); // flush transport buffers
|
||||
```
|
||||
|
||||
In this example the library boots with `s_enabled = false`, so nothing is emitted until `app_main()` calls `esp_trace_start()`. The trailing pair `esp_trace_flush(); esp_trace_stop();` makes sure the last events reach the host before the trace channel goes silent. Adapter wiring lives in [`adapter_encoder_ext_trace_lib.c`](components/ext_trace_lib/src/adapter_encoder_ext_trace_lib.c) (`start` / `stop` / `flush` callbacks); flush forwards to the transport's `flush_nolock`.
|
||||
@@ -86,7 +86,7 @@ def _capture_trace(ser: serial.Serial, trace_log_path: str, capture_s: float = 5
|
||||
except serial.SerialTimeoutException:
|
||||
assert False, 'Timeout reached while reading from serial port, exiting...'
|
||||
|
||||
# Drain anything still in flight after the capture window.
|
||||
# Read out anything still in flight after the capture window.
|
||||
time.sleep(0.2)
|
||||
end_time = time.time() + 1.0
|
||||
last_data_time = time.time()
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
This test code shows how to perform system-wide behavioral analysis of the program using [SEGGER SystemView tool](https://www.segger.com/products/development-tools/systemview/).
|
||||
|
||||
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.
|
||||
For description of [SystemView tracing](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/sysview.html) please refer to **ESP32 Programming Guide**, section **Application Level Tracing library**. The following example provides practical implementation of this functionality.
|
||||
|
||||
|
||||
## Use Case
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
|
||||
# SystemView Heap and Log Tracing Example
|
||||
|
||||
Heap memory leaking is quite widespread software bug. IDF provides [heap tracing feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/heap_debug.html#heap-tracing) which allows to collect information related to heap operations (allocations/deallocations) and detect potential memory leaks. This feature can be used in two modes: standalone and host-based. In standalone mode collected data are kept on-board, so this mode is limited by available memory in the system. Host-based mode does not have such limitation because collected data are sent to the host and can be analysed there using special tools. One of such tool is SEGGER SystemView. For description of [SystemView tracing feature](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**. SystemView is also can be useful to show log message sent from the target.
|
||||
Heap memory leaking is quite widespread software bug. IDF provides [heap tracing feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/heap_debug.html#heap-tracing) which allows to collect information related to heap operations (allocations/deallocations) and detect potential memory leaks. This feature can be used in two modes: standalone and host-based. In standalone mode collected data are kept on-board, so this mode is limited by available memory in the system. Host-based mode does not have such limitation because collected data are sent to the host and can be analysed there using special tools. One of such tool is SEGGER SystemView. For description of [SystemView tracing feature](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/tracing/sysview.html) please refer to **ESP32 Programming Guide**, section **Application Level Tracing library**. SystemView is also can be useful to show log message sent from the target.
|
||||
This example shows how to use this tool and IDF's scripts for host-based heap and log tracing analysis.
|
||||
|
||||
Consider the following situation. User program have two tasks. One task allocates memory and puts obtained addresses into the queue. Another task waits on that queue, reads sent pointers and frees memory. The first task queues only part of the pointers so some of the allocated blocks are not freed and become leaked. Both tasks uses IDF's logging API to report their actions. This example uses IDF's heap tracing module to record allocations and deallocations to detect memory leaks. Both heap tracing records and log messages are redirected to the host.
|
||||
|
||||
Reference in New Issue
Block a user