refactor(brownout): correct names comments in the LL driver

components/bootloader_support/private_include/bootloader_soc.h

@@ -17,13 +17,6 @@ extern "C"
  */
 void bootloader_ana_super_wdt_reset_config(bool enable);
 
-/**
- * @brief Configure analog brownout reset
- *
- * @param enable Boolean to enable or disable brownout reset
- */
-void bootloader_ana_bod_reset_config(bool enable);
-
 /**
  * @brief Configure analog clock glitch reset
  *

components/bootloader_support/src/esp32c2/bootloader_esp32c2.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -37,6 +37,7 @@
 #include "hal/mmu_hal.h"
 #include "hal/cache_hal.h"
 #include "hal/rwdt_ll.h"
+#include "hal/brownout_ll.h"
 
 static const char *TAG = "boot.esp32c2";
 
@@ -81,8 +82,8 @@ static inline void bootloader_ana_reset_config(void)
 {
     //Enable super WDT reset.
     bootloader_ana_super_wdt_reset_config(true);
-    //Enable BOD reset
+    //Enable BOD reset (mode1)
-    bootloader_ana_bod_reset_config(true);
+    brownout_ll_ana_reset_enable(true);
 }
 
 esp_err_t bootloader_init(void)
@@ -138,7 +139,7 @@ esp_err_t bootloader_init(void)
     }
 #endif // !CONFIG_APP_BUILD_TYPE_RAM
 
-    // check whether a WDT reset happend
+    // check whether a WDT reset happened
     bootloader_check_wdt_reset();
     // config WDT
     bootloader_config_wdt();

components/bootloader_support/src/esp32c2/bootloader_soc.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -18,17 +18,6 @@ void bootloader_ana_super_wdt_reset_config(bool enable)
     }
 }
 
-void bootloader_ana_bod_reset_config(bool enable)
-{
-    REG_CLR_BIT(RTC_CNTL_FIB_SEL_REG, RTC_CNTL_FIB_BOD_RST);
-
-    if (enable) {
-        REG_SET_BIT(RTC_CNTL_BROWN_OUT_REG, RTC_CNTL_BROWN_OUT_ANA_RST_EN);
-    } else {
-        REG_CLR_BIT(RTC_CNTL_BROWN_OUT_REG, RTC_CNTL_BROWN_OUT_ANA_RST_EN);
-    }
-}
-
 //Not supported but common bootloader calls the function. Do nothing
 void bootloader_ana_clock_glitch_reset_config(bool enable)
 {

components/bootloader_support/src/esp32c3/bootloader_esp32c3.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -42,6 +42,7 @@
 #include "hal/cache_hal.h"
 #include "hal/efuse_hal.h"
 #include "hal/rwdt_ll.h"
+#include "hal/brownout_ll.h"
 
 static const char *TAG = "boot.esp32c3";
 
@@ -106,18 +107,18 @@ static inline void bootloader_ana_reset_config(void)
         case 0:
         case 1:
             //Disable BOD and GLITCH reset
-            bootloader_ana_bod_reset_config(false);
+            brownout_ll_ana_reset_enable(false);
             bootloader_ana_clock_glitch_reset_config(false);
             break;
         case 2:
             //Enable BOD reset. Disable GLITCH reset
-            bootloader_ana_bod_reset_config(true);
+            brownout_ll_ana_reset_enable(true);
             bootloader_ana_clock_glitch_reset_config(false);
             break;
         case 3:
         default:
             //Enable BOD, and GLITCH reset
-            bootloader_ana_bod_reset_config(true);
+            brownout_ll_ana_reset_enable(true);
             bootloader_ana_clock_glitch_reset_config(true);
             break;
     }
@@ -182,7 +183,7 @@ esp_err_t bootloader_init(void)
     }
 #endif  //#if !CONFIG_APP_BUILD_TYPE_RAM
 
-    // check whether a WDT reset happend
+    // check whether a WDT reset happened
     bootloader_check_wdt_reset();
     // config WDT
     bootloader_config_wdt();

components/bootloader_support/src/esp32c3/bootloader_soc.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -18,17 +18,6 @@ void bootloader_ana_super_wdt_reset_config(bool enable)
     }
 }
 
-void bootloader_ana_bod_reset_config(bool enable)
-{
-    REG_CLR_BIT(RTC_CNTL_FIB_SEL_REG, RTC_CNTL_FIB_BOD_RST);
-
-    if (enable) {
-        REG_SET_BIT(RTC_CNTL_BROWN_OUT_REG, RTC_CNTL_BROWN_OUT_ANA_RST_EN);
-    } else {
-        REG_CLR_BIT(RTC_CNTL_BROWN_OUT_REG, RTC_CNTL_BROWN_OUT_ANA_RST_EN);
-    }
-}
-
 void bootloader_ana_clock_glitch_reset_config(bool enable)
 {
     REG_CLR_BIT(RTC_CNTL_FIB_SEL_REG, RTC_CNTL_FIB_GLITCH_RST);

components/bootloader_support/src/esp32c5/bootloader_esp32c5.c

@@ -95,8 +95,8 @@ static inline void bootloader_ana_reset_config(void)
     //Enable super WDT reset.
     // bootloader_ana_super_wdt_reset_config(true);
     // TODO: [ESP32C5] IDF-8647
-    //Enable BOD reset
+    //Enable BOD reset TODO: [ESP32C5] IDF-8667
-    // bootloader_ana_bod_reset_config(true);
+    // brownout_ll_ana_reset_enable(true);
 }
 
 esp_err_t bootloader_init(void)

components/bootloader_support/src/esp32c5/bootloader_soc.c

@@ -16,12 +16,6 @@ void bootloader_ana_super_wdt_reset_config(bool enable)
     ESP_EARLY_LOGW("bootloader", "bootloader_ana_super_wdt_reset_config() has not been implemented on C5 yet");
 }
 
-void bootloader_ana_bod_reset_config(bool enable)
-{
-     // TODO: [ESP32C5] IDF-8667
-    ESP_EARLY_LOGW("bootloader", "bootloader_ana_bod_reset_config() has not been implemented on C5 yet");
-}
-
 //Not supported but common bootloader calls the function. Do nothing
 void bootloader_ana_clock_glitch_reset_config(bool enable)
 {

components/bootloader_support/src/esp32c6/bootloader_esp32c6.c

@@ -44,6 +44,7 @@
 #include "hal/efuse_hal.h"
 #include "hal/lpwdt_ll.h"
 #include "hal/regi2c_ctrl_ll.h"
+#include "hal/brownout_ll.h"
 
 static const char *TAG = "boot.esp32c6";
 
@@ -103,8 +104,8 @@ static inline void bootloader_ana_reset_config(void)
 {
     //Enable super WDT reset.
     bootloader_ana_super_wdt_reset_config(true);
-    //Enable BOD reset
+    //Enable BOD mode1 hardware reset
-    bootloader_ana_bod_reset_config(true);
+    brownout_ll_ana_reset_enable(true);
 }
 
 esp_err_t bootloader_init(void)

components/bootloader_support/src/esp32c6/bootloader_soc.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -15,17 +15,6 @@ void bootloader_ana_super_wdt_reset_config(bool enable)
     REG_CLR_BIT(LP_ANALOG_PERI_LP_ANA_FIB_ENABLE_REG, LP_ANALOG_PERI_LP_ANA_FIB_SUPER_WDT_RST);
 }
 
-void bootloader_ana_bod_reset_config(bool enable)
-{
-    REG_CLR_BIT(LP_ANALOG_PERI_LP_ANA_FIB_ENABLE_REG, LP_ANALOG_PERI_LP_ANA_FIB_BOD_RST);
-
-    if (enable) {
-        REG_SET_BIT(LP_ANALOG_PERI_LP_ANA_BOD_MODE1_CNTL_REG, LP_ANALOG_PERI_LP_ANA_BOD_MODE1_RESET_ENA);
-    } else {
-        REG_CLR_BIT(LP_ANALOG_PERI_LP_ANA_BOD_MODE1_CNTL_REG, LP_ANALOG_PERI_LP_ANA_BOD_MODE1_RESET_ENA);
-    }
-}
-
 //Not supported but common bootloader calls the function. Do nothing
 void bootloader_ana_clock_glitch_reset_config(bool enable)
 {

components/bootloader_support/src/esp32c61/bootloader_esp32c61.c

@@ -94,8 +94,8 @@ static inline void bootloader_ana_reset_config(void)
 {
     //Enable super WDT reset.
     bootloader_ana_super_wdt_reset_config(true);
-    //Enable BOD reset
+    //Enable BOD reset TODO: IDF-9254 BOD support
-    bootloader_ana_bod_reset_config(true);
+    // brownout_ll_ana_reset_enable(true);
 }
 
 esp_err_t bootloader_init(void)

components/bootloader_support/src/esp32c61/bootloader_soc.c

@@ -18,18 +18,6 @@ void bootloader_ana_super_wdt_reset_config(bool enable)
     // REG_CLR_BIT(LP_ANALOG_PERI_LP_ANA_FIB_ENABLE_REG, LP_ANALOG_PERI_LP_ANA_FIB_SUPER_WDT_RST);
 }
 
-void bootloader_ana_bod_reset_config(bool enable)
-{
-    // lp_analog_peri_reg.h updated, now following registers
-    // REG_CLR_BIT(LP_ANALOG_PERI_LP_ANA_FIB_ENABLE_REG, LP_ANALOG_PERI_LP_ANA_FIB_BOD_RST);
-
-    if (enable) {
-        REG_SET_BIT(LP_ANA_BOD_MODE1_CNTL_REG, LP_ANA_BOD_MODE1_RESET_ENA);
-    } else {
-        REG_CLR_BIT(LP_ANA_BOD_MODE1_CNTL_REG, LP_ANA_BOD_MODE1_RESET_ENA);
-    }
-}
-
 //Not supported but common bootloader calls the function. Do nothing
 void bootloader_ana_clock_glitch_reset_config(bool enable)
 {

components/bootloader_support/src/esp32h2/bootloader_esp32h2.c

@@ -43,6 +43,7 @@
 #include "soc/pmu_reg.h"
 #include "hal/efuse_hal.h"
 #include "hal/regi2c_ctrl_ll.h"
+#include "hal/brownout_ll.h"
 
 static const char *TAG = "boot.esp32h2";
 
@@ -97,8 +98,8 @@ static inline void bootloader_ana_reset_config(void)
 {
     //Enable super WDT reset.
     bootloader_ana_super_wdt_reset_config(true);
-    //Enable BOD reset
+    //Enable BOD reset (mode1)
-    bootloader_ana_bod_reset_config(true);
+    brownout_ll_ana_reset_enable(true);
 }
 
 esp_err_t bootloader_init(void)

components/bootloader_support/src/esp32h2/bootloader_soc.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -13,17 +13,6 @@ void bootloader_ana_super_wdt_reset_config(bool enable)
     REG_CLR_BIT(LP_ANALOG_PERI_LP_ANA_FIB_ENABLE_REG, LP_ANALOG_PERI_LP_ANA_FIB_SUPER_WDT_RST);
 }
 
-void bootloader_ana_bod_reset_config(bool enable)
-{
-    REG_CLR_BIT(LP_ANALOG_PERI_LP_ANA_FIB_ENABLE_REG, LP_ANALOG_PERI_LP_ANA_FIB_BOD_RST);
-
-    if (enable) {
-        REG_SET_BIT(LP_ANALOG_PERI_LP_ANA_BOD_MODE1_CNTL_REG, LP_ANALOG_PERI_LP_ANA_BOD_MODE1_RESET_ENA);
-    } else {
-        REG_CLR_BIT(LP_ANALOG_PERI_LP_ANA_BOD_MODE1_CNTL_REG, LP_ANALOG_PERI_LP_ANA_BOD_MODE1_RESET_ENA);
-    }
-}
-
 //Not supported but common bootloader calls the function. Do nothing
 void bootloader_ana_clock_glitch_reset_config(bool enable)
 {

components/bootloader_support/src/esp32p4/bootloader_esp32p4.c

@@ -49,6 +49,7 @@
 #include "soc/regi2c_bias.h"
 #include "esp_private/periph_ctrl.h"
 #include "hal/regi2c_ctrl_ll.h"
+#include "hal/brownout_ll.h"
 
 static const char *TAG = "boot.esp32p4";
 
@@ -120,8 +121,8 @@ static inline void bootloader_ana_reset_config(void)
 {
     //Enable super WDT reset.
     bootloader_ana_super_wdt_reset_config(true);
-    //Enable BOD reset
+    //Enable BOD reset (mode1)
-    bootloader_ana_bod_reset_config(true);
+    brownout_ll_ana_reset_enable(true);
 }
 
 esp_err_t bootloader_init(void)

components/bootloader_support/src/esp32p4/bootloader_soc.c

@@ -5,21 +5,12 @@
  */
 #include <stdbool.h>
 #include "soc/lp_analog_peri_reg.h"
-#include "soc/soc.h"
-#include "hal/brownout_ll.h"
 
 void bootloader_ana_super_wdt_reset_config(bool enable)
 {
     //TODO: IDF-7514
 }
 
-void bootloader_ana_bod_reset_config(bool enable)
-{
-    REG_CLR_BIT(LP_ANALOG_PERI_FIB_ENABLE_REG, LP_ANALOG_PERI_LP_ANA_FIB_BOD_RST);
-
-    brownout_ll_ana_reset_enable(enable);
-}
-
 void bootloader_ana_clock_glitch_reset_config(bool enable)
 {
     //TODO: IDF-7514

components/bootloader_support/src/esp32s3/bootloader_esp32s3.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -39,6 +39,7 @@
 #include "hal/mmu_hal.h"
 #include "hal/cache_hal.h"
 #include "hal/rwdt_ll.h"
+#include "hal/brownout_ll.h"
 #include "xtensa/config/core.h"
 #include "xt_instr_macros.h"
 
@@ -133,7 +134,7 @@ static inline void bootloader_ana_reset_config(void)
 {
     //Enable WDT, BOD, and GLITCH reset
     bootloader_ana_super_wdt_reset_config(true);
-    bootloader_ana_bod_reset_config(true);
+    brownout_ll_ana_reset_enable(true);
     bootloader_ana_clock_glitch_reset_config(true);
 }
 
@@ -204,7 +205,7 @@ esp_err_t bootloader_init(void)
     }
 #endif // !CONFIG_APP_BUILD_TYPE_RAM
 
-    // check whether a WDT reset happend
+    // check whether a WDT reset happened
     bootloader_check_wdt_reset();
     // config WDT
     bootloader_config_wdt();

components/bootloader_support/src/esp32s3/bootloader_soc.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -18,17 +18,6 @@ void bootloader_ana_super_wdt_reset_config(bool enable)
     }
 }
 
-void bootloader_ana_bod_reset_config(bool enable)
-{
-    REG_CLR_BIT(RTC_CNTL_FIB_SEL_REG, RTC_CNTL_FIB_BOD_RST);
-
-    if (enable) {
-        REG_SET_BIT(RTC_CNTL_BROWN_OUT_REG, RTC_CNTL_BROWN_OUT_ANA_RST_EN);
-    } else {
-        REG_CLR_BIT(RTC_CNTL_BROWN_OUT_REG, RTC_CNTL_BROWN_OUT_ANA_RST_EN);
-    }
-}
-
 void bootloader_ana_clock_glitch_reset_config(bool enable)
 {
     REG_CLR_BIT(RTC_CNTL_FIB_SEL_REG, RTC_CNTL_FIB_GLITCH_RST);

components/hal/brownout_hal.c

@@ -13,10 +13,10 @@ void brownout_hal_config(const brownout_hal_config_t *cfg)
     // If brownout software control is enabled, hw ana reset should be disabled, because it always has the highest priority.
     brownout_ll_ana_reset_enable(false);
     brownout_ll_set_intr_wait_cycles(2);
-    brownout_ll_enable_flash_power_down(cfg->flash_power_down);
+    brownout_ll_enable_flash_suspend(cfg->flash_power_down);
     brownout_ll_enable_rf_power_down(cfg->rf_power_down);
     brownout_ll_clear_count();
-    brownout_ll_reset_config(cfg->reset_enabled, 0x3ff, 1);
+    brownout_ll_reset_config(cfg->reset_enabled, 0x3ff, BROWNOUT_RESET_LEVEL_SYSTEM);
     brownout_ll_set_threshold(cfg->threshold);
     brownout_ll_bod_enable(cfg->enabled);
 }

components/hal/esp32/include/hal/brownout_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -13,17 +13,18 @@
 #pragma once
 #include <stdbool.h>
 #include "soc/rtc_cntl_struct.h"
+#include "hal/psdet_types.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * @brief power down the flash when a brown out happens.
+ * @brief suspend the flash when a brown out happens.
  *
- * @param enable true: power down flash. false: not power down
+ * @param enable true: suspend flash. false: not suspend
  */
-static inline void brownout_ll_enable_flash_power_down(bool enable)
+static inline void brownout_ll_enable_flash_suspend(bool enable)
 {
     RTCCNTL.brown_out.close_flash_ena = enable;
 }
@@ -31,7 +32,7 @@ static inline void brownout_ll_enable_flash_power_down(bool enable)
 /**
  * @brief power down the RF circuits when a brown out happens
  *
- * @param enable true: power down. false: not power done.
+ * @param enable true: power down. false: not power down.
  */
 static inline void brownout_ll_enable_rf_power_down(bool enable)
 {
@@ -39,22 +40,24 @@ static inline void brownout_ll_enable_rf_power_down(bool enable)
 }
 
 /**
- * @brief Enable this to reset brown out
+ * @brief Configure the brown out detector to do a hardware reset
  *
- * @note: If brown out interrupt is used, this should be disabled.
+ * @note: If brown out interrupt is also used, the hardware reset can be disabled,
+ *        because we can call software reset in the interrupt handler.
  *
  * @param reset_ena true: enable reset. false: disable reset.
  * @param reset_wait brown out reset wait cycles
- * @param select 1: chip reset, 0: system reset
+ * @param reset_level reset level
  */
-static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, uint8_t select)
+static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, brownout_reset_level_t reset_level)
 {
+    (void)reset_level;
     RTCCNTL.brown_out.rst_wait = reset_wait;
     RTCCNTL.brown_out.rst_ena = reset_ena;
 }
 
 /**
- * @brief Set brown out threshold
+ * @brief Set brown out threshold voltage
  *
  * @param threshold brownout threshold
  */
@@ -96,7 +99,7 @@ static inline void brownout_ll_intr_enable(bool enable)
 /**
  * @brief Enable brownout hardware reset
  *
- * @param enable
+ * @param enable true: enable, false: disable
  */
 static inline void brownout_ll_ana_reset_enable(bool enable)
 {

components/hal/esp32c2/include/hal/brownout_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -12,20 +12,24 @@
 
 #pragma once
 #include <stdbool.h>
+#include "esp_bit_defs.h"
 #include "soc/rtc_cntl_struct.h"
 #include "hal/regi2c_ctrl.h"
+#include "hal/psdet_types.h"
 #include "soc/regi2c_brownout.h"
 
+#define BROWNOUT_DETECTOR_LL_FIB_ENABLE       (BIT(1))
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * @brief power down the flash when a brown out happens.
+ * @brief suspend the flash when a brown out happens.
  *
- * @param enable true: power down flash. false: not power down
+ * @param enable true: suspend flash. false: not suspend
  */
-static inline void brownout_ll_enable_flash_power_down(bool enable)
+static inline void brownout_ll_enable_flash_suspend(bool enable)
 {
     RTCCNTL.brown_out.close_flash_ena = enable;
 }
@@ -33,7 +37,7 @@ static inline void brownout_ll_enable_flash_power_down(bool enable)
 /**
  * @brief power down the RF circuits when a brown out happens
  *
- * @param enable true: power down. false: not power done.
+ * @param enable true: power down. false: not power down.
  */
 static inline void brownout_ll_enable_rf_power_down(bool enable)
 {
@@ -41,23 +45,24 @@ static inline void brownout_ll_enable_rf_power_down(bool enable)
 }
 
 /**
- * @brief Enable this to reset brown out
+ * @brief Configure the brown out detector to do a hardware reset
  *
- * @note: If brown out interrupt is used, this should be disabled.
+ * @note: If brown out interrupt is also used, the hardware reset can be disabled,
+ *        because we can call software reset in the interrupt handler.
  *
  * @param reset_ena true: enable reset. false: disable reset.
  * @param reset_wait brown out reset wait cycles
- * @param select 1: chip reset, 0: system reset
+ * @param reset_level reset level
  */
-static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, uint8_t select)
+static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, brownout_reset_level_t reset_level)
 {
     RTCCNTL.brown_out.rst_wait = reset_wait;
     RTCCNTL.brown_out.rst_ena = reset_ena;
-    RTCCNTL.brown_out.rst_sel = select;
+    RTCCNTL.brown_out.rst_sel = reset_level;
 }
 
 /**
- * @brief Set brown out threshold
+ * @brief Set brown out threshold voltage
  *
  * @param threshold brownout threshold
  */
@@ -97,12 +102,15 @@ static inline void brownout_ll_intr_enable(bool enable)
 }
 
 /**
- * @brief Enable brownout hardware reset
+ * @brief Enable brownout hardware reset (mode1)
  *
- * @param enable
+ * @param enable true: enable, false: disable
  */
 static inline void brownout_ll_ana_reset_enable(bool enable)
 {
+    // give BOD mode1 control permission to the software
+    RTCCNTL.fib_sel.val &= ~BROWNOUT_DETECTOR_LL_FIB_ENABLE;
+    // then we can enable or disable if we want the BOD mode1 to reset the system
     RTCCNTL.brown_out.ana_rst_en = enable;
 }
 

components/hal/esp32c3/include/hal/brownout_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -12,20 +12,24 @@
 
 #pragma once
 #include <stdbool.h>
+#include "esp_bit_defs.h"
 #include "soc/rtc_cntl_struct.h"
 #include "hal/regi2c_ctrl.h"
+#include "hal/psdet_types.h"
 #include "soc/regi2c_brownout.h"
 
+#define BROWNOUT_DETECTOR_LL_FIB_ENABLE       (BIT(1))
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * @brief power down the flash when a brown out happens.
+ * @brief suspend the flash when a brown out happens.
  *
- * @param enable true: power down flash. false: not power down
+ * @param enable true: suspend flash. false: not suspend
  */
-static inline void brownout_ll_enable_flash_power_down(bool enable)
+static inline void brownout_ll_enable_flash_suspend(bool enable)
 {
     RTCCNTL.brown_out.close_flash_ena = enable;
 }
@@ -33,7 +37,7 @@ static inline void brownout_ll_enable_flash_power_down(bool enable)
 /**
  * @brief power down the RF circuits when a brown out happens
  *
- * @param enable true: power down. false: not power done.
+ * @param enable true: power down. false: not power down.
  */
 static inline void brownout_ll_enable_rf_power_down(bool enable)
 {
@@ -41,23 +45,24 @@ static inline void brownout_ll_enable_rf_power_down(bool enable)
 }
 
 /**
- * @brief Enable this to reset brown out
+ * @brief Configure the brown out detector to do a hardware reset
  *
- * @note: If brown out interrupt is used, this should be disabled.
+ * @note: If brown out interrupt is also used, the hardware reset can be disabled,
+ *        because we can call software reset in the interrupt handler.
  *
  * @param reset_ena true: enable reset. false: disable reset.
  * @param reset_wait brown out reset wait cycles
- * @param select 1: chip reset, 0: system reset
+ * @param reset_level reset level
  */
-static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, uint8_t select)
+static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, brownout_reset_level_t reset_level)
 {
     RTCCNTL.brown_out.rst_wait = reset_wait;
     RTCCNTL.brown_out.rst_ena = reset_ena;
-    RTCCNTL.brown_out.rst_sel = select;
+    RTCCNTL.brown_out.rst_sel = reset_level;
 }
 
 /**
- * @brief Set brown out threshold
+ * @brief Set brown out threshold voltage
  *
  * @param threshold brownout threshold
  */
@@ -99,10 +104,13 @@ static inline void brownout_ll_intr_enable(bool enable)
 /**
  * @brief Enable brownout hardware reset
  *
- * @param enable
+ * @param enable true: enable, false: disable
  */
 static inline void brownout_ll_ana_reset_enable(bool enable)
 {
+    // give BOD mode1 control permission to the software
+    RTCCNTL.fib_sel.val &= ~BROWNOUT_DETECTOR_LL_FIB_ENABLE;
+    // then we can enable or disable if we want the BOD mode1 to reset the system
     RTCCNTL.brown_out.ana_rst_en = enable;
 }
 

components/hal/esp32c6/include/hal/brownout_ll.h

@@ -12,22 +12,25 @@
 
 #pragma once
 #include <stdbool.h>
+#include "esp_bit_defs.h"
 #include "soc/lp_analog_peri_struct.h"
 #include "hal/regi2c_ctrl.h"
+#include "hal/psdet_types.h"
 #include "soc/regi2c_brownout.h"
 
+#define BROWNOUT_DETECTOR_LL_INTERRUPT_MASK   (BIT(31))
+#define BROWNOUT_DETECTOR_LL_FIB_ENABLE       (BIT(1))
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-#define BROWNOUT_DETECTOR_LL_INTERRUPT_MASK   (BIT(31))
-
 /**
- * @brief power down the flash when a brown out happens.
+ * @brief suspend the flash when a brown out happens.
  *
- * @param enable true: power down flash. false: not power down
+ * @param enable true: suspend flash. false: not suspend
  */
-static inline void brownout_ll_enable_flash_power_down(bool enable)
+static inline void brownout_ll_enable_flash_suspend(bool enable)
 {
     LP_ANA_PERI.bod_mode0_cntl.bod_mode0_close_flash_ena = enable;
 }
@@ -35,7 +38,7 @@ static inline void brownout_ll_enable_flash_power_down(bool enable)
 /**
  * @brief power down the RF circuits when a brown out happens
  *
- * @param enable true: power down. false: not power done.
+ * @param enable true: power down. false: not power down.
  */
 static inline void brownout_ll_enable_rf_power_down(bool enable)
 {
@@ -43,22 +46,24 @@ static inline void brownout_ll_enable_rf_power_down(bool enable)
 }
 
 /**
- * @brief Enable this to reset brown out
+ * @brief Configure the brown out detector to do a hardware reset
  *
- * @note: If brown out interrupt is used, this should be disabled.
+ * @note: If brown out interrupt is also used, the hardware reset can be disabled,
+ *        because we can call software reset in the interrupt handler.
  *
  * @param reset_ena true: enable reset. false: disable reset.
  * @param reset_wait brown out reset wait cycles
- * @param select 1: chip reset, 0: system reset
+ * @param reset_level reset level
  */
-static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, uint8_t select)
+static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, brownout_reset_level_t reset_level)
 {
     LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_wait = reset_wait;
     LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_ena = reset_ena;
-    LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_sel = select;
+    LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_sel = reset_level;
 }
+
 /**
- * @brief Set brown out threshold
+ * @brief Set brown out threshold voltage
  *
  * @param threshold brownout threshold
  */
@@ -98,12 +103,15 @@ static inline void brownout_ll_intr_enable(bool enable)
 }
 
 /**
- * @brief Enable brownout hardware reset
+ * @brief Enable brownout hardware reset (mode1)
  *
- * @param enable
+ * @param enable true: enable, false: disable
  */
 static inline void brownout_ll_ana_reset_enable(bool enable)
 {
+    // give BOD mode1 control permission to the software
+    LP_ANA_PERI.fib_enable.val &= ~BROWNOUT_DETECTOR_LL_FIB_ENABLE;
+    // then we can enable or disable if we want the BOD mode1 to reset the system
     LP_ANA_PERI.bod_mode1_cntl.bod_mode1_reset_ena = enable;
 }
 

components/hal/esp32h2/include/hal/brownout_ll.h

@@ -12,22 +12,25 @@
 
 #pragma once
 #include <stdbool.h>
+#include "esp_bit_defs.h"
 #include "soc/lp_analog_peri_struct.h"
 #include "hal/regi2c_ctrl.h"
+#include "hal/psdet_types.h"
 #include "soc/regi2c_brownout.h"
 
+#define BROWNOUT_DETECTOR_LL_INTERRUPT_MASK   (BIT(31))
+#define BROWNOUT_DETECTOR_LL_FIB_ENABLE       (BIT(1))
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-#define BROWNOUT_DETECTOR_LL_INTERRUPT_MASK   (BIT(31))
-
 /**
- * @brief power down the flash when a brown out happens.
+ * @brief suspend the flash when a brown out happens.
  *
- * @param enable true: power down flash. false: not power down
+ * @param enable true: suspend flash. false: not suspend
  */
-static inline void brownout_ll_enable_flash_power_down(bool enable)
+static inline void brownout_ll_enable_flash_suspend(bool enable)
 {
     LP_ANA_PERI.bod_mode0_cntl.bod_mode0_close_flash_ena = enable;
 }
@@ -35,7 +38,7 @@ static inline void brownout_ll_enable_flash_power_down(bool enable)
 /**
  * @brief power down the RF circuits when a brown out happens
  *
- * @param enable true: power down. false: not power done.
+ * @param enable true: power down. false: not power down.
  */
 static inline void brownout_ll_enable_rf_power_down(bool enable)
 {
@@ -43,23 +46,24 @@ static inline void brownout_ll_enable_rf_power_down(bool enable)
 }
 
 /**
- * @brief Enable this to reset brown out
+ * @brief Configure the brown out detector to do a hardware reset
  *
- * @note: If brown out interrupt is used, this should be disabled.
+ * @note: If brown out interrupt is also used, the hardware reset can be disabled,
+ *        because we can call software reset in the interrupt handler.
  *
  * @param reset_ena true: enable reset. false: disable reset.
  * @param reset_wait brown out reset wait cycles
- * @param select 1: chip reset, 0: system reset
+ * @param reset_level reset level
  */
-static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, uint8_t select)
+static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, brownout_reset_level_t reset_level)
 {
     LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_wait = reset_wait;
     LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_ena = reset_ena;
-    LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_sel = select;
+    LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_sel = reset_level;
 }
 
 /**
- * @brief Set brown out threshold
+ * @brief Set brown out threshold voltage
  *
  * @param threshold brownout threshold
  */
@@ -99,12 +103,15 @@ static inline void brownout_ll_intr_enable(bool enable)
 }
 
 /**
- * @brief Enable brownout hardware reset
+ * @brief Enable brownout hardware reset (mode1)
  *
- * @param enable
+ * @param enable true: enable, false: disable
  */
 static inline void brownout_ll_ana_reset_enable(bool enable)
 {
+    // give BOD mode1 control permission to the software
+    LP_ANA_PERI.fib_enable.val &= ~BROWNOUT_DETECTOR_LL_FIB_ENABLE;
+    // then we can enable or disable if we want the BOD mode1 to reset the system
     LP_ANA_PERI.bod_mode1_cntl.bod_mode1_reset_ena = enable;
 }
 

components/hal/esp32p4/include/hal/brownout_ll.h

@@ -12,20 +12,24 @@
 
 #pragma once
 #include <stdbool.h>
+#include "esp_bit_defs.h"
 #include "soc/lp_analog_peri_struct.h"
 #include "hal/regi2c_ctrl.h"
+#include "hal/psdet_types.h"
 #include "soc/regi2c_brownout.h"
 
+#define BROWNOUT_DETECTOR_LL_FIB_ENABLE       (BIT(1))
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * @brief power down the flash when a brown out happens.
+ * @brief suspend the flash when a brown out happens.
  *
- * @param enable true: power down flash. false: not power down
+ * @param enable true: suspend flash. false: not suspend
  */
-static inline void brownout_ll_enable_flash_power_down(bool enable)
+static inline void brownout_ll_enable_flash_suspend(bool enable)
 {
     LP_ANA_PERI.bod_mode0_cntl.bod_mode0_close_flash_ena = enable;
 }
@@ -33,7 +37,7 @@ static inline void brownout_ll_enable_flash_power_down(bool enable)
 /**
  * @brief power down the RF circuits when a brown out happens
  *
- * @param enable true: power down. false: not power done.
+ * @param enable true: power down. false: not power down.
  */
 static inline void brownout_ll_enable_rf_power_down(bool enable)
 {
@@ -41,22 +45,24 @@ static inline void brownout_ll_enable_rf_power_down(bool enable)
 }
 
 /**
- * @brief Enable this to reset brown out
+ * @brief Configure the brown out detector to do a hardware reset
  *
- * @note: If brown out interrupt is used, this should be disabled.
+ * @note: If brown out interrupt is also used, the hardware reset can be disabled,
+ *        because we can call software reset in the interrupt handler.
  *
  * @param reset_ena true: enable reset. false: disable reset.
  * @param reset_wait brown out reset wait cycles
- * @param select 1: chip reset, 0: system reset
+ * @param reset_level reset level
  */
-static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, uint8_t select)
+static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, brownout_reset_level_t reset_level)
 {
     LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_wait = reset_wait;
     LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_ena = reset_ena;
-    LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_sel = select;
+    LP_ANA_PERI.bod_mode0_cntl.bod_mode0_reset_sel = reset_level;
 }
+
 /**
- * @brief Set brown out threshold
+ * @brief Set brown out threshold voltage
  *
  * @param threshold brownout threshold
  */
@@ -96,12 +102,15 @@ static inline void brownout_ll_intr_enable(bool enable)
 }
 
 /**
- * @brief Enable brownout hardware reset
+ * @brief Enable brownout hardware reset (mode1)
  *
- * @param enable
+ * @param enable true: enable, false: disable
  */
 static inline void brownout_ll_ana_reset_enable(bool enable)
 {
+    // give BOD mode1 control permission to the software
+    LP_ANA_PERI.fib_enable.val &= ~BROWNOUT_DETECTOR_LL_FIB_ENABLE;
+    // then we can enable or disable if we want the BOD mode1 to reset the system
     LP_ANA_PERI.bod_mode1_cntl.bod_mode1_reset_ena = enable;
 }
 

components/hal/esp32s2/include/hal/brownout_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -14,6 +14,7 @@
 #include <stdbool.h>
 #include "soc/rtc_cntl_struct.h"
 #include "hal/regi2c_ctrl.h"
+#include "hal/psdet_types.h"
 #include "soc/regi2c_brownout.h"
 
 #ifdef __cplusplus
@@ -21,11 +22,11 @@ extern "C" {
 #endif
 
 /**
- * @brief power down the flash when a brown out happens.
+ * @brief suspend the flash when a brown out happens.
  *
- * @param enable true: power down flash. false: not power down
+ * @param enable true: suspend flash. false: not suspend
  */
-static inline void brownout_ll_enable_flash_power_down(bool enable)
+static inline void brownout_ll_enable_flash_suspend(bool enable)
 {
     RTCCNTL.brown_out.close_flash_ena = enable;
 }
@@ -33,7 +34,7 @@ static inline void brownout_ll_enable_flash_power_down(bool enable)
 /**
  * @brief power down the RF circuits when a brown out happens
  *
- * @param enable true: power down. false: not power done.
+ * @param enable true: power down. false: not power down.
  */
 static inline void brownout_ll_enable_rf_power_down(bool enable)
 {
@@ -41,24 +42,25 @@ static inline void brownout_ll_enable_rf_power_down(bool enable)
 }
 
 /**
- * @brief Enable this to reset brown out
+ * @brief Configure the brown out detector to do a hardware reset
  *
- * @note: If brown out interrupt is used, this should be disabled.
+ * @note: If brown out interrupt is also used, the hardware reset can be disabled,
+ *        because we can call software reset in the interrupt handler.
  *
  * @param reset_ena true: enable reset. false: disable reset.
  * @param reset_wait brown out reset wait cycles
- * @param select 1: chip reset, 0: system reset
+ * @param reset_level reset level
  */
-static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, uint8_t select)
+static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, brownout_reset_level_t reset_level)
 {
     RTCCNTL.brown_out.rst_wait = reset_wait;
     RTCCNTL.brown_out.rst_ena = reset_ena;
     RTCCNTL.brown_out.out2_ena = true;
-    RTCCNTL.brown_out.rst_sel = select;
+    RTCCNTL.brown_out.rst_sel = reset_level;
 }
 
 /**
- * @brief Set brown out threshold
+ * @brief Set brown out threshold voltage
  *
  * @param threshold brownout threshold
  */
@@ -100,7 +102,7 @@ static inline void brownout_ll_intr_enable(bool enable)
 /**
  * @brief Enable brownout hardware reset
  *
- * @param enable
+ * @param enable true: enable, false: disable
  */
 static inline void brownout_ll_ana_reset_enable(bool enable)
 {

components/hal/esp32s3/include/hal/brownout_ll.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -12,20 +12,24 @@
 
 #pragma once
 #include <stdbool.h>
+#include "esp_bit_defs.h"
 #include "soc/rtc_cntl_struct.h"
 #include "hal/regi2c_ctrl.h"
+#include "hal/psdet_types.h"
 #include "soc/regi2c_brownout.h"
 
+#define BROWNOUT_DETECTOR_LL_FIB_ENABLE       (BIT(1))
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * @brief power down the flash when a brown out happens.
+ * @brief suspend the flash when a brown out happens.
  *
- * @param enable true: power down flash. false: not power down
+ * @param enable true: suspend flash. false: not suspend
  */
-static inline void brownout_ll_enable_flash_power_down(bool enable)
+static inline void brownout_ll_enable_flash_suspend(bool enable)
 {
     RTCCNTL.brown_out.close_flash_ena = enable;
 }
@@ -33,7 +37,7 @@ static inline void brownout_ll_enable_flash_power_down(bool enable)
 /**
  * @brief power down the RF circuits when a brown out happens
  *
- * @param enable true: power down. false: not power done.
+ * @param enable true: power down. false: not power down.
  */
 static inline void brownout_ll_enable_rf_power_down(bool enable)
 {
@@ -41,23 +45,24 @@ static inline void brownout_ll_enable_rf_power_down(bool enable)
 }
 
 /**
- * @brief Enable this to reset brown out
+ * @brief Configure the brown out detector to do a hardware reset
  *
- * @note: If brown out interrupt is used, this should be disabled.
+ * @note: If brown out interrupt is also used, the hardware reset can be disabled,
+ *        because we can call software reset in the interrupt handler.
  *
  * @param reset_ena true: enable reset. false: disable reset.
  * @param reset_wait brown out reset wait cycles
- * @param select 1: chip reset, 0: system reset
+ * @param reset_level reset level
  */
-static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, uint8_t select)
+static inline void brownout_ll_reset_config(bool reset_ena, uint32_t reset_wait, brownout_reset_level_t reset_level)
 {
     RTCCNTL.brown_out.rst_wait = reset_wait;
     RTCCNTL.brown_out.rst_ena = reset_ena;
-    RTCCNTL.brown_out.rst_sel = select;
+    RTCCNTL.brown_out.rst_sel = reset_level;
 }
 
 /**
- * @brief Set brown out threshold
+ * @brief Set brown out threshold voltage
  *
  * @param threshold brownout threshold
  */
@@ -97,12 +102,15 @@ static inline void brownout_ll_intr_enable(bool enable)
 }
 
 /**
- * @brief Enable brownout hardware reset
+ * @brief Enable brownout hardware reset (mode1)
  *
- * @param enable
+ * @param enable true: enable, false: disable
  */
 static inline void brownout_ll_ana_reset_enable(bool enable)
 {
+    // give BOD mode1 control permission to the software
+    RTCCNTL.fib_sel.val &= ~BROWNOUT_DETECTOR_LL_FIB_ENABLE;
+    // then we can enable or disable if we want the BOD mode1 to reset the system
     RTCCNTL.brown_out.ana_rst_en = enable;
 }
 

components/hal/include/hal/psdet_types.h

@@ -0,0 +1,25 @@
+/*
+ * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Brownout reset level
+ */
+typedef enum {
+    BROWNOUT_RESET_LEVEL_CHIP,   // Reset the whole chip, including the analog part
+    BROWNOUT_RESET_LEVEL_SYSTEM, // Reset the whole digital system, including RTC sub-system
+} brownout_reset_level_t;
+
+#ifdef __cplusplus
+}
+#endif