From f6003fb8bf893cf5c5b3e1a3efec3f6aa7ae5671 Mon Sep 17 00:00:00 2001 From: shenmengjing Date: Mon, 26 Aug 2024 11:44:14 +0800 Subject: [PATCH] docs: Update CN translation for several docs --- docs/en/api-guides/fatal-errors.rst | 2 +- docs/en/api-reference/system/intr_alloc.rst | 2 +- docs/en/contribute/documenting-code.rst | 8 ++-- docs/zh_CN/api-guides/fatal-errors.rst | 8 ++-- .../zh_CN/api-reference/system/intr_alloc.rst | 40 ++++++++++++++++--- docs/zh_CN/contribute/documenting-code.rst | 21 +++++++--- 6 files changed, 60 insertions(+), 21 deletions(-) diff --git a/docs/en/api-guides/fatal-errors.rst b/docs/en/api-guides/fatal-errors.rst index 77dcfbd82a..9803a9220d 100644 --- a/docs/en/api-guides/fatal-errors.rst +++ b/docs/en/api-guides/fatal-errors.rst @@ -398,7 +398,7 @@ Indicates that an interrupt watchdog timeout has occurred. See :doc:`Watchdogs < |CACHE_ERR_MSG| ^^^^^^^^^^^^^^^ -In some situations, ESP-IDF will temporarily disable access to external SPI Flash and SPI RAM via caches. For example, this happens when spi_flash APIs are used to read/write/erase/mmap regions of SPI Flash. In these situations, tasks are suspended, and interrupt handlers not registered with ``ESP_INTR_FLAG_IRAM`` are disabled. Make sure that any interrupt handlers registered with this flag have all the code and data in IRAM/DRAM. For more details, see the :ref:`SPI flash API documentation ` and the :ref:`IRAM-Safe Interrupt Handlers ` section. +In some situations, ESP-IDF will temporarily disable access to external SPI flash and SPI RAM via caches. For example, this happens when spi_flash APIs are used to read/write/erase/mmap regions of SPI flash. In these situations, tasks are suspended, and interrupt handlers not registered with ``ESP_INTR_FLAG_IRAM`` are disabled. Make sure that any interrupt handlers registered with this flag have all the code and data in IRAM/DRAM. For more details, see the :ref:`SPI flash API documentation ` and the :ref:`IRAM-Safe Interrupt Handlers ` section. .. only:: SOC_MEMPROT_SUPPORTED diff --git a/docs/en/api-reference/system/intr_alloc.rst b/docs/en/api-reference/system/intr_alloc.rst index e73881d11d..6effc5d7df 100644 --- a/docs/en/api-reference/system/intr_alloc.rst +++ b/docs/en/api-reference/system/intr_alloc.rst @@ -94,7 +94,7 @@ To illustrate why shared interrupts can only be level-triggered, take the scenar IRAM-Safe Interrupt Handlers ---------------------------- -When performing write and erase operations on SPI flash, the {IDF_TARGET_NAME} will disable the cache, making SPI flash and SPIRAM inaccessible for interrupt handlers. This is why there are two types of interrupt handlers in ESP-IDF, which have their advantages and disadvantages: +When performing write and erase operations on SPI flash, {IDF_TARGET_NAME} will disable the cache, making SPI flash and SPIRAM inaccessible for interrupt handlers. This is why there are two types of interrupt handlers in ESP-IDF, which have their advantages and disadvantages: **IRAM-safe interrupt handlers** - only access code and data in internal memory (IRAM for code, DRAM for data). diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst index c259d0535b..0ca4e96143 100644 --- a/docs/en/contribute/documenting-code.rst +++ b/docs/en/contribute/documenting-code.rst @@ -173,13 +173,13 @@ Building Documentation To build documentation, start by installing the dependencies: 1. Install `Doxygen `_. -2. Chances are you already set up the required `tools `_ by running ``./install.sh``. To enable building docs, you need to run: +2. Chances are you already set up the required `tools `_ by running ``./install.sh``. To enable building docs, you need to run: - .. code-block:: bash + .. code-block:: bash - ./install.sh --enable-docs + ./install.sh --enable-docs - This action will install the ``esp-docs`` Python package. This package is a wrapper around `Sphinx `_ and is required to build ESP-IDF documentation. + This action will install the ``esp-docs`` Python package. This package is a wrapper around `Sphinx `_ and is required to build ESP-IDF documentation. After installing the dependencies, go to the ``docs`` folder and run the following to build the documentation: diff --git a/docs/zh_CN/api-guides/fatal-errors.rst b/docs/zh_CN/api-guides/fatal-errors.rst index b02286d92d..6426732ae4 100644 --- a/docs/zh_CN/api-guides/fatal-errors.rst +++ b/docs/zh_CN/api-guides/fatal-errors.rst @@ -393,15 +393,17 @@ Interrupt wdt timeout on CPU0 / CPU1 这表示发生了中断看门狗超时，详细信息请查阅 :doc:`看门狗 <../api-reference/system/wdts>` 文档。 +.. _cache_error: + |CACHE_ERR_MSG| ^^^^^^^^^^^^^^^ -在某些情况下，ESP-IDF 会暂时禁止通过高速缓存访问外部 SPI flash 和 SPI RAM，例如在使用 spi_flash API 读取/写入/擦除/映射 SPI flash 的时候。在这些情况下，任务会被挂起，并且未使用 ``ESP_INTR_FLAG_IRAM`` 注册的中断处理程序会被禁用。请确保任何使用此标志注册的中断处理程序所访问的代码和数据分别位于 IRAM 和 DRAM 中。更多详细信息请参阅 :ref:`SPI flash API 文档 `。 +某些情况下，ESP-IDF 会暂时禁止通过 cache 访问外部 SPI flash 和 SPI RAM，例如在使用 spi_flash API 读取/写入/擦除/映射 SPI flash 的时候。在这些情况下，任务会被挂起，并且未使用 ``ESP_INTR_FLAG_IRAM`` 注册的中断处理程序会被禁用。请确保任何使用此标志注册的中断处理程序所访问的代码和数据分别位于 IRAM 和 DRAM 中。更多详细信息请参阅 :ref:`SPI flash API 文档 ` 和 :ref:`IRAM 安全中断处理程序 `。 .. only:: SOC_MEMPROT_SUPPORTED - Memory protection fault - ^^^^^^^^^^^^^^^^^^^^^^^ + 内存保护错误 + ^^^^^^^^^^^^ ESP-IDF 中使用 {IDF_TARGET_NAME} 的权限控制功能来防止以下类型的内存访问： diff --git a/docs/zh_CN/api-reference/system/intr_alloc.rst b/docs/zh_CN/api-reference/system/intr_alloc.rst index c20ad0dfdc..d50fd63c71 100644 --- a/docs/zh_CN/api-reference/system/intr_alloc.rst +++ b/docs/zh_CN/api-reference/system/intr_alloc.rst @@ -89,17 +89,45 @@ 须注意从未关联到内核的任务中调用 :cpp:func:`esp_intr_alloc` 的情况。在任务切换期间，这些任务可能在不同内核之间进行迁移，因此无法确定中断分配到了哪个 CPU，给释放中断句柄造成困难，也可能引起调试问题。建议使用特定 CoreID 参数的 :cpp:func:`xTaskCreatePinnedToCore` 来创建中断分配任务，这对于内部中断源而言是必要的。 +.. _iram_safe_interrupts_handlers: -IRAM-safe 中断处理程序 ----------------------- +IRAM 安全中断处理程序 +--------------------- -``ESP_INTR_FLAG_IRAM`` flag 注册的中断处理程序始终在 IRAM（并从 DRAM 读取其所有数据）中运行，因此在擦除和写入 flash 时无需禁用。 +在执行 SPI flash 的写入和擦除操作时，{IDF_TARGET_NAME} 会禁用 cache，中断处理程序将无法访问 SPI flash 和 SPIRAM。因此，ESP-IDF 中存在两种中断处理程序，它们各有优缺点： -这对于需要保证最小执行延迟的中断来说非常有用，因为 flash 写入和擦除操作可能很慢（擦除可能需要数十毫秒或数百毫秒才能完成）。 +**IRAM 安全中断处理程序** - 只能访问内部内存中的代码和数据（代码存储在 IRAM 中，数据存储在 DRAM 中）。 -如果中断被频繁调用，可以将中断处理程序保留在 IRAM 中，避免 flash cache 丢失。 +.. list:: -有关更多详细信息，请参阅 :ref:`SPI flash API 相关文档 `。 + - **+** **延迟**：flash 写入和擦除操作相对缓慢，例如擦除可能需要几十或几百毫秒才能完成，但这些中断处理程序不受影响，执行速度较快且延迟较低，能够保证最小执行延迟。 + - **-** **占用内部内存**：中断处理程序占用了宝贵的内部内存，这些内存本可以用于其他目的。 + - **+** **cache 未命中**：中断处理程序不依赖 cache, 因此就不会出现 cache 未命中带来的不确定性，因为代码和数据已存储在内部存储器中了。 + - **使用场景**：请使用 :c:macro:`ESP_INTR_FLAG_IRAM` 标志，通过中断分配器 API 注册此类中断。 + +**非 IRAM 安全中断处理程序** - 可能会访问 flash 中的代码和（只读）数据。 + +.. list:: + + - **-** **延迟**：在进行 flash 操作时，中断处理程序会被推迟，因此平均延迟较高且难以预测。 + - **+** **占用内部内存**：该中断处理程序不使用内部 RAM，或者使用的内存比 IRAM 安全中断要少。 + - **使用场景**：通过中断分配器 API 注册此类中断时，请 **不要** 使用 :c:macro:`ESP_INTR_FLAG_IRAM` 标志。 + +*请注意，没有任何显式标记将中断处理程序标识为 IRAM 安全。* 当且仅当要访问的代码和数据存储在内部内存中时，中断处理程序才被隐式标记为 IRAM 安全。“IRAM 安全”这个术语实际上有点误导性，因为除了将处理程序的代码放在 IRAM 中之外，还有更多其他要求。以下是 **不属于** IRAM 安全的中断处理程序示例： + +.. list:: + + - 部分代码放置在 flash 中。 + - 放置在 IRAM 中但调用了存储在 flash 里的函数。 + - 代码放置在 IRAM 中但访问了位于 flash 中的只读变量。 + +关于如何将代码和数据放置在 IRAM 或 DRAM 中，请参见 :ref:`how-to-place-code-in-iram`。 + +有关 SPI flash 操作及其与中断处理程序交互的更多详细信息，请参见 :ref:`SPI flash API 文档 `。 + +.. note:: + + 如果不能 100% 确定中断处理程序访问的所有代码和数据都位于 IRAM（代码）或 DRAM（数据）中，切勿使用 ``ESP_INTR_FLAG_IRAM`` 标志注册中断处理程序。忽略这一点将导致（有时是偶发性的）:ref:`cache 错误 `。通过调用函数间接访问代码和数据时也需要注意这点。 .. _intr-alloc-shared-interrupts: diff --git a/docs/zh_CN/contribute/documenting-code.rst b/docs/zh_CN/contribute/documenting-code.rst index 46b35868db..c8a1ee2d10 100644 --- a/docs/zh_CN/contribute/documenting-code.rst +++ b/docs/zh_CN/contribute/documenting-code.rst @@ -170,21 +170,30 @@ Doxygen 支持多种格式，并支持文档内部的多个详情级别，具有 构建文档 ----------- -文档由基于 `Sphinx `_ 的 Python 包 `esp-docs` 进行构建。 +要构建文档，请先安装以下依赖项： -安装命令:: +1. 安装 `Doxygen `_。 +2. 如果已经通过运行 ``./install.sh`` 设置好了所需的 `工具 `_，请运行以下命令，启用文档构建功能： - pip install esp-docs + .. code-block:: bash -安装成功后，使用如下命令在 docs 文件夹中构建文档:: + ./install.sh --enable-docs + + 上述操作将安装 ``esp-docs`` Python 包。该包是 `Sphinx `_ 的一个封装器，用于构建 ESP-IDF 文档。 + +安装好依赖项后，进入 ``docs`` 文件夹并运行以下命令构建文档： + +.. code-block:: bash build-docs build -或使用以下命令指定目标芯片和语言:: +也可以通过指定目标和语言，仅构建所需的文档，从而加快构建过程： + +.. code-block:: bash build-docs -t esp32 -l en build -如需深入了解 `esp-docs` 的功能，请参考 `esp-docs `_。 +更多详细信息，请参阅 `esp-docs `_。 小结 ------