mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-01 18:50:34 +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
@@ -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
|
||||
^^^^^
|
||||
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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`.
|
||||
Reference in New Issue
Block a user