refactor(hal): extract cache && mmu HAL into esp_hal_cache

components/bootloader/subproject/main/ld/esp32/bootloader.sections.ld.in

@@ -31,7 +31,7 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hw_support.a:rtc_clk.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32c2/bootloader.sections.ld.in

@@ -30,8 +30,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hw_support.a:rtc_clk.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32c3/bootloader.sections.ld.in

@@ -29,8 +29,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hw_support.a:rtc_clk.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32c5/bootloader.sections.ld.in

@@ -31,8 +31,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hal_security.a:huk_hal.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32c6/bootloader.sections.ld.in

@@ -32,8 +32,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hw_support.a:rtc_clk.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32c61/bootloader.sections.ld.in

@@ -31,8 +31,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hw_support.a:rtc_clk.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32h2/bootloader.sections.ld.in

@@ -30,8 +30,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hw_support.a:rtc_clk.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32h21/bootloader.sections.ld.in

@@ -30,8 +30,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hw_support.a:rtc_clk.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32h4/bootloader.sections.ld.in

@@ -31,8 +31,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hw_support.a:rtc_clk.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32p4/bootloader.sections.ld.in

@@ -30,8 +30,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hal_security.a:huk_hal.*(.literal .text .literal.* .text.*) \
@@ -72,8 +72,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_security.a:huk_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_security.a:key_mgr_hal.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32s2/bootloader.sections.ld.in

@@ -31,8 +31,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hw_support.a:rtc_clk.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32s3/bootloader.sections.ld.in

@@ -31,8 +31,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hw_support.a:rtc_clk.*(.literal .text .literal.* .text.*) \

components/bootloader/subproject/main/ld/esp32s31/bootloader.sections.ld.in

@@ -31,8 +31,8 @@
     *libesp_image_verify.a:secure_boot_signatures_bootloader.*(.literal .text .literal.* .text.*) \
     *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*) \
     *libspi_flash.a:*.*(.literal .text .literal.* .text.*) \
-    *libhal.a:mmu_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:mmu_hal.*(.literal .text .literal.* .text.*) \
-    *libhal.a:cache_hal.*(.literal .text .literal.* .text.*) \
+    *libesp_hal_cache.a:cache_hal.*(.literal .text .literal.* .text.*) \
     *libhal.a:efuse_hal.*(.literal .text .literal.* .text.*) \
     *libesp_hal_wdt.a:wdt_hal_iram.*(.literal .text .literal.* .text.*) \
     *libesp_hal_security.a:huk_hal.*(.literal .text .literal.* .text.*) \

components/bootloader_support/CMakeLists.txt

@@ -27,7 +27,7 @@ if(esp_tee_build)
     # from bootloader_utility_tee.c.
     idf_component_register(SRCS ${tee_srcs}
                            INCLUDE_DIRS ${tee_inc_dirs}
-                           PRIV_REQUIRES efuse esp_app_format esptool_py esp_hal_security
+                           PRIV_REQUIRES efuse esp_app_format esptool_py esp_hal_security esp_hal_cache
                                          esp_image_verify)
     return()
 endif()
@@ -74,7 +74,7 @@ if(BOOTLOADER_BUILD OR CONFIG_APP_BUILD_TYPE_RAM)
     # micro-ecc is only needed for secure boot sources built under BOOTLOADER_BUILD.
     # For CONFIG_APP_BUILD_TYPE_RAM (loadable ELF app) we don't build those sources,
     # and micro-ecc lives in the bootloader subproject so it isn't available in app builds.
-    set(priv_requires spi_flash efuse esp_bootloader_format esp_app_format esptool_py)
+    set(priv_requires spi_flash efuse esp_bootloader_format esp_app_format esptool_py esp_hal_cache)
     if(BOOTLOADER_BUILD)
         list(APPEND priv_requires micro-ecc esp_image_verify)
     endif()
@@ -97,7 +97,7 @@ else()
     set(include_dirs "include" "bootloader_flash/include")
     set(priv_include_dirs "private_include")
     # heap is required for `heap_memory_layout.h`.
-    set(priv_requires spi_flash efuse heap esp_bootloader_format esp_app_format
+    set(priv_requires spi_flash efuse heap esp_bootloader_format esp_app_format esp_hal_cache
         esptool_py)
     # `esp_hal_ana_conv` is required by bootloader_random_esp32xx.c
     list(APPEND priv_requires esp_mspi esp_hal_wdt esp_hal_gpio esp_hal_uart esp_hal_ana_conv

components/esp_common/test_apps/esp_common/main/CMakeLists.txt

@@ -4,5 +4,5 @@ idf_component_register(SRCS "test_app_main.c"
                             "test_esp_err_to_name.c"
                             "test_esp_macro.c"
                        INCLUDE_DIRS "."
-                       PRIV_REQUIRES unity esp_mm esp_psram
+                       PRIV_REQUIRES unity esp_mm esp_psram esp_hal_cache
                        WHOLE_ARCHIVE)

components/esp_driver_dma/CMakeLists.txt

@@ -4,7 +4,7 @@ if(${target} STREQUAL "linux")
 endif()
 
 set(public_include "include")
-set(requires esp_hal_dma)
+set(requires esp_hal_dma esp_hal_cache)
 set(srcs "src/esp_dma_utils.c" "src/gdma_link.c")
 
 if(CONFIG_SOC_GDMA_SUPPORTED)

components/esp_driver_parlio/test_apps/parlio/main/CMakeLists.txt

@@ -19,7 +19,7 @@ endif()
 idf_component_register(SRCS ${srcs}
                        PRIV_REQUIRES unity esp_driver_parlio esp_driver_gpio
                                     esp_driver_i2s esp_driver_spi esp_psram
-                                    esp_driver_bitscrambler
+                                    esp_driver_bitscrambler esp_hal_cache
                        WHOLE_ARCHIVE)
 
 if(CONFIG_SOC_BITSCRAMBLER_SUPPORTED)

components/esp_hal_cache/CMakeLists.txt

@@ -0,0 +1,38 @@
+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(includes "include" "${target}/include")
+
+# The cache HAL is always built for normal apps, where the flash cache is enabled.
+# Pure RAM apps do not use the flash cache, except on chips where internal memory
+# accesses also go through the L1 cache (e.g. ESP32-P4): cache synchronization is
+# still required around internal RAM DMA operations on such chips.
+if(NOT CONFIG_APP_BUILD_TYPE_PURE_RAM_APP OR CONFIG_SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE)
+    if(${target} STREQUAL "esp32")
+        list(APPEND srcs "esp32/cache_hal_esp32.c")
+    else()
+        list(APPEND srcs "cache_hal.c")
+    endif()
+endif()
+
+# The MMU HAL implements external memory (flash/PSRAM) address translation.
+# Pure RAM apps do not map any external memory, so it is not built for them.
+if(NOT CONFIG_APP_BUILD_TYPE_PURE_RAM_APP AND CONFIG_SOC_MMU_PERIPH_NUM)
+    list(APPEND srcs "mmu_hal.c")
+endif()
+
+# Target-specific cache peripheral data
+if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/${target}/cache_periph.c")
+    list(APPEND srcs "${target}/cache_periph.c")
+endif()
+
+idf_component_register(
+    SRCS ${srcs}
+    INCLUDE_DIRS ${includes}
+    REQUIRES soc hal
+    LDFRAGMENTS linker.lf
+)

components/esp_hal_cache/README.md

@@ -0,0 +1,39 @@
+# ESP Hardware Abstraction Layer for Cache and MMU
+
+> [!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_cache` component provides a **Hardware Abstraction Layer** for the cache and the external-memory MMU across all ESP-IDF supported targets. It serves as a foundation for higher-level drivers (DMA drivers, `esp_mm`, `spi_flash`, etc.) by offering a consistent interface to cache maintenance and external-memory address translation, while hiding the complexities of chip-specific implementations.
+
+## Architecture
+
+The HAL architecture consists of two primary layers:
+
+1. **HAL Layer (Upper)**: Defines the operational sequences and data structures required to interact with the cache and MMU, including:
+   - Cache initialization, enabling and disabling
+   - Cache maintenance operations (writeback, invalidate, writeback + invalidate, sync)
+   - Cache freezing and preloading on supported chips
+   - MMU mapping operations (virtual-to-physical address translation for flash and PSRAM)
+
+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 (`<target>/include/hal/cache_ll.h` and `<target>/include/hal/mmu_ll.h`)
+   - Chip-specific register configurations
+   - Hardware feature compatibility
+
+Implementation notes:
+
+- `cache_hal.c` implements the target-independent HAL sequences; ESP32 uses its dedicated ROM-compatible implementation (`esp32/cache_hal_esp32.c`).
+- `<target>/cache_periph.c` contains target-specific cache peripheral data.
+
+## Usage
+
+This component is primarily used by ESP-IDF drivers and system components such as `esp_driver_dma`, `esp_mm`, `esp_mspi`, `spi_flash` and `esp_psram`, as well as by the bootloader.
+
+For advanced developers implementing custom DMA or memory-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 cache and MMU register definitions and SoC capabilities
+- `hal`: Core hardware abstraction utilities and macros

components/esp_hal_cache/cache_hal.c

@@ -12,8 +12,6 @@
 #include "hal/cache_hal.h"
 #include "hal/cache_types.h"
 #include "hal/cache_ll.h"
-#include "hal/mmu_hal.h"
-#include "hal/mmu_ll.h"
 #include "soc/soc_caps.h"
 
 /*------------------------------------------------------------------------------

components/esp_hal_cache/esp32s2/include/hal/mmu_ll.h

@@ -379,19 +379,6 @@ static inline uint32_t mmu_ll_entry_id_to_vaddr_base(uint32_t mmu_id, uint32_t e
     return vaddr_base + (entry_id << 16);
 }
 
-/**
- * Check if the external memory vaddr belongs to the DPORT bus region
- *
- * @param vaddr start of the virtual address
- *
- * @return True for valid
- */
-__attribute__((always_inline))
-static inline bool mmu_ll_vaddr_in_dport_bus_region(uint32_t vaddr)
-{
-    return (vaddr >= SOC_DPORT_CACHE_ADDRESS_LOW && vaddr < SOC_DPORT_CACHE_ADDRESS_HIGH);
-}
-
 #ifdef __cplusplus
 }
 #endif

components/esp_hal_cache/linker.lf

@@ -1,9 +1,9 @@
-[mapping:hal]
+[mapping:esp_hal_cache]
-archive: libhal.a
+archive: libesp_hal_cache.a
 entries:
     if APP_BUILD_TYPE_PURE_RAM_APP = n:
-        mmu_hal (noflash)
         if IDF_TARGET_ESP32 = y:
             cache_hal_esp32 (noflash)
         else:
             cache_hal (noflash)
+        mmu_hal (noflash)

components/esp_hal_debug_assist/CMakeLists.txt

@@ -6,6 +6,10 @@ endif()
 set(srcs)
 set(public_include "include" "${target}/include")
 
+if(CONFIG_SOC_DEBUG_PROBE_SUPPORTED)
+    list(APPEND srcs "${target}/debug_probe_periph.c")
+endif()
+
 if(CONFIG_SOC_RISCV_TRACE_SUPPORTED)
     list(APPEND srcs "riscv_trace_hal.c")
 endif()

components/esp_hal_debug_assist/esp32p4/debug_probe_periph.c

@@ -1,12 +1,12 @@
 /*
  * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
 #include "soc/gpio_sig_map.h"
 #include "soc/lp_gpio_sig_map.h"
-#include "soc/debug_probe_periph.h"
+#include "hal/debug_probe_periph.h"
 
 const debug_probe_signal_conn_t debug_probe_periph_signals = {
     .units = {

components/esp_hal_debug_assist/esp32p4/include/hal/debug_probe_targets.h

@@ -1,7 +1,7 @@
 /*
  * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
 #pragma once

components/esp_hal_debug_assist/esp32s31/debug_probe_periph.c

@@ -1,12 +1,12 @@
 /*
  * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
 #include "soc/gpio_sig_map.h"
 #include "soc/lp_gpio_sig_map.h"
-#include "soc/debug_probe_periph.h"
+#include "hal/debug_probe_periph.h"
 
 const debug_probe_signal_conn_t debug_probe_periph_signals = {
     .units = {

components/esp_hal_debug_assist/esp32s31/include/hal/debug_probe_targets.h

@@ -1,7 +1,7 @@
 /*
  * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
 #pragma once

components/esp_hal_debug_assist/include/hal/debug_probe_periph.h

@@ -1,7 +1,7 @@
 /*
  * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
 #pragma once

components/esp_hal_gpio/esp32h4/rtc_io_periph.c

@@ -1,7 +1,7 @@
 /**
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- *  SPDX-License-Identifier: Apache-2.0 OR MIT
+ *  SPDX-License-Identifier: Apache-2.0
  */
 
 #include "hal/rtc_io_periph.h"

components/esp_hal_pmu/CMakeLists.txt

@@ -36,6 +36,7 @@ endif()
 
 if(CONFIG_SOC_BOD_SUPPORTED)
     list(APPEND srcs "brownout_hal.c")
+    list(APPEND srcs "${target}/power_supply_periph.c")
 endif()
 
 if(CONFIG_SOC_VBAT_SUPPORTED)

components/esp_hal_pmu/README.md

@@ -39,6 +39,9 @@ The HAL architecture consists of two primary layers:
 - Control ready wait cycle configuration (isolate/reset)
 - Power mode transitions (active, sleep, modem)
 
+### Brownout Detection
+- Brownout detector control (enable/disable, thresholds, reset behavior)
+
 ### Sleep and Wakeup
 - Sleep mode configuration
 - Wakeup source management

components/esp_hal_pmu/esp32/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_RTC_CORE_INTR_SOURCE,

components/esp_hal_pmu/esp32c2/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_RTC_CORE_INTR_SOURCE,

components/esp_hal_pmu/esp32c3/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_RTC_CORE_INTR_SOURCE,

components/esp_hal_pmu/esp32c5/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_LP_RTC_TIMER_INTR_SOURCE,

components/esp_hal_pmu/esp32c6/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_LP_RTC_TIMER_INTR_SOURCE,

components/esp_hal_pmu/esp32c61/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_LP_RTC_TIMER_INTR_SOURCE,

components/esp_hal_pmu/esp32h2/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_LP_RTC_TIMER_INTR_SOURCE,

components/esp_hal_pmu/esp32h21/power_supply_periph.c

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "hal/power_supply_periph.h"
+
+const power_supply_signal_conn_t power_supply_periph_signal = {
+    .irq = ETS_LP_RTC_TIMER_INTR_SOURCE,
+};

components/esp_hal_pmu/esp32h4/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_LP_RTC_TIMER_INTR_SOURCE,

components/esp_hal_pmu/esp32p4/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_LP_ANAPERI_INTR_SOURCE,

components/esp_hal_pmu/esp32s2/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_RTC_CORE_INTR_SOURCE,

components/esp_hal_pmu/esp32s3/power_supply_periph.c

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "hal/power_supply_periph.h"
+
+const power_supply_signal_conn_t power_supply_periph_signal = {
+    .irq = ETS_RTC_CORE_INTR_SOURCE,
+};

components/esp_hal_pmu/esp32s31/power_supply_periph.c

@@ -1,10 +1,10 @@
 /*
  * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 const power_supply_signal_conn_t power_supply_periph_signal = {
     .irq = ETS_LP_ANAPERI_INTR_SOURCE,

components/esp_hal_pmu/include/hal/power_supply_periph.h

@@ -1,7 +1,7 @@
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
- * SPDX-License-Identifier: Apache-2.0 OR MIT
+ * SPDX-License-Identifier: Apache-2.0
  */
 
 #pragma once

components/esp_hal_security/esp32s2/include/hal/sha_ll.h

@@ -10,12 +10,25 @@
 #include "soc/hwcrypto_reg.h"
 #include "hal/sha_types.h"
 #include "soc/dport_reg.h"
-#include "hal/mmu_ll.h"
+#include "soc/ext_mem_defs.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * Check if the external memory vaddr belongs to the DPORT bus region
+ *
+ * @param vaddr start of the virtual address
+ *
+ * @return True for valid
+ */
+__attribute__((always_inline))
+static inline bool _vaddr_in_dport_bus_region(uint32_t vaddr)
+{
+    return (vaddr >= SOC_DPORT_CACHE_ADDRESS_LOW && vaddr < SOC_DPORT_CACHE_ADDRESS_HIGH);
+}
+
 /**
  * @brief Enable the bus clock for SHA peripheral module
  *
@@ -158,7 +171,7 @@ static inline void sha_ll_fill_text_block(const void *input_text, size_t block_w
      * Thus, when accessing data from these addresses we need to ensure
      * the operations are word-aligned.
      */
-    if (mmu_ll_vaddr_in_dport_bus_region((uint32_t)input_text)) {
+    if (_vaddr_in_dport_bus_region((uint32_t)input_text)) {
         force_word_aligned_access = true;
     }
 

components/esp_hw_support/CMakeLists.txt

@@ -38,7 +38,7 @@ if(__ULP_BUILDV2)
     return()
 endif()
 
-set(requires esp_hal_gpio esp_hal_usb esp_hal_pmu esp_hal_regi2c esp_hal_uart esp_hal_debug_assist)
+set(requires esp_hal_gpio esp_hal_usb esp_hal_pmu esp_hal_regi2c esp_hal_uart esp_hal_debug_assist esp_hal_cache)
 set(priv_requires efuse                 # only esp_hw_support/adc_share_hw_ctrl.c requires efuse component
                   esp_mspi
                   bootloader_support

components/esp_hw_support/debug_probe/debug_probe.c

@@ -14,7 +14,7 @@
 #include "esp_check.h"
 #include "esp_heap_caps.h"
 #include "soc/soc_caps.h"
-#include "soc/debug_probe_periph.h"
+#include "hal/debug_probe_periph.h"
 #include "soc/io_mux_reg.h"
 #include "driver/rtc_io.h"
 #include "driver/lp_io.h"

components/esp_hw_support/debug_probe/include/esp_private/debug_probe_types.h

@@ -12,7 +12,7 @@
 #include "soc/soc_caps.h"
 #include "hal/debug_probe_types.h"
 #if SOC_DEBUG_PROBE_SUPPORTED
-#include "soc/debug_probe_targets.h"
+#include "hal/debug_probe_targets.h"
 #endif
 
 #ifdef __cplusplus

components/esp_hw_support/power_supply/brownout.c

@@ -25,7 +25,7 @@
 #include "sdkconfig.h"
 #include "esp_rom_serial_output.h"
 #include "hal/uart_ll.h"
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 #include "esp_brownout.h"
 #include "esp_check.h"
 #include "esp_memory_utils.h"

components/esp_hw_support/power_supply/vbat.c

@@ -24,7 +24,7 @@
 #include "esp_check.h"
 #include "soc/rtc.h"
 #include "soc/clk_tree_defs.h"
-#include "soc/power_supply_periph.h"
+#include "hal/power_supply_periph.h"
 
 #if CONFIG_ESP_VBAT_INIT_AUTO
 #if CONFIG_ESP_VBAT_ISR_CACHE_SAFE

components/esp_image_verify/CMakeLists.txt

@@ -54,7 +54,7 @@ endif()
 # from bootloader_support's public include path.
 set(requires bootloader_support esp_app_format esp_bootloader_format)
 
-set(priv_requires spi_flash efuse esp_hal_security)
+set(priv_requires spi_flash efuse esp_hal_security esp_hal_cache)
 
 if(BOOTLOADER_BUILD)
     list(APPEND priv_requires micro-ecc)

components/esp_libc/test_apps/newlib/main/CMakeLists.txt

@@ -21,5 +21,5 @@ if(CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS)
 endif()
 
 idf_component_register(SRCS "${srcs}"
-                       PRIV_REQUIRES unity vfs cmock esp_timer esp_mspi test_utils pthread esp_psram
+                       PRIV_REQUIRES unity vfs cmock esp_timer esp_mspi esp_hal_cache test_utils pthread esp_psram
                        WHOLE_ARCHIVE)

components/esp_mm/CMakeLists.txt

@@ -7,6 +7,8 @@ endif()
 set(includes "include")
 
 # Note: requires esp_mspi for cache_utils
+# REQUIRES esp_hal_cache — esp_mmu_map.h (public header) includes hal/mmu_types.h
+set(requires esp_hal_cache)
 set(priv_requires heap esp_hal_dma esp_mspi)
 
 set(srcs)
@@ -28,5 +30,6 @@ endif()
 
 idf_component_register(SRCS ${srcs}
                        INCLUDE_DIRS ${includes}
+                       REQUIRES ${requires}
                        PRIV_REQUIRES ${priv_requires}
                        LDFRAGMENTS linker.lf)

components/esp_mspi/CMakeLists.txt

@@ -11,7 +11,7 @@ endif()
 if(non_os_build OR CONFIG_APP_BUILD_TYPE_PURE_RAM_APP)
     # efuse is required by esp_mspi_align.c to query the flash encryption state
     set(priv_requires bootloader_support soc esp_hal_gpio efuse)
-    set(requires hal esp_hal_mspi)
+    set(requires esp_hal_mspi esp_hal_cache)
     set(srcs "spi_flash_wrap.c" "spi_flash_os_tee_stub.c")
     if(NOT BOOTLOADER_BUILD)
         list(APPEND srcs "esp_mspi_align/esp_mspi_align.c")

components/esp_system/test_apps/esp_system_unity_tests/main/CMakeLists.txt

@@ -5,7 +5,8 @@ set(requires "unity"
              "esp_hal_wdt"
              "esp_timer"
              "nvs_flash"
-             "esp_psram")
+             "esp_psram"
+             "esp_hal_cache")
 
 set(SRC  "test_app_main.c"
           "test_backtrace.c"

components/esp_tee/CMakeLists.txt

@@ -82,7 +82,7 @@ else()
     idf_component_register(INCLUDE_DIRS include
                            SRCS ${srcs}
                            PRIV_REQUIRES efuse esp_hal_wdt esp_security esp_stdio
-                                         esp_system esptool_py mbedtls spi_flash esp_mspi)
+                                         esp_system esptool_py mbedtls spi_flash esp_mspi esp_hal_cache)
     if(CONFIG_SECURE_ENABLE_TEE)
         set(EXTRA_LINK_FLAGS)
         list(APPEND EXTRA_LINK_FLAGS "-u esp_tee_app_config")

components/esp_tee/subproject/main/ld/esp32c5/esp_tee.ld.in

@@ -101,8 +101,8 @@ SECTIONS
     *libmain.a:esp_tee_intr.c*(.literal .text .literal.* .text.*)
     *libmain.a:esp_tee_apm_intr.c*(.literal .text .literal.* .text.*)
     /* HAL */
-    *libhal.a:mmu_hal.c*(.literal .text .literal.* .text.*)
+    *libesp_hal_cache.a:mmu_hal.c*(.literal .text .literal.* .text.*)
-    *libhal.a:cache_hal.c*(.literal .text .literal.* .text.*)
+    *libesp_hal_cache.a:cache_hal.c*(.literal .text .literal.* .text.*)
     *libesp_hal_security.a:apm_hal.c*(.literal .text .literal.* .text.*)
     *libesp_hal_mspi.a:*(.literal .text .literal.* .text.*)
     *libesp_hal_wdt.a:*(.literal .text .literal.* .text.*)
@@ -175,8 +175,8 @@ SECTIONS
     *libmain.a:panic_helper_riscv.*(.rodata .srodata .rodata.* .srodata.*)
     *libmain.a:esp_tee_apm_intr.c.*(.rodata .srodata .rodata.* .srodata.*)
     /* HAL (noflash) */
-    *libhal.a:mmu_hal.c*(.rodata .srodata .rodata.* .srodata.*)
+    *libesp_hal_cache.a:mmu_hal.c*(.rodata .srodata .rodata.* .srodata.*)
-    *libhal.a:cache_hal.c*(.rodata .srodata .rodata.* .srodata.*)
+    *libesp_hal_cache.a:cache_hal.c*(.rodata .srodata .rodata.* .srodata.*)
     *libesp_hal_mspi.a:*(.rodata .srodata .rodata.* .srodata.*)
     *libesp_mspi.a:*(.rodata .rodata.* .srodata .srodata.*)
     _tee_rodata_end = ABSOLUTE(.);

components/esp_tee/subproject/main/ld/esp32c6/esp_tee.ld.in

@@ -99,8 +99,8 @@ SECTIONS
     *libmain.a:esp_tee_intr.c*(.literal .text .literal.* .text.*)
     *libmain.a:esp_tee_apm_intr.c*(.literal .text .literal.* .text.*)
     /* HAL */
-    *libhal.a:mmu_hal.c*(.literal .text .literal.* .text.*)
+    *libesp_hal_cache.a:mmu_hal.c*(.literal .text .literal.* .text.*)
-    *libhal.a:cache_hal.c*(.literal .text .literal.* .text.*)
+    *libesp_hal_cache.a:cache_hal.c*(.literal .text .literal.* .text.*)
     *libesp_hal_security.a:apm_hal.c*(.literal .text .literal.* .text.*)
     *libesp_hal_mspi.a:*(.literal .text .literal.* .text.*)
     *libesp_hal_wdt.a:*(.literal .text .literal.* .text.*)
@@ -173,8 +173,8 @@ SECTIONS
     *libmain.a:panic_helper_riscv.*(.rodata .srodata .rodata.* .srodata.*)
     *libmain.a:esp_tee_apm_intr.c.*(.rodata .srodata .rodata.* .srodata.*)
     /* HAL (noflash) */
-    *libhal.a:mmu_hal.c*(.rodata .srodata .rodata.* .srodata.*)
+    *libesp_hal_cache.a:mmu_hal.c*(.rodata .srodata .rodata.* .srodata.*)
-    *libhal.a:cache_hal.c*(.rodata .srodata .rodata.* .srodata.*)
+    *libesp_hal_cache.a:cache_hal.c*(.rodata .srodata .rodata.* .srodata.*)
     *libesp_hal_mspi.a:*(.rodata .srodata .rodata.* .srodata.*)
     *libesp_mspi.a:*(.rodata .rodata.* .srodata .srodata.*)
     _tee_rodata_end = ABSOLUTE(.);

components/esp_tee/subproject/main/ld/esp32c61/esp_tee.ld.in

@@ -99,8 +99,8 @@ SECTIONS
     *libmain.a:esp_tee_intr.c*(.literal .text .literal.* .text.*)
     *libmain.a:esp_tee_apm_intr.c*(.literal .text .literal.* .text.*)
     /* HAL */
-    *libhal.a:mmu_hal.c*(.literal .text .literal.* .text.*)
+    *libesp_hal_cache.a:mmu_hal.c*(.literal .text .literal.* .text.*)
-    *libhal.a:cache_hal.c*(.literal .text .literal.* .text.*)
+    *libesp_hal_cache.a:cache_hal.c*(.literal .text .literal.* .text.*)
     *libesp_hal_security.a:apm_hal.c*(.literal .text .literal.* .text.*)
     *libesp_hal_mspi.a:*(.literal .text .literal.* .text.*)
     *libesp_hal_wdt.a:*(.literal .text .literal.* .text.*)
@@ -173,8 +173,8 @@ SECTIONS
     *libmain.a:panic_helper_riscv.*(.rodata .srodata .rodata.* .srodata.*)
     *libmain.a:esp_tee_apm_intr.c.*(.rodata .srodata .rodata.* .srodata.*)
     /* HAL (noflash) */
-    *libhal.a:mmu_hal.c*(.rodata .srodata .rodata.* .srodata.*)
+    *libesp_hal_cache.a:mmu_hal.c*(.rodata .srodata .rodata.* .srodata.*)
-    *libhal.a:cache_hal.c*(.rodata .srodata .rodata.* .srodata.*)
+    *libesp_hal_cache.a:cache_hal.c*(.rodata .srodata .rodata.* .srodata.*)
     *libesp_hal_mspi.a:*(.rodata .srodata .rodata.* .srodata.*)
     *libesp_mspi.a:*(.rodata .rodata.* .srodata .srodata.*)
     _tee_rodata_end = ABSOLUTE(.);