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)
2026-10-02 11:10:54 +03:00 · 2026-08-31 15:02:14 +02:00
parent 5e8921d589
commit 70e16c4331
46 changed files with 1160 additions and 441 deletions
@@ -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` 可以在几乎不影响代码执行的情况下测量其执行速度。

 任务
 ^^^^^^^
@@ -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 参考
@@ -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 跟踪钩子头文件的包含链，以及通过编码器锁实现多核序列化。
@@ -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 收集覆盖率数据。
@@ -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`：外部跟踪库集成模板
@@ -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`。
@@ -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 更改
 ^^^^^^^^^^^