Line data Source code
1 1 : /* 2 : * Copyright (c) 2023 Carlo Caione <ccaione@baylibre.com> 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : 7 : /** 8 : * @file 9 : * Public APIs for architectural cache controller drivers 10 : */ 11 : 12 : #ifndef ZEPHYR_INCLUDE_ARCH_CACHE_H_ 13 : #define ZEPHYR_INCLUDE_ARCH_CACHE_H_ 14 : 15 : /** 16 : * @brief Cache Controller Interface 17 : * @defgroup cache_arch_interface Cache Controller Interface 18 : * @ingroup io_interfaces 19 : * @{ 20 : */ 21 : 22 : #if defined(CONFIG_ARM64) 23 : #include <zephyr/arch/arm64/cache.h> 24 : #elif defined(CONFIG_XTENSA) 25 : #include <zephyr/arch/xtensa/cache.h> 26 : #endif 27 : 28 : #if defined(CONFIG_DCACHE) || defined(__DOXYGEN__) 29 : 30 : /** 31 : * @brief Enable the d-cache 32 : * 33 : * Enable the data cache. 34 : */ 35 1 : void arch_dcache_enable(void); 36 : 37 0 : #define cache_data_enable arch_dcache_enable 38 : 39 : /** 40 : * @brief Disable the d-cache 41 : * 42 : * Disable the data cache. 43 : */ 44 1 : void arch_dcache_disable(void); 45 : 46 0 : #define cache_data_disable arch_dcache_disable 47 : 48 : /** 49 : * @brief Flush the d-cache 50 : * 51 : * Flush the whole data cache. 52 : * 53 : * @retval 0 If succeeded. 54 : * @retval -ENOTSUP If not supported. 55 : * @retval -errno Negative errno for other failures. 56 : */ 57 1 : int arch_dcache_flush_all(void); 58 : 59 0 : #define cache_data_flush_all arch_dcache_flush_all 60 : 61 : /** 62 : * @brief Invalidate the d-cache 63 : * 64 : * Invalidate the whole data cache. 65 : * 66 : * @retval 0 If succeeded. 67 : * @retval -ENOTSUP If not supported. 68 : * @retval -errno Negative errno for other failures. 69 : */ 70 1 : int arch_dcache_invd_all(void); 71 : 72 0 : #define cache_data_invd_all arch_dcache_invd_all 73 : 74 : /** 75 : * @brief Flush and Invalidate the d-cache 76 : * 77 : * Flush and Invalidate the whole data cache. 78 : * 79 : * @retval 0 If succeeded. 80 : * @retval -ENOTSUP If not supported. 81 : * @retval -errno Negative errno for other failures. 82 : */ 83 1 : int arch_dcache_flush_and_invd_all(void); 84 : 85 0 : #define cache_data_flush_and_invd_all arch_dcache_flush_and_invd_all 86 : 87 : /** 88 : * @brief Flush an address range in the d-cache 89 : * 90 : * Flush the specified address range of the data cache. 91 : * 92 : * @note the cache operations act on cache line. When multiple data structures 93 : * share the same cache line being flushed, all the portions of the 94 : * data structures sharing the same line will be flushed. This is usually 95 : * not a problem because writing back is a non-destructive process that 96 : * could be triggered by hardware at any time, so having an aligned 97 : * @p addr or a padded @p size is not strictly necessary. 98 : * 99 : * @param addr Starting address to flush. 100 : * @param size Range size. 101 : * 102 : * @retval 0 If succeeded. 103 : * @retval -ENOTSUP If not supported. 104 : * @retval -errno Negative errno for other failures. 105 : */ 106 1 : int arch_dcache_flush_range(void *addr, size_t size); 107 : 108 0 : #define cache_data_flush_range(addr, size) arch_dcache_flush_range(addr, size) 109 : 110 : /** 111 : * @brief Invalidate an address range in the d-cache 112 : * 113 : * Invalidate the specified address range of the data cache. 114 : * 115 : * @note the cache operations act on cache line. When multiple data structures 116 : * share the same cache line being invalidated, all the portions of the 117 : * non-read-only data structures sharing the same line will be 118 : * invalidated as well. This is a destructive process that could lead to 119 : * data loss and/or corruption. When @p addr is not aligned to the cache 120 : * line and/or @p size is not a multiple of the cache line size the 121 : * behaviour is undefined. 122 : * 123 : * @param addr Starting address to invalidate. 124 : * @param size Range size. 125 : * 126 : * @retval 0 If succeeded. 127 : * @retval -ENOTSUP If not supported. 128 : * @retval -errno Negative errno for other failures. 129 : */ 130 1 : int arch_dcache_invd_range(void *addr, size_t size); 131 : 132 0 : #define cache_data_invd_range(addr, size) arch_dcache_invd_range(addr, size) 133 : 134 : /** 135 : * @brief Flush and Invalidate an address range in the d-cache 136 : * 137 : * Flush and Invalidate the specified address range of the data cache. 138 : * 139 : * @note the cache operations act on cache line. When multiple data structures 140 : * share the same cache line being flushed, all the portions of the 141 : * data structures sharing the same line will be flushed before being 142 : * invalidated. This is usually not a problem because writing back is a 143 : * non-destructive process that could be triggered by hardware at any 144 : * time, so having an aligned @p addr or a padded @p size is not strictly 145 : * necessary. 146 : * 147 : * @param addr Starting address to flush and invalidate. 148 : * @param size Range size. 149 : * 150 : * @retval 0 If succeeded. 151 : * @retval -ENOTSUP If not supported. 152 : * @retval -errno Negative errno for other failures. 153 : */ 154 : 155 1 : int arch_dcache_flush_and_invd_range(void *addr, size_t size); 156 : 157 0 : #define cache_data_flush_and_invd_range(addr, size) \ 158 : arch_dcache_flush_and_invd_range(addr, size) 159 : 160 : #if defined(CONFIG_DCACHE_LINE_SIZE_DETECT) || defined(__DOXYGEN__) 161 : 162 : /** 163 : * 164 : * @brief Get the d-cache line size. 165 : * 166 : * The API is provided to dynamically detect the data cache line size at run 167 : * time. 168 : * 169 : * The function must be implemented only when CONFIG_DCACHE_LINE_SIZE_DETECT is 170 : * defined. 171 : * 172 : * @retval size Size of the d-cache line. 173 : * @retval 0 If the d-cache is not enabled. 174 : */ 175 1 : size_t arch_dcache_line_size_get(void); 176 : 177 0 : #define cache_data_line_size_get arch_dcache_line_size_get 178 : 179 : #endif /* CONFIG_DCACHE_LINE_SIZE_DETECT || __DOXYGEN__ */ 180 : 181 : #endif /* CONFIG_DCACHE || __DOXYGEN__ */ 182 : 183 : #if defined(CONFIG_ICACHE) || defined(__DOXYGEN__) 184 : 185 : /** 186 : * @brief Enable the i-cache 187 : * 188 : * Enable the instruction cache. 189 : */ 190 1 : void arch_icache_enable(void); 191 : 192 0 : #define cache_instr_enable arch_icache_enable 193 : 194 : /** 195 : * @brief Disable the i-cache 196 : * 197 : * Disable the instruction cache. 198 : */ 199 1 : void arch_icache_disable(void); 200 : 201 0 : #define cache_instr_disable arch_icache_disable 202 : 203 : /** 204 : * @brief Flush the i-cache 205 : * 206 : * Flush the whole instruction cache. 207 : * 208 : * @retval 0 If succeeded. 209 : * @retval -ENOTSUP If not supported. 210 : * @retval -errno Negative errno for other failures. 211 : */ 212 1 : int arch_icache_flush_all(void); 213 : 214 0 : #define cache_instr_flush_all arch_icache_flush_all 215 : 216 : /** 217 : * @brief Invalidate the i-cache 218 : * 219 : * Invalidate the whole instruction cache. 220 : * 221 : * @retval 0 If succeeded. 222 : * @retval -ENOTSUP If not supported. 223 : * @retval -errno Negative errno for other failures. 224 : */ 225 1 : int arch_icache_invd_all(void); 226 : 227 0 : #define cache_instr_invd_all arch_icache_invd_all 228 : 229 : /** 230 : * @brief Flush and Invalidate the i-cache 231 : * 232 : * Flush and Invalidate the whole instruction cache. 233 : * 234 : * @retval 0 If succeeded. 235 : * @retval -ENOTSUP If not supported. 236 : * @retval -errno Negative errno for other failures. 237 : */ 238 1 : int arch_icache_flush_and_invd_all(void); 239 : 240 0 : #define cache_instr_flush_and_invd_all arch_icache_flush_and_invd_all 241 : 242 : /** 243 : * @brief Flush an address range in the i-cache 244 : * 245 : * Flush the specified address range of the instruction cache. 246 : * 247 : * @note the cache operations act on cache line. When multiple data structures 248 : * share the same cache line being flushed, all the portions of the 249 : * data structures sharing the same line will be flushed. This is usually 250 : * not a problem because writing back is a non-destructive process that 251 : * could be triggered by hardware at any time, so having an aligned 252 : * @p addr or a padded @p size is not strictly necessary. 253 : * 254 : * @param addr Starting address to flush. 255 : * @param size Range size. 256 : * 257 : * @retval 0 If succeeded. 258 : * @retval -ENOTSUP If not supported. 259 : * @retval -errno Negative errno for other failures. 260 : */ 261 1 : int arch_icache_flush_range(void *addr, size_t size); 262 : 263 0 : #define cache_instr_flush_range(addr, size) arch_icache_flush_range(addr, size) 264 : 265 : /** 266 : * @brief Invalidate an address range in the i-cache 267 : * 268 : * Invalidate the specified address range of the instruction cache. 269 : * 270 : * @note the cache operations act on cache line. When multiple data structures 271 : * share the same cache line being invalidated, all the portions of the 272 : * non-read-only data structures sharing the same line will be 273 : * invalidated as well. This is a destructive process that could lead to 274 : * data loss and/or corruption. When @p addr is not aligned to the cache 275 : * line and/or @p size is not a multiple of the cache line size the 276 : * behaviour is undefined. 277 : * 278 : * @param addr Starting address to invalidate. 279 : * @param size Range size. 280 : * 281 : * @retval 0 If succeeded. 282 : * @retval -ENOTSUP If not supported. 283 : * @retval -errno Negative errno for other failures. 284 : */ 285 1 : int arch_icache_invd_range(void *addr, size_t size); 286 : 287 0 : #define cache_instr_invd_range(addr, size) arch_icache_invd_range(addr, size) 288 : 289 : /** 290 : * @brief Flush and Invalidate an address range in the i-cache 291 : * 292 : * Flush and Invalidate the specified address range of the instruction cache. 293 : * 294 : * @note the cache operations act on cache line. When multiple data structures 295 : * share the same cache line being flushed, all the portions of the 296 : * data structures sharing the same line will be flushed before being 297 : * invalidated. This is usually not a problem because writing back is a 298 : * non-destructive process that could be triggered by hardware at any 299 : * time, so having an aligned @p addr or a padded @p size is not strictly 300 : * necessary. 301 : * 302 : * @param addr Starting address to flush and invalidate. 303 : * @param size Range size. 304 : * 305 : * @retval 0 If succeeded. 306 : * @retval -ENOTSUP If not supported. 307 : * @retval -errno Negative errno for other failures. 308 : */ 309 1 : int arch_icache_flush_and_invd_range(void *addr, size_t size); 310 : 311 0 : #define cache_instr_flush_and_invd_range(addr, size) \ 312 : arch_icache_flush_and_invd_range(addr, size) 313 : 314 : #if defined(CONFIG_ICACHE_LINE_SIZE_DETECT) || defined(__DOXYGEN__) 315 : 316 : /** 317 : * 318 : * @brief Get the i-cache line size. 319 : * 320 : * The API is provided to dynamically detect the instruction cache line size at 321 : * run time. 322 : * 323 : * The function must be implemented only when CONFIG_ICACHE_LINE_SIZE_DETECT is 324 : * defined. 325 : * 326 : * @retval size Size of the d-cache line. 327 : * @retval 0 If the d-cache is not enabled. 328 : */ 329 : 330 1 : size_t arch_icache_line_size_get(void); 331 : 332 0 : #define cache_instr_line_size_get arch_icache_line_size_get 333 : 334 : #endif /* CONFIG_ICACHE_LINE_SIZE_DETECT || __DOXYGEN__ */ 335 : 336 : #endif /* CONFIG_ICACHE || __DOXYGEN__ */ 337 : 338 : #if CONFIG_CACHE_DOUBLEMAP || __DOXYGEN__ 339 0 : bool arch_cache_is_ptr_cached(void *ptr); 340 0 : #define cache_is_ptr_cached(ptr) arch_cache_is_ptr_cached(ptr) 341 : 342 0 : bool arch_cache_is_ptr_uncached(void *ptr); 343 0 : #define cache_is_ptr_uncached(ptr) arch_cache_is_ptr_uncached(ptr) 344 : 345 0 : void __sparse_cache *arch_cache_cached_ptr_get(void *ptr); 346 0 : #define cache_cached_ptr(ptr) arch_cache_cached_ptr_get(ptr) 347 : 348 0 : void *arch_cache_uncached_ptr_get(void __sparse_cache *ptr); 349 0 : #define cache_uncached_ptr(ptr) arch_cache_uncached_ptr_get(ptr) 350 : #endif /* CONFIG_CACHE_DOUBLEMAP */ 351 : 352 : 353 0 : void arch_cache_init(void); 354 : 355 : /** 356 : * @} 357 : */ 358 : 359 : #endif /* ZEPHYR_INCLUDE_ARCH_CACHE_H_ */
