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