doc: add flash suspend feature to iram usage doc

docs/en/api-reference/storage/auto_suspend.inc

@@ -1,11 +1,14 @@
-.. _auto_suspend:
+.. _auto-suspend:
 
-When auto suspend is enabled
-----------------------------
+Flash Auto Suspend Feature
+--------------------------
 
 .. important::
 
-    The flash chip you are using must have suspend/resume function, even then, and not all flash chips with suspend/resume support auto-suspend on {IDF_TARGET_NAME}. If you use suspend feature on a 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. Even then, thorough testing is recommended.
+    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).
+
+    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).
 
@@ -15,9 +18,8 @@ When auto suspend is enabled
 
     4. When the flash is successfully resumed, another suspend can be sent immediately at this state.
 
-When auto suspend is enabled, the cache will be kept enabled while accessing the SPI1 bus (e.g. erasing/writing/reading main flash). The hardware handles the arbitration between them.
 
-If SPI1 operation is short (like reading operation), the CPU and the cache will wait until the SPI1 operation is done. However if it's an erasing, auto suspend will happen, interrupting the erasing, making the CPU able to read from cache in 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 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.
 
@@ -31,3 +33,5 @@ In other words, there are three kinds of code:
 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` .

docs/en/api-reference/storage/spi_flash_concurrency.rst

@@ -1,3 +1,5 @@
+.. _concurrency-constraints-flash:
+
 Concurrency Constraints for flash on SPI1
 =========================================
 
@@ -9,33 +11,43 @@ The SPI0/1 bus is shared between the instruction & data cache (for firmware exec
 
 .. only:: esp32c3
 
-    On {IDF_TARGET_NAME}, the config option :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` (enabled by default) allows the cache to read flash & PSRAM concurrently with SPI1 operations. See :ref:`auto_suspend` for more details.
+    On {IDF_TARGET_NAME}, the config option :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` (enabled by default) allows the cache to read flash concurrently with SPI1 operations. See :ref:`auto-suspend` for more details.
 
     If this option is disabled, the caches must be disabled while reading/writing/erasing operations. There are some constraints using driver on the SPI1 bus, see :ref:`impact_disabled_cache`. This constraints will cause more IRAM/DRAM usages.
 
+
 .. _impact_disabled_cache:
 
 When the caches are disabled
 ----------------------------
 
-This means that all CPUs must be running code from IRAM and must only be reading data from DRAM while flash write operations occur. If you use the API functions documented here, then the caches will be disabled automatically and transparently. However, note that it will have some performance impact on other tasks in the system.
+Under this condition, all CPUs should always execute code and access data from internal RAM. The APIs documented in this file will disable the caches automatically and transparently.
 
-There are no such constraints and impacts for flash chips on other SPI buses than SPI0/1.
+.. only:: esp32c3
 
-For differences between IRAM, DRAM, and flash cache, please refer to the :ref:`application memory layout <memory-layout>` documentation.
+    However, when :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is enabled, these APIs won't disable the caches. The hardware will handle the arbitration between them.
 
 .. only:: not CONFIG_FREERTOS_UNICORE
 
-    To avoid reading flash cache accidentally, when one CPU initiates a flash write or erase operation, the other CPU is put into a blocked state, and all non-IRAM-safe interrupts are disabled on all CPUs until the flash operation completes.
+    The way that these APIs disable the caches will suspend all the other tasks. Besides, all non-IRAM-safe interrupts will be disabled. The other core will be polling in a busy loop. These will be restored until the Flash operation completes.
+
+.. only:: CONFIG_FREERTOS_UNICORE
+
+    The way that these APIs disable the caches will also disable non-IRAM-safe interrupts. These will be restored until the Flash operation completes.
 
 See also :ref:`esp_flash_os_func`, :ref:`spi_bus_lock`.
 
+There are no such constraints and impacts for flash chips on other SPI buses than SPI0/1.
+
+For differences between internal RAM (e.g. IRAM, DRAM) and flash cache, please refer to the :ref:`application memory layout <memory-layout>` documentation.
+
+
 .. _iram-safe-interrupt-handlers:
 
 IRAM-Safe Interrupt Handlers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you have an interrupt handler that you want to execute while a flash operation is in progress (for example, for low latency operations), set the ``ESP_INTR_FLAG_IRAM`` flag when the :doc:`interrupt handler is registered </api-reference/system/intr_alloc>`.
+For interrupt handlers which need to execute when the cache is disabled (e.g., for low latency operations), set the ``ESP_INTR_FLAG_IRAM`` flag when the :doc:`interrupt handler is registered </api-reference/system/intr_alloc>`.
 
 You must ensure that all data and functions accessed by these interrupt handlers, including the ones that handlers call, are located in IRAM or DRAM. See :ref:`how-to-place-code-in-iram`.
 
@@ -45,6 +57,12 @@ If a function or symbol is not correctly put into IRAM/DRAM, and the interrupt h
 
    When working with string in ISRs, it is not advised to use ``printf`` and other output functions. For debugging purposes, use :cpp:func:`ESP_DRAM_LOGE` and similar macros when logging from ISRs. Make sure that both ``TAG`` and format string are placed into ``DRAM`` in that case.
 
+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
 
    .. include:: auto_suspend.inc