Merge branch 'fix/allows_to_forcibly_disable_sleep_submodes' into 'master'

fix(esp_hw_support): allows to forcefully disable sleep submode

Closes IDFCI-2380 and PM-228

See merge request espressif/esp-idf!33481

components/esp_hw_support/include/esp_private/esp_sleep_internal.h

@@ -43,6 +43,7 @@ typedef enum {
 
 /**
  * @brief Set sub-sleep power mode in sleep, mode enabled status is maintained by reference count.
+ *        The caller should ensure that the enabling and disabling behavior is symmetric.
  *        This submode configuration will kept after deep sleep wakeup.
  *
  * @param  mode     sub-sleep mode type
@@ -54,6 +55,17 @@ typedef enum {
  */
 esp_err_t esp_sleep_sub_mode_config(esp_sleep_sub_mode_t mode, bool activate);
 
+/**
+ * @brief Force disable sub-sleep power mode in sleep, usually used during initialization.
+ *
+ * @param  mode     sub-sleep mode type
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if either of the arguments is out of range
+ */
+esp_err_t esp_sleep_sub_mode_force_disable(esp_sleep_sub_mode_t mode);
+
 /**
  * Dump the sub-sleep power mode enable status
  * @param  stream     The stream to dump to, if NULL then nothing will be dumped

components/esp_hw_support/sleep_modes.c

@@ -2189,6 +2189,18 @@ esp_err_t esp_sleep_sub_mode_config(esp_sleep_sub_mode_t mode, bool activate)
     return ESP_OK;
 }
 
+esp_err_t esp_sleep_sub_mode_force_disable(esp_sleep_sub_mode_t mode)
+{
+    if (mode >= ESP_SLEEP_MODE_MAX) {
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    portENTER_CRITICAL_SAFE(&s_config.lock);
+    s_sleep_sub_mode_ref_cnt[mode] = 0;
+    portEXIT_CRITICAL_SAFE(&s_config.lock);
+    return ESP_OK;
+}
+
 int32_t* esp_sleep_sub_mode_dump_config(FILE *stream) {
     if (stream) {
         for (uint32_t mode = 0; mode < ESP_SLEEP_MODE_MAX; mode++) {
@@ -2414,15 +2426,27 @@ esp_deep_sleep_disable_rom_logging(void)
 
 __attribute__((deprecated("Please use esp_sleep_sub_mode_config instead"))) void esp_sleep_periph_use_8m(bool use_or_not)
 {
+    if (use_or_not) {
         esp_sleep_sub_mode_config(ESP_SLEEP_DIG_USE_RC_FAST_MODE, use_or_not);
+    } else {
+        esp_sleep_sub_mode_force_disable(ESP_SLEEP_DIG_USE_RC_FAST_MODE);
+    }
 }
 
 __attribute__((deprecated("Please use esp_sleep_sub_mode_config instead"))) void esp_sleep_enable_adc_tsens_monitor(bool enable)
 {
+    if (enable) {
         esp_sleep_sub_mode_config(ESP_SLEEP_USE_ADC_TSEN_MONITOR_MODE, enable);
+    } else {
+        esp_sleep_sub_mode_force_disable(ESP_SLEEP_USE_ADC_TSEN_MONITOR_MODE);
+    }
 }
 
 __attribute__((deprecated("Please use esp_sleep_sub_mode_config instead"))) void rtc_sleep_enable_ultra_low(bool enable)
 {
+    if (enable) {
         esp_sleep_sub_mode_config(ESP_SLEEP_ULTRA_LOW_MODE, enable);
+    } else {
+        esp_sleep_sub_mode_force_disable(ESP_SLEEP_ULTRA_LOW_MODE);
+    }
 }

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

@@ -90,7 +90,7 @@ In Deep-sleep mode, the CPUs, most of the RAM, and all digital peripherals that
 
     Features:
 
-    1. RTC IO input/RTC memory at high temperature (experimental): Use RTC IO as input pins, or use RTC memory at high temperature. The chip can go into ultra low power mode when these features are disabled. Controlled by API :cpp:func:`rtc_sleep_enable_ultra_low`.
+    1. RTC IO input/RTC memory at high temperature (experimental): Use RTC IO as input pins, or use RTC memory at high temperature. The chip can go into ultra low power mode when these features are disabled. Controlled by API :cpp:func:`esp_sleep_sub_mode_config` with `ESP_SLEEP_ULTRA_LOW_MODE` argument.
 
     2. ADC_TSEN_MONITOR: Use ADC/Temperature Sensor in monitor mode (controlled by ULP). Enabled by API :cpp:func:`ulp_adc_init` or its higher level APIs. Only available for ESP32-S2 and ESP32-S3 chips with monitor mode.
 

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

@@ -90,7 +90,7 @@
 
     功能：
 
-    1. RTC IO 输入/高温下 RTC 内存（试验功能）：将 RTC IO 用作输入管脚，或在高温下使用 RTC 内存。禁用上述功能，芯片可进入超低功耗模式。由 API :cpp:func:`rtc_sleep_enable_ultra_low` 控制。
+    1. RTC IO 输入/高温下 RTC 内存（试验功能）：将 RTC IO 用作输入管脚，或在高温下使用 RTC 内存。禁用上述功能，芯片可进入超低功耗模式。由 API :cpp:func:`esp_sleep_sub_mode_config` 配置 `ESP_SLEEP_ULTRA_LOW_MODE` 模式的使能与关闭。
 
     2. ADC_TSEN_MONITOR：在 monitor 模式下使用 ADC/温度传感器（由 ULP 控制），通过 :cpp:func:`ulp_adc_init` 或其更高级别的 API 启用。仅适用于支持 monitor 模式的 ESP32-S2 和 ESP32-S3 芯片。