docs: Sync CN and EN docs

docs/en/api-guides/bootloader.rst

@@ -202,8 +202,8 @@ If the bootloader grows too large then it can collide with the partition table,
 
     The recovery bootloader feature enables safe OTA updates of the bootloader itself. When the eFuse field ``ESP_EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR`` is set, it specifies the flash address (in sectors) of the recovery bootloader. If the primary bootloader at {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} fails to load, the ROM bootloader attempts to load the recovery bootloader from this address.
 
-    - The eFuse can be programmed using ``espefuse.py`` or via the user application using :cpp:func:`esp_efuse_set_recovery_bootloader_offset()`.
+    - The eFuse can be set using ``espefuse.py`` or by calling :cpp:func:`esp_efuse_set_recovery_bootloader_offset()` in the user application.
-    - The address can be set via the ``CONFIG_BOOTLOADER_RECOVERY_OFFSET``, it must be a multiple of the flash sector size (0x1000 bytes). This Kconfig option helps ensure the recovery bootloader does not overlap with existing partitions.
+    - The address can be set using ``CONFIG_BOOTLOADER_RECOVERY_OFFSET``. This value must be a multiple of the flash sector size (0x1000 bytes). The Kconfig option helps ensure that the recovery bootloader does not overlap with existing partitions.
     - Note that the eFuse field stores the offset in sectors. Setting it to the maximum value ``0xFFF`` disables the feature.
     - The recovery bootloader image at the ``CONFIG_BOOTLOADER_RECOVERY_OFFSET`` is not flashed by default. It can be written as part of the OTA update process.
 
@@ -250,7 +250,7 @@ If the bootloader grows too large then it can collide with the partition table,
 
     - ``EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR`` (12 bits): Flash sector address for the recovery bootloader. Default value is 0 (disabled), set any other value to enable, 0xFFF to permanently disable.
     - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN`` (1 bit): Enables anti-rollback check in the ROM bootloader.
-    - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION`` (4 bits): Secure version for anti-rollback protection. The value increases as bits are set - 0x0, 0x1, 0x3, 0x7, 0xF.
+    - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION`` (4 bits): Secure version for anti-rollback protection. The value increases as bits are set—0x0, 0x1, 0x3, 0x7, 0xF.
     - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM`` (1 bit): Allows the ROM bootloader to update the secure version in eFuse.
 
     .. note::

docs/en/api-reference/protocols/esp_http_server.rst

@@ -68,6 +68,7 @@ The HTTP server component provides WebSocket support. The WebSocket feature can
 
 :example:`protocols/http_server/ws_echo_server` demonstrates how to create a WebSocket echo server using the HTTP server, which starts on a local network and requires a WebSocket client for interaction, echoing back received WebSocket frames.
 
+
 WebSocket Pre-Handshake Callback
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/en/api-reference/protocols/modbus.rst

@@ -25,4 +25,3 @@ Protocol References
 -------------------
 
     - For the detailed protocol specifications, see `The Modbus Organization <https://modbus.org/specs.php>`_.
-

docs/en/api-reference/system/heap_debug.rst

@@ -207,23 +207,27 @@ The feature allows users to track the heap memory usage of each task created sin
 An additional configuration can be enabled by the user via the menuconfig: ``Component config`` > ``Heap memory debugging`` > ``Keep information about the memory usage of deleted tasks`` (see :ref:`CONFIG_HEAP_TRACK_DELETED_TASKS`) to keep the statistics collected for a given task even after it is deleted.
 
 .. note::
+
     Note that the Heap Task Tracking cannot detect the deletion of statically allocated tasks. Therefore, users will have to keep in mind while reading the following section that statically allocated tasks will always be considered alive in the scope of the Heap Task Tracking feature.
 
 It is important to mention that its usage is strongly discouraged for other purposes than debugging for the following reasons:
 
 .. list::
+
     - Tracking the allocations and storing the resulting statistics for each task requires a non-negligible RAM usage overhead.
     - The overall performance of the heap allocator is severely impacted due to the additional processing required for each allocation and free operation.
 
 .. note::
+
     Note that the memory allocated by the heap task tracking feature will not be visible when dumping or accessing the statistics.
 
-Structure of the statistics and information
+Structure of the Statistics And Information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For a given task, the heap task tracking feature categorizes statistics on three different levels:
 
 .. list::
+
     - The task level statistics
     - The heap level statistics
     - The allocation level statistics
@@ -231,6 +235,7 @@ For a given task, the heap task tracking feature categorizes statistics on three
 The task level statistics provides the following information:
 
 .. list::
+
     - Name of the given task
     - Task handle of the given task
     - Status of the given task (if the task is running or deleted)
@@ -241,9 +246,10 @@ The task level statistics provides the following information:
 The heap level statistics provides the following information for each heap used by the given task:
 
 .. list::
+
     - Name of the given heap
-  - Caps the capabilities of the given heap (without priority)
+    - Capabilities of the given heap (without priority)
-  - Size the total size of the given heap
+    - Total size of the given heap
     - Current usage of the given task on the given heap
     - Peak usage of the given task on the given heap
     - Number of allocations done by the given task for on the given heap
@@ -251,10 +257,11 @@ The heap level statistics provides the following information for each heap used
 The allocation level statistics provides the following information for each allocation done by the given task on the given heap:
 
 .. list::
+
     - Address of the given allocation
     - Size of the given allocation
 
-Dumping the statistics and information
+Dumping the Statistics And Information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The :cpp:func:`heap_caps_print_single_task_stat_overview` API prints an overview of heap usage for a specific task to the provided output stream.
@@ -283,7 +290,8 @@ The :cpp:func:`heap_caps_print_single_task_stat_overview` API prints an overview
   └────────────────────┴─────────┴──────────────────────┴───────────────────┴─────────────────┘
 
 .. note::
-  Note that the task named “Pre-scheduler” represents allocations that occurred before the scheduler was started. It is not an actual task, so the "status" field (which is shown as "ALIVE") is not meaningful and should be ignored.
+
+    Note that the task named "Pre-scheduler" represents allocations that occurred before the scheduler was started. It is not an actual task, so the "status" field (which is shown as "ALIVE") is not meaningful and should be ignored.
 
 Use :cpp:func:`heap_caps_print_single_task_stat` to dump the complete set of statistics for a specific task, or :cpp:func:`heap_caps_print_all_task_stat` to dump statistics for all tasks:
 
@@ -316,12 +324,14 @@ Use :cpp:func:`heap_caps_print_single_task_stat` to dump the complete set of sta
             ├ ALLOC 0x3fc96570, SIZE 344
 
 .. note::
+
     The dump shown above has been truncated (see "[...]") for readability reasons and only displays the statistics and information of the **main** task and the **Pre-scheduler**. The goal here is only to demonstrate the information displayed when calling the :cpp:func:`heap_caps_print_all_task_stat` (resp. :cpp:func:`heap_caps_print_single_task_stat`) API functions.
 
 .. note::
+
     Detailed use of the API functions described in this section can be found in :example:`system/heap_task_tracking/basic`.
 
-Getting the statistics and information
+Getting the Statistics And Information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 :cpp:func:`heap_caps_get_single_task_stat` allows the user to access information of a specific task. The information retrieved by calling this API is identical to the one dumped using :cpp:func:`heap_caps_print_single_task_stat`.
@@ -330,13 +340,15 @@ Getting the statistics and information
 
 Each getter function requires a pointer to the data structure that will be used by the heap task tracking to gather the statistics and information of a given task (or all tasks). This data structure contains pointers to arrays that the user can allocate statically or dynamically.
 
-Due to the difficulty of estimating the size of the arrays used to store information — since it's hard to determine the number of allocations per task, the number of heaps used by each task, and the number of tasks created since startup — the heap task tracking also provides :cpp:func:`heap_caps_alloc_single_task_stat_arrays` (resp. :cpp:func:`heap_caps_alloc_all_task_stat_arrays`) to dynamically allocate the required amount of memory for those arrays.
+The size of the arrays used to store information is difficult to estimate. Examples include the number of allocations per task, the number of heaps used by each task, and the number of tasks created since startup. Therefore, the heap task tracking also provides :cpp:func:`heap_caps_alloc_single_task_stat_arrays` (resp. :cpp:func:`heap_caps_alloc_all_task_stat_arrays`) to dynamically allocate the required amount of memory for those arrays.
 
 Similarly, the heap task tracking also provides :cpp:func:`heap_caps_free_single_task_stat_arrays` (resp. :cpp:func:`heap_caps_free_all_task_stat_arrays`) to free the memory dynamically allocated when calling :cpp:func:`heap_caps_alloc_single_task_stat_arrays` (resp. :cpp:func:`heap_caps_alloc_all_task_stat_arrays`).
 
 .. note::
+
     Detailed use of the API functions described in this section can be found in :example:`system/heap_task_tracking/advanced`.
 
+
 .. _heap-tracing:
 
 Heap Tracing
@@ -764,12 +776,12 @@ Application Examples
 - :example:`system/heap_task_tracking/basic` demonstrates the use of the overview feature of the heap task tracking, dumping per-task summary statistics on heap memory usage.
 - :example:`system/heap_task_tracking/advanced` demonstrates the use of the statistics getter functions of the heap task tracking, accessing per-task complete statistic on the heap memory usage.
 
-API Reference - Heap Task Tracking
+API Reference–Heap Task Tracking
 ----------------------------------
 
 .. include-build-file:: inc/esp_heap_task_info.inc
 
-API Reference - Heap Tracing
+API Reference–Heap Tracing
 ----------------------------
 
 .. include-build-file:: inc/esp_heap_trace.inc

docs/en/contribute/esp-idf-tests-with-pytest.rst

@@ -645,7 +645,9 @@ This marker means that the test case could still be run locally with ``pytest --
 Add New Markers
 ---------------
 
-You can add new markers by adding one line under the :idf_file:`pytest.ini`. If it is a marker that specifies a type of test environment, it should be added into ``env_markers`` section. Otherwise it should be added into ``markers`` section. The syntax should be: ``<marker_name>: <marker_description>``.
+We currently use two types of custom markers. The target marker indicates which target chips the test case supports, and the env marker specifies that the test case should be assigned to a CI runner with the corresponding tag.
+
+You can add new markers by adding one line under the :idf_file:`pytest.ini`. If it is a marker that specifies a type of test environment, it should be added into ``env_markers`` section. Otherwise, it should be added into ``markers`` section. The syntax should be: ``<marker_name>: <marker_description>``.
 
 Skip Auto Flash Binary
 ----------------------

docs/en/migration-guides/release-6.x/6.0/protocols.rst

@@ -38,5 +38,3 @@ Discussions
 ~~~~~~~~~~~
 
 * `Discussions for version v2 <https://github.com/espressif/esp-modbus/discussions>`__
-
-

docs/zh_CN/api-guides/bootloader.rst

@@ -192,3 +192,67 @@ ESP-IDF 二级引导加载程序位于 flash 的 {IDF_TARGET_CONFIG_BOOTLOADER_O
 * :example:`storage/nvs/nvs_bootloader`
 
 如果引导加载程序过大，则可能与内存中的分区表重叠，分区表默认烧录在偏移量 0x8000 处。增加 :ref:`分区表偏移量 <CONFIG_PARTITION_TABLE_OFFSET>` ，将分区表放在 flash 中靠后的区域，这样可以增加引导加载程序的可用空间。
+
+.. only:: SOC_RECOVERY_BOOTLOADER_SUPPORTED
+
+    恢复引导加载程序
+    ----------------
+
+    {IDF_TARGET_NAME} 引入了恢复引导加载程序 (Recovery Bootloader) 和防回滚引导加载程序 (Anti-rollback Bootloader) 功能，这些功能在 ROM 引导加载程序中实现，用于提升设备在 OTA 升级过程中的安全性和可靠性。
+
+    恢复引导加载程序功能可在 OTA 升级失败时为引导加载程序提供安全回退机制。eFuse 字段 ``ESP_EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR`` 将指定恢复引导加载程序的 flash（以扇区为单位）地址。如果位于 {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} 的主引导加载程序加载失败，ROM 引导加载程序会尝试从指定地址加载恢复引导加载程序。
+
+    - 可以使用 ``espefuse.py`` 或在用户应用程序中调用 :cpp:func:`esp_efuse_set_recovery_bootloader_offset()` 来设置 eFuse。
+    - 该地址可通过 ``CONFIG_BOOTLOADER_RECOVERY_OFFSET`` 进行设置，且必须为 flash 扇区大小（0x1000 字节）的整数倍。此 Kconfig 选项有助于确保恢复引导加载程序不会与现有分区重叠。
+    - 注意，eFuse 字段存储的是以扇区为单位的偏移量。将其设置为最大值 ``0xFFF`` 可禁用恢复引导加载程序功能。
+    - 默认情况下，``CONFIG_BOOTLOADER_RECOVERY_OFFSET`` 处的恢复引导加载程序镜像不会被烧录，但可以作为 OTA 升级流程的一部分进行写入。
+
+    下方示例展示了主引导加载程序加载失败后，恢复引导加载程序被加载时的引导日志。
+
+    .. code-block:: none
+
+        ESP-ROM:esp32c5-eco2-20250121
+        Build:Jan 21 2025
+        rst:0x1 (POWERON),boot:0x18 (SPI_FAST_FLASH_BOOT)
+        invalid header: 0xffffffff
+        invalid header: 0xffffffff
+        invalid header: 0xffffffff
+        PRIMARY - FAIL
+        Loading RECOVERY Bootloader...
+        SPI mode:DIO, clock div:1
+        load:0x408556b0,len:0x17cc
+        load:0x4084bba0,len:0xdac
+        load:0x4084e5a0,len:0x3140
+        entry 0x4084bbaa
+
+        I (46) boot: ESP-IDF v6.0-dev-172-g12c5d730097-dirty 2nd stage bootloader
+        I (46) boot: compile time May 22 2025 12:41:59
+        I (47) boot: chip revision: v1.0
+        I (48) boot: efuse block revision: v0.1
+        I (52) boot.esp32c5: SPI Speed      : 80MHz
+        I (55) boot.esp32c5: SPI Mode       : DIO
+        I (59) boot.esp32c5: SPI Flash Size : 4MB
+        I (63) boot: Enabling RNG early entropy source...
+        I (67) boot: Partition Table:
+        ...
+
+    防回滚功能
+    ^^^^^^^^^^
+
+    防回滚功能可防止降级到可能存在安全漏洞的旧版引导加载程序。引导加载程序头部包含安全版本号，由 ``CONFIG_BOOTLOADER_SECURE_VERSION`` 定义。设置 ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN`` 后，ROM 引导加载程序会将该安全版本号与 ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION`` 中存储的值进行比对。只有版本号大于或等于 eFuse 值的引导加载程序才允许启动。
+
+    - 如果设置了 ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM``，ROM 引导加载程序可以更新 eFuse 中的安全版本号。
+    - 随着新引导加载程序版本的发布，安全版本号会递增，且不能降低。
+    - 如果 ROM 引导加载程序未更新 eFuse 中的安全版本号，则应用程序可以通过 :cpp:func:`esp_efuse_write_field_blob` 函数进行更新。
+
+    相关 eFuse
+    ^^^^^^^^^^
+
+    - ``EFUSE_RECOVERY_BOOTLOADER_FLASH_SECTOR`` （12 位）：恢复引导加载程序的 flash 扇区地址。默认值为 0（禁用），设置为其他值则启用，设置为 0xFFF 时永久禁用。
+    - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_EN`` （1 位）：在 ROM 引导加载程序中启用防回滚检查。
+    - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION`` （4 位）：防回滚保护的安全版本号。该值随位数增加而递增—0x0、0x1、0x3、0x7、0xF。
+    - ``EFUSE_BOOTLOADER_ANTI_ROLLBACK_SECURE_VERSION_UPDATE_IN_ROM`` （1 位）：允许 ROM 引导加载程序更新 eFuse 中的安全版本号。
+
+    .. note::
+
+        建议使用以上功能提升设备在 OTA 升级过程中的安全性和可靠性。请谨慎规划 eFuse 的烧录，因为这些设置是永久性的，可能影响未来的升级策略。

docs/zh_CN/api-reference/protocols/esp_http_server.rst

@@ -69,6 +69,38 @@ HTTP 服务器组件提供 websocket 支持。可以在 menuconfig 中使用 :re
 :example:`protocols/http_server/ws_echo_server` 演示了如何使用 HTTP 服务器创建一个 WebSocket 回显服务器，该服务器在本地网络上启动，与 WebSocket 客户端进行交互，回显接收到的 WebSocket 帧。
 
 
+WebSocket 握手前回调
+^^^^^^^^^^^^^^^^^^^^
+
+HTTP 服务器组件为 WebSocket 端点提供了握手前回调 (pre-handshake callback) 的功能。该回调函数会在处理 WebSocket 握手前被调用——此时连接仍然是 HTTP 连接，还未升级为 WebSocket。
+
+握手前回调函数可用于身份认证、权限校验及其他检查。如果回调返回 :c:macro:`ESP_OK`，WebSocket 握手将继续进行；如果返回其他值，则握手中止，连接也会关闭。
+
+要使用 WebSocket 握手前回调，需在项目配置中启用 :ref:`CONFIG_HTTPD_WS_PRE_HANDSHAKE_CB_SUPPORT` 选项。
+
+.. code-block:: c
+
+    static esp_err_t ws_auth_handler(httpd_req_t *req)
+    {
+        // 在此处编写认证逻辑
+        // 返回 ESP_OK 允许握手，返回其他值则拒绝握手
+        return ESP_OK;
+    }
+
+    // 注册带有握手前认证的 WebSocket URI 处理程序
+    static const httpd_uri_t ws = {
+        .uri        = "/ws",
+        .method     = HTTP_GET,
+        .handler    = handler,           // WebSocket 数据处理程序
+        .user_ctx   = NULL,
+        .is_websocket = true,
+        .ws_pre_handshake_cb = ws_auth_handler // 设置握手前回调函数
+    };
+
+    // 在启动服务器后注册该处理程序
+    httpd_register_uri_handler(server, &ws);
+
+
 事件处理
 --------------
 

docs/zh_CN/api-reference/provisioning/wifi_provisioning.rst

@@ -83,6 +83,7 @@ Wi-Fi 配网
                             ESP_LOGE(TAG, "Failed to de-initialize provisioning manager: %s", esp_err_to_name(err));
                         }
                         break;
+                    }
                     default:
                         break;
                 }

docs/zh_CN/api-reference/system/heap_debug.rst

@@ -198,11 +198,155 @@ ESP-IDF 集成了用于请求 :ref:`堆内存信息 <heap-information>`、:ref:`
 .. _heap-task-tracking:
 
 堆任务跟踪
-------------------
+----------
 
-堆任务跟踪可获取堆内存分配的各任务信息，应用程序须指定计划跟踪堆分配的堆属性。
+可以通过 menuconfig 启用堆任务跟踪功能：``Component config`` > ``Heap memory debugging`` > ``Enable heap task tracking`` （参见 :ref:`CONFIG_HEAP_TASK_TRACKING`）。
 
-示例代码可参考 :example:`system/heap_task_tracking`。
+该功能允许用户跟踪自启动以来每个任务的堆内存使用情况，并提供一系列统计信息，这些信息可以通过 getter 函数获取，或直接输出到用户指定的流中。此功能有助于识别内存使用模式和潜在的内存泄漏。
+
+用户还可以通过 menuconfig 启用额外配置：``Component config`` > ``Heap memory debugging`` > ``Keep information about the memory usage of deleted tasks`` （参见 :ref:`CONFIG_HEAP_TRACK_DELETED_TASKS`），以便在任务被删除后仍然保留其统计信息。
+
+.. note::
+
+    请注意，堆任务跟踪无法检测静态分配的任务是否被删除。因此，在阅读下文时需注意，静态分配的任务在堆任务跟踪功能范围内始终被视为存活状态。
+
+需要特别说明的是，除调试目的外，强烈不建议将该功能用于其他用途，原因如下：
+
+.. list::
+
+    - 跟踪每个任务的分配并存储统计信息会占用较大 RAM。
+    - 每次内存分配和释放操作所需的额外数据处理会大幅降低堆分配器的整体性能。
+
+.. note::
+
+    在统计信息输出或访问时不会显示堆任务跟踪功能自身分配的内存。
+
+统计信息的结构
+^^^^^^^^^^^^^^
+
+堆任务跟踪功能将每个任务的统计信息分为三个层级：
+
+.. list::
+
+    - 任务级统计信息
+    - 堆级统计信息
+    - 分配级统计信息
+
+任务级统计信息包括以下内容：
+
+.. list::
+
+    - 任务名称
+    - 任务句柄
+    - 任务状态（运行中或已删除）
+    - 任务的峰值内存使用量（任务生命周期内使用的最大内存）
+    - 任务的当前内存使用量
+    - 该任务分配过内存的堆数量
+
+堆级统计信息针对每个被该任务使用的堆，包含以下内容：
+
+.. list::
+
+    - 堆名称
+    - 堆的内存分配能力（不含优先级）
+    - 堆的总大小
+    - 该任务在该堆上的当前使用量
+    - 该任务在该堆上的峰值使用量
+    - 该任务在该堆上的分配次数
+
+分配级统计信息针对该任务在该堆上的每次分配，包含以下内容：
+
+.. list::
+
+    - 分配的地址
+    - 分配的大小
+
+输出统计信息
+^^^^^^^^^^^^
+
+:cpp:func:`heap_caps_print_single_task_stat_overview` API 可将指定任务的堆使用情况概览输出到指定流。
+
+.. code-block:: text
+
+  ┌────────────────────┬─────────┬──────────────────────┬───────────────────┬─────────────────┐
+  │ TASK               │ STATUS  │ CURRENT MEMORY USAGE │ PEAK MEMORY USAGE │ TOTAL HEAP USED │
+  ├────────────────────┼─────────┼──────────────────────┼───────────────────┼─────────────────┤
+  │          task_name │ ALIVE   │                    0 │              7152 │               1 │
+  └────────────────────┴─────────┴──────────────────────┴───────────────────┴─────────────────┘
+
+:cpp:func:`heap_caps_print_all_task_stat_overview` 可输出所有任务（若启用 :ref:`CONFIG_HEAP_TRACK_DELETED_TASKS`，则包括已删除任务）的堆使用概览。
+
+.. code-block:: text
+
+  ┌────────────────────┬─────────┬──────────────────────┬───────────────────┬─────────────────┐
+  │ TASK               │ STATUS  │ CURRENT MEMORY USAGE │ PEAK MEMORY USAGE │ TOTAL HEAP USED │
+  ├────────────────────┼─────────┼──────────────────────┼───────────────────┼─────────────────┤
+  │          task_name │ DELETED │                11392 │             11616 │               1 │
+  │    other_task_name │ ALIVE   │                    0 │              9408 │               2 │
+  │               main │ ALIVE   │                 3860 │              7412 │               2 │
+  │               ipc1 │ ALIVE   │                   32 │                44 │               1 │
+  │               ipc0 │ ALIVE   │                10080 │             10092 │               1 │
+  │      Pre-scheduler │ ALIVE   │                 2236 │              2236 │               1 │
+  └────────────────────┴─────────┴──────────────────────┴───────────────────┴─────────────────┘
+
+.. note::
+
+    名为 "Pre-scheduler" 的任务表示调度器启动前发生的内存分配。这并非实际任务，因此 "status" 字段（显示为 "ALIVE"）没有实际意义，可忽略。
+
+使用 :cpp:func:`heap_caps_print_single_task_stat` 可输出指定任务的完整统计信息，或使用 :cpp:func:`heap_caps_print_all_task_stat` 输出所有任务的统计信息：
+
+.. code-block:: text
+
+  [...]
+  ├ ALIVE: main, CURRENT MEMORY USAGE 308, PEAK MEMORY USAGE 7412, TOTAL HEAP USED 2:
+  │    ├ HEAP: RAM, CAPS: 0x0010580e, SIZE: 344400, USAGE: CURRENT 220 (0%), PEAK 220 (0%), ALLOC COUNT: 2
+  │    │    ├ ALLOC 0x3fc99024, SIZE 88
+  │    │    ├ ALLOC 0x3fc99124, SIZE 132
+  │    └ HEAP: RAM, CAPS: 0x0010580e, SIZE: 22308, USAGE: CURRENT 88 (0%), PEAK 7192 (32%), ALLOC COUNT: 5
+  │         ├ ALLOC 0x3fce99f8, SIZE 20
+  │         ├ ALLOC 0x3fce9a10, SIZE 12
+  │         ├ ALLOC 0x3fce9a20, SIZE 16
+  │         ├ ALLOC 0x3fce9a34, SIZE 20
+  │         ├ ALLOC 0x3fce9a4c, SIZE 20
+  [...]
+  └ ALIVE: Pre-scheduler, CURRENT MEMORY USAGE 2236, PEAK MEMORY USAGE 2236, TOTAL HEAP USED 1:
+      └ HEAP: RAM, CAPS: 0x0010580e, SIZE: 344400, USAGE: CURRENT 2236 (0%), PEAK 2236 (0%), ALLOC COUNT: 11
+            ├ ALLOC 0x3fc95cb0, SIZE 164
+            ├ ALLOC 0x3fc95dd8, SIZE 12
+            ├ ALLOC 0x3fc95dfc, SIZE 12
+            ├ ALLOC 0x3fc95e20, SIZE 16
+            ├ ALLOC 0x3fc95e48, SIZE 24
+            ├ ALLOC 0x3fc95e78, SIZE 88
+            ├ ALLOC 0x3fc95ee8, SIZE 88
+            ├ ALLOC 0x3fc95f58, SIZE 88
+            ├ ALLOC 0x3fc95fc8, SIZE 88
+            ├ ALLOC 0x3fc96038, SIZE 1312
+            ├ ALLOC 0x3fc96570, SIZE 344
+
+.. note::
+
+    为了便于阅读，上述输出内容有删减（见 "[...]"），仅展示了 **main** 任务和 **Pre-scheduler** 任务的统计信息。此处演示了示调用 :cpp:func:`heap_caps_print_all_task_stat` （或 :cpp:func:`heap_caps_print_single_task_stat`）API 时的输出内容。
+
+.. note::
+
+    本节所述 API 的详细用法可参考 :example:`system/heap_task_tracking/basic`。
+
+获取统计信息
+^^^^^^^^^^^^
+
+用户可使用 :cpp:func:`heap_caps_get_single_task_stat` 获取指定任务的信息。通过该 API 获取的信息与 :cpp:func:`heap_caps_print_single_task_stat` 的输出内容一致。
+
+用户可使用 :cpp:func:`heap_caps_get_all_task_stat` 获取所有任务（若启用 :ref:`CONFIG_HEAP_TRACK_DELETED_TASKS`，则包括已删除任务）的统计信息概览。通过该 API 获取的信息与 :cpp:func:`heap_caps_print_all_task_stat` 的输出内容一致。
+
+每个 getter 函数都需要一个指向数据结构的指针，该结构用于堆任务跟踪收集指定任务（或所有任务）的统计信息。该数据结构包含指向数组的指针，用户可以选择静态或动态分配这些数组。
+
+由于难以预估用于存储信息的数组大小（如每个任务的分配次数、每个任务使用的堆数量、自启动以来创建的任务总数等），堆任务跟踪还提供了 :cpp:func:`heap_caps_alloc_single_task_stat_arrays` （或 :cpp:func:`heap_caps_alloc_all_task_stat_arrays`）来动态分配这些数组所需的内存。
+
+同时，堆任务跟踪还提供 :cpp:func:`heap_caps_free_single_task_stat_arrays` （或 :cpp:func:`heap_caps_free_all_task_stat_arrays`）用于释放通过上述 API 动态分配的内存。
+
+.. note::
+
+    本节所述 API 的详细用法可参考 :example:`system/heap_task_tracking/advanced`。
 
 
 .. _heap-tracing:
@@ -632,7 +776,12 @@ ESP-IDF 集成了用于请求 :ref:`堆内存信息 <heap-information>`、:ref:`
 - :example:`system/heap_task_tracking/basic` 演示了堆任务跟踪的概览功能，用于导出每个任务在堆内存使用方面的统计信息概要。
 - :example:`system/heap_task_tracking/advanced` 演示了堆任务跟踪中统计信息函数的用法，用于访问每个任务在堆内存使用方面的完整统计数据。
 
-API 参考 - 堆内存跟踪
+API 参考–堆任务跟踪
+----------------------------------
+
+.. include-build-file:: inc/esp_heap_task_info.inc
+
+API 参考–堆内存跟踪
 ----------------------------
 
 .. include-build-file:: inc/esp_heap_trace.inc

docs/zh_CN/api-reference/system/soc_caps.rst

@@ -28,6 +28,7 @@ SoC 能力宏
       - 判断芯片是否具有某个硬件模块或功能
       - ``#if SOC_HAS(DAC)`` 判断是否具有 DAC 模块
 
+
 API 参考
 --------
 

docs/zh_CN/contribute/esp-idf-tests-with-pytest.rst

@@ -643,7 +643,7 @@ Pytest 使用技巧
 这一 marker 表明，此测试用例仍可以在本地用 ``pytest --target esp32`` 执行，但不会在 CI 中执行。
 
 添加新 marker
-----------------
+-------------
 
 我们目前使用两种自定义 marker。target marker 是指测试用例支持此目标芯片，env marker 是指测试用例应分配到 CI 中具有相应 tag 的 runner 上。