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

components/esp_hal_cache/include/hal/cache_hal.h

@@ -0,0 +1,185 @@
+
+/*
+ * SPDX-FileCopyrightText: 2021-2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+#include "soc/soc_caps.h"
+#include "hal/cache_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Cache hal config
+ */
+typedef struct {
+    uint8_t core_nums;              ///< CPU core numbers
+    uint32_t l2_cache_size;         ///< L2 cache size
+    uint32_t l2_cache_line_size;    ///< L2 cache line size
+} cache_hal_config_t;
+
+/**
+ * Cache init and cache hal context init
+ *
+ * @param config  Cache hal config
+ */
+void cache_hal_init(const cache_hal_config_t *config);
+
+/**
+ * @brief Disable Cache
+ *
+ * Disable the ICache or DCache or both, of a certain level or all levels.
+ * All the items in the corresponding Cache(s) will be invalideated.
+ * Next request to these items will trigger a transaction to the physical memory
+ *
+ * @note If the autoload feature is enabled, this API will return until the ICache autoload is disabled.
+ *
+ * @param cache_level  Level of the Cache(s)
+ * @param type         see `cache_type_t`
+ */
+void cache_hal_disable(uint32_t cache_level, cache_type_t type);
+
+/**
+ * @brief Enable Cache
+ *
+ * Enable the ICache or DCache or both, of a certain level or all levels.
+ *
+ * @param cache_level  Level of the Cache(s)
+ * @param type         see `cache_type_t`
+ */
+void cache_hal_enable(uint32_t cache_level, cache_type_t type);
+
+/**
+ * @brief Suspend Cache
+ *
+ * Suspend the ICache or DCache or both, of a certain level or all levels.
+ * This API suspends the CPU access to cache for a while, without invalidation.
+ *
+ * @param cache_level  Level of the Cache(s)
+ * @param type         see `cache_type_t`
+ */
+void cache_hal_suspend(uint32_t cache_level, cache_type_t type);
+
+/**
+ * @brief Resume Cache
+ *
+ * Resume the ICache or DCache or both, of a certain level or all levels.
+ *
+ * @param cache_level  Level of the Cache(s)
+ * @param type         see `cache_type_t`
+ */
+void cache_hal_resume(uint32_t cache_level, cache_type_t type);
+
+/**
+ * @brief Check if corresponding cache is enabled or not
+ *
+ * @param cache_level  Level of the Cache(s)
+ * @param type         see `cache_type_t`
+ *
+ * @return true: enabled; false: disabled
+ */
+bool cache_hal_is_cache_enabled(uint32_t cache_level, cache_type_t type);
+
+/**
+ * @brief Invalidate Cache supported addr
+ *
+ * Invalidate a Cache item for either ICache or DCache.
+ *
+ * @param vaddr  Start address of the region to be invalidated
+ * @param size   Size of the region to be invalidated
+ *
+ * @return       True for valid address. No operation if invalid
+ */
+bool cache_hal_invalidate_addr(uint32_t vaddr, uint32_t size);
+
+#if SOC_CACHE_WRITEBACK_SUPPORTED
+/**
+ * @brief Writeback Cache supported addr
+ *
+ * Writeback the DCache item to external memory
+ *
+ * @param vaddr  Start address of the region to writeback
+ * @param size   Size of the region to writeback
+ *
+ * @return       True for valid address. No operation if invalid
+ */
+bool cache_hal_writeback_addr(uint32_t vaddr, uint32_t size);
+#endif  //#if SOC_CACHE_WRITEBACK_SUPPORTED
+
+#if SOC_CACHE_FREEZE_SUPPORTED
+/**
+ * @brief Freeze Cache
+ *
+ * Freeze cache, CPU access to cache will be suspended, until the cache is unfrozen.
+ *
+ * @param cache_level  Level of the Cache(s)
+ * @param type         see `cache_type_t`
+ */
+void cache_hal_freeze(uint32_t cache_level, cache_type_t type);
+
+/**
+ * @brief Unfreeze cache
+ *
+ * Unfreeze cache, CPU access to cache will be restored
+ *
+ * @param cache_level  Level of the Cache(s)
+ * @param type         see `cache_type_t`
+ */
+void cache_hal_unfreeze(uint32_t cache_level, cache_type_t type);
+#endif  //#if SOC_CACHE_FREEZE_SUPPORTED
+
+/**
+ * @brief Get cache line size, in bytes
+ *
+ * @param cache_level  Level of the Cache(s)
+ * @param type         see `cache_type_t`
+ *
+ * @return cache line size, in bytes. 0 stands for no such cache in this type or level
+ */
+uint32_t cache_hal_get_cache_line_size(uint32_t cache_level, cache_type_t type);
+
+/**
+ * @brief Start cache preload for a region (manual preload)
+ *
+ * Preloads the given address range into cache, this can improve
+ * performance when the region will be read soon.
+ *
+ * @param cache_level  Level of the cache (e.g. CACHE_LL_LEVEL_EXT_MEM)
+ * @param type         CACHE_TYPE_DATA, CACHE_TYPE_INSTRUCTION, or CACHE_TYPE_ALL
+ * @param vaddr        Start virtual address of the region to preload
+ * @param size         Size in bytes. Should be cache-line aligned; if not,
+ *                     the actual preloaded length is rounded down to cache-line boundary.
+ * @param order        preload order
+ */
+void cache_hal_preload(uint32_t cache_level, cache_type_t type, uint32_t vaddr, uint32_t size, cache_preload_order_t order);
+
+/**
+ * @brief Wait until cache preload started by cache_hal_preload() is done
+ *
+ * @param cache_level  Level of the cache (must match the level used in cache_hal_preload)
+ * @param type         CACHE_TYPE_DATA, CACHE_TYPE_INSTRUCTION, or CACHE_TYPE_ALL
+ */
+void cache_hal_preload_wait_done(uint32_t cache_level, cache_type_t type);
+
+/**
+ * @brief Get Cache level and the ID of the vaddr
+ *
+ * @param vaddr_start       virtual address start
+ * @param len               vaddr length
+ * @param out_level         cache level
+ * @param out_id            cache id
+ *
+ * @return true for valid, false for invalid addr or null pointer
+ */
+bool cache_hal_vaddr_to_cache_level_id(uint32_t vaddr_start, uint32_t len, uint32_t *out_level, uint32_t *out_id);
+
+#ifdef __cplusplus
+}
+#endif