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