From f6bbbf90c6cb36eb0cf6a43110fc8c43a79d27c9 Mon Sep 17 00:00:00 2001 From: Zhang Shuxian Date: Thu, 23 Jul 2026 10:34:28 +0800 Subject: [PATCH] docs: Update CN translation for tracing (cherry picked from commit 35deba1bd7687923f60db045de329f5bcb16443d) --- docs/en/api-guides/tracing/architecture.rst | 2 +- docs/en/api-guides/tracing/index.rst | 2 +- docs/en/api-guides/tracing/sysview.rst | 4 +- docs/en/api-guides/tracing/transports.rst | 18 ++++----- .../zh_CN/api-guides/tracing/architecture.rst | 20 +++++----- .../tracing/custom-trace-library.rst | 6 +-- docs/zh_CN/api-guides/tracing/index.rst | 4 +- docs/zh_CN/api-guides/tracing/sysview.rst | 10 ++--- docs/zh_CN/api-guides/tracing/transports.rst | 40 +++++++++---------- 9 files changed, 53 insertions(+), 53 deletions(-) diff --git a/docs/en/api-guides/tracing/architecture.rst b/docs/en/api-guides/tracing/architecture.rst index f86e98230a6..7daf83803cd 100644 --- a/docs/en/api-guides/tracing/architecture.rst +++ b/docs/en/api-guides/tracing/architecture.rst @@ -69,7 +69,7 @@ Transport Port The transport port interface (:component_file:`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. +Each trace session pairs one encoder with one transport. The encoder can pass encoded trace data to the transport selected for the session, and runtime trace writes do not allocate memory. Initialization -------------- diff --git a/docs/en/api-guides/tracing/index.rst b/docs/en/api-guides/tracing/index.rst index ef9541dde2d..3fb2d9ae31e 100644 --- a/docs/en/api-guides/tracing/index.rst +++ b/docs/en/api-guides/tracing/index.rst @@ -45,7 +45,7 @@ The trace format and the transport are selected independently. Pick the host lin .. 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 JTAG**: Highest throughput and host-initiated control (start, stop, or 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. diff --git a/docs/en/api-guides/tracing/sysview.rst b/docs/en/api-guides/tracing/sysview.rst index 701998b2c27..d579c7a85de 100644 --- a/docs/en/api-guides/tracing/sysview.rst +++ b/docs/en/api-guides/tracing/sysview.rst @@ -94,7 +94,7 @@ For detailed command syntax and options, refer to the ``esp sysview`` command ab Data Visualization ------------------ -After trace data are collected, users can use a special tool to visualize the results and inspect behavior of the program. +After trace data are collected, use a special tool to visualize the results and inspect behavior of the program. .. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES @@ -114,7 +114,7 @@ Good instructions on how to install, configure, and visualize data in Impulse fr .. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES - Configure Impulse for Dual Core Traces + 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: diff --git a/docs/en/api-guides/tracing/transports.rst b/docs/en/api-guides/tracing/transports.rst index 935dad312cc..c30eac780fc 100644 --- a/docs/en/api-guides/tracing/transports.rst +++ b/docs/en/api-guides/tracing/transports.rst @@ -35,7 +35,7 @@ The library supports two modes of operation: **Post-mortem mode:** This is the default mode. The mode does not need interaction with the host side. In this mode, tracing module does not check whether the host has read all the data from *HW UP BUFFER*, but directly overwrites old data with the new ones. This mode is useful when only the latest trace data is interesting to the user, e.g., for analyzing program's behavior just before the crash. The host can read the data later on upon user request, e.g., via special OpenOCD command in case of working via JTAG interface. -**Streaming mode:** Tracing module enters this mode when the host connects to {IDF_TARGET_NAME}. In this mode, before writing new data to *HW UP BUFFER*, the tracing module checks that whether there is enough space in it and if necessary, waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to the trace buffer using the finite value of the maximum waiting time, it is possible that this data will be dropped. This is especially true for tracing from time critical code (ISRs, OS scheduler code, etc.) where infinite timeouts can lead to system malfunction. +**Streaming mode:** Tracing module enters this mode when the host connects to {IDF_TARGET_NAME}. In this mode, before writing new data to *HW UP BUFFER*, the tracing module checks that whether there is enough space in it and if necessary, waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to the trace buffer using the finite value of the maximum waiting time, it is possible that this data will be dropped. This is especially true for tracing from time-critical code (ISRs, OS scheduler code, etc.) where infinite timeouts can lead to system malfunction. Configuration Options and Dependencies @@ -53,7 +53,7 @@ Using of this feature depends on two components: There are some additional menuconfig options not mentioned above: -1. *Threshold for flushing last trace data to host on panic* (:ref:`CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH`). This option is necessary due to the nature of working over JTAG. In this mode, trace data is exposed to the host in 16 KB blocks. In post-mortem mode, when one block is filled, it is exposed to the host and the previous one becomes unavailable. In other words, the trace data is overwritten in 16 KB granularity. On panic, the latest data from the current input block is exposed to the host and the host can read them for post-analysis. System panic may occur when a very small amount of data are not exposed to the host yet. In this case, the previous 16 KB of collected data will be lost and the host will see the latest, but very small piece of the trace. It can be insufficient to diagnose the problem. This menuconfig option allows avoiding such situations. It controls the threshold for flushing data in case of apanic. For example, users can decide that it needs no less than 512 bytes of the recent trace data, so if there is less then 512 bytes of pending data at the moment of panic, they will not be flushed and will not overwrite the previous 16 KB. The option is only meaningful in post-mortem mode and when working over JTAG. +1. *Threshold for flushing last trace data to host on panic* (:ref:`CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH`). This option is necessary due to the nature of working over JTAG. In this mode, trace data is exposed to the host in 16 KB blocks. In post-mortem mode, when one block is filled, it is exposed to the host and the previous one becomes unavailable. In other words, the trace data is overwritten in 16 KB granularity. On panic, the latest data from the current input block is exposed to the host and the host can read them for post-analysis. System panic may occur when a very small amount of data are not exposed to the host yet. In this case, the previous 16 KB of collected data will be lost and the host will see the latest, but very small piece of the trace. It can be insufficient to diagnose the problem. This menuconfig option allows avoiding such situations. It controls the threshold for flushing data in case of apanic. For example, you can decide that it needs no less than 512 bytes of the recent trace data, so if there is less than 512 bytes of pending data at the moment of panic, they will not be flushed and will not overwrite the previous 16 KB. The option is only meaningful in post-mortem mode and when working over JTAG. 2. *Timeout for flushing last trace data to host on panic* (:ref:`CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO`). The option is only meaningful in streaming mode and it controls the maximum time that the tracing module will wait for the host to read the last data in case of panic. @@ -67,7 +67,7 @@ There are some additional menuconfig options not mentioned above: How to Use This Library ----------------------- -This library provides APIs for transferring arbitrary data between the host and {IDF_TARGET_NAME}. When enabled in menuconfig, the application tracing module is automatically initialized during system startup using configuration from menuconfig. Users can then call corresponding APIs to send, receive, or flush the data. +This library provides APIs for transferring arbitrary data between the host and {IDF_TARGET_NAME}. When enabled in menuconfig, the application tracing module is automatically initialized during system startup using configuration from menuconfig. You can then call corresponding APIs to send, receive, or flush the data. Optionally, users can override the default configuration by implementing the weak callback function :cpp:func:`esp_apptrace_get_user_params()`. This callback will be active when there is no selected trace library, meaning the Application Level Tracing library (``app_trace`` component) will be working standalone. Otherwise, :cpp:func:`esp_trace_get_user_params()` will be used for overriding the configuration. @@ -110,7 +110,7 @@ Quick Start Summary Application Specific Tracing ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In general, users should decide what type of data should be transferred in every direction and how these data must be interpreted (processed). The following steps must be performed to transfer data between the target and the host: +In general, you should decide what type of data should be transferred in every direction and how these data must be interpreted (processed). The following steps must be performed to transfer data between the target and the host: 1. **Configuration:** Application tracing is automatically initialized during system startup using configuration from menuconfig. If you need to override the default configuration at runtime (e.g., to use custom UART pins), implement the :cpp:func:`esp_apptrace_get_user_params()` callback: @@ -167,7 +167,7 @@ In general, users should decide what type of data should be transferred in every return res; } - Also according to his needs, the user may want to receive data from the host. Piece of code below shows an example on how to do this. + If you need to receive data from the host. Piece of code below shows an example on how to do this. .. code-block:: c @@ -264,7 +264,7 @@ Sub-commands: ``status`` Get tracing status. ``dump`` - Dump all data from (post-mortem dump). + Dump all data from (post-mortem dump). Start command syntax: @@ -344,7 +344,7 @@ By default, ESP-IDF's logging library uses vprintf-like function to write format Though the implementation of the vprintf-like function can be optimized to a certain level, all steps above have to be performed in any case and every step takes some time (especially item 3). So it frequently occurs that with additional log added to the program to identify the problem, the program behavior is changed and the problem cannot be reproduced. And in the worst cases, the program cannot work normally at all and ends up with an error or even hangs. -Possible ways to overcome this problem are to use higher UART bitrates (or another faster interface) and/or to move string formatting procedure to the host. +Possible ways to overcome this problem are to use higher UART bitrates (or another faster interface) and to move string formatting procedure to the host. The application level tracing feature can be used to transfer log information to the host using ``esp_apptrace_vprintf`` function. This function does not perform full parsing of the format string and arguments. Instead, it just calculates the number of arguments passed and sends them along with the format string address to the host. On the host, log data is processed and printed out by a special Python script. @@ -360,10 +360,10 @@ Current implementation of logging over JTAG has some limitations: 4. The maximum number of printf arguments is 256. -How To Use It +How to Use It """"""""""""" -In order to use logging via trace module, users need to perform the following steps: +In order to use logging via trace module, you need to perform the following steps: 1. Enable application tracing in menuconfig 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``. 2. On the target side, the special vprintf-like function :cpp:func:`esp_apptrace_vprintf` needs to be installed. It sends log data to the host. An example is ``esp_log_set_vprintf(esp_apptrace_vprintf);``. To send log data to UART again, use ``esp_log_set_vprintf(vprintf);``. diff --git a/docs/zh_CN/api-guides/tracing/architecture.rst b/docs/zh_CN/api-guides/tracing/architecture.rst index b2c2eecfc45..6252d139f51 100644 --- a/docs/zh_CN/api-guides/tracing/architecture.rst +++ b/docs/zh_CN/api-guides/tracing/architecture.rst @@ -8,18 +8,18 @@ 概述 ---- -应用程序可以使用 ``esp_trace`` 从目标设备收集运行时信息，并发送到主机工具进行分析。这支持多种场景，例如使用 SEGGER SystemView 分析 FreeRTOS 任务和中断、使用 Gcov 获取源代码覆盖率，以及通过 apptrace 收集应用程序自定义数据。 +应用程序使用 ``esp_trace`` 从目标设备收集运行时信息，并将其发送到主机工具进行分析。这支持多种场景，例如使用 SEGGER SystemView 分析 FreeRTOS 任务和中断、使用 Gcov 获取源代码覆盖率，以及通过 apptrace 收集应用程序自定义数据。 -ESP-IDF 提供常用的跟踪格式和传输方式，同一框架也可以扩展到新的格式或传输，例如自定义跟踪格式、SPI 传输或 UDP 传输。 +ESP-IDF 提供通用的跟踪格式和传输方式，并且可以在同一框架下扩展新的跟踪格式和传输方式，例如自定义跟踪格式、SPI 传输或 UDP 传输。 -ESP-IDF 跟踪系统采用 **端口与适配器（Port & Adapter）** 设计。应用程序调用公共的 ``esp_trace`` API，跟踪核心则将所选编码器与所选传输连接起来。 +ESP-IDF 跟踪系统采用 **Port & Adapter（端口与适配器）** 设计。应用程序调用公共的 ``esp_trace`` API，跟踪核心则将所选编码器与所选传输连接起来。 -该设计提供： +该设计具有以下优势： -- 稳定的应用程序侧 API。 -- 跟踪格式和主机链路的独立选择。 -- 适配器相关细节不进入核心跟踪代码。 -- 由跟踪系统负责启动和 Panic 处理。 +- 提供稳定的面向应用程序的 API。 +- 可独立选择跟踪格式和主机链路。 +- 将适配器相关实现细节与核心跟踪代码隔离。 +- 由跟踪系统统一负责启动和 Panic 处理。 .. mermaid:: @@ -39,7 +39,7 @@ ESP-IDF 跟踪系统采用 **端口与适配器（Port & Adapter）** 设计。 subgraph ADAPTERS["适配器"] direction LR encoder["编码器适配器
外部组件，例如 espressif/esp_sysview
格式化记录器事件"] - transport["传输适配器
esp_trace 组件
JTAG/UART 上的 apptrace、USB Serial JTAG"] + transport["传输适配器
esp_trace 组件
JTAG 或 UART 上的 apptrace、USB Serial JTAG"] end app --> api --> core @@ -67,7 +67,7 @@ ESP-IDF 跟踪系统采用 **端口与适配器（Port & Adapter）** 设计。 传输端口 ^^^^^^^^ -传输端口接口（:component_file:`esp_trace_port_transport.h `）定义编码后的跟踪数据如何离开目标设备。传输负责将字节写入面向主机的链路，并处理链路相关操作，例如刷新、主机连接检查和 Panic 时输出。``esp_trace`` 提供内置的 apptrace（JTAG/UART）和 USB Serial JTAG 传输适配器。参见 :doc:`transports`。 +传输端口接口（:component_file:`esp_trace_port_transport.h `）定义编码后的跟踪数据如何离开目标设备。传输负责将字节写入面向主机的链路，并处理链路相关操作，例如刷新、主机连接检查和 Panic 时输出。``esp_trace`` 提供内置的 apptrace（JTAG 或 UART）和 USB Serial JTAG 传输适配器。参见 :doc:`transports`。 每个跟踪会话都将一个编码器与一个传输配对。编码器可以将编码后的跟踪数据交给当前会话选择的传输，且跟踪写入期间不进行动态分配。 diff --git a/docs/zh_CN/api-guides/tracing/custom-trace-library.rst b/docs/zh_CN/api-guides/tracing/custom-trace-library.rst index 03ab87ae2c2..993893578cc 100644 --- a/docs/zh_CN/api-guides/tracing/custom-trace-library.rst +++ b/docs/zh_CN/api-guides/tracing/custom-trace-library.rst @@ -12,7 +12,7 @@ - 一个 **编码器适配器**，通过 ``ESP_TRACE_REGISTER_ENCODER()`` 注册，用于将跟踪数据格式化为该记录器的协议。 - 一个 ``esp_trace_freertos_impl.h`` 头文件，用于定义记录器所需的 FreeRTOS 跟踪钩子。 -编码器独立于主机链路。它可以使用任何已注册的 :doc:`传输 `，例如 JTAG/UART 上的 apptrace、USB Serial JTAG 或自定义传输。 +编码器独立于主机链路。它可以使用任何已注册的 :doc:`传输 `，例如 JTAG 或 UART 上的 apptrace、USB Serial JTAG 或自定义传输。 编码器端口 ---------- @@ -57,14 +57,14 @@ - 流缓冲区和消息缓冲区 API - 可能获取内部互斥量的堆分配 -在运行时回调中，应使用无锁或仅自旋锁的原语（``esp_trace_lock_*``、``esp_trace_rb_*``）、底层寄存器访问、原子操作以及 ``esp_rom_*`` 辅助函数。较重的工作（例如 FreeRTOS API 调用或内存分配）只应在 ``init()`` 中、跟踪开始前完成。 +在运行时回调中，应使用无锁或仅自旋锁的原语（``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 `。 +为捕获 FreeRTOS 事件，外部组件需提供 ``esp_trace_freertos_impl.h`` 头文件，其中定义所需的跟踪宏（``traceTASK_SWITCHED_IN()``、``traceISR_ENTER()`` 等）。启用 :ref:`CONFIG_ESP_TRACE_LIB_EXTERNAL ` 时，``esp_trace`` 会包含该头文件。 应用示例 -------- diff --git a/docs/zh_CN/api-guides/tracing/index.rst b/docs/zh_CN/api-guides/tracing/index.rst index 3fd2b75d337..e7b9487e775 100644 --- a/docs/zh_CN/api-guides/tracing/index.rst +++ b/docs/zh_CN/api-guides/tracing/index.rst @@ -6,7 +6,7 @@ ESP 跟踪 概述 ---- -ESP-IDF 提供了一套跟踪系统，用于程序行为分析和调试。它允许用户以较小开销从 {IDF_TARGET_NAME} 收集运行时数据，并将数据发送到主机。 +ESP-IDF 提供了一套跟踪系统，用于程序行为分析和调试。以较小开销从 {IDF_TARGET_NAME} 收集运行时数据，并将数据发送到主机。 该系统以 **esp_trace** 组件为中心。它提供公共跟踪 API，管理活动跟踪会话，并将跟踪编码器与跟踪传输连接起来。SEGGER SystemView、Gcov 和 apptrace 传输等跟踪功能都接入这一模型。 @@ -45,7 +45,7 @@ ESP-IDF 提供了一套跟踪系统，用于程序行为分析和调试。它允 .. list:: - - **apptrace（JTAG）**：吞吐量最高，并支持由主机发起的控制（start / stop / dump）。需要 JTAG 适配器以及主机上运行的 OpenOCD。适用于 SystemView 以及按需的 Gcov 转储。 + - **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 未被控制台占用时可用。 diff --git a/docs/zh_CN/api-guides/tracing/sysview.rst b/docs/zh_CN/api-guides/tracing/sysview.rst index d3679812f4b..73980d86ba0 100644 --- a/docs/zh_CN/api-guides/tracing/sysview.rst +++ b/docs/zh_CN/api-guides/tracing/sysview.rst @@ -23,7 +23,7 @@ SystemView 功能由托管组件 ``espressif/esp_sysview`` 提供。完成以下 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。 +之后，可通过 ``Component config`` > ``SEGGER SystemView Configuration`` 配置 SystemView。该菜单可用于选择时间戳源 (:ref:`CONFIG_ESP_TRACE_TIMESTAMP_SOURCE`)、单独启用或禁用 SystemView 事件收集 (``CONFIG_SEGGER_SYSVIEW_EVT_XXX``)，以及在使用 UART 目标时选择要跟踪的 CPU。 .. note:: @@ -94,7 +94,7 @@ Start 子命令语法： 数据可视化 ---------- -收集到跟踪数据后，用户可以使用特殊的工具对结果进行可视化并分析程序行为。 +收集到跟踪数据后，可以使用特殊的工具对结果进行可视化并分析程序行为。 .. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES @@ -106,7 +106,7 @@ Start 子命令语法： 对于旧版本的 SystemView，在不同的实例中分别分析每个核的数据可能较为不便。另一个选择是使用名为 *Impulse* 的 Eclipse 插件，该插件可同时加载多个跟踪文件，实现在同一视图中检查来自两个核心的事件。与 SystemView 免费版相比，此插件还不受 100 万事件数量的限制。 -关于如何安装、配置 Impulse 并使用它来可视化来自单个核心的跟踪数据，请参阅 `官方教程 `_ 。 +关于如何安装、配置 Impulse 并使用它来可视化来自单个核心的跟踪数据，请参阅 `官方教程 `_。 .. note:: @@ -121,13 +121,13 @@ Start 子命令语法： 1. 打开 ``Signal Ports`` 视图，前往 ``Windows`` > ``Show View`` > ``Other`` 菜单，在 Impulse 文件夹中找到 ``Signal Ports`` 视图并双击。 2. 在 ``Signal Ports`` 视图中，右键 ``Ports`` 并选择 ``Add``，然后选择 ``New Multi Adapter Port``。 - 3. 在打开的对话框中按下 ``add`` 按钮，选择 ``New Pipe/File``。 + 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 官方文档 `_ 。 + 9. 有关设置测量光标和其他的功能，请参阅 `Impulse 官方文档 `_。 .. note:: diff --git a/docs/zh_CN/api-guides/tracing/transports.rst b/docs/zh_CN/api-guides/tracing/transports.rst index 076ec3e4478..b8818e72706 100644 --- a/docs/zh_CN/api-guides/tracing/transports.rst +++ b/docs/zh_CN/api-guides/tracing/transports.rst @@ -3,11 +3,11 @@ :link_to_translation:`en:[English]` -**应用层跟踪** 库（``app_trace`` 组件）是 :doc:`esp_trace ` 跟踪系统默认使用的传输方式。它允许用户在程序运行开销很小的前提下，通过 JTAG 或 UART 接口在主机和 {IDF_TARGET_NAME} 之间传输任意数据。用户也可同时使用 JTAG 和 UART 接口。UART 接口主要用于连接 SEGGER SystemView 工具（参见 :doc:`sysview`）。基于 USB Serial JTAG 外设的跟踪由一个独立的传输提供，而非 apptrace。 +**应用层跟踪** 库（``app_trace`` 组件）是 :doc:`esp_trace ` 跟踪系统默认使用的传输方式。可在程序运行开销很小的前提下，通过 JTAG 或 UART 接口在主机和 {IDF_TARGET_NAME} 之间传输任意数据。也可同时使用 JTAG 和 UART 接口。UART 接口主要用于连接 SEGGER SystemView 工具（参见 :doc:`sysview`）。基于 USB Serial JTAG 外设的跟踪由一个独立的传输提供，而非 apptrace。 -本页介绍该传输本身：如何配置它、如何通过它发送和接收任意应用程序数据，以及用于在主机端收集数据的 OpenOCD 命令。基于该传输构建的高级功能在其他页面中单独介绍： +本页介绍该传输方式本身，包括如何对其进行配置、如何通过其发送和接收任意应用程序数据，以及主机端用于收集数据的 OpenOCD 命令。基于该传输方式构建的更高级功能将在其他文档中介绍： -- 基于 SEGGER SystemView 的系统行为分析：参见 :doc:`sysview`。 +- 使用 SEGGER SystemView 进行系统行为分析：参见 :doc:`sysview`。 - 使用 Gcov 获取源代码覆盖率：参见 :doc:`gcov`。 - 接入你自己的跟踪记录器：参见 :doc:`custom-trace-library`。 @@ -53,7 +53,7 @@ 以下为前述未提及的另外几个 menuconfig 选项： -1. *Threshold for flushing last trace data to host on panic* (:ref:`CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH`)。使用 JTAG 接口时，此选项是必选项。在该模式下，跟踪数据以 16 KB 数据块的形式暴露给主机。在后验模式中，一个块被填充后会被暴露给主机，同时之前的块不再可用。也就是说，跟踪数据以 16 KB 的粒度进行覆盖。发生 Panic 时，当前输入块的最新数据将会被暴露给主机，主机可以读取数据以进行后续分析。如果系统发生 Panic 时，仍有少量数据还没来得及暴露给主机，那么之前收集的 16 KB 数据将丢失，主机只能获取少部分的最新跟踪数据，从而可能无法诊断问题。此 menuconfig 选项有助于避免此类情况，它可以控制发生 Panic 时刷新数据的阈值。例如，用户可以设置需要不少于 512 字节的最新跟踪数据，如果在发生 Panic 时待处理的数据少于 512 字节，则数据不会被刷新，也不会覆盖之前的 16 KB 数据。该选项仅在后验模式和使用 JTAG 工作时可发挥作用。 +1. *Threshold for flushing last trace data to host on panic* (:ref:`CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH`)。使用 JTAG 接口时，此选项是必选项。在该模式下，跟踪数据以 16 KB 数据块的形式暴露给主机。在后验模式中，一个块被填充后会被暴露给主机，同时之前的块不再可用。也就是说，跟踪数据以 16 KB 的粒度进行覆盖。发生 Panic 时，当前输入块的最新数据将会被暴露给主机，主机可以读取数据以进行后续分析。如果系统发生 Panic 时，仍有少量数据还没来得及暴露给主机，那么之前收集的 16 KB 数据将丢失，主机只能获取少部分的最新跟踪数据，从而可能无法诊断问题。此 menuconfig 选项有助于避免此类情况，它可以控制发生 Panic 时刷新数据的阈值。例如，可以设置需要不少于 512 字节的最新跟踪数据，如果在发生 Panic 时待处理的数据少于 512 字节，则数据不会被刷新，也不会覆盖之前的 16 KB 数据。该选项仅在后验模式和使用 JTAG 工作时可发挥作用。 2. *Timeout for flushing last trace data to host on panic* (:ref:`CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO`)。该选项仅在流模式下才可发挥作用，它可用于控制跟踪模块在发生 Panic 时等待主机读取最新数据的最长时间。 @@ -67,7 +67,7 @@ 如何使用此库 -------------- -该库提供了用于在主机和 {IDF_TARGET_NAME} 之间传输任意数据的 API。在 menuconfig 中启用该库后，应用程序跟踪模块会在系统启动期间使用 menuconfig 配置自动初始化。随后用户可以调用相应的 API 来发送、接收或者刷新数据。 +该库提供了用于在主机和 {IDF_TARGET_NAME} 之间传输任意数据的 API。在 menuconfig 中启用该库后，应用程序跟踪模块会在系统启动期间使用 menuconfig 配置自动初始化。随后可以调用相应的 API 来发送、接收或者刷新数据。 用户可选择通过实现弱回调函数 :cpp:func:`esp_apptrace_get_user_params()` 来覆盖默认配置。该函数仅在未选择任何跟踪库时生效，此时，仅应用层跟踪库（``app_trace`` 组件）独立运行。否则，系统将调用 :cpp:func:`esp_trace_get_user_params()` 来覆盖默认配置。 @@ -110,7 +110,7 @@ 特定应用程序的跟踪 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -通常，用户需要决定在每个方向上待传输数据的类型以及如何解析（处理）这些数据。要想在目标和主机之间传输数据，则需执行以下几个步骤： +通常，需要决定在每个方向上待传输数据的类型以及如何解析（处理）这些数据。要想在目标和主机之间传输数据，则需执行以下几个步骤： 1. **配置：** 应用程序跟踪会在系统启动期间使用 menuconfig 配置自动初始化。如需在运行时覆盖默认配置（例如使用自定义的 UART 引脚），可实现 :cpp:func:`esp_apptrace_get_user_params()` 回调函数： @@ -154,20 +154,20 @@ #include "esp_app_trace.h" ... int number = 10; - char *ptr = (char *)esp_apptrace_buffer_get(32, 100/*tmo in us*/); + char *ptr = (char *)esp_apptrace_buffer_get(32, 100/*超时，单位：微秒*/); if (ptr == NULL) { ESP_LOGE(TAG, "Failed to get buffer!"); return ESP_FAIL; } sprintf(ptr, "Here is the number %d", number); - esp_err_t res = esp_apptrace_buffer_put(ptr, 100/*tmo in us*/); + esp_err_t res = esp_apptrace_buffer_put(ptr, 100/*超时，单位：微秒*/); if (res != ESP_OK) { - /* in case of error host tracing tool (e.g. OpenOCD) will report incomplete user buffer */ + /* 如果发生错误，主机端跟踪工具（如 OpenOCD）会报告用户缓冲区未完整传输 */ ESP_LOGE(TAG, "Failed to put buffer!"); return res; } - 另外，根据实际项目的需要，用户可能希望从主机接收数据。下面的代码片段展示了如何执行此操作。 + 如需要从主机接收数据，下面的代码片段展示了如何实现此功能。 .. code-block:: c @@ -177,20 +177,20 @@ char down_buf[32]; size_t sz = sizeof(buf); - /* config down buffer */ + /* 配置下行缓冲区 */ esp_err_t res = esp_apptrace_down_buffer_config(down_buf, sizeof(down_buf)); if (res != ESP_OK) { ESP_LOGE(TAG, "Failed to config down buffer!"); return res; } - /* check for incoming data and read them if any */ - res = esp_apptrace_read(buf, &sz, 0/*do not wait*/); + /* 检查是否有传入数据；若有则读取 */ + res = esp_apptrace_read(buf, &sz, 0/*不等待*/); if (res != ESP_OK) { ESP_LOGE(TAG, "Failed to read data from host!"); return res; } if (sz > 0) { - /* we have data, process them */ + /* 已收到数据，进行处理 */ ... } @@ -204,13 +204,13 @@ uint32_t *number; size_t sz = 32; - /* config down buffer */ + /* 配置下行缓冲区 */ esp_err_t res = esp_apptrace_down_buffer_config(down_buf, sizeof(down_buf)); if (res != ESP_OK) { ESP_LOGE(TAG, "Failed to config down buffer!"); return res; } - char *ptr = (char *)esp_apptrace_down_buffer_get(&sz, 100/*tmo in us*/); + char *ptr = (char *)esp_apptrace_down_buffer_get(&sz, 100/*超时，单位：微秒*/); if (ptr == NULL) { ESP_LOGE(TAG, "Failed to get buffer!"); return ESP_FAIL; @@ -221,9 +221,9 @@ } else { printf("No data"); } - res = esp_apptrace_down_buffer_put(ptr, 100/*tmo in us*/); + res = esp_apptrace_down_buffer_put(ptr, 100/*超时，单位：微秒*/); if (res != ESP_OK) { - /* in case of error host tracing tool (e.g. OpenOCD) will report incomplete user buffer */ + /* 如果发生错误，主机端跟踪工具（如 OpenOCD）会报告用户缓冲区未完整传输 */ ESP_LOGE(TAG, "Failed to put buffer!"); return res; } @@ -234,7 +234,7 @@ 5. 连接到 OpenOCD 的 telnet 服务器。用户可在终端执行命令 ``telnet 4444``。如果用户是在运行 OpenOCD 的同一台机器上打开 telnet 会话，可以使用 ``localhost`` 替换上面命令中的 ````。 -6. 使用特殊的 OpenOCD 命令开始收集待跟踪的命令。此命令将传输跟踪数据并将其重定向到指定的文件或套接字。相关命令的说明，请参阅 `OpenOCD 应用程序跟踪命令`_。 +6. 使用特殊的 OpenOCD 命令开始收集跟踪数据。此命令将传输跟踪数据并将其重定向到指定的文件或套接字。相关命令的说明，请参阅 `OpenOCD 应用程序跟踪命令`_。 7. 最后，处理接收到的数据。由于数据格式由用户自己定义，本文档中省略数据处理的具体流程。数据处理的范例可以参考位于 ``$IDF_PATH/tools/esp_app_trace`` 下的 Python 脚本 ``sysviewtrace_proc.py`` （用于功能测试）和 ``logtrace_proc.py`` （请参阅 :ref:`app_trace-logging-to-host` 章节中的详细信息）。 @@ -363,7 +363,7 @@ ESP-IDF 的日志库会默认使用类 vprintf 的函数将格式化的字符串 如何使用 """""""" -为了使用跟踪模块来记录日志，用户需要执行以下步骤： +为了使用跟踪模块来记录日志，需要执行以下步骤： 1. 在 menuconfig 中开启应用程序跟踪功能。须首先通过 ``Component config`` > ``ESP Trace Configuration`` > ``Trace transport`` 并选择 ``ESP-IDF apptrace`` 启用应用程序跟踪。之后，可以在 ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing`` 中进行详细配置。 2. 在目标端，需要安装特殊的类 vprintf 函数 :cpp:func:`esp_apptrace_vprintf`，该函数负责将日志数据发送给主机，使用方法为 ``esp_log_set_vprintf(esp_apptrace_vprintf);``。如需将日志数据再次重定向给 UART，请使用 ``esp_log_set_vprintf(vprintf);``。