refactor(psram): cleanup psram component code structure

.gitlab/CODEOWNERS

@@ -106,7 +106,8 @@
 /components/esp_partition/            @esp-idf-codeowners/storage
 /components/esp_phy/                  @esp-idf-codeowners/bluetooth @esp-idf-codeowners/wifi @esp-idf-codeowners/ieee802154
 /components/esp_pm/                   @esp-idf-codeowners/power-management @esp-idf-codeowners/bluetooth @esp-idf-codeowners/wifi @esp-idf-codeowners/system
-/components/esp_psram/                @esp-idf-codeowners/peripherals @esp-idf-codeowners/system
+/components/esp_psram/                @esp-idf-codeowners/peripherals
+/components/esp_psram/system_layer/   @esp-idf-codeowners/peripherals @esp-idf-codeowners/system
 /components/esp_ringbuf/              @esp-idf-codeowners/system
 /components/esp_rom/                  @esp-idf-codeowners/system @esp-idf-codeowners/bluetooth @esp-idf-codeowners/wifi
 /components/esp_security/             @esp-idf-codeowners/security

.gitlab/ci/rules.yml

@@ -35,6 +35,7 @@
   # Add folders excluded by "???[!t]" and "??[!s]?"
   # pre-commit: tools/ci/check_rules_components_patterns.py
   - "components/bt/host/**/*"
+  - "components/esp_psram/system_layer/*"
 
 .patterns-downloadable-tools: &patterns-downloadable-tools
   - "tools/idf_tools.py"

components/esp_psram/CMakeLists.txt

@@ -6,6 +6,10 @@ endif()
 
 set(includes "include")
 
+if(CONFIG_SOC_SPIRAM_XIP_SUPPORTED)
+    list(APPEND includes xip_impl/include)
+endif()
+
 set(priv_requires heap spi_flash esp_mm)
 if(${target} STREQUAL "esp32")
     list(APPEND priv_requires bootloader_support esp_driver_spi esp_driver_gpio)
@@ -14,46 +18,36 @@ endif()
 set(srcs)
 
 if(CONFIG_SPIRAM)
-    list(APPEND srcs "esp_psram.c")
+    list(APPEND srcs "system_layer/esp_psram.c")
 
     if(${target} STREQUAL "esp32")
         list(APPEND srcs "esp32/esp_psram_extram_cache.c"
                          "esp32/esp_himem.c")
     endif()
 
-    if(${target} STREQUAL "esp32s2")
-        list(APPEND srcs "mmu_psram_flash.c")
-    endif()
-
-    if(${target} STREQUAL "esp32s3")
-        list(APPEND srcs "mmu_psram_flash.c")
-    endif()
-
-    if(CONFIG_SPIRAM_FLASH_LOAD_TO_PSRAM)
-        list(APPEND srcs "mmu_psram_flash_v2.c")
-    endif()
-
     if(CONFIG_SPIRAM_MODE_QUAD)
         if(${target} STREQUAL "esp32" OR ${target} STREQUAL "esp32s2")
             list(APPEND srcs "${target}/esp_psram_impl_quad.c")
-        else()
-            list(APPEND srcs "device/esp_psram_impl_ap_quad.c")
         endif()
 
     elseif(CONFIG_SPIRAM_MODE_OCT)
         list(APPEND srcs "${target}/esp_psram_impl_octal.c")
     endif()
-
-    if(CONFIG_SPIRAM_MODE_HEX)
-        list(APPEND srcs "device/esp_psram_impl_ap_hex.c")
-    endif()
 endif()
 
 idf_component_register(SRCS ${srcs}
                        INCLUDE_DIRS ${includes}
+                       PRIV_INCLUDE_DIRS device/include
                        PRIV_REQUIRES ${priv_requires}
                        LDFRAGMENTS linker.lf)
 
+if(CONFIG_SPIRAM)
+    add_subdirectory(device)
+endif()
+if(CONFIG_SOC_SPIRAM_XIP_SUPPORTED)
+    add_subdirectory(xip_impl)
+endif()
+
 if(CONFIG_IDF_TARGET_ESP32 AND CONFIG_SPIRAM_CACHE_WORKAROUND AND NOT BOOTLOADER_BUILD)
     # Note: Adding as a PUBLIC compile option here causes this option to propagate to all
     # components that depend on esp_psram.

components/esp_psram/device/CMakeLists.txt

@@ -0,0 +1,13 @@
+set(srcs)
+
+if(CONFIG_SPIRAM_MODE_QUAD)
+    if(NOT ${target} STREQUAL "esp32" AND NOT ${target} STREQUAL "esp32s2")
+        list(APPEND srcs "esp_psram_impl_ap_quad.c")
+    endif()
+endif()
+
+if(CONFIG_SPIRAM_MODE_HEX)
+    list(APPEND srcs "esp_psram_impl_ap_hex.c")
+endif()
+
+target_sources(${COMPONENT_LIB} PRIVATE "${srcs}")

components/esp_psram/device/esp_psram_impl_ap_hex.c

@@ -10,7 +10,7 @@
 #include "esp_log.h"
 #include "esp_private/periph_ctrl.h"
 #include "esp_private/mspi_timing_tuning.h"
-#include "../esp_psram_impl.h"
+#include "esp_private/esp_psram_impl.h"
 #include "hal/psram_ctrlr_ll.h"
 #include "hal/mspi_ll.h"
 #include "clk_ctrl_os.h"

components/esp_psram/device/esp_psram_impl_ap_quad.c

@@ -7,7 +7,7 @@
 #include "sdkconfig.h"
 #include "esp_err.h"
 #include "esp_log.h"
-#include "../esp_psram_impl.h"
+#include "esp_private/esp_psram_impl.h"
 #include "rom/spi_flash.h"
 #include "rom/opi_flash.h"
 #include "esp_rom_gpio.h"

components/esp_psram/device/include/esp_private/esp_psram_impl.h

@@ -30,7 +30,7 @@ esp_err_t esp_psram_impl_get_physical_size(uint32_t *out_size_bytes);
 /**
  * @brief To get the available physical psram size in bytes.
  *
- * @param[out] out_size_bytes    availabe physical psram size in bytes.
+ * @param[out] out_size_bytes    available physical psram size in bytes.
  */
 esp_err_t esp_psram_impl_get_available_size(uint32_t *out_size_bytes);
 

components/esp_psram/esp32/esp_himem.c

@@ -14,7 +14,7 @@
 #include "soc/soc.h"
 #include "esp_log.h"
 #include "esp_check.h"
-#include "../esp_psram_impl.h"
+#include "esp_private/esp_psram_impl.h"
 
 /*
 So, why does the API look this way and is so inflexible to not allow any maps beyond the full 32K chunks? Most of

components/esp_psram/esp32/esp_psram_impl_quad.c

@@ -15,7 +15,7 @@
 #include "esp_types.h"
 #include "esp_bit_defs.h"
 #include "esp_log.h"
-#include "../esp_psram_impl.h"
+#include "esp_private/esp_psram_impl.h"
 #include "esp32/rom/spi_flash.h"
 #include "esp32/rom/cache.h"
 #include "rom/efuse.h"

components/esp_psram/esp32s2/esp_psram_impl_quad.c

@@ -15,7 +15,7 @@
 #include "esp_types.h"
 #include "esp_bit_defs.h"
 #include "esp_log.h"
-#include "../esp_psram_impl.h"
+#include "esp_private/esp_psram_impl.h"
 #include "esp32s2/rom/spi_flash.h"
 #include "esp32s2/rom/opi_flash.h"
 #include "rom/efuse.h"

components/esp_psram/esp32s3/esp_psram_impl_octal.c

@@ -11,7 +11,7 @@
 #include "esp_types.h"
 #include "esp_bit_defs.h"
 #include "esp_log.h"
-#include "../esp_psram_impl.h"
+#include "esp_private/esp_psram_impl.h"
 #include "esp32s3/rom/ets_sys.h"
 #include "esp32s3/rom/spi_flash.h"
 #include "esp32s3/rom/opi_flash.h"

components/esp_psram/system_layer/esp_psram.c

@@ -18,24 +18,34 @@
 #include "esp_log.h"
 #include "freertos/FreeRTOS.h"
 #include "esp_heap_caps_init.h"
+#include "esp_psram.h"
+#include "esp_mmu_map.h"
 #include "hal/mmu_hal.h"
 #include "hal/mmu_ll.h"
 #include "hal/cache_ll.h"
 #include "soc/soc_caps.h"
 #include "esp_private/esp_psram_io.h"
 #include "esp_private/esp_psram_extram.h"
-#include "esp_private/mmu_psram_flash.h"
-#include "esp_psram_impl.h"
-#include "esp_psram.h"
 #include "esp_private/esp_mmu_map_private.h"
-#include "esp_mmu_map.h"
+#include "esp_private/esp_psram_impl.h"
 #include "esp_private/startup_internal.h"
+#if SOC_SPIRAM_XIP_SUPPORTED
+#include "esp_private/mmu_psram_flash.h"
+#endif
 #if CONFIG_IDF_TARGET_ESP32
 #include "esp32/himem.h"
 #include "esp32/rom/cache.h"
 #include "esp_private/esp_cache_esp32_private.h"
 #endif
 
+#if CONFIG_IDF_TARGET_ESP32
+#define MMU_PAGE_SIZE                   0x8000
+#else
+#define MMU_PAGE_SIZE                   CONFIG_MMU_PAGE_SIZE
+#endif
+#define MMU_PAGE_TO_BYTES(page_id)      ((page_id) * MMU_PAGE_SIZE)
+#define BYTES_TO_MMU_PAGE(bytes)        ((bytes) / MMU_PAGE_SIZE)
+
 /**
  * Two types of PSRAM memory regions for now:
  * - 8bit aligned

components/esp_psram/xip_impl/CMakeLists.txt

@@ -0,0 +1,15 @@
+set(srcs)
+
+if(${target} STREQUAL "esp32s2")
+    list(APPEND srcs "mmu_psram_flash.c")
+endif()
+
+if(${target} STREQUAL "esp32s3")
+    list(APPEND srcs "mmu_psram_flash.c")
+endif()
+
+if(CONFIG_SPIRAM_FLASH_LOAD_TO_PSRAM)
+    list(APPEND srcs "mmu_psram_flash_v2.c")
+endif()
+
+target_sources(${COMPONENT_LIB} PRIVATE "${srcs}")

components/esp_system/port/cpu_start.c

@@ -78,8 +78,10 @@
 #include "esp_private/image_process.h"
 #if CONFIG_SPIRAM
 #include "esp_psram.h"
-#include "esp_private/mmu_psram_flash.h"
 #include "esp_private/esp_psram_extram.h"
+#if SOC_SPIRAM_XIP_SUPPORTED
+#include "esp_private/mmu_psram_flash.h"
+#endif
 #endif
 
 #include "esp_private/spi_flash_os.h"

components/esp_system/system_init_fn.txt

@@ -45,7 +45,7 @@ CORE: 102: init_libc in components/newlib/src/init.c on BIT(0)
 # Add the psram to heap, psram vaddr region is reserved when initialising the heap, after
 # psram is initialised (and necessary reservation for psram usage), the rest of the psram
 # will be added to the heap
-CORE: 103: add_psram_to_heap in components/esp_psram/esp_psram.c on BIT(0)
+CORE: 103: add_psram_to_heap in components/esp_psram/system_layer/esp_psram.c on BIT(0)
 
 CORE: 104: init_brownout in components/esp_system/startup_funcs.c on BIT(0)
 CORE: 105: init_newlib_time in components/esp_system/startup_funcs.c on BIT(0)

components/spi_flash/flash_mmap.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -16,6 +16,7 @@
 #include "hal/mmu_ll.h"
 #include "hal/mmu_hal.h"
 #include "hal/cache_hal.h"
+#include "soc/soc_caps.h"
 #if ESP_ROM_NEEDS_SET_CACHE_MMU_SIZE
 #include "soc/mmu.h"
 #endif
@@ -25,8 +26,10 @@
 #include "esp_rom_spiflash.h"
 #if CONFIG_SPIRAM
 #include "esp_private/esp_psram_extram.h"
+#if SOC_SPIRAM_XIP_SUPPORTED
 #include "esp_private/mmu_psram_flash.h"
 #endif
+#endif
 
 #if CONFIG_IDF_TARGET_ESP32
 #include "esp_private/esp_cache_esp32_private.h"