From 5bf739aef3cf23789b23c479617de226ee3cfa04 Mon Sep 17 00:00:00 2001 From: Cao Sen Miao Date: Mon, 20 Dec 2021 17:24:13 +0800 Subject: [PATCH] spi_flash: Add hint for explaining erase yield --- components/spi_flash/Kconfig | 5 +++++ docs/en/api-reference/storage/spi_flash.rst | 12 ++++++++++++ docs/en/api-reference/system/wdts.rst | 9 +++++++++ 3 files changed, 26 insertions(+) diff --git a/components/spi_flash/Kconfig b/components/spi_flash/Kconfig index 9a56da7604..9fa4f7f543 100644 --- a/components/spi_flash/Kconfig +++ b/components/spi_flash/Kconfig @@ -131,6 +131,11 @@ menu "SPI Flash driver" help This allows to yield the CPUs between erase commands. Prevents starvation of other tasks. + Please use this configuration together with ``SPI_FLASH_ERASE_YIELD_DURATION_MS`` and + ``SPI_FLASH_ERASE_YIELD_TICKS`` after carefully checking flash datasheet to avoid a + watchdog timeout. + For more information, please check `SPI Flash API` reference documenation + under section `OS Function`. config SPI_FLASH_ERASE_YIELD_DURATION_MS int "Duration of erasing to yield CPUs (ms)" diff --git a/docs/en/api-reference/storage/spi_flash.rst b/docs/en/api-reference/storage/spi_flash.rst index 548f39b0cb..8edaaf2142 100644 --- a/docs/en/api-reference/storage/spi_flash.rst +++ b/docs/en/api-reference/storage/spi_flash.rst @@ -210,6 +210,18 @@ The delay is used by some long operations which requires the master to wait or p The top API wraps these the chip driver and OS functions into an entire component, and also provides some argument checking. +OS functions can also help to avoid a watchdog timeout when erasing large flash areas. During this time, the CPU is occupied with the flash erasing task. This stops other tasks from being executed. Among these tasks is the idle task to feed the watchdog timer (WDT). If the configuration option :ref:`CONFIG_ESP_TASK_WDT_PANIC` is selected and the flash operation time is longer than the watchdog timeout period, the system will reboot. + +It's pretty hard to totally eliminate this risk, because the erasing time varies with different flash chips, making it hard to be compatible in flash drivers. Therefore, users need to pay attention to it. Please use the following guidelines: + +1. It is recommended to enable the :ref:`CONFIG_SPI_FLASH_YIELD_DURING_ERASE` option to allow the scheduler to re-schedule during erasing flash memory. Besides, following parameters can also be used. + +- Increase :ref:`CONFIG_SPI_FLASH_ERASE_YIELD_TICKS` or decrease :ref:`CONFIG_SPI_FLASH_ERASE_YIELD_DURATION_MS` in menuconfig. +- You can also increase :ref:`CONFIG_ESP_TASK_WDT_TIMEOUT_S` in menuconfig for a larger watchdog timeout period. However, with larger watchdog timeout period, previously detected timeouts may no longer be detected. + +2. Please be aware of the consequences of enabling the :ref:`CONFIG_ESP_TASK_WDT_PANIC` option when doing long-running SPI flash operations which will trigger the panic handler when it times out. However, this option can also help dealing with unexpected exceptions in your application. Please decide whether this is needed to be enabled according to actual condition. + +3. During your development, please carefully review the actual flash operation according to the specific requirements and time limits on erasing flash memory of your projects. Always allow reasonable redundancy based on your specific product requirements when configuring the flash erasing timeout threshold, thus improving the reliability of your product. See Also -------- diff --git a/docs/en/api-reference/system/wdts.rst b/docs/en/api-reference/system/wdts.rst index 372a6bde4c..fd9dc46bf7 100644 --- a/docs/en/api-reference/system/wdts.rst +++ b/docs/en/api-reference/system/wdts.rst @@ -99,6 +99,15 @@ single task will need to monopolise the CPU (for example, if you expect the app intensive calculation and should not yield to other tasks). It is also possible to change this timeout at runtime by calling :cpp:func:`esp_task_wdt_init`. +.. note:: + + It might cause severe watchdog timeout issue when erasing large flash areas. Here are two methods to avoid this issue: + + - Increase :ref:`CONFIG_ESP_TASK_WDT_TIMEOUT_S` in menuconfig for a larger watchdog timeout period. + - You can also call :cpp:func:`esp_task_wdt_init` to increase the watchdog timeout period before erasing a large flash area. + + For more information, you can refer to :doc:`SPI Flash <../storage/spi_flash>`. + The following config options control TWDT configuration at startup. They are all enabled by default: {IDF_TARGET_IDLE_TASK:default="Idle task", esp32="CPU0 Idle task", esp32s3="CPU0 Idle task"}