feat(esp_hal_pmu): graduate pmu/rtc_cntl hal driver into a new component: esp_hal_pmu

components/esp_hal_pmu/CMakeLists.txt

@@ -0,0 +1,22 @@
+idf_build_get_property(target IDF_TARGET)
+if(${target} STREQUAL "linux")
+    return() # This component is not supported by the POSIX/Linux simulator
+endif()
+
+set(srcs)
+set(public_include "include" "${target}/include")
+
+# New chips with PMU peripheral
+if(CONFIG_SOC_PMU_SUPPORTED)
+    list(APPEND srcs "${target}/pmu_hal.c")
+endif()
+
+# Legacy chips with RTC_CNTL peripheral
+if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/${target}/rtc_cntl_hal.c")
+    list(APPEND srcs "${target}/rtc_cntl_hal.c")
+endif()
+
+idf_component_register(SRCS ${srcs}
+                       INCLUDE_DIRS ${public_include}
+                       REQUIRES soc hal esp_rom
+                       LDFRAGMENTS linker.lf)

components/esp_hal_pmu/README.md

@@ -0,0 +1,68 @@
+# ESP Hardware Abstraction Layer for PMU and RTC Control Peripherals
+
+> [!NOTE]
+> This component is currently in beta. Its API, behavior, and compatibility may change at any time and without notice; backward compatibility is not guaranteed. Use caution when integrating into production systems.
+
+## Overview
+
+The `esp_hal_pmu` component provides a **Hardware Abstraction Layer** for Power Management Unit (PMU) and legacy RTC Control (RTC_CNTL) peripherals across ESP-IDF supported targets. This HAL enables unified power management operations including sleep mode control, power domain management, wakeup configuration, and retention control across different ESP chip families.
+
+The component consolidates power management functionality from two different peripheral implementations:
+- **PMU**: Modern power management unit in newer ESP chips
+- **RTC_CNTL**: Legacy RTC control peripheral in older ESP chips
+
+## Architecture
+
+The HAL architecture consists of two primary layers:
+
+1. **HAL Layer (Upper)**: Defines the operational sequences and data structures required to interact with PMU/RTC_CNTL peripherals, including:
+   - Power domain configuration and control
+   - Sleep mode management
+   - Wakeup source configuration
+   - Retention control (CPU, tagmem)
+   - Power-up/down wait cycle configuration
+   - Backup enable/disable operations
+
+2. **Low-Level Layer (Bottom)**: Acts as a translation layer between the HAL and the register definitions in the `soc` component, handling:
+   - Register access abstractions
+   - Chip-specific register configurations
+   - Hardware feature compatibility
+   - Power domain and clock control
+
+## Features
+
+### Power Management
+- Power domain control (HP/LP system power domains)
+- Digital power supply and power-up wait cycle configuration
+- Control ready wait cycle configuration (isolate/reset)
+- Power mode transitions (active, sleep, modem)
+
+### Sleep and Wakeup
+- Sleep mode configuration
+- Wakeup source management
+- Sleep rejection handling
+- Wakeup cause detection
+
+### Retention Control
+- CPU retention enable/disable
+- Tagmem retention support (on supported chips)
+- DMA link buffer configuration for retention
+
+### Backup Operations
+- Sleep-to-active backup enable/disable
+- Sleep-to-modem backup enable/disable
+- Modem-to-active backup enable/disable
+
+## Usage
+This component is primarily used by ESP-IDF system services such as:
+- **esp_pm**: Power management framework
+- **esp_hw_support**: Hardware support layer for sleep modes and power management
+- **ulp**: Ultra-low-power coprocessor support
+
+For advanced developers implementing custom power management solutions, the HAL functions can be used directly. However, please note that the interfaces provided by this component are internal to ESP-IDF and are subject to change.
+
+## Dependencies
+
+- `soc`: Provides chip-specific register definitions and peripheral capabilities
+- `hal`: Core hardware abstraction utilities and macros
+- `esp_rom`: ROM function interfaces (where applicable)

components/esp_hal_pmu/esp32/include/hal/rtc_cntl_ll.h

@@ -8,7 +8,7 @@
 
 #include "soc/soc.h"
 #include "esp_attr.h"
-#include "clk_tree_ll.h"
+#include "hal/clk_tree_ll.h"
 #include "esp_rom_sys.h"
 #include "hal/assert.h"
 
@@ -39,10 +39,10 @@ FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_set_wakeup_pins(uint32_t io_mask, uint32
     REG_SET_FIELD(RTC_CNTL_EXT_WAKEUP1_REG, RTC_CNTL_EXT_WAKEUP1_SEL, io_mask);
     if ((io_mask & mode_mask) == io_mask) {
         SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1,
-                1, RTC_CNTL_EXT_WAKEUP1_LV_S);
+                          1, RTC_CNTL_EXT_WAKEUP1_LV_S);
     } else {
         SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1,
-                0, RTC_CNTL_EXT_WAKEUP1_LV_S);
+                          0, RTC_CNTL_EXT_WAKEUP1_LV_S);
     }
 }
 

components/esp_hal_pmu/esp32c2/rtc_cntl_hal.c

@@ -48,7 +48,7 @@ void rtc_cntl_hal_enable_cpu_retention(void *addr)
         pbuf->cfg[0] = 0;
         pbuf->cfg[1] = 0;
         pbuf->cfg[2] = 0;
-        pbuf->cfg[3] = (uint32_t)-1;
+        pbuf->cfg[3] = (uint32_t) -1;
 
         rtc_cntl_ll_enable_cpu_retention((uint32_t)addr);
     }

components/esp_hal_pmu/esp32c3/rtc_cntl_hal.c

@@ -53,7 +53,7 @@ void rtc_cntl_hal_enable_cpu_retention(void *addr)
             pbuf->cfg[0] = 0;
             pbuf->cfg[1] = 0;
             pbuf->cfg[2] = 0;
-            pbuf->cfg[3] = (uint32_t)-1;
+            pbuf->cfg[3] = (uint32_t) -1;
 
             rtc_cntl_ll_set_cpu_retention_link_addr((uint32_t)plink);
             rtc_cntl_ll_enable_cpu_retention_clock();

components/esp_hal_pmu/esp32c5/include/hal/pmu_ll.h

@@ -239,7 +239,6 @@ FORCE_INLINE_ATTR void pmu_ll_hp_set_regulator_driver_bar(pmu_dev_t *hw, pmu_hp_
     hw->hp_sys[mode].regulator1.drv_b = drv_b;
 }
 
-
 FORCE_INLINE_ATTR void pmu_ll_lp_set_regulator_slp_xpd(pmu_dev_t *hw, pmu_lp_mode_t mode, bool slp_xpd)
 {
     hw->lp_sys[mode].regulator0.slp_xpd = slp_xpd;
@@ -271,7 +270,6 @@ FORCE_INLINE_ATTR void pmu_ll_lp_set_xtal_xpd(pmu_dev_t *hw, pmu_lp_mode_t mode,
     hw->lp_sys[mode].xtal.xpd_xtal = xpd_xtal;
 }
 
-
 FORCE_INLINE_ATTR void pmu_ll_lp_set_dig_power(pmu_dev_t *hw, pmu_lp_mode_t mode, uint32_t flag)
 {
     hw->lp_sys[mode].dig_power.val = flag;
@@ -311,7 +309,6 @@ FORCE_INLINE_ATTR void pmu_ll_lp_set_bias_sleep_enable(pmu_dev_t *hw, pmu_lp_mod
     hw->lp_sys[mode].bias.bias_sleep = en;
 }
 
-
 /****/
 FORCE_INLINE_ATTR void pmu_ll_imm_set_clk_power(pmu_dev_t *hw, uint32_t flag)
 {
@@ -697,7 +694,6 @@ FORCE_INLINE_ATTR uint32_t pmu_ll_get_sysclk_sleep_select_state(pmu_dev_t *hw)
     return hw->clk_state0.sysclk_slp_sel;
 }
 
-
 FORCE_INLINE_ATTR uint32_t pmu_ll_lp_get_interrupt_raw(pmu_dev_t *hw)
 {
     return hw->lp_ext.int_raw.val;

components/esp_hal_pmu/esp32c6/include/hal/pmu_ll.h

@@ -239,7 +239,6 @@ FORCE_INLINE_ATTR void pmu_ll_hp_set_regulator_driver_bar(pmu_dev_t *hw, pmu_hp_
     hw->hp_sys[mode].regulator1.drv_b = drv_b;
 }
 
-
 FORCE_INLINE_ATTR void pmu_ll_lp_set_regulator_slp_xpd(pmu_dev_t *hw, pmu_lp_mode_t mode, bool slp_xpd)
 {
     hw->lp_sys[mode].regulator0.slp_xpd = slp_xpd;
@@ -271,7 +270,6 @@ FORCE_INLINE_ATTR void pmu_ll_lp_set_xtal_xpd(pmu_dev_t *hw, pmu_lp_mode_t mode,
     hw->lp_sys[mode].xtal.xpd_xtal = xpd_xtal;
 }
 
-
 FORCE_INLINE_ATTR void pmu_ll_lp_set_dig_power(pmu_dev_t *hw, pmu_lp_mode_t mode, uint32_t flag)
 {
     hw->lp_sys[mode].dig_power.val = flag;
@@ -311,7 +309,6 @@ FORCE_INLINE_ATTR void pmu_ll_lp_set_bias_sleep_enable(pmu_dev_t *hw, pmu_lp_mod
     hw->lp_sys[mode].bias.bias_sleep = en;
 }
 
-
 /****/
 FORCE_INLINE_ATTR void pmu_ll_imm_set_clk_power(pmu_dev_t *hw, uint32_t flag)
 {

components/esp_hal_pmu/esp32c61/include/hal/pmu_ll.h

@@ -17,7 +17,6 @@
 #include "hal/pmu_types.h"
 #include "hal/misc.h"
 
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -240,7 +239,6 @@ FORCE_INLINE_ATTR void pmu_ll_hp_set_regulator_driver_bar(pmu_dev_t *hw, pmu_hp_
     hw->hp_sys[mode].regulator1.drv_b = drv_b;
 }
 
-
 FORCE_INLINE_ATTR void pmu_ll_lp_set_regulator_slp_xpd(pmu_dev_t *hw, pmu_lp_mode_t mode, bool slp_xpd)
 {
     hw->lp_sys[mode].regulator0.slp_xpd = slp_xpd;
@@ -272,7 +270,6 @@ FORCE_INLINE_ATTR void pmu_ll_lp_set_xtal_xpd(pmu_dev_t *hw, pmu_lp_mode_t mode,
     hw->lp_sys[mode].xtal.xpd_xtal = xpd_xtal;
 }
 
-
 FORCE_INLINE_ATTR void pmu_ll_lp_set_dig_power(pmu_dev_t *hw, pmu_lp_mode_t mode, uint32_t flag)
 {
     hw->lp_sys[mode].dig_power.val = flag;
@@ -312,7 +309,6 @@ FORCE_INLINE_ATTR void pmu_ll_lp_set_bias_sleep_enable(pmu_dev_t *hw, pmu_lp_mod
     hw->lp_sys[mode].bias.bias_sleep = en;
 }
 
-
 /****/
 FORCE_INLINE_ATTR void pmu_ll_imm_set_clk_power(pmu_dev_t *hw, uint32_t flag)
 {

components/esp_hal_pmu/esp32h21/include/hal/pmu_ll.h

@@ -139,7 +139,6 @@ FORCE_INLINE_ATTR void pmu_ll_hp_set_discnnt_dig_rtc(pmu_dev_t *hw, pmu_hp_mode_
     hw->hp_sys[mode].bias.discnnt_dig_rtc = discnnt;
 }
 
-
 FORCE_INLINE_ATTR void pmu_ll_hp_set_current_power_off(pmu_dev_t *hw, pmu_hp_mode_t mode, bool off)
 {
     hw->hp_sys[mode].bias.pd_cur = off;

components/esp_hal_pmu/esp32p4/include/hal/pmu_ll.h

@@ -156,7 +156,6 @@ FORCE_INLINE_ATTR void pmu_ll_hp_set_sleep_to_active_backup_disable(pmu_dev_t *h
     hw->hp_sys[PMU_MODE_HP_ACTIVE].backup.hp_sleep2active_backup_en = 0;
 }
 
-
 FORCE_INLINE_ATTR void pmu_ll_hp_set_active_to_sleep_backup_enable(pmu_dev_t *hw)
 {
     hw->hp_sys[PMU_MODE_HP_SLEEP].backup.hp_active2sleep_backup_en = 1;
@@ -234,7 +233,6 @@ FORCE_INLINE_ATTR void pmu_ll_hp_set_regulator_driver_bar(pmu_dev_t *hw, pmu_hp_
     hw->hp_sys[mode].regulator1.drv_b = drv_b;
 }
 
-
 FORCE_INLINE_ATTR void pmu_ll_lp_set_regulator_slp_xpd(pmu_dev_t *hw, pmu_lp_mode_t mode, bool slp_xpd)
 {
     hw->lp_sys[mode].regulator0.slp_xpd = slp_xpd;
@@ -266,7 +264,6 @@ FORCE_INLINE_ATTR void pmu_ll_lp_set_xtal_xpd(pmu_dev_t *hw, pmu_lp_mode_t mode,
     hw->lp_sys[mode].xtal.xpd_xtal = xpd_xtal;
 }
 
-
 FORCE_INLINE_ATTR void pmu_ll_lp_set_dig_power(pmu_dev_t *hw, pmu_lp_mode_t mode, uint32_t flag)
 {
     hw->lp_sys[mode].dig_power.val = flag;

components/esp_hal_pmu/esp32s2/include/hal/rtc_cntl_ll.h

@@ -41,10 +41,10 @@ FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_set_wakeup_pins(uint32_t io_mask, uint32
     REG_SET_FIELD(RTC_CNTL_EXT_WAKEUP1_REG, RTC_CNTL_EXT_WAKEUP1_SEL, io_mask);
     if ((io_mask & mode_mask) == io_mask) {
         SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1,
-                1, RTC_CNTL_EXT_WAKEUP1_LV_S);
+                          1, RTC_CNTL_EXT_WAKEUP1_LV_S);
     } else {
         SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1,
-                0, RTC_CNTL_EXT_WAKEUP1_LV_S);
+                          0, RTC_CNTL_EXT_WAKEUP1_LV_S);
     }
 }
 

components/esp_hal_pmu/esp32s3/include/hal/rtc_cntl_ll.h

@@ -45,10 +45,10 @@ FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_set_wakeup_pins(uint32_t io_mask, uint32
     REG_SET_FIELD(RTC_CNTL_EXT_WAKEUP1_REG, RTC_CNTL_EXT_WAKEUP1_SEL, io_mask);
     if ((io_mask & mode_mask) == io_mask) {
         SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1,
-                1, RTC_CNTL_EXT_WAKEUP1_LV_S);
+                          1, RTC_CNTL_EXT_WAKEUP1_LV_S);
     } else {
         SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1,
-                0, RTC_CNTL_EXT_WAKEUP1_LV_S);
+                          0, RTC_CNTL_EXT_WAKEUP1_LV_S);
     }
 }
 

components/esp_hal_pmu/esp32s3/rtc_cntl_hal.c

@@ -62,10 +62,10 @@ void rtc_cntl_hal_enable_cpu_retention(void *addr)
 
             rtc_cntl_ll_set_cpu_retention_link_addr((uint32_t)plink);
             rtc_cntl_ll_config_cpu_retention_timing(
-                    DEFAULT_RETENTION_WAIT_CYCLES,
+                DEFAULT_RETENTION_WAIT_CYCLES,
-                    DEFAULT_RETENTION_CLKOFF_WAIT_CYCLES,
+                DEFAULT_RETENTION_CLKOFF_WAIT_CYCLES,
-                    DEFAULT_RETENTION_DONE_WAIT_CYCLES
+                DEFAULT_RETENTION_DONE_WAIT_CYCLES
-                );
+            );
             rtc_cntl_ll_enable_cpu_retention_clock();
             rtc_cntl_ll_enable_cpu_retention();
 #if SOC_PM_SUPPORT_TAGMEM_PD
@@ -119,17 +119,17 @@ void rtc_cntl_hal_enable_tagmem_retention(void *addr)
             rtc_cntl_ll_enable_tagmem_retention();
             if (retent->tagmem.icache.enable) {
                 rtc_cntl_ll_enable_icache_tagmem_retention(
-                        retent->tagmem.icache.start_point,
+                    retent->tagmem.icache.start_point,
-                        retent->tagmem.icache.vld_size,
+                    retent->tagmem.icache.vld_size,
-                        retent->tagmem.icache.size
+                    retent->tagmem.icache.size
-                    );
+                );
             }
             if (retent->tagmem.dcache.enable) {
                 rtc_cntl_ll_enable_dcache_tagmem_retention(
-                        retent->tagmem.dcache.start_point,
+                    retent->tagmem.dcache.start_point,
-                        retent->tagmem.dcache.vld_size,
+                    retent->tagmem.dcache.vld_size,
-                        retent->tagmem.dcache.size
+                    retent->tagmem.dcache.size
-                    );
+                );
             }
         }
     }

components/esp_hal_pmu/esp32s31/include/hal/pmu_hal.h

@@ -0,0 +1,23 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// The HAL layer for PMU
+
+#pragma once
+
+#include "soc/soc_caps.h"
+#include "hal/pmu_ll.h"
+#include "hal/pmu_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// TODO: ["ESP32S31"] IDF-14653
+
+#ifdef __cplusplus
+}
+#endif

components/esp_hal_pmu/esp32s31/include/hal/pmu_ll.h

@@ -0,0 +1,29 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// The LL layer for ESP32-S31 PMU register operations
+
+#pragma once
+
+#include <stdlib.h>
+#include <stdbool.h>
+#include "soc/soc.h"
+#include "esp_attr.h"
+#include "hal/assert.h"
+#include "soc/pmu_struct.h"
+#include "hal/pmu_types.h"
+#include "hal/misc.h"
+#include "hal/config.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// TODO: ["ESP32S31"] IDF-14653
+
+#ifdef __cplusplus
+}
+#endif

components/esp_hal_pmu/esp32s31/pmu_hal.c

@@ -0,0 +1,9 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// The HAL layer for PMU (ESP32-S31 specific part)
+
+// TODO: ["ESP32S31"] IDF-14653

components/esp_hal_pmu/linker.lf

@@ -0,0 +1,5 @@
+[mapping:esp_hal_pmu]
+archive: libesp_hal_pmu.a
+entries:
+    if SOC_PMU_SUPPORTED = y:
+        pmu_hal (noflash)

components/esp_hw_support/CMakeLists.txt

@@ -9,7 +9,7 @@ if(${target} STREQUAL "linux")
     return()
 endif()
 
-set(requires esp_hal_dma esp_hal_gpio esp_hal_usb)
+set(requires esp_hal_dma esp_hal_gpio esp_hal_usb esp_hal_pmu)
 # only esp_hw_support/adc_share_hw_ctrl.c requires efuse component
 set(priv_requires efuse spi_flash bootloader_support esp_hal_wdt)
 

components/esp_pm/linker.lf

@@ -81,14 +81,18 @@ entries:
         esp_time_impl:esp_time_impl_get_boot_time (noflash)
         esp_time_impl:esp_set_time_from_rtc (noflash)
 
-[mapping:hal_pm]
+[mapping:esp_hal_pmu_pm]
-archive: libhal.a
+archive: libesp_hal_pmu.a
 entries:
     if SOC_PM_CPU_RETENTION_BY_RTCCNTL = y:
         if PM_SLP_IRAM_OPT = y && PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP = y:
             rtc_cntl_hal:rtc_cntl_hal_enable_cpu_retention (noflash)
         if PM_SLP_IRAM_OPT = y && PM_RESTORE_CACHE_TAGMEM_AFTER_LIGHT_SLEEP = y:
             rtc_cntl_hal:rtc_cntl_hal_enable_tagmem_retention (noflash)
+
+[mapping:hal_pm]
+archive: libhal.a
+entries:
     if SOC_TEMP_SENSOR_SUPPORTED = y:
         if PM_SLP_IRAM_OPT = y:
             temperature_sensor_hal:temperature_sensor_hal_get_raw_value (noflash)

components/hal/CMakeLists.txt

@@ -140,10 +140,6 @@ elseif(NOT BOOTLOADER_BUILD)
         list(APPEND srcs "sdio_slave_hal.c")
     endif()
 
-    if(CONFIG_SOC_PMU_SUPPORTED)
-        list(APPEND srcs "${target}/pmu_hal.c")
-    endif()
-
     if(CONFIG_SOC_APM_SUPPORTED)
         list(APPEND srcs "apm_hal.c")
     endif()
@@ -161,11 +157,6 @@ elseif(NOT BOOTLOADER_BUILD)
     if(CONFIG_SOC_TEMP_SENSOR_SUPPORTED)
         list(APPEND srcs "temperature_sensor_hal.c")
     endif()
-
-    if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/${target}/rtc_cntl_hal.c")
-        list(APPEND srcs "${target}/rtc_cntl_hal.c")
-    endif()
-
 endif()
 
 idf_component_register(SRCS ${srcs}

components/hal/linker.lf

@@ -9,5 +9,3 @@ entries:
             cache_hal (noflash)
     if SOC_SYSTIMER_SUPPORTED = y && HAL_SYSTIMER_USE_ROM_IMPL = n:
         systimer_hal (noflash)
-    if SOC_PMU_SUPPORTED = y:
-        pmu_hal (noflash)

components/ulp/CMakeLists.txt

@@ -97,5 +97,6 @@ endif()
 idf_component_register(
     SRCS ${srcs}
     INCLUDE_DIRS ${includes}
-    REQUIRES esp_adc esp_driver_gpio esp_driver_uart esp_driver_i2s esp_hal_i2c esp_hal_touch_sens esp_hal_gpspi
+    REQUIRES esp_adc esp_driver_gpio esp_driver_uart esp_driver_i2s
+             esp_hal_i2c esp_hal_touch_sens esp_hal_gpspi esp_hal_pmu
 )

tools/test_apps/system/g1_components/CMakeLists.txt

@@ -21,6 +21,7 @@ set(esp_hal_components
     esp_hal_usb
     esp_hal_wdt
     esp_hal_gpspi
+    esp_hal_pmu
 )
 set(COMPONENTS ${g0_components} ${g1_components} ${esp_hal_components} main)