Merge branch 'feature/added_cache_msync_behaviour_per_direction' into 'master'

feat(cache): added direction selection to esp_cache_msync API

Closes IDF-7674

See merge request espressif/esp-idf!24614

components/esp_mm/esp_cache.c

@@ -17,8 +17,6 @@
 
 
 static const char *TAG = "cache";
-
-#if SOC_CACHE_WRITEBACK_SUPPORTED
 DEFINE_CRIT_SECTION_LOCK_STATIC(s_spinlock);
 
 void s_cache_freeze(void)
@@ -44,38 +42,54 @@ void s_cache_unfreeze(void)
      * we don't need to do more
      */
 }
-#endif  //#if SOC_CACHE_WRITEBACK_SUPPORTED
 
 
 esp_err_t esp_cache_msync(void *addr, size_t size, int flags)
 {
     ESP_RETURN_ON_FALSE_ISR(addr, ESP_ERR_INVALID_ARG, TAG, "null pointer");
     ESP_RETURN_ON_FALSE_ISR(mmu_hal_check_valid_ext_vaddr_region(0, (uint32_t)addr, size, MMU_VADDR_DATA), ESP_ERR_INVALID_ARG, TAG, "invalid address");
+    bool both_dir = (flags & ESP_CACHE_MSYNC_FLAG_DIR_C2M) && (flags & ESP_CACHE_MSYNC_FLAG_DIR_M2C);
+    ESP_RETURN_ON_FALSE_ISR(!both_dir, ESP_ERR_INVALID_ARG, TAG, "both C2M and M2C directions are selected, you should only select one");
+
+    uint32_t vaddr = (uint32_t)addr;
+
+    if (flags & ESP_CACHE_MSYNC_FLAG_DIR_M2C) {
+        ESP_EARLY_LOGD(TAG, "M2C DIR");
+
+        esp_os_enter_critical_safe(&s_spinlock);
+        s_cache_freeze();
+
+        //Add preload feature / flag here, IDF-7800
+        cache_hal_invalidate_addr(vaddr, size);
+
+        s_cache_unfreeze();
+        esp_os_exit_critical_safe(&s_spinlock);
+
+    } else {
+        ESP_EARLY_LOGD(TAG, "C2M DIR");
 
 #if SOC_CACHE_WRITEBACK_SUPPORTED
-    if ((flags & ESP_CACHE_MSYNC_FLAG_UNALIGNED) == 0) {
         esp_os_enter_critical_safe(&s_spinlock);
         uint32_t data_cache_line_size = cache_hal_get_cache_line_size(CACHE_TYPE_DATA);
         esp_os_exit_critical_safe(&s_spinlock);
 
-        ESP_RETURN_ON_FALSE_ISR(((uint32_t)addr % data_cache_line_size) == 0, ESP_ERR_INVALID_ARG, TAG, "start address isn't aligned with the data cache line size (%d)B", data_cache_line_size);
-        ESP_RETURN_ON_FALSE_ISR((size % data_cache_line_size) == 0, ESP_ERR_INVALID_ARG, TAG, "size isn't aligned with the data cache line size (%d)B", data_cache_line_size);
-        ESP_RETURN_ON_FALSE_ISR((((uint32_t)addr + size) % data_cache_line_size) == 0, ESP_ERR_INVALID_ARG, TAG, "end address isn't aligned with the data cache line size (%d)B", data_cache_line_size);
-    }
+        if ((flags & ESP_CACHE_MSYNC_FLAG_UNALIGNED) == 0) {
+            bool aligned_addr = (((uint32_t)addr % data_cache_line_size) == 0) && ((size % data_cache_line_size) == 0);
+            ESP_RETURN_ON_FALSE_ISR(aligned_addr, ESP_ERR_INVALID_ARG, TAG, "start address, end address or the size is(are) not aligned with the data cache line size (%d)B", data_cache_line_size);
+        }
 
-    uint32_t vaddr = (uint32_t)addr;
+        esp_os_enter_critical_safe(&s_spinlock);
+        s_cache_freeze();
 
-    esp_os_enter_critical_safe(&s_spinlock);
-    s_cache_freeze();
+        cache_hal_writeback_addr(vaddr, size);
+        if (flags & ESP_CACHE_MSYNC_FLAG_INVALIDATE) {
+            cache_hal_invalidate_addr(vaddr, size);
+        }
 
-    cache_hal_writeback_addr(vaddr, size);
-    if (flags & ESP_CACHE_MSYNC_FLAG_INVALIDATE) {
-        cache_hal_invalidate_addr(vaddr, size);
-    }
-
-    s_cache_unfreeze();
-    esp_os_exit_critical_safe(&s_spinlock);
+        s_cache_unfreeze();
+        esp_os_exit_critical_safe(&s_spinlock);
 #endif
+    }
 
     return ESP_OK;
 }

components/esp_mm/include/esp_cache.h

@@ -18,26 +18,42 @@ extern "C" {
  * Cache msync flags
  */
 /**
- * @brief Do an invalidation with the values that just written
+ * @brief Do an invalidation
+ * - For cache-to-memory (C2M) direction: setting this flag will start an invalidation after the cache writeback operation
+ * - For memory-to-cache (M2C) direction: setting / unsetting this flag will behave similarly, trigger an invalidation
  */
 #define ESP_CACHE_MSYNC_FLAG_INVALIDATE    BIT(0)
 /**
- * @brief Allow writeback a block that are not aligned to the data cache line size
+ * @brief Allow msync to a address block that are not aligned to the data cache line size
  */
 #define ESP_CACHE_MSYNC_FLAG_UNALIGNED     BIT(1)
-
+/**
+ * @brief Cache msync direction: from Cache to memory
+ * @note If you don't set direction (ESP_CACHE_MSYNC_FLAG_DIR_x flags), it is by default cache-to-memory (C2M) direction
+ */
+#define ESP_CACHE_MSYNC_FLAG_DIR_C2M       BIT(2)
+/**
+ * @brief Cache msync direction: from memory to Cache
+ */
+#define ESP_CACHE_MSYNC_FLAG_DIR_M2C       BIT(3)
 
 /**
- * @brief Memory sync between Cache and external memory
+ * @brief Memory sync between Cache and storage memory
  *
+ *
+ * For cache-to-memory (C2M) direction:
  * - For cache writeback supported chips (you can refer to SOC_CACHE_WRITEBACK_SUPPORTED in soc_caps.h)
- *   - this API will do a writeback to synchronise between cache and the PSRAM
- *   - with ESP_CACHE_MSYNC_FLAG_INVALIDATE, this API will also invalidate the values that just written
- *   - note: although ESP32 is with PSRAM, but cache writeback isn't supported, so this API will do nothing on ESP32
+ *   - This API will do a writeback to synchronise between cache and storage memory
+ *   - With ESP_CACHE_MSYNC_FLAG_INVALIDATE, this API will also invalidate the values that just written
+ *   - Note: although ESP32 is with PSRAM, but cache writeback isn't supported, so this API will do nothing on ESP32
  * - For other chips, this API will do nothing. The out-of-sync should be already dealt by the SDK
  *
+ * For memory-to-cache (M2C) direction:
+ * - This API will by default do an invalidation
+ *
  * This API is cache-safe and thread-safe
  *
+ * @note If you don't set direction (ESP_CACHE_MSYNC_FLAG_DIR_x flags), this API is by default C2M direction
  * @note You should not call this during any Flash operations (e.g. esp_flash APIs, nvs and some other APIs that are based on esp_flash APIs)
  * @note If XIP_From_PSRAM is enabled (by enabling both CONFIG_SPIRAM_FETCH_INSTRUCTIONS and CONFIG_SPIRAM_RODATA), you can call this API during Flash operations
  *
@@ -48,7 +64,7 @@ extern "C" {
  * @return
  *        - ESP_OK:
  *                  - Successful msync
- *                  - If this chip doesn't support cache writeback, if the input addr is a cache supported one, this API will return ESP_OK
+ *                  - For C2M direction, if this chip doesn't support cache writeback, if the input addr is a cache supported one, this API will return ESP_OK
  *        - ESP_ERR_INVALID_ARG:   Invalid argument, not cache supported addr, see printed logs
  */
 esp_err_t esp_cache_msync(void *addr, size_t size, int flags);

components/esp_mm/test_apps/mm/main/test_cache_msync.c

@@ -77,13 +77,13 @@ TEST_CASE("test cache msync short enough when suspending an ISR", "[cache]")
 
     //Do msync first, as the first writeback / invalidate takes long time, next msyncs will be shorter and they keep unchanged almost
     RECORD_TIME_START();
-    TEST_ESP_OK(esp_cache_msync((void *)TEST_SYNC_START, TEST_SYNC_SIZE, ESP_CACHE_MSYNC_FLAG_INVALIDATE));
+    TEST_ESP_OK(esp_cache_msync((void *)TEST_SYNC_START, TEST_SYNC_SIZE, ESP_CACHE_MSYNC_FLAG_DIR_C2M | ESP_CACHE_MSYNC_FLAG_INVALIDATE));
     RECORD_TIME_END(sync_time);
     sync_time_us = GET_US_BY_CCOUNT(sync_time);
     printf("first sync_time_us: %"PRId32"\n", sync_time_us);
 
     RECORD_TIME_START();
-    TEST_ESP_OK(esp_cache_msync((void *)TEST_SYNC_START, TEST_SYNC_SIZE, ESP_CACHE_MSYNC_FLAG_INVALIDATE));
+    TEST_ESP_OK(esp_cache_msync((void *)TEST_SYNC_START, TEST_SYNC_SIZE, ESP_CACHE_MSYNC_FLAG_DIR_C2M | ESP_CACHE_MSYNC_FLAG_INVALIDATE));
     RECORD_TIME_END(sync_time);
     sync_time_us = GET_US_BY_CCOUNT(sync_time);
     printf("sync_time_us: %"PRId32"\n", sync_time_us);
@@ -103,7 +103,7 @@ TEST_CASE("test cache msync short enough when suspending an ISR", "[cache]")
 
     RECORD_TIME_START();
     sync_flag = true;
-    TEST_ESP_OK(esp_cache_msync((void *)TEST_SYNC_START, TEST_SYNC_SIZE, ESP_CACHE_MSYNC_FLAG_INVALIDATE | ESP_CACHE_MSYNC_FLAG_UNALIGNED));
+    TEST_ESP_OK(esp_cache_msync((void *)TEST_SYNC_START, TEST_SYNC_SIZE, ESP_CACHE_MSYNC_FLAG_DIR_C2M | ESP_CACHE_MSYNC_FLAG_INVALIDATE | ESP_CACHE_MSYNC_FLAG_UNALIGNED));
     sync_flag = false;
     RECORD_TIME_END(sync_time);
 
@@ -132,7 +132,7 @@ TEST_CASE("test cache msync short enough to be in an ISR", "[cache]")
     RECORD_TIME_PREPARE();
 
     RECORD_TIME_START();
-    TEST_ESP_OK(esp_cache_msync((void *)TEST_SYNC_START, TEST_SYNC_SIZE, ESP_CACHE_MSYNC_FLAG_INVALIDATE | ESP_CACHE_MSYNC_FLAG_UNALIGNED));
+    TEST_ESP_OK(esp_cache_msync((void *)TEST_SYNC_START, TEST_SYNC_SIZE, ESP_CACHE_MSYNC_FLAG_DIR_C2M | ESP_CACHE_MSYNC_FLAG_INVALIDATE | ESP_CACHE_MSYNC_FLAG_UNALIGNED));
     RECORD_TIME_END(sync_time);
     sync_time_us = GET_US_BY_CCOUNT(sync_time);
     printf("sync_time_us: %"PRId32"\n", sync_time_us);
@@ -175,7 +175,7 @@ TEST_CASE("test cache msync work with Flash operation when XIP from PSRAM", "[ca
     RECORD_TIME_PREPARE();
 
     RECORD_TIME_START();
-    TEST_ESP_OK(esp_cache_msync((void *)TEST_SYNC_START, TEST_SYNC_SIZE, ESP_CACHE_MSYNC_FLAG_INVALIDATE));
+    TEST_ESP_OK(esp_cache_msync((void *)TEST_SYNC_START, TEST_SYNC_SIZE, ESP_CACHE_MSYNC_FLAG_DIR_C2M | ESP_CACHE_MSYNC_FLAG_INVALIDATE));
     RECORD_TIME_END(sync_time);
     uint32_t sync_time_us = GET_US_BY_CCOUNT(sync_time);
     printf("sync_time_us: %"PRId32"\n", sync_time_us);

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

@@ -153,6 +153,11 @@ SPI Flash can be accessed by SPI1 (ESP-IDF `esp_flash` driver APIs), or by point
 
    PSRAM can also be accessed by EDMA. Data desynchronisation may happen because hardware does not guarantee the data consistency under such condition. You should call :cpp:func:`esp_cache_msync` to synchronise the Cache and the PSRAM.
 
+   :cpp:func:`esp_cache_msync` has two synchronization directions,
+
+   * c:macro:`ESP_CACHE_MSYNC_FLAG_DIR_C2M`: from cache to memory. By default (if you don't specify a direction), the synchronization is in this direction. Content in the address you specified will be written back to the memory.
+   * c:macro:`ESP_CACHE_MSYNC_FLAG_DIR_M2C`: from memory to cache. By default, content in the address you specified will be invalidated from the cache.
+
 
 Thread Safety
 =============

docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst

@@ -1 +1 @@
-.. include:: /../en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst
+.. include:: ../../../../en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst

docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst

@@ -1 +1 @@
-.. include:: /../en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst
+.. include:: ../../../../en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst

docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst

@@ -1 +1 @@
-.. include:: /../en/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst
+.. include:: ../../../../en/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst

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

@@ -1 +1 @@
-.. include:: /../en/api-reference/system/mm.rst
+.. include:: ../../../en/api-reference/system/mm.rst