fix(cache): fixed l2 cache suspended/frozen but l1cache triggers l2 writeback issue

components/esp_hw_support/mspi_timing_tuning.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -14,8 +14,7 @@
 #include "soc/io_mux_reg.h"
 #include "soc/soc.h"
 #include "hal/spi_flash_hal.h"
-#include "hal/cache_hal.h"
+#include "esp_private/esp_cache_private.h"
-#include "hal/cache_ll.h"
 #include "esp_private/mspi_timing_tuning.h"
 #include "esp_private/mspi_timing_config.h"
 #include "mspi_timing_by_mspi_delay.h"
@@ -551,7 +550,7 @@ void mspi_timing_change_speed_mode_cache_safe(bool switch_down)
      * for preventing concurrent from MSPI to external memory
      */
 #if SOC_CACHE_FREEZE_SUPPORTED
-    cache_hal_freeze(CACHE_LL_LEVEL_EXT_MEM, CACHE_TYPE_ALL);
+    esp_cache_freeze_ext_mem_cache();
 #endif  //#if SOC_CACHE_FREEZE_SUPPORTED
 
     if (switch_down) {
@@ -563,7 +562,7 @@ void mspi_timing_change_speed_mode_cache_safe(bool switch_down)
     }
 
 #if SOC_CACHE_FREEZE_SUPPORTED
-    cache_hal_unfreeze(CACHE_LL_LEVEL_EXT_MEM, CACHE_TYPE_ALL);
+    esp_cache_unfreeze_ext_mem_cache();
 #endif  //#if SOC_CACHE_FREEZE_SUPPORTED
 
 #if SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE && !CONFIG_FREERTOS_UNICORE

components/esp_mm/esp_cache.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -147,6 +147,42 @@ esp_err_t esp_cache_msync(void *addr, size_t size, int flags)
     return ESP_OK;
 }
 
+void esp_cache_suspend_ext_mem_cache(void)
+{
+#if (CONFIG_SPIRAM && SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE)
+    /**
+     * before suspending the external mem cache, writeback internal mem cache content back to external mem cache
+     * to avoid stuck issue caused by internal mem cache auto-writeback
+     */
+    cache_ll_writeback_all(CACHE_LL_LEVEL_INT_MEM, CACHE_TYPE_DATA, CACHE_LL_ID_ALL);
+#endif
+    cache_hal_suspend(CACHE_LL_LEVEL_EXT_MEM, CACHE_TYPE_ALL);
+}
+
+void esp_cache_resume_ext_mem_cache(void)
+{
+    cache_hal_resume(CACHE_LL_LEVEL_EXT_MEM, CACHE_TYPE_ALL);
+}
+
+#if SOC_CACHE_FREEZE_SUPPORTED
+void esp_cache_freeze_ext_mem_cache(void)
+{
+#if (CONFIG_SPIRAM && SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE)
+    /**
+     * before freezing the external mem cache, writeback internal mem cache content back to external mem cache
+     * to avoid stuck issue caused by internal mem cache auto-writeback
+     */
+    cache_ll_writeback_all(CACHE_LL_LEVEL_INT_MEM, CACHE_TYPE_DATA, CACHE_LL_ID_ALL);
+#endif
+    cache_hal_freeze(CACHE_LL_LEVEL_EXT_MEM, CACHE_TYPE_ALL);
+}
+
+void esp_cache_unfreeze_ext_mem_cache(void)
+{
+    cache_hal_unfreeze(CACHE_LL_LEVEL_EXT_MEM, CACHE_TYPE_ALL);
+}
+#endif  //#if SOC_CACHE_FREEZE_SUPPORTED
+
 //The esp_cache_aligned_malloc function is marked deprecated but also called by other
 //(also deprecated) functions in this file. In order to work around that generating warnings, it's
 //split into a non-deprecated internal function and the stubbed external deprecated function.

components/esp_mm/include/esp_private/esp_cache_private.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -7,6 +7,7 @@
 
 #include <stdlib.h>
 #include <stdint.h>
+#include "soc/soc_caps.h"
 #include "esp_err.h"
 #include "esp_bit_defs.h"
 #include "esp_heap_caps.h"
@@ -15,6 +16,45 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Suspend external memory cache
+ *
+ * @note CPU branch predictor should be disabled before calling this API
+ * @note This API is only for internal usage, no thread safety guaranteed
+ * @note This API is Non-Nestable and Non-Reentrant
+ * @note Call to this API must be followed by a `esp_cache_resume_ext_mem_cache`
+ */
+void esp_cache_suspend_ext_mem_cache(void);
+
+/**
+ * @brief Resume external memory cache
+ *
+ * @note This API is only for internal usage, no thread safety guaranteed
+ * @note This API is Non-Nestable and Non-Reentrant
+ * @note This API must be called after a `esp_cache_suspend_ext_mem_cache`
+ */
+void esp_cache_resume_ext_mem_cache(void);
+
+#if SOC_CACHE_FREEZE_SUPPORTED
+/**
+ * @brief Freeze external memory cache
+ *
+ * @note This API is only for internal usage, no thread safety guaranteed
+ * @note This API is Non-Nestable and Non-Reentrant
+ * @note Call to this API must be followed by a `esp_cache_unfreeze_ext_mem_cache`
+ */
+void esp_cache_freeze_ext_mem_cache(void);
+
+/**
+ * @brief Unfreeze external memory cache
+ *
+ * @note This API is only for internal usage, no thread safety guaranteed
+ * @note This API is Non-Nestable and Non-Reentrant
+ * @note This API must be called after a `esp_cache_freeze_ext_mem_cache`
+ */
+void esp_cache_unfreeze_ext_mem_cache(void);
+#endif
+
 /**
  * @brief Helper function for malloc a cache aligned data memory buffer
  *

components/spi_flash/cache_utils.c

@@ -58,11 +58,11 @@
 #include "esp_memory_utils.h"
 #include "esp_intr_alloc.h"
 #include "spi_flash_override.h"
+#include "esp_private/esp_cache_private.h"
 #include "esp_private/cache_utils.h"
 #include "esp_private/spi_flash_os.h"
 #include "esp_private/freertos_idf_additions_priv.h"
 #include "esp_log.h"
-#include "esp_cpu.h"
 
 static __attribute__((unused)) const char *TAG = "cache";
 
@@ -368,12 +368,12 @@ void IRAM_ATTR spi_flash_disable_cache(uint32_t cpuid, uint32_t *saved_state)
     //branch predictor will start cache request as well
     esp_cpu_branch_prediction_disable();
 #endif
-    cache_hal_suspend(CACHE_LL_LEVEL_EXT_MEM, CACHE_TYPE_ALL);
+    esp_cache_suspend_ext_mem_cache();
 }
 
 void IRAM_ATTR spi_flash_restore_cache(uint32_t cpuid, uint32_t saved_state)
 {
-    cache_hal_resume(CACHE_LL_LEVEL_EXT_MEM, CACHE_TYPE_ALL);
+    esp_cache_resume_ext_mem_cache();
 #if SOC_BRANCH_PREDICTOR_SUPPORTED
     esp_cpu_branch_prediction_enable();
 #endif