diff --git a/docs/_static/diagrams/spi_flash/flash_auto_suspend_timing.json b/docs/_static/diagrams/spi_flash/flash_auto_suspend_timing.json new file mode 100644 index 0000000000..b9abb1b3cb --- /dev/null +++ b/docs/_static/diagrams/spi_flash/flash_auto_suspend_timing.json @@ -0,0 +1,23 @@ +{ + "signal": [ + { + "name": "SPI1(flash)", + "wave": "x73...|.8x........8x3..", + "data": ["PE", "Programming...", "SUS", "RES", "CONTINUE.."], + "node":".........E.........FG" }, + { + "name": "SPI0(cache)", + "wave": "x.........3...|.x......", + "data":["READ"], "node": "..........D" }, + { + "name": "ISR", "wave": "0......1.........0...1.", + "data":["1"], "node": ".......a.........b...c" }, + { + "node": ".......A.............C"} + ], + "edge": [ + "A+C ISR interval", + "E~D tsus", "F~G tsus", + "a~b ISR time" + ] +} 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 74460ecff6..59f48c6886 100644 --- a/docs/en/api-reference/peripherals/spi_flash/auto_suspend.inc +++ b/docs/en/api-reference/peripherals/spi_flash/auto_suspend.inc @@ -35,3 +35,16 @@ In other words, there are three kinds of code: 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` . + +.. 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. + + .. wavedrom:: /../_static/diagrams/spi_flash/flash_auto_suspend_timing.json + + 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. + + 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. diff --git a/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst b/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst index adb95766ad..3885e71285 100644 --- a/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst +++ b/docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst @@ -76,7 +76,7 @@ Non-IRAM-Safe Interrupt Handlers If the ``ESP_INTR_FLAG_IRAM`` flag is not set when registering, the interrupt handler will not get executed when the caches are disabled. Once the caches are restored, the non-IRAM-safe interrupts will be re-enabled. After this moment, the interrupt handler will run normally again. This means that as long as caches are disabled, users won't see the corresponding hardware event happening. -.. only:: esp32c3 +.. only:: esp32c3 or esp32c2 or esp32s3 .. include:: auto_suspend.inc 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 7ead7b2bf8..2f1fe58917 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 @@ -28,17 +28,24 @@ Some features are not supported on all ESP chips and Flash chips. You can check Auto Suspend & Resume --------------------- -.. only:: esp32c3 - - You can refer to :ref:`auto-suspend` for more information about this feature. The support list is as follows. +The support list is as follows. ESP Chips List: 1. ESP32C3 +2. ESP32C2 +3. ESP32S3 Flash Chips List: 1. XM25QxxC series. +2. GD25QxxE series. + +.. only:: esp32c3 or esp32c2 or esp32s3 + + .. attention:: + + There are multiple limitations about the auto-suspend feature, please do read :ref:`auto-suspend` for more information before you enable this feature. Flash unique ID --------------- diff --git a/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst b/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst index 160cf9f49a..ffb387f4e5 100644 --- a/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst +++ b/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst @@ -76,7 +76,7 @@ IRAM 安全中断处理程序 如果在注册时没有设置 `ESP_INTR_FLAG_IRAM` 标志，当 cache 被禁用时，将不会执行中断处理程序。一旦 cache 恢复，非 IRAM 安全的中断将重新启用，中断处理程序随即再次正常运行。这意味着，只要 cache 被禁用，将不会发生相应的硬件事件。 -.. only:: esp32c3 +.. only:: esp32c3 or esp32c2 or esp32s3 .. include:: auto_suspend.inc