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_ */
|
