feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

feat(doc): Update the WDT article

Browse Source 
Closes https://github.com/espressif/esp-idf/issues/12995
This commit is contained in:
KonstantinKondrashov
2024-01-18 18:34:14 +08:00
committed by BOT
parent afa876fac9
commit c40afaf4ad
4 changed files with 61 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
components/bootloader/Kconfig.projbuild
View File

@@ -293,8 +293,11 @@ menu "Bootloader config"
If this option is not set (default), then rtc_wdt will be disabled by ESP-IDF before calling
the app_main() function.
Use function rtc_wdt_feed() for resetting counter of rtc_wdt.
Use function rtc_wdt_disable() for disabling rtc_wdt.
Use function wdt_hal_feed() for resetting counter of RTC_WDT.
For esp32/s2 you can also use rtc_wdt_feed().
Use function wdt_hal_disable() for disabling RTC_WDT.
For esp32/s2 you can also use rtc_wdt_disable().
config BOOTLOADER_WDT_TIME_MS
int "Timeout for RTC watchdog (ms)"

6
docs/en/api-guides/bootloader.rst
View File

@@ -129,14 +129,16 @@ Rollback and anti-rollback features must be configured in the bootloader as well
Consult the :ref:`app_rollback` and :ref:`anti-rollback` sections in the :doc:`OTA API reference document </api-reference/system/ota>`.
.. _bootloader-watchdog:
Watchdog
--------
By default, the hardware RTC Watchdog timer remains running while the bootloader is running and will automatically reset the chip if no app has successfully started after 9 seconds.
The chips come equipped with two groups of watchdog timers: Main System Watchdog Timer (MWDT_WDT) and the RTC Watchdog Timer (RTC_WDT). Both watchdog timer groups are enabled when the chip is powered up. However, in the bootloader, they will both be disabled. If the :ref:`CONFIG_BOOTLOADER_WDT_ENABLE` is set (which is the default behavior), the RTC_WDT is re-enabled. It tracks time from the bootloader until the user's main function is called. In this scenario, the RTC_WDT remains operational and will automatically reset the chip if no application successfully starts within 9 seconds. This functionality is particularly useful in preventing lockups caused by an unstable power source during startup.
- The timeout period can be adjusted by setting :ref:`CONFIG_BOOTLOADER_WDT_TIME_MS` and recompiling the bootloader.
- The app's behaviour can be adjusted so the RTC Watchdog remains enabled after app startup. The Watchdog would need to be explicitly reset (i.e., fed) by the app to avoid a reset. To do this, set the :ref:`CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE` option, modify the app as needed, and then recompile the app.
- The RTC Watchdog can be disabled in the bootloader by disabling the :ref:`CONFIG_BOOTLOADER_WDT_ENABLE` setting and recompiling the bootloader. This is not recommended.
- See the :ref:`app-hardware-watchdog-timers`, how ``RTC_WDT`` is used in the application.
.. _bootloader-size:

23
docs/en/api-guides/hardware-abstraction.rst
View File

@@ -140,6 +140,29 @@ The following HAL function examples are selected from the Watchdog Timer HAL as
// De-initialize the WDT
void wdt_hal_deinit(wdt_hal_context_t *hal);
.. _hw-abstraction-hal-layer-disable-rtc-wdt:
To disable RTC_WDT
^^^^^^^^^^^^^^^^^^
.. code-block:: c
wdt_hal_context_t rtc_wdt_ctx = RWDT_HAL_CONTEXT_DEFAULT();
wdt_hal_write_protect_disable(&rtc_wdt_ctx);
wdt_hal_disable(&rtc_wdt_ctx);
wdt_hal_write_protect_enable(&rtc_wdt_ctx);
.. _hw-abstraction-hal-layer-feed-rtc-wdt:
To reset the RTC_WDT counter
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: c
wdt_hal_context_t rtc_wdt_ctx = RWDT_HAL_CONTEXT_DEFAULT();
wdt_hal_write_protect_disable(&rtc_wdt_ctx);
wdt_hal_feed(&rtc_wdt_ctx);
wdt_hal_write_protect_enable(&rtc_wdt_ctx);
HAL functions generally have the following characteristics:

31
docs/en/api-reference/system/wdts.rst
View File

@@ -10,6 +10,7 @@ ESP-IDF supports multiple types of watchdogs:
.. list::
- Hardware Watchdog Timers
- Interrupt Watchdog Timer (IWDT)
- Task Watchdog Timer (TWDT)
:SOC_XT_WDT_SUPPORTED: - XTAL32K Watchdog Timer (Crystal 32K Watchdog Timer, i.e., XTWDT)
@@ -18,6 +19,32 @@ The Interrupt Watchdog is responsible for ensuring that ISRs (Interrupt Service
The various watchdog timers can be enabled using the :ref:`project-configuration-menu`. However, the TWDT can also be enabled during runtime.
.. _app-hardware-watchdog-timers:
Hardware Watchdog Timers
------------------------
The chips have two groups of watchdog timers:
.. list::
:not esp32c2: - Main System Watchdog Timer (``MWDT_WDT``) - used by Interrupt Watchdog Timer (``IWDT``) and Task Watchdog Timer (TWDT).
:esp32c2: - Main System Watchdog Timer (``MWDT_WDT``) - used by Interrupt Watchdog Timer (``IWDT``).
- RTC Watchdog Timer (``RTC_WDT``) - used to track the boot time from power-up until the user's main function (by default RTC Watchdog is disabled immediately before the user's main function).
Refer to the :ref:`bootloader-watchdog` section to understand how watchdogs are utilized in the bootloader.
The app's behaviour can be adjusted so the RTC Watchdog remains enabled after app startup. The Watchdog would need to be explicitly reset (i.e., fed) or disabled by the app to avoid the chip reset. To do this, set the :ref:`CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE` option, modify the app as needed, and then recompile the app. In this case, the following APIs should be used:
.. list::
- :cpp:func:`wdt_hal_disable`, see :ref:`hw-abstraction-hal-layer-disable-rtc-wdt`,
- :cpp:func:`wdt_hal_feed`, see :ref:`hw-abstraction-hal-layer-feed-rtc-wdt`,
:esp32 or esp32s2: - :cpp:func:`rtc_wdt_feed`,
:esp32 or esp32s2: - :cpp:func:`rtc_wdt_disable`.
If ``RTC_WDT`` is not reset/disabled in time, the chip will be automatically reset. See :ref:`RTC-Watchdog-Timeout` for more information.
Interrupt Watchdog Timer (IWDT)
-------------------------------
@@ -29,7 +56,7 @@ The purpose of the IWDT is to ensure that interrupt service routines (ISRs) are
- Critical Sections (also disables interrupts)
- Other same/higher priority ISRs which block same/lower priority ISRs from running
The IWDT utilizes the watchdog timer in {IDF_TARGET_IWDT_TIMER_GROUP} as its underlying hardware timer and leverages the FreeRTOS tick interrupt on each CPU to feed the watchdog timer. If the tick interrupt on a particular CPU is not run at within the IWDT timeout period, it is indicative that something is blocking ISRs from being run on that CPU (see the list of reasons above).
The IWDT utilizes the ``MWDT_WDT`` watchdog timer in {IDF_TARGET_IWDT_TIMER_GROUP} as its underlying hardware timer and leverages the FreeRTOS tick interrupt on each CPU to feed the watchdog timer. If the tick interrupt on a particular CPU is not run at within the IWDT timeout period, it is indicative that something is blocking ISRs from being run on that CPU (see the list of reasons above).
When the IWDT times out, the default action is to invoke the panic handler and display the panic reason as ``Interrupt wdt timeout on CPU0`` or ``Interrupt wdt timeout on CPU1`` (as applicable). Depending on the panic handler's configured behavior (see :ref:`CONFIG_ESP_SYSTEM_PANIC`), users can then debug the source of the IWDT timeout (via the backtrace, OpenOCD, gdbstub etc) or simply reset the chip (which may be preferred in a production environment).
@@ -63,7 +90,7 @@ The Task Watchdog Timer (TWDT) is used to monitor particular tasks, ensuring tha
.. only:: not esp32c2
The TWDT is built around the Hardware Watchdog Timer in Timer Group 0. When a timeout occurs, an interrupt is triggered.
The TWDT is built around the ``MWDT_WDT`` watchdog timer in Timer Group 0. When a timeout occurs, an interrupt is triggered.
.. only:: esp32c2