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