diff --git a/docs/en/api-guides/performance/ram-usage.rst b/docs/en/api-guides/performance/ram-usage.rst index 7bcd3b1a96..f0a4fa532d 100644 --- a/docs/en/api-guides/performance/ram-usage.rst +++ b/docs/en/api-guides/performance/ram-usage.rst @@ -193,7 +193,7 @@ The following options will reduce IRAM usage of some ESP-IDF features: :esp32c2: - Enable :ref:`CONFIG_BT_RELEASE_IRAM`. Release BT text section and merge BT data, bss & text into a large free heap region when ``esp_bt_mem_release`` is called. This makes Bluetooth unavailable until the next restart, but saving ~22 KB or more of IRAM. - Disable :ref:`CONFIG_LIBC_LOCKS_PLACE_IN_IRAM` if no ISRs that run while cache is disabled (i.e. IRAM ISRs) use libc lock APIs. :CONFIG_ESP_ROM_HAS_SUBOPTIMAL_NEWLIB_ON_MISALIGNED_MEMORY: - Disable :ref:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS` to save approximately 1000 bytes of IRAM, at the cost of reduced performance. - :SOC_SPIRAM_SUPPORTED: - Enable :ref:`CONFIG_ESP_EVENT_LOOP_IN_EXT_RAM` to force esp_event to place event loop related allocations in external RAM instead of internal RAM. + :SOC_SPIRAM_SUPPORTED: - Enable :ref:`CONFIG_ESP_EVENT_LOOP_IN_EXT_RAM` to force ``esp_event`` to place event loop related allocations in external RAM instead of internal RAM. .. only:: esp32 diff --git a/docs/en/api-reference/peripherals/ecdsa.rst b/docs/en/api-reference/peripherals/ecdsa.rst index 6a2e5a1602..9ad5dd5656 100644 --- a/docs/en/api-reference/peripherals/ecdsa.rst +++ b/docs/en/api-reference/peripherals/ecdsa.rst @@ -134,7 +134,6 @@ The ECDSA peripheral in Mbed TLS stack is integrated by overriding the ECDSA sig For a particular TLS context, additional APIs have been supplied to populate certain fields (e.g., private key ctx) to differentiate routing to hardware. ESP-TLS layer integrates these APIs internally and hence no additional work is required at the application layer. However, for custom use-cases please refer to API details below. - API Reference ------------- diff --git a/docs/en/api-reference/peripherals/i3c_master.rst b/docs/en/api-reference/peripherals/i3c_master.rst index c66c6c70f7..54301e9aa4 100644 --- a/docs/en/api-reference/peripherals/i3c_master.rst +++ b/docs/en/api-reference/peripherals/i3c_master.rst @@ -1,3 +1,4 @@ +==================== I3C master interface ==================== @@ -501,10 +502,12 @@ Thread Safety The following functions of the I3C driver are thread-safe and can be called from different RTOS tasks without additional lock protection: Factory functions: + - :cpp:func:`i3c_new_master_bus` - :cpp:func:`i3c_del_master_bus` I3C master operation functions (thread safety guaranteed through bus operation signals): + - :cpp:func:`i3c_master_bus_add_i3c_static_device` - :cpp:func:`i3c_master_bus_rm_i3c_device` - :cpp:func:`i3c_master_i3c_device_transmit` diff --git a/docs/en/api-reference/system/esp_timer.rst b/docs/en/api-reference/system/esp_timer.rst index 1a06885ac1..cbbc390a3d 100644 --- a/docs/en/api-reference/system/esp_timer.rst +++ b/docs/en/api-reference/system/esp_timer.rst @@ -216,7 +216,7 @@ The general procedure to create, start, stop, and delete a timer is as follows: 3. Stop the timer - To stop the running timer, call the function :cpp:func:`esp_timer_stop`. But it does not guarantee that after this call, the callback will not be running one or more times. To check if the callback is not running after stopping the timer, you can use :cpp:func:`esp_timer_is_active`. Another approach is to use a blocking stop API. - - Blocking the timer stop operation until any in-flight callback completes can be done using :cpp:func:`esp_timer_stop_blocking`. + - To block the timer stop operation until any in-flight callback completes, use :cpp:func:`esp_timer_stop_blocking`. 4. Delete the timer diff --git a/docs/en/contribute/esp-idf-tests-with-pytest.rst b/docs/en/contribute/esp-idf-tests-with-pytest.rst index 7d04b61e51..c1e6a19eaa 100644 --- a/docs/en/contribute/esp-idf-tests-with-pytest.rst +++ b/docs/en/contribute/esp-idf-tests-with-pytest.rst @@ -449,22 +449,20 @@ Dependency-driven build rules are defined in per-folder manifest files (``.build - esp_eth - esp_netif - We also have a set of common components (defined as ``common_components`` in :idf_file:`.idf_build_apps.toml`). ``common_components`` is a list of baseline (core) components that are used by many apps. In general, if one of these components changes, you usually want to rebuild and retest the apps that depend on it. The app maintainer should decide which components are important for their app. If the app should depend on a ``common_components``, add it to ``depends_components``. If not, specify only the important components. If ``depends_components`` is not specified, we use the calculated components (``project_description.json``) and check whether the app is affected by the changed components. -Deprecated (prefer using ``depends_components`` / ``common_components`` instead): -``deactivate_dependency_driven_build_by_components`` disables the dependency-driven checks if certain components change. +Deprecated (prefer using ``depends_components`` and ``common_components`` instead): ``deactivate_dependency_driven_build_by_components`` disables the dependency-driven checks if certain components change. Target Test Jobs ---------------- In CI, all generated target test jobs are named according to the pattern " - ". For example, single-dut test job ``esp32 - generic``, or multi-dut test job ``esp32,esp32 - multi_dut_generic``. -The binaries in the target test jobs are downloaded from our internal MinIO servers. For most of the test cases, only the files that are required by flash (like .bin files, flash_args files, etc) would be downloaded. For some test cases, like jtag test cases, .elf files are also downloaded. +The binaries in the target test jobs are downloaded from our internal MinIO servers. For most of the test cases, only the files that are required by flash (like .bin files, flash_args files, etc) would be downloaded. For some test cases, like JTAG test cases, .elf files are also downloaded. .. _run_the_tests_locally: diff --git a/docs/zh_CN/api-guides/performance/ram-usage.rst b/docs/zh_CN/api-guides/performance/ram-usage.rst index 72239a0cd3..f7f30a82e5 100644 --- a/docs/zh_CN/api-guides/performance/ram-usage.rst +++ b/docs/zh_CN/api-guides/performance/ram-usage.rst @@ -193,6 +193,7 @@ IRAM 优化 :esp32c2: - 启用 :ref:`CONFIG_BT_RELEASE_IRAM`。 蓝牙所使用的 data，bss 和 text 段已经被分配在连续的RAM区间。当调用 ``esp_bt_mem_release`` 时，这些段都会被添加到 Heap 中。 这将节省约 22 KB 的 RAM。但要再次使用蓝牙功能，需要重启程序。 - 禁用 :ref:`CONFIG_LIBC_LOCKS_PLACE_IN_IRAM`。若在缓存禁用的情况下，运行中的中断服务程序（即 IRAM ISR）没有使用 libc 锁 API，那么禁用该配置可以节省 IRAM 空间。 :CONFIG_ESP_ROM_HAS_SUBOPTIMAL_NEWLIB_ON_MISALIGNED_MEMORY: - 禁用 :ref:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS` 可以节省大约 1000 字节的 IRAM，但会降低性能。 + :SOC_SPIRAM_SUPPORTED: - 启用 :ref:`CONFIG_ESP_EVENT_LOOP_IN_EXT_RAM`，强制 ``esp_event`` 将事件循环相关的内存分配放在外部 RAM 而不是内部 RAM 中。 .. only:: esp32 diff --git a/docs/zh_CN/api-reference/peripherals/i3c_master.rst b/docs/zh_CN/api-reference/peripherals/i3c_master.rst index 92895e781a..bc20774f23 100644 --- a/docs/zh_CN/api-reference/peripherals/i3c_master.rst +++ b/docs/zh_CN/api-reference/peripherals/i3c_master.rst @@ -1,6 +1,6 @@ -======================== +============ I3C 主机接口 -======================== +============ :link_to_translation:`en:[English]` diff --git a/docs/zh_CN/api-reference/system/esp_timer.rst b/docs/zh_CN/api-reference/system/esp_timer.rst index 3520a3bf96..ce25c912c9 100644 --- a/docs/zh_CN/api-reference/system/esp_timer.rst +++ b/docs/zh_CN/api-reference/system/esp_timer.rst @@ -215,7 +215,8 @@ FreeRTOS 定时器 3. 暂停定时器 - - 调用函数 :cpp:func:`esp_timer_stop`，可暂停运行中的定时器。 + - 调用函数 :cpp:func:`esp_timer_stop` 可以暂停运行中的定时器。但在调用此函数之后，回调函数可能还会再执行一次或多次。使用 :cpp:func:`esp_timer_is_active`，可以检查暂停定时器后回调函数是否仍在运行；也可以使用阻塞式停止 API。 + - 使用 :cpp:func:`esp_timer_stop_blocking` 可以阻塞定时器停止操作，直到所有正在执行的回调函数执行完毕。 4. 删除定时器 diff --git a/docs/zh_CN/contribute/esp-idf-tests-with-pytest.rst b/docs/zh_CN/contribute/esp-idf-tests-with-pytest.rst index 14cbf1c3c0..fc7fd44932 100644 --- a/docs/zh_CN/contribute/esp-idf-tests-with-pytest.rst +++ b/docs/zh_CN/contribute/esp-idf-tests-with-pytest.rst @@ -1,6 +1,6 @@ -======================== +=================== ESP-IDF pytest 指南 -======================== +=================== :link_to_translation:`en:[English]` @@ -31,7 +31,7 @@ ESP-IDF 在主机端使用 pytest 框架（以及一些 pytest 插件）来自 本指南专门面向 ESP-IDF 贡献者。一些概念（如自定义标记）可能不直接适用于使用 ESP-IDF SDK 的个人项目。要在个人项目中运行 pytest-embedded，请参阅 `pytest-embedded 文档 `__ 和 `提供的示例 `__。 安装 -============ +==== 基础依赖项可以通过执行 ESP-IDF 安装脚本 ``--enable-ci`` 进行安装： @@ -48,7 +48,7 @@ ESP-IDF 在主机端使用 pytest 框架（以及一些 pytest 插件）来自 上面的脚本已预先实现了一些机制，以确保所有安装过程顺利进行。如果您在安装过程中遇到任何问题，请在 `GitHub Issue 版块 `__ 上提交问题说明。 常见概念 -=============== +======== **测试应用程序** 是一组二进制文件，从一个 IDF 项目构建，用于测试项目的特定功能。测试应用程序通常位于 ``${IDF_PATH}/examples``，``${IDF_PATH}/tools/test_apps``，和 ``${IDF_PATH}/components//test_apps``。 @@ -81,13 +81,13 @@ ESP-IDF 在主机端使用 pytest 框架（以及一些 pytest 插件）来自 └── pytest_foo_bar.py 在 ESP-IDF 中使用 pytest -============================ +======================== 单个 DUT 测试用例 ------------------- +----------------- 入门教程 -^^^^^^^^^^^^^^^ +^^^^^^^^ .. code-block:: python @@ -121,7 +121,7 @@ ESP-IDF 在主机端使用 pytest 框架（以及一些 pytest 插件）来自 关于测试函数，使用了一个 ``dut`` fixture。在单一 DUT 测试用例中，``dut`` fixture 是 ``IdfDut`` 类的一个实例，对于多个 DUT 测试用例，它是 ``IdfDut`` 实例的一个元组。有关 ``IdfDut`` 类的更多详细信息，请参阅 `pytest-embedded IdfDut API 参考 `__。 使用不同的 sdkconfig 文件运行相同的应用程序 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 某些测试用例可能需要使用不同的 sdkconfig 文件运行相同的应用程序。与 sdkconfig 相关概念的详细文档，请参阅 `idf-build-apps 文档 `__。 @@ -183,7 +183,7 @@ ESP-IDF 在主机端使用 pytest 框架（以及一些 pytest 插件）来自 几乎所有 pytest-embedded 的 CLI 选项都支持参数化。要查看所有支持的 CLI 选项，您可以运行 ``pytest --help`` 命令，并检查 ``embedded-...`` 部分以查看普通 pytest-embedded 选项，以及 ``idf`` 部分以查看 ESP-IDF 特定选项。 使用不同的 sdkconfig 文件运行相同的应用程序，支持不同的目标芯片 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 对于某些测试用例，可能需要使用不同的 sdkconfig 文件运行相同的应用程序。这些 sdkconfig 文件支持不同的目标芯片。可以使用 ``idf_parametrize`` 来实现。使用与上文相同的文件夹结构。 @@ -204,7 +204,7 @@ ESP-IDF 在主机端使用 pytest 框架（以及一些 pytest 插件）来自 * ``esp32s2.bar.test_foo_bar`` 测试串行输出 -^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^ 为确保测试在目标芯片上顺利执行，测试脚本可使用 ``dut.expect()`` 函数来测试目标芯片上的串行输出： @@ -221,10 +221,10 @@ ESP-IDF 在主机端使用 pytest 框架（以及一些 pytest 插件）来自 如需了解关于 ``expect`` 函数类型的更多信息，请参考 `pytest-embedded 辅助文档 `__。 多个 DUT 的测试用例 ------------------------------- +------------------- 用同一应用程序进行多个 DUT 测试 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 有时，一个测试可能涉及多个目标芯片运行同一测试程序。在这种情况下，可以使用 ``count`` 将想要进行测试的 DUT 数量参数化。 @@ -257,7 +257,7 @@ ESP-IDF 在主机端使用 pytest 框架（以及一些 pytest 插件）来自 有关详细的多个 DUT 参数化文档，请参阅 `pytest-embedded Multi-DUT 文档 `__。 用不同应用程序和目标芯片进行多目标测试 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 在某些情况下，一个测试可能涉及多个目标芯片运行不同的测试应用程序（例如，将不同的目标用作主节点和从节点）。通常在 ESP-IDF 中，文件夹结构会是这样的： @@ -303,7 +303,7 @@ ESP-IDF 在主机端使用 pytest 框架（以及一些 pytest 插件）来自 * dut-0, ESP32-S2 运行 ``master`` 应用程序, dut-1, ESP32运行 ``slave`` 应用程序 运行 Unity 测试用例 ------------------------ +------------------- 使用 `Unity 测试框架 `__ 进行单元测试。共有三种测试用例（ `Unity 测试框架 `__）： @@ -368,7 +368,7 @@ ESP-IDF 在主机端使用 pytest 框架（以及一些 pytest 插件）来自 有关可用函数的完整列表，请参阅 `pytest-embedded case_tester API 参考 `__。 在 CI 中执行板载测试 -====================== +==================== CI 的工作流程如下所示： @@ -409,7 +409,7 @@ CI 的工作流程如下所示： 所有编译和目标测试都是由我们的 CI 脚本 :project:`tools/ci/dynamic_pipelines` 自动生成。 编译 ------------ +---- 在 CI 中，所有位于 ``components``、``examples`` 和 ``tools/test_apps`` 下的 ESP-IDF 项目都会使用所有支持的目标芯片和 sdkconfig 文件进行编译。二进制文件将编译在 ``build__`` 下。例如： @@ -435,20 +435,42 @@ CI 的工作流程如下所示： 对于 ``build_non_test_related_apps``，在编译完成后，所有编译的二进制文件将被删除。只有编译日志文件将上传到内部 MinIO 服务器。下载链接可以在内部 MR 中发布的编译报告中获取。 +由依赖驱动的构建 +^^^^^^^^^^^^^^^^ + +为了优化 CI 构建时间，我们使用 idf-build-apps 的依赖驱动构建功能，从而只构建受变更组件影响的应用程序。 + +每个文件夹的清单文件 (``.build-test-rules.yml``) 中定义了依赖驱动构建的规则，每个应用程序可以定义 ``depends_components``。 + +.. code-block:: yaml + + examples/foo/bar: + depends_components: + - esp_eth + - esp_netif + +此外还有一组通用组件（在 :idf_file:`.idf_build_apps.toml` 中定义为 ``common_components``）。``common_components`` 是许多应用程序使用的基础（核心）组件列表。通常情况下，如果这些组件之一发生变更，则需要重新构建和测试依赖该组件的应用程序。 + +应用程序维护者应明确该应用依赖的关键组件。如果应用程序应该依赖某个 ``common_components``，请将其添加至 ``depends_components``；否则，仅指定真正重要的组件即可。 + +如果未指定 ``depends_components``，则将使用计算出的组件 (``project_description.json``) 并检查应用程序是否受变更组件的影响。 + +已弃用（建议使用 ``depends_components`` 和 ``common_components``）：``deactivate_dependency_driven_build_by_components`` 可在指定组件变更时禁用依赖驱动检查。 + 板载测试任务 ----------------- +------------ -在CI中，所有板载测试任务都以 " - " 格式命名。例如，单个 DUT 测试任务 ``esp32 - generic`` 或多个 DUT 测试任务 ``esp32,esp32 - multi_dut_generic``。 +在CI中，所有板载测试任务都以 " - " 格式命名。例如，单个 DUT 测试任务 ``esp32 - generic``，或多个 DUT 测试任务 ``esp32,esp32 - multi_dut_generic``。 -板载测试任务中的二进制文件是从内部 MinIO 服务器下载的。对于大多数测试用例，仅下载烧录所需的文件（如 .bin 文件、flash_args 文件等）。对于某些测试用例，如 jtag 测试用例，还会下载 .elf 文件。 +板载测试任务中的二进制文件从内部 MinIO 服务器中下载。对于大多数测试用例，仅下载烧录所需的文件（如 ``.bin`` 文件、``flash_args`` 文件等）。对于某些测试用例，如 JTAG 测试用例，还会下载 ``.elf`` 文件。 .. _run_the_tests_locally: 本地测试 -========== +======== 安装 -------- +---- 首先，你需为 ESP-IDF 安装 Python 依赖：