From efd344e4b34a34212e56b7ce5aa08cb3545bfdd4 Mon Sep 17 00:00:00 2001 From: "C.S.M" Date: Fri, 8 May 2026 18:20:47 +0800 Subject: [PATCH] doc(spi_flash): Add more flash suspend information --- .../peripherals/spi_flash/auto_suspend.inc | 27 +++++++++++++++++++ .../spi_flash/spi_flash_optional_feature.rst | 6 ++--- .../peripherals/spi_flash/auto_suspend.inc | 27 +++++++++++++++++++ .../spi_flash/spi_flash_optional_feature.rst | 6 ++--- 4 files changed, 58 insertions(+), 8 deletions(-) diff --git a/docs/en/api-reference/peripherals/spi_flash/auto_suspend.inc b/docs/en/api-reference/peripherals/spi_flash/auto_suspend.inc index beb78d5c534..a4b32d1d101 100644 --- a/docs/en/api-reference/peripherals/spi_flash/auto_suspend.inc +++ b/docs/en/api-reference/peripherals/spi_flash/auto_suspend.inc @@ -50,3 +50,30 @@ Regarding the flash suspend feature usage and corresponding response time delay, The ``tsus`` time mentioned in point 2 can be found by looking through the flash datasheets, usually in the AC CHARACTERISTICS section. Users needs to make sure that the ``tsus`` value obtained from the datasheets is not greater than the :ref:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US` value in Kconfig. 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. + +Advanced Suspend-resume Usage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the default configuration, flash suspend is issued automatically by hardware, and the resume is also handled by hardware at an appropriate moment, while a fixed time delay is used to wait for the suspend command to take effect. This implementation already covers the majority of use cases. However, in scenarios that have stricter requirements on real-time response, performance, or suspend granularity, ESP-IDF also provides additional advanced configuration options for fine-tuning the suspend-resume behavior. + +1. Detect Whether Suspend Has Taken Effect via Flash Register + +Normally, after issuing the suspend command, the hardware waits for a fixed period of time defined by ``tsus`` before handing the memory bus back to SPI0/CPU. Because this delay must be configured according to the worst case given in the datasheet, it is conservative in most situations. + +By enabling :ref:`CONFIG_SPI_FLASH_AUTO_CHECK_SUSPEND_STATUS`, the hardware will instead poll the ``WIP`` bit in the flash status register to determine whether the suspend command has actually taken effect, rather than waiting for the fixed time given by :ref:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US`. Since the actual suspend setup time is usually much shorter than the maximum value listed in the datasheet, this approach can significantly reduce the overhead during suspend and improve overall performance. + +.. important:: + + Before enabling this option, please confirm that the behavior of the ``WIP`` bit after suspend on your flash chip matches the expectation. Most flash chips that support suspend/resume satisfy this requirement, but it is still recommended to consult the corresponding datasheet to verify it. + +2. Software-controlled Flash Resume + +Normally, after the flash is suspended, the hardware will automatically arrange an appropriate moment to send the resume command, allowing the flash to continue its original erase/write operation. This implementation is transparent to software, but it has a side effect: while a high-priority task or interrupt is still running, the hardware may again initiate a suspend/resume sequence, which interrupts those tasks and affects the continuity and timing of their execution. + +By enabling :ref:`CONFIG_SPI_FLASH_SOFTWARE_RESUME`, the hardware auto-resume feature is disabled, and the flash resume operation is instead issued by software at an appropriate point. With this option enabled, once the flash is suspended it will stay suspended until software explicitly resumes it. In the SPI1 wait-idle flow, software actively checks the flash's suspend state, and if it finds the flash in a suspended state, it calls the driver's resume interface to let the flash continue the original operation. This means that the resume command is only issued after the high-priority task or interrupt has truly finished and software has returned to the SPI1 operation context, avoiding repeated bus preemption caused by suspend-resume on high-priority paths. + +Because this mechanism relies on the software layer to perform resume at well-defined execution points, and the current implementation does not provide corresponding protection for multi-core scenarios, this option has the following limitations: + +- It is only supported on single-core scenarios. :ref:`CONFIG_FREERTOS_UNICORE` must be enabled. +- It is an experimental feature and is only visible after :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES` is enabled. +- This feature improves the continuity of interrupt response and the overall application performance. However, it also increases the time needed to complete a single flash operation. diff --git a/docs/en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst b/docs/en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst index 247cff269c3..a112881a16f 100644 --- a/docs/en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst +++ b/docs/en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst @@ -34,15 +34,13 @@ Some features are not supported on all ESP chips and flash chips. You can check Auto Suspend & Resume --------------------- -This feature is only supported on ESP32-S3, ESP32-C2, ESP32-C3, ESP32-C6, and ESP32-H2 for now. - -The support for ESP32-P4 may be added in the future. +This feature is supported on all Espressif chips except ESP32 and ESP32-S2. .. only:: SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND List of flash chips that support this feature: - 1. XM25QxxC series + 1. XM25QxxD series 2. GD25QxxE series 3. FM25Q32 diff --git a/docs/zh_CN/api-reference/peripherals/spi_flash/auto_suspend.inc b/docs/zh_CN/api-reference/peripherals/spi_flash/auto_suspend.inc index 1f465725d26..1fa982112d9 100644 --- a/docs/zh_CN/api-reference/peripherals/spi_flash/auto_suspend.inc +++ b/docs/zh_CN/api-reference/peripherals/spi_flash/auto_suspend.inc @@ -50,3 +50,30 @@ flash 自动暂停功能 对于第 2 点中所提到的 ``tsus`` 时间可以通过翻阅 flash datasheets 查找，通常在 AC CHARACTERISTICS 章节中。用户需要保证从 datasheets 获得的 ``tsus`` 值不大于 :ref:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US` 值。 此外，flash 暂停可能延迟。CPU 和缓存通过 SPI0 频繁访问 flash，且 SPI1 频繁发送暂停命令时，会导致 MSPI 数据传输效率下降。可以通过在内部使用 **锁** 来避免此种情况。当 SPI1 发送暂停命令时，SPI0 将接管内存 SPI 总线并启用锁。SPI0 完成数据传输后，在锁延迟时间结束前，都将保有对内存 SPI 总线的控制权。在此锁延迟期间，如果接收到其他 SPI0 事务，则该 SPI0 事务将正常进行，并开启新一轮锁延迟周期。如无其他 SPI0 事务，则 SPI0 释放内存总线并启动 SPI0/1 仲裁。 + +suspend-resume 进阶用法 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +在默认配置下，flash 暂停由硬件自动发出，恢复也由硬件在合适的时机自动完成，并采用基于固定时间的延迟来等待暂停命令生效。这种实现已经可以满足绝大多数场景。然而在某些对实时性、性能或暂停粒度有更高要求的场景下，ESP-IDF 还提供了进阶配置项，用于精细化控制 suspend-resume 行为。 + +1. 通过 flash 寄存器自动判断暂停是否生效 + +通常情况下，硬件在发出暂停命令后，会按 ``tsus`` 设定的时间延迟一段时间，再开放内存总线给 SPI0/CPU 使用。该延迟必须按 datasheet 中的最坏情况进行设置，因此在大多数情况下都偏保守。 + +通过启用 :ref:`CONFIG_SPI_FLASH_AUTO_CHECK_SUSPEND_STATUS` 后，硬件将通过读取 flash 状态寄存器中的 ``WIP`` 位，来判断暂停命令是否真正生效，而不再依据 :ref:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US` 给出的固定时间进行等待。由于实际的暂停建立时间通常远小于 datasheet 给出的最大值，所以这种方式可以显著降低暂停过程中的开销，提升整体性能。 + +.. important:: + + 使用前需确认所用 flash 在暂停后 ``WIP`` 位的行为符合预期。绝大多数支持 suspend/resume 的 flash 都满足该条件，但仍建议查阅相应 datasheet 进行确认。 + +2. 软件控制的 flash resume + +通常情况下，硬件在 flash 被暂停后，会自动安排合适的时机发送 resume 命令，让 flash 继续完成原有的擦除/写入操作。这种实现对软件透明，但存在一个副作用：在高优先级任务/中断仍在运行时，硬件可能再次发起 suspend/resume 流程，从而打断这些任务，影响其执行的连续性与时序。 + +通过启用 :ref:`CONFIG_SPI_FLASH_SOFTWARE_RESUME` 后，硬件自动 resume 功能将被关闭，flash 的恢复操作改由软件在合适的时机主动发出。此时，flash 在被暂停后将一直保持暂停状态，直到软件显式恢复。在 SPI1 的等待空闲流程中，软件会主动检查 flash 的 suspend 状态，若发现处于暂停状态则调用驱动的 resume 接口让 flash 重新开始原有操作。这意味着只有当高优先级任务或中断真正完成、软件回到 SPI1 操作上下文时，才会发出 resume，从而避免 suspend-resume 行为在高优先级路径上反复抢占总线。 + +由于该机制依赖软件层在确定的执行点完成 resume，且当前实现没有针对多核做相应保护，因此该选项有以下限制： + +- 仅支持单核场景，需要使能 :ref:`CONFIG_FREERTOS_UNICORE`。 +- 属于实验性功能，需要使能 :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES` 后才能可见。 +- 该功能会提升中断响应的连续性，提升应用的性能。但同时，单次操作 flash 的耗时会上升。 diff --git a/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst b/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst index abb1b624517..971961da3fa 100644 --- a/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst +++ b/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst @@ -34,15 +34,13 @@ flash 的可选功能 自动挂起和恢复 -------------- -目前仅有 ESP32-S3、ESP32-C2、ESP32-C3、ESP32-C6 及 ESP32-H2 支持此功能。 - -未来 ESP32-P4 可能会添加此功能。 +乐鑫芯片除 ESP32、ESP32-S2 外，均支持此功能。 .. only:: SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND 支持此功能的 flash 芯片列表： - 1. XM25QxxC 系列 + 1. XM25QxxD 系列 2. GD25QxxE 系列 3. FM25Q32