docs: Update CN translation for auto_suspend.inc (!22755)

docs/en/api-reference/peripherals/spi_flash/auto_suspend.inc

@@ -6,45 +6,45 @@ Flash Auto Suspend Feature
 .. important::
 
     1. The flash chip you are using should have a suspend/resume feature.
-    2. The MSPI hardware should support the auto-suspend feature (hardware can send suspend command automatically).
+
+    2. The MSPI hardware should support the auto-suspend feature, i.e., hardware can send suspend command automatically.
 
     If you use suspend feature on an unsupported chip, it may cause a severe crash. Therefore, we strongly suggest you reading the flash chip datasheets first. Ensure the flash chip satisfies the following conditions at minimum.
 
-    1. SUS bit in status registers should in SR2 bit7 (or SR bit15)(This is caused by the restriction of out software implementation).
+    1. With the current software implementation, SUS bit in status registers should in SR2 bit7 or SR bit15.
 
-    2. Suspend command is 75H, resume command is 7AH(This is caused by the restriction of out software implementation).
+    2. With the current software implementation, suspend command should be 75H, with resume command being 7AH.
 
-    3. When the flash is successfully suspended, all address of the flash, except from the section/block being erased, can be read correctly. And resume can be sent immediately at this state.
+    3. When the flash is successfully suspended, all address of the flash, except from the section/block being erased, can be read correctly. At this state，resume can be sent immediately as well.
 
     4. When the flash is successfully resumed, another suspend can be sent immediately at this state.
 
+When :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is enabled, the caches will be kept enabled. They would be disabled if :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is disabled. The hardware handles the arbitration between SPI0 and SPI1. If the SPI1 operation is short, such as a reading operation, the CPU and the cache will wait until the SPI1 operation is completed. However, during processes like erasing, page programming, or status register writing (e.g., ``SE``, ``PP``, and ``WRSR``), an auto suspend will happen, interrupting the ongoing flash operation. This allows the CPU to access data from the cache and flash within limited time.
 
-When :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is enabled, the caches will be kept enabled (they would be disabled if :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is disabled). The hardware handles the arbitration between SPI0 and SPI1. If SPI1 operation is short (like reading operation), the CPU and the cache will wait until the SPI1 operation is done. However, if it is erasing, page programming or status register writing (e.g. `SE`, `PP` and `WRSR`), an auto suspend will happen, interrupting the ongoing flash operation, making the CPU able to read from cache and flash in limited time.
+This approach allows certain code/variables to be stored in flash/PSRAM instead of IRAM/DRAM, while still being executable during flash erasing. This reduces the usage of IRAM/DRAM.
 
-This way some code/variables can be put into the flash/psram instead of IRAM/DRAM, while still able to be executed during flash erasing. This reduces the some usage of IRAM/DRAM.
+Please note that this feature comes with the overhead of flash suspend/resume. Frequent interruptions during flash erasing can significantly prolong the erasing process. To avoid this, you may use FreeRTOS task priorities to ensure that only real-time critical tasks are executed at a higher priority than flash erasing, allowing the flash erasing to complete in reasonable time.
 
-Please note this feature has the overhead of the flash suspend/resume. The flash erasing can be extremely long if the erasing is interrupted too often. Use FreeRTOS task priorities to ensure that only real-time critical tasks are executed at higher priority than flash erase, to allow the flash erase to complete in reasonable time.
+There are three kinds of code:
 
+1. Critical code: inside IRAM/DRAM. This kind of code usually has high performance requirements, related to cache/flash/PSRAM, or is called very often.
 
-In other words, there are three kinds of code:
+2. Cached code: inside flash/PSRAM. This kind of code has lower performance requirements or is called less often. They will execute during erasing, with some overhead.
 
-1. Critical code: inside IRAM/DRAM. This kind of code usually has high performance requirements, related to cache/flash/psram, or called very often.
+3. Low-priority code: inside flash/PSRAM and disabled during erasing. This kind of code should be forbidden from being executed to avoid affecting the flash erasing, by setting a lower task priority than the erasing task.
 
-2. Cached code: inside flash/psram. This kind of code has lower performance requirements or called less often. They will execute during erasing, with some overhead.
-
-3. Low priority code: inside flash/psram and disabled during erasing. This kind of code should be forbidden from executed to avoid affecting the flash erasing, by setting a lower task priority than the erasing task.
-
-Regarding the flash suspend feature usage, and corresponding response time delay, please also see this example :example:`system/flash_suspend` .
+Regarding the flash suspend feature usage and corresponding response time delay, please also see the :example:`system/flash_suspend` example.
 
 .. note::
 
-    The flash auto suspend feature relies heavily on strict timing. You can see it as a kind of optimisation plan, which means that you cannot use it in every situation, like high requirement of real-time system or triggering interrupt very frequently (e.g. lcd flush, bluetooth, wifi, etc.). You should take following steps to evaluate what kind of ISR can be used together with flash suspend.
+    The flash auto suspend feature relies heavily on strict timing. You can see it as a kind of optimization plan, which means that you cannot use it in every situation, like high requirement of real-time system or triggering interrupt very frequently (e.g., LCD flush, bluetooth, Wi-Fi, etc.). You should take following steps to evaluate what kind of ISR can be used together with flash suspend.
 
     .. wavedrom:: /../_static/diagrams/spi_flash/flash_auto_suspend_timing.json
 
-    As you can see from the diagram. Two key values should be noted.
+    As you can see from the diagram, two key values should be noted:
 
-    1. ISR time: The ISR time cannot be very long, at least not larger than the value you set in `IWDT`. But it will significantly lengthen the erase/write completion times.
-    2. ISR interval: The ISR cannot be triggered very often. The most important time is the `ISR interval minus ISR time`(from point b to point c in the diagram). During this time, SPI1 will send resume to restart the operation, but it needs a time `tsus` for preparation, and the typical value of `tsus` is about **40us**. If SPI1 cannot resume the operation but another suspend comes, it will cause CPU starve and `TWDT` may be triggered.
+    1. ISR time: The ISR time cannot be very long, at least not larger than the value you set in ``IWDT``. But it will significantly lengthen the erasing/writing completion time.
 
-    Furthermore, the flash suspend might be delayed. If CPU and the cache operation accesses to flash via SPI0 very frequently and SPI1 sending suspend command is also very frequently, it will influence the efficiency of MSPI data transfer. So, we have a "lock" inside to prevent this. When SPI1 send suspend command, then SPI0 will take over memory SPI bus and take the "lock". After SPI0 finishes sending data, SPI0 will still take the memory SPI bus until the "lock" delay period time finishes. During this "lock" delay period, if there is any other SPI0 transaction, then start SPI0 transaction and "lock" delay period start again. Otherwise, SPI0 will release the memory bus and start SPI0/1 arbitration.
+    2. ISR interval: ISR cannot be triggered very often. The most important time is the **ISR interval minus ISR time** (from point b to point c in the diagram). During this time, SPI1 will send resume command to restart the operation. However, it needs a time ``tsus`` for preparation, and the typical value of ``tsus`` is about **40 us**. If SPI1 cannot resume the operation but another suspend command comes, it will cause CPU starve and ``TWDT`` may be triggered.
+
+    Furthermore, the flash suspend might be delayed. If both the CPU and the cache access the flash via SPI0 frequently and SPI1 sends the suspend command frequently as well, the efficiency of MSPI data transfer will be influenced. So, we have a **lock** inside to prevent this. When SPI1 sends the suspend command, SPI0 will take over memory SPI bus and take the lock. After SPI0 finishes sending data, it will retain control of the memory SPI bus until the lock delay period time finishes. During this lock delay period, if there is any other SPI0 transaction, then the SPI0 transaction will be proceeded and a new lock delay period will start. Otherwise, SPI0 will release the memory bus and start SPI0/1 arbitration.

docs/en/api-reference/peripherals/spi_flash/index.rst

@@ -6,12 +6,12 @@ SPI Flash API
 Overview
 --------
 
-The spi_flash component contains API functions related to reading, writing, erasing, memory mapping for data in the external flash.
+The spi_flash component contains API functions related to reading, writing, erasing, and memory mapping for data in the external flash.
 
 For higher-level API functions which work with partitions defined in the :doc:`partition table </api-guides/partition-tables>`, see :doc:`/api-reference/storage/partition`
 
 .. note::
-    ``esp_partition_*`` APIs are recommended to be used instead of the lower level ``esp_flash_*`` API functions when accessing the main SPI Flash chip, since they do bounds checking and are guaranteed to calculate correct offsets in flash based on the information in the partition table. ``esp_flash_*`` functions can still be used directly when accessing an external (secondary) SPI flash chip.
+    ``esp_partition_*`` APIs are recommended to be used instead of the lower level ``esp_flash_*`` API functions when accessing the main SPI flash chip, since they conduct bounds checking and are guaranteed to calculate correct offsets in flash based on the information in the partition table. ``esp_flash_*`` functions can still be used directly when accessing an external (secondary) SPI flash chip.
 
 Different from the API before ESP-IDF v4.0, the functionality of ``esp_flash_*`` APIs is not limited to the "main" SPI flash chip (the same SPI flash chip from which program runs). With different chip pointers, you can access external flash chips connected to not only SPI0/1 but also other SPI buses like SPI2.
 
@@ -19,7 +19,7 @@ Different from the API before ESP-IDF v4.0, the functionality of ``esp_flash_*``
 
     Instead of going through the cache connected to the SPI0 peripheral, most ``esp_flash_*`` APIs go through other SPI peripherals like SPI1, SPI2, etc. This makes them able to access not only the main flash, but also external (secondary) flash.
 
-    However, due to limitations of the cache, operations through the cache are limited to the main flash. The address range limitation for these operations are also on the cache side. The cache is not able to access external flash chips or address range above its capabilities. These cache operations include: mmap, encrypted read/write, executing code or access to variables in the flash.
+    However, due to the limitations of the cache, operations through the cache are limited to the main flash. The address range limitation for these operations is also on the cache side. The cache is not able to access external flash chips or address range above its capabilities. These cache operations include: mmap, encrypted read/write, executing code or access to variables in the flash.
 
 .. note::
 
@@ -37,7 +37,7 @@ Quad/Dual Mode Chips
 
 Features of different flashes are implemented in different ways and thus need special support. The fast/slow read and Dual mode (DOUT/DIO) of almost all flashes with 24-bit address are supported, because they don't need any vendor-specific commands.
 
-Quad mode (QIO/QOUT) is supported on following chip types:
+Quad mode (QIO/QOUT) is supported on the following chip types:
 
 1. ISSI
 2. GD
@@ -237,6 +237,7 @@ Implementation Details
 ----------------------
 
 In order to perform some flash operations, it is necessary to make sure that both CPUs are not running any code from flash for the duration of the flash operation:
+
 - In a single-core setup, the SDK needs to disable interrupts or scheduler before performing the flash operation.
 - In a dual-core setup, the SDK needs to make sure that both CPUs are not running any code from flash.
 

docs/zh_CN/api-reference/peripherals/spi_flash/auto_suspend.inc

@@ -1,28 +1,50 @@
-
 .. _auto-suspend:
 
-当使能 flash 擦除的自动暂停
+flash 自动暂停功能
 --------------------------------------
 
 .. important:
 
-    您使用的 flash 需要有 suspend/resume 功能，而且不是所有具备 suspend/resume 的 flash 都可以在 {IDF_TARGET_NAME} 上使用自动暂停功能。如果您在不支持自动暂停的 flash 上使用该功能，可能会造成严重的程序崩溃。因此，我们强烈建议您在使用前阅读对应的 flash 的数据手册，确保您的 flash 可以满足如下条件, 即使这样，我们也建议您对 flash 做完整的测试：
+    1. 应使用支持暂停/恢复功能的 flash。
 
-    1. flash 状态寄存器中的 SUS bit 应当位于 SR2 bit7 ( 或者是 SR bit15 )(这是当前软件的实现限制)。
-    2. 暂停的命令是 75H，恢复的命令是 7AH(这是当前软件的实现限制)。
-    3. 当 flash 芯片成功暂停之后，除了正在被擦除的段或块外的任何 flash 地址中的的内容，都可以被正确的读取。恢复命令也可以在这种状态下立即下达。
-    4. 当 flash 已经从暂停的模式恢复后，另一个暂停命令可以立即下达。
+    2. 应使用支持自动暂停功能的 MSPI 硬件，即硬件支持自动发送暂停命令。
 
-当使能 flash 擦除的自动暂停，访问 SPI1 时（如擦除、写入、读取主 flash ） cache 便无需被禁用。硬件会负责仲裁二者的访问。
+    如果在不支持自动暂停的 flash 上使用该功能，可能会造成严重的程序崩溃。因此，强烈建议提前阅读规格书，确保 flash 至少满足如下条件：
 
-当 SPI1 操作较短时（如读取操作）， CPU 和 cache 会等待直到 SPI1 的操作结束。然而对于一个擦除操作，自动暂停会发生并打断擦除操作，允许 CPU 能够在有限时间内从 cache 读取数据。
+    1. 基于当前软件的实现限制，flash 状态寄存器中的 SUS 位应当位于 SR2 bit7 或 SR bit15。
 
-因此，部分的代码及变量便可以放入 flash / PSRAM 而非 IRAM / DRAM ，同时仍然能够在 flash 擦除期间被执行。这样就减少了 IRAM / DRAM 的消耗。
+    2. 基于当前软件的实现限制，flash 暂停命令应为 75H，恢复命令为 7AH。
 
-请注意这个功能会带来 flash 暂停及恢复时的额外开销。如果被频繁打断， flash 的擦除时间可能异常的长。为了确保 flash 擦除操作在一个合理的时间内完成，请调整 FreeRTOS 任务优先级，这样仅有那些高于擦除任务优先级的任务，会在擦除进行过程中会被执行。
+    3. flash 成功暂停后，除已擦除的段或块外，flash 地址中的任何内容都支持读取。也可以在此种状态下立即下达恢复命令。
 
-换句话说，代码可以分为以下三类：
+    4. flash 从暂停模式恢复后，支持立即下达另一个暂停命令。
 
-1. 关键代码：放置在 IRAM / DRAM 中。这类代码通常有较高的性能要求，与 cache / flash / PSRAM 相关，或者被频繁调用。
-2. cache 访问的代码：放置在 flash / PSRAM中。这类代码的性能要求较低，或者较少被调用。他们会在 flash 擦除的时候被执行，带来一定的开销。
-3. 低优先级代码：放置在 flash / PSRAM 中，并且在 flash 擦除的期间被禁止运行。这类代码的任务优先级应被设置的低于擦除任务，从而避免影响 flash 擦除的速度。
+启用 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 后，缓存将保持启用状态，禁用该选项即可禁用缓存。SPI0 和 SPI1 之间的仲裁由硬件决定。当 SPI1 进行读取等耗时较短的操作时，CPU 和缓存将等待至 SPI1 操作完成。然而，在擦除、页面写入或状态寄存器写入等过程中，如 ``SE``、``PP`` 和 ``WRSR``，自动暂停功能将中断正在进行的 flash 操作，使 CPU 得以在有限的时间内读取缓存及 flash 中的数据。
+
+基于此功能，部分的代码及变量现可存放在 flash/PSRAM 中，同时仍能保证在 flash 擦除期间的正常执行，减少了 IRAM/DRAM 的消耗。
+
+需注意，使用此功能暂停/恢复 flash 时，会导致额外开销。在 flash 擦除期间，频繁触发中断将显著延长擦除时间。为避免这种情况，建议调整 FreeRTOS 任务优先级，仅将实时关键的任务排在擦除操作前，从而确保在合理时间内完成 flash 擦除操作。
+
+代码可以分为以下三类：
+
+1. 关键代码：存放在 IRAM/DRAM 中。这类代码通常有较高的性能要求，与 cache/flash/PSRAM 相关，或者被频繁调用。
+
+2. 缓存访问的代码：存放在 flash/PSRAM 中。这类代码的性能要求较低，或者较少被调用。flash 擦除时将执行这类代码，导致一定的开销。
+
+3. 低优先级代码：存放在 flash/PSRAM 中，且在 flash 擦除期间禁止运行。这类代码的任务优先级应低于擦除操作，避免影响 flash 擦除的速度。
+
+关于 flash 自动暂停功能的用法和对应的响应时间延迟，请参考 :example:`system/flash_suspend` 示例。
+
+.. note::
+
+    由于 flash 自动暂停功能极度依赖时序，其多用作为一种优化方案，而非万能解法。例如 LCD 刷新、蓝牙、Wi-Fi 等场景对实时系统要求较高、或需要频繁触发中断，所以此方案并不适用。建议参照以下步骤，选择搭配 flash 自动暂停功能使用的 ISR 类型：
+
+    .. wavedrom:: /../_static/diagrams/spi_flash/flash_auto_suspend_timing.json
+
+    需注意图中的两个关键值：
+
+    1. ISR 时间 (ISR time)：ISR 时间不能过长，需小于 ``IWDT`` 中设置的值。ISR 时间会显著增加擦除/写入操作的完成时间。
+
+    2. ISR 间隔时间 (ISR interval)：由于不能频繁触发 ISR，需格外注意 **ISR 间隔时间减去 ISR 时间后的剩余时间** （图中 b 点至 c 点的距离）。在此期间，SPI1 会发送恢复命令重新启动操作，所需准备时间 ``tsus`` 的典型值约为 **40 us**。如果在 SPI1 完成恢复操作前接收到了新的暂停命令，可能导致 CPU 饥饿，触发 ``TWDT``。
+
+    此外，flash 暂停可能延迟。CPU 和缓存通过 SPI0 频繁访问 flash，且 SPI1 频繁发送暂停命令时，会导致 MSPI 数据传输效率下降。可以通过在内部使用 **锁** 来避免此种情况。当 SPI1 发送暂停命令时，SPI0 将接管内存 SPI 总线并启用锁。SPI0 完成数据传输后，在锁延迟时间结束前，都将保有对内存 SPI 总线的控制权。在此锁延迟期间，如果接收到其他 SPI0 事务，则该 SPI0 事务将正常进行，并开启新一轮锁延迟周期。如无其他 SPI0 事务，则 SPI0 释放内存总线并启动 SPI0/1 仲裁。

docs/zh_CN/api-reference/peripherals/spi_flash/index.rst

@@ -19,7 +19,7 @@ spi_flash 组件提供外部 flash 数据读取、写入、擦除和内存映射
 
     大多数 ``esp_flash_*`` API 使用 SPI1，SPI2 等外设而非通过 SPI0 上的 cache。这使得它们不仅能访问主 flash，也能访问外部 flash 。
 
-    而由于 cache 的限制，所有经过 cache 的操作都只能对主 flash 进行。这些操作的地址同样受到 cache 能力的限制。Cache 无法访问外部 flash 或者高于它能力的地址段。这些 cache 操作包括：mmap ，加密读写，执行代码或者访问在 flash 中的变量。
+    而由于 cache 的限制，所有经过 cache 的操作都只能对主 flash 进行。这些操作的地址同样受到 cache 能力的限制。Cache 无法访问外部 flash 或者高于它能力的地址段。这些 cache 操作包括：mmap、加密读写、执行代码或者访问在 flash 中的变量。
 
 .. note::
 
@@ -237,6 +237,7 @@ OS 函数层目前支持访问锁和延迟的方法。
 ------------
 
 必须确保操作期间，两个 CPU 均未从 flash 运行代码，实现细节如下：
+
 - 单核模式下，SDK 在执行 flash 操作前将禁用中断或调度算法。
 - 双核模式下，SDK 需确保两个 CPU 均未运行 flash 代码。