Merge branch 'feature/update_config_wdt_desc' into 'master'

feat(bootloader): Update WDT Kconfig description

Closes IDFGH-11913 and IDFGH-7850

See merge request espressif/esp-idf!28568

components/bootloader/Kconfig.projbuild

@@ -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 wdt_hal_feed() for resetting counter of RTC_WDT.
-            Use function rtc_wdt_disable() for disabling 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)"

docs/en/api-guides/bootloader.rst

@@ -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 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 :ref:`CONFIG_BOOTLOADER_WDT_ENABLE` is set (which is the default behavior), RTC_WDT is re-enabled. It tracks the time from the bootloader is enabled until the user's main function is called. In this scenario, 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 :ref:`app-hardware-watchdog-timers` to learn how RTC_WDT is used in the application.
 
 .. _bootloader-size:
 

docs/en/api-guides/hardware-abstraction.rst

@@ -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:
 

docs/en/api-reference/system/wdts.rst

@@ -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
 

docs/zh_CN/api-guides/bootloader.rst

@@ -129,14 +129,16 @@ ROM 中的 :ref:`first-stage-bootloader` 从 flash 中读取 :ref:`second-stage-
 
 请参考 :doc:`OTA API 参考文档 </api-reference/system/ota>` 中的 :ref:`app_rollback` 和 :ref:`anti-rollback` 章节。
 
+.. _bootloader-watchdog:
+
 看门狗
 ----------
 
-默认情况下，硬件 RTC 看门狗定时器在引导加载程序运行时保持运行，如果 9 秒后没有应用程序成功启动，它将自动重置芯片。
+芯片配备两组看门狗定时器：主系统看门狗定时器 (MWDT_WDT) 和 RTC 看门狗定时器 (RTC_WDT)。芯片上电时，两组看门狗定时器都会被启用，但在引导加载程序中，两组看门狗定时器都会被禁用。设置 :ref:`CONFIG_BOOTLOADER_WDT_ENABLE` （默认设置）可以重新启用 RTC 看门狗定时器，用于跟踪从启用引导加载程序到调用用户主函数的时间。此期间内 RTC 看门狗定时器始终可用，并且如果在 9 秒内没有应用程序成功启动，则 RTC 看门狗定时器会自动重置芯片。这一功能可以有效防止启动过程中由于电源不稳定而导致的死机。
 
 - 可以通过设置 :ref:`CONFIG_BOOTLOADER_WDT_TIME_MS` 并重新编译引导加载程序来调整超时时间。
-- 可以通过调整应用程序的行为使 RTC 看门狗在应用程序启动后保持启用。看门狗需要由应用程序显示地重置（即“喂狗”），以避免重置。为此，请设置 :ref:`CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE` 选项，根据需要修改应用程序，然后重新编译应用程序。
 - 通过禁用 :ref:`CONFIG_BOOTLOADER_WDT_ENABLE` 设置并重新编译引导加载程序，可以在引导加载程序中禁用 RTC 看门狗，但并不建议这样做。
+- 请参阅 :ref:`app-hardware-watchdog-timers`，了解如何在应用程序中使用 RTC_WDT。
 
 .. _bootloader-size:
 

docs/zh_CN/api-guides/hardware-abstraction.rst

@@ -140,6 +140,29 @@ HAL 将外设的操作过程建模成一组通用步骤，其中每个步骤都
     // 去初始化 WDT
     void wdt_hal_deinit(wdt_hal_context_t *hal);
 
+.. _hw-abstraction-hal-layer-disable-rtc-wdt:
+
+禁用 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:
+
+重置 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_feed(&rtc_wdt_ctx);
+    wdt_hal_write_protect_enable(&rtc_wdt_ctx);
 
 HAL 函数通常具有以下特点：
 

docs/zh_CN/api-reference/system/wdts.rst

@@ -10,6 +10,7 @@ ESP-IDF 支持以下类型的看门狗定时器：
 
 .. list::
 
+    - 硬件看门狗定时器
     - 中断看门狗定时器 (IWDT)
     - 任务看门狗定时器 (TWDT)
     :SOC_XT_WDT_SUPPORTED: - XTAL32K 看门狗定时器 (Crystal 32K 看门狗定时器，即 XTWDT)
@@ -18,6 +19,32 @@ ESP-IDF 支持以下类型的看门狗定时器：
 
 通过 :ref:`project-configuration-menu` 可启用各种看门狗定时器。其中，TWDT 也可以在程序运行时启用。
 
+.. _app-hardware-watchdog-timers:
+
+硬件看门狗定时器
+----------------
+
+芯片有两组看门狗定时器：
+
+.. list::
+
+    :not esp32c2: - 主系统看门狗定时器 (MWDT_WDT) - 用于中断看门狗定时器 (IWDT) 和任务看门狗定时器 (TWDT)。
+    :esp32c2: - 主系统看门狗定时器 (MWDT_WDT) - 用于中断看门狗定时器 (IWDT)。
+    - RTC 看门狗定时器 (RTC_WDT) - 用于跟踪从上电到执行用户主函数的启动时间（默认情况下，RTC 看门狗在执行用户主函数之前会被立即禁用）。
+
+请参阅 :ref:`bootloader-watchdog` 小节，了解如何在引导加载程序中使用看门狗。
+
+用户可以调整应用程序行为，使 RTC 看门狗在应用程序启动后保持启用状态。应用程序需要显式重置（即喂狗）或禁用看门狗，以避免芯片重置。具体而言，用户可设置 :ref:`CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE` 选项，根据需要修改应用程序并重新编译。此过程中应使用以下 API：
+
+.. list::
+
+    - :cpp:func:`wdt_hal_disable`：参考 :ref:`hw-abstraction-hal-layer-disable-rtc-wdt`
+    - :cpp:func:`wdt_hal_feed`：参考 :ref:`hw-abstraction-hal-layer-feed-rtc-wdt`
+    :esp32 or esp32s2: - :cpp:func:`rtc_wdt_feed`
+    :esp32 or esp32s2: - :cpp:func:`rtc_wdt_disable`
+
+如果未能及时重置或禁用 RTC_WDT，芯片将自动重置。请参阅 :ref:`RTC-Watchdog-Timeout` 了解更多信息。
+
 中断看门狗定时器 (IWDT)
 -------------------------------
 
@@ -29,7 +56,7 @@ IWDT 的目的是，确保中断服务例程 (ISR) 运行不会受到长时间
 - 临界区（也会禁用中断）
 - 其他相同或更高优先级的 ISR，在完成前会阻止相同或较低优先级的 ISR
 
-IWDT 利用 {IDF_TARGET_IWDT_TIMER_GROUP} 中的看门狗定时器作为其底层硬件定时器，并在每个 CPU 上使用 FreeRTOS 时钟滴答中断，即 tick 中断。如果某个 CPU 上的 tick 中断没有在 IWDT 超时前运行，就表明该 CPU 上的 ISR 运行受阻（参见上文原因列表）。
+IWDT 利用 {IDF_TARGET_IWDT_TIMER_GROUP} 中的 MWDT_WDT 看门狗定时器作为其底层硬件定时器，并在每个 CPU 上使用 FreeRTOS 时钟滴答中断，即 tick 中断。如果某个 CPU 上的 tick 中断没有在 IWDT 超时前运行，就表明该 CPU 上的 ISR 运行受阻（参见上文原因列表）。
 
 当 IWDT 超时后，默认操作是调用紧急处理程序 (Panic Handler)，并显示 出错原因（ ``Interrupt wdt timeout on CPU0`` 或 ``Interrupt wdt timeout on CPU1``，视情况而定）。根据紧急处理程序的配置行为（参见 :ref:`CONFIG_ESP_SYSTEM_PANIC`），用户可通过回溯、OpenOCD、gdbstub 等来调试 IWDT 超时问题，也可以重置芯片（这在生产环境中可能是首选）。
 
@@ -63,7 +90,7 @@ IWDT 利用 {IDF_TARGET_IWDT_TIMER_GROUP} 中的看门狗定时器作为其底
 
 .. only:: not esp32c2
 
-    TWDT 是基于定时器组 0 中的硬件看门狗定时器构建的。超时发生时会触发中断。
+    TWDT 是基于定时器组 0 中的 MWDT_WDT 看门狗定时器构建的。超时发生时会触发中断。
 
 .. only:: esp32c2