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