Merge branch 'bugfix/flash_suspend_restriction' into 'master'

spi_flash: make suspend off by default and add more information for using suspend

See merge request espressif/esp-idf!12812

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

@@ -3,6 +3,18 @@
 When auto suspend is enabled
 ----------------------------
 
+.. 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. SUS bit in status registers should in SR2 bit7 (or SR bit15)(This is caused by the restriction of out software implementation).
+
+    2. Suspend command is 75H, resume command is 7AH(This is caused by the restriction of out software implementation).
+
+    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.
+
+    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.

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

@@ -4,6 +4,15 @@
 当使能 flash 擦除的自动暂停
 --------------------------------------
 
+.. important:
+
+    您使用的 flash 需要有 suspend/resume 功能，而且不是所有具备 suspend/resume 的 flash 都可以在 {IDF_TARGET_NAME} 上使用自动暂停功能。如果您在不支持自动暂停的 flash 上使用该功能，可能会造成严重的程序崩溃。因此，我们强烈建议您在使用前阅读对应的 flash 的数据手册，确保您的 flash 可以满足如下条件, 即使这样，我们也建议您对 flash 做完整的测试：
+
+    1. flash 状态寄存器中的 SUS bit 应当位于 SR2 bit7 ( 或者是 SR bit15 )(这是当前软件的实现限制)。
+    2. 暂停的命令是 75H，恢复的命令是 7AH(这是当前软件的实现限制)。
+    3. 当 flash 芯片成功暂停之后，除了正在被擦除的段或块外的任何 flash 地址中的的内容，都可以被正确的读取。恢复命令也可以在这种状态下立即下达。
+    4. 当 flash 已经从暂停的模式恢复后，另一个暂停命令可以立即下达。
+
 当使能 flash 擦除的自动暂停，访问 SPI1 时（如擦除、写入、读取主 flash ） cache 便无需被禁用。硬件会负责仲裁二者的访问。
 
 当 SPI1 操作较短时（如读取操作）， CPU 和 cache 会等待直到 SPI1 的操作结束。然而对于一个擦除操作，自动暂停会发生并打断擦除操作，允许 CPU 能够在有限时间内从 cache 读取数据。