1 /*
2  * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #pragma once
8 
9 #include <stdint.h>
10 
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14 
15 #ifndef BIT
16 #define BIT(nr)  (1 << (nr))
17 #endif
18 
19 /** \defgroup cache_apis, cache operation related apis
20   * @brief cache apis
21   */
22 
23 /** @addtogroup cache_apis
24   * @{
25   */
26 #define MIN_ICACHE_SIZE                 16384
27 #define MAX_ICACHE_SIZE                 32768
28 #define MIN_DCACHE_SIZE                 32768
29 #define MAX_DCACHE_SIZE                 65536
30 #define MIN_ICACHE_WAYS                 4
31 #define MAX_ICACHE_WAYS                 8
32 #define MIN_DCACHE_WAYS                 4
33 #define MAX_DCACHE_WAYS                 4
34 #define MAX_CACHE_WAYS                  8
35 #define MIN_CACHE_LINE_SIZE             16
36 #define TAG_SIZE                        4
37 #define MIN_ICACHE_BANK_NUM             1
38 #define MAX_ICACHE_BANK_NUM             2
39 #define MIN_DCACHE_BANK_NUM             1
40 #define MAX_DCACHE_BANK_NUM             2
41 #define CACHE_MEMORY_BANK_NUM           4
42 #define CACHE_MEMORY_IBANK_SIZE         0x4000
43 #define CACHE_MEMORY_DBANK_SIZE         0x8000
44 
45 #define MAX_ITAG_BANK_ITEMS             (MAX_ICACHE_SIZE / MAX_ICACHE_BANK_NUM / MIN_CACHE_LINE_SIZE)
46 #define MAX_ITAG_BLOCK_ITEMS            (MAX_ICACHE_SIZE / MAX_ICACHE_BANK_NUM / MAX_ICACHE_WAYS / MIN_CACHE_LINE_SIZE)
47 #define MAX_ITAG_BANK_SIZE              (MAX_ITAG_BANK_ITEMS * TAG_SIZE)
48 #define MAX_ITAG_BLOCK_SIZE             (MAX_ITAG_BLOCK_ITEMS * TAG_SIZE)
49 #define MAX_DTAG_BANK_ITEMS             (MAX_DCACHE_SIZE / MAX_DCACHE_BANK_NUM /  MIN_CACHE_LINE_SIZE)
50 #define MAX_DTAG_BLOCK_ITEMS            (MAX_DCACHE_SIZE / MAX_DCACHE_BANK_NUM / MAX_DCACHE_WAYS / MIN_CACHE_LINE_SIZE)
51 #define MAX_DTAG_BANK_SIZE              (MAX_DTAG_BANK_ITEMS * TAG_SIZE)
52 #define MAX_DTAG_BLOCK_SIZE             (MAX_DTAG_BLOCK_ITEMS * TAG_SIZE)
53 
54 typedef enum {
55     CACHE_DCACHE = 0,
56     CACHE_ICACHE0 = 1,
57     CACHE_ICACHE1 = 2,
58 } cache_t;
59 
60 typedef enum {
61     CACHE_MEMORY_INVALID = 0,
62     CACHE_MEMORY_IBANK0 = BIT(0),
63     CACHE_MEMORY_IBANK1 = BIT(1),
64     CACHE_MEMORY_IBANK2 = BIT(2),
65     CACHE_MEMORY_IBANK3 = BIT(3),
66     CACHE_MEMORY_DBANK0 = BIT(0),
67     CACHE_MEMORY_DBANK1 = BIT(1),
68     CACHE_MEMORY_DBANK2 = BIT(2),
69     CACHE_MEMORY_DBANK3 = BIT(3),
70 } cache_array_t;
71 
72 #define ICACHE_SIZE_16KB  CACHE_SIZE_HALF
73 #define ICACHE_SIZE_32KB  CACHE_SIZE_FULL
74 #define DCACHE_SIZE_32KB  CACHE_SIZE_HALF
75 #define DCACHE_SIZE_64KB  CACHE_SIZE_FULL
76 
77 typedef enum {
78     CACHE_SIZE_HALF = 0,                /*!< 8KB for icache and dcache */
79     CACHE_SIZE_FULL = 1,                /*!< 16KB for icache and dcache */
80 } cache_size_t;
81 
82 typedef enum {
83     CACHE_4WAYS_ASSOC = 0,              /*!< 4 way associated cache */
84     CACHE_8WAYS_ASSOC = 1,              /*!< 8 way associated cache */
85 } cache_ways_t;
86 
87 typedef enum {
88     CACHE_LINE_SIZE_16B = 0,            /*!< 16 Byte cache line size */
89     CACHE_LINE_SIZE_32B = 1,            /*!< 32 Byte cache line size */
90     CACHE_LINE_SIZE_64B = 2,            /*!< 64 Byte cache line size */
91 } cache_line_size_t;
92 
93 typedef enum {
94     CACHE_AUTOLOAD_POSITIVE = 0,        /*!< cache autoload step is positive */
95     CACHE_AUTOLOAD_NEGATIVE = 1,        /*!< cache autoload step is negative */
96 } cache_autoload_order_t;
97 
98 typedef enum {
99     CACHE_AUTOLOAD_REGION0 = 0,         /*!< cache autoload region0 */
100     CACHE_AUTOLOAD_REGION1 = 1,         /*!< cache autoload region1 */
101 } cache_autoload_region_t;
102 
103 #define CACHE_AUTOLOAD_STEP(i) ((i) - 1)
104 
105 typedef enum {
106     CACHE_AUTOLOAD_MISS_TRIGGER = 0,    /*!< autoload only triggered by cache miss */
107     CACHE_AUTOLOAD_HIT_TRIGGER  = 1,    /*!< autoload only triggered by cache hit */
108     CACHE_AUTOLOAD_BOTH_TRIGGER = 2,    /*!< autoload triggered both by cache miss and hit */
109 } cache_autoload_trigger_t;
110 
111 typedef enum {
112     CACHE_FREEZE_ACK_BUSY = 0,          /*!< in this mode, cache ack busy to CPU if a cache miss happens*/
113     CACHE_FREEZE_ACK_ERROR  = 1,        /*!< in this mode, cache ack wrong data to CPU and trigger an error if a cache miss happens */
114 } cache_freeze_mode_t;
115 
116 struct cache_mode {
117     uint32_t cache_size;                /*!< cache size in byte */
118     uint16_t cache_line_size;           /*!< cache line size in byte */
119     uint8_t cache_ways;                 /*!< cache ways, always 4 */
120     uint8_t icache;                     /*!< the cache index, 0 for dcache, 1 for icache */
121 };
122 
123 struct icache_tag_item {
124     uint32_t valid: 1;                  /*!< the tag item is valid or not */
125     uint32_t lock: 1;                   /*!< the cache line is locked or not */
126     uint32_t attr: 4;                   /*!< the attribute of the external memory physical address */
127     uint32_t fifo_cnt: 3;               /*!< fifo cnt, 0 ~ 3 for 4 ways cache */
128     uint32_t tag: 14;                   /*!< the tag is the high part of the cache address, however is only 64MB range, and without low part */
129     uint32_t reserved: 9;
130 };
131 
132 struct dcache_tag_item {
133     uint32_t dirty: 1;                  /*!< the cache line value is dirty or not */
134     uint32_t valid: 1;                  /*!< the tag item is valid or not */
135     uint32_t lock: 1;                   /*!< the cache line is locked or not */
136     uint32_t occupy: 1;                 /*!< the cache line is occupied as internal sram */
137     uint32_t attr: 4;                   /*!< the attribute of the external memory physical address */
138     uint32_t fifo_cnt: 2;               /*!< fifo cnt, 0 ~ 3 for 4 ways cache */
139     uint32_t tag: 13;                   /*!< the tag is the high part of the cache address, however is only 64MB range, and without low part */
140     uint32_t reserved: 9;
141 };
142 
143 struct autoload_config {
144     uint8_t ena;                        /*!< autoload enable */
145     uint8_t order;                      /*!< autoload step is positive or negative */
146     uint8_t trigger;                    /*!< autoload trigger */
147     uint8_t size;                       /*!< autoload size */
148 };
149 
150 struct autoload_region_config {
151     uint8_t region;                     /*!< autoload region*/
152     uint8_t ena;                        /*!< autoload region enable */
153     uint32_t addr;                      /*!< autoload region start address */
154     uint32_t size;                      /*!< autoload region size */
155 };
156 
157 struct tag_group_info {
158     struct cache_mode mode;                         /*!< cache and cache mode */
159     uint32_t filter_addr;                           /*!< the address that used to generate the struct */
160     uint32_t vaddr_offset;                          /*!< virtual address offset of the cache ways */
161     uint32_t tag_addr[MAX_CACHE_WAYS];              /*!< tag memory address, only [0~mode.ways-1] is valid to use */
162     uint32_t cache_memory_offset[MAX_CACHE_WAYS];   /*!< cache memory address, only [0~mode.ways-1] is valid to use */
163     uint8_t use_legacy;                             /*!< 1 for using legacy tag api, 0 for using 2rd tag api */
164 };
165 
166 struct lock_config {
167     uint32_t addr;                                  /*!< manual lock address*/
168     uint16_t size;                                  /*!< manual lock size*/
169     uint16_t group;                                 /*!< manual lock group, 0 or 1*/
170 };
171 
172 struct cache_internal_stub_table {
173     uint32_t (* icache_line_size)(void);
174     uint32_t (* dcache_line_size)(void);
175     uint32_t (* icache_addr)(uint32_t addr);
176     uint32_t (* dcache_addr)(uint32_t addr);
177     void (* invalidate_icache_items)(uint32_t addr, uint32_t items);
178     void (* invalidate_dcache_items)(uint32_t addr, uint32_t items);
179     void (* clean_items)(uint32_t addr, uint32_t items);
180     void (* writeback_items)(uint32_t addr, uint32_t items);
181     void (* lock_icache_items)(uint32_t addr, uint32_t items);
182     void (* lock_dcache_items)(uint32_t addr, uint32_t items);
183     void (* unlock_icache_items)(uint32_t addr, uint32_t items);
184     void (* unlock_dcache_items)(uint32_t addr, uint32_t items);
185     void (* occupy_items)(uint32_t addr, uint32_t items);
186     uint32_t (* suspend_icache_autoload)(void);
187     void (* resume_icache_autoload)(uint32_t autoload);
188     uint32_t (* suspend_dcache_autoload)(void);
189     void (* resume_dcache_autoload)(uint32_t autoload);
190     void (* freeze_icache_enable)(cache_freeze_mode_t mode);
191     void (* freeze_icache_disable)(void);
192     void (* freeze_dcache_enable)(cache_freeze_mode_t mode);
193     void (* freeze_dcache_disable)(void);
194     int (* op_addr)(uint32_t op_icache, uint32_t start_addr, uint32_t size, uint32_t cache_line_size, uint32_t max_sync_num, void(* cache_Iop)(uint32_t, uint32_t), void(* cache_Dop)(uint32_t, uint32_t));
195 };
196 
197 typedef void (* cache_op_start)(void);
198 typedef void (* cache_op_end)(void);
199 
200 typedef struct {
201     cache_op_start start;
202     cache_op_end end;
203 } cache_op_cb_t;
204 
205 #define ESP_ROM_ERR_INVALID_ARG         1
206 #define MMU_SET_ADDR_ALIGNED_ERROR      2
207 #define MMU_SET_PASE_SIZE_ERROR         3
208 #define MMU_SET_VADDR_OUT_RANGE         4
209 
210 #define CACHE_OP_ICACHE_Y               1
211 #define CACHE_OP_ICACHE_N               0
212 
213 /**
214   * @brief Initialise cache mmu, mark all entries as invalid.
215   *        Please do not call this function in your SDK application.
216   *
217   * @param  None
218   *
219   * @return None
220   */
221 void Cache_MMU_Init(void);
222 
223 /**
224   * @brief Set ICache mmu mapping.
225   *        Please do not call this function in your SDK application.
226   *
227   * @param  uint32_t ext_ram : MMU_ACCESS_FLASH for flash, MMU_ACCESS_SPIRAM for spiram, MMU_INVALID for invalid.
228   *
229   * @param  uint32_t vaddr : virtual address in CPU address space.
230   *                              Can be Iram0,Iram1,Irom0,Drom0 and AHB buses address.
231   *                              Should be aligned by psize.
232   *
233   * @param  uint32_t paddr : physical address in external memory.
234   *                              Should be aligned by psize.
235   *
236   * @param  uint32_t psize : page size of ICache, in kilobytes. Should be 64 here.
237   *
238   * @param  uint32_t num : pages to be set.
239   *
240   * @param  uint32_t fixed : 0 for physical pages grow with virtual pages, other for virtual pages map to same physical page.
241   *
242   * @return uint32_t: error status
243   *                   0 : mmu set success
244   *                   2 : vaddr or paddr is not aligned
245   *                   3 : psize error
246   *                   4 : vaddr is out of range
247   */
248 int Cache_Ibus_MMU_Set(uint32_t ext_ram, uint32_t vaddr, uint32_t paddr,  uint32_t psize, uint32_t num, uint32_t fixed);
249 
250 /**
251   * @brief Set DCache mmu mapping.
252   *        Please do not call this function in your SDK application.
253   *
254   * @param  uint32_t ext_ram : MMU_ACCESS_FLASH for flash, MMU_ACCESS_SPIRAM for spiram, MMU_INVALID for invalid.
255   *
256   * @param  uint32_t vaddr : virtual address in CPU address space.
257   *                              Can be DRam0, DRam1, DRom0, DPort and AHB buses address.
258   *                              Should be aligned by psize.
259   *
260   * @param  uint32_t paddr : physical address in external memory.
261   *                              Should be aligned by psize.
262   *
263   * @param  uint32_t psize : page size of DCache, in kilobytes. Should be 64 here.
264   *
265   * @param  uint32_t num : pages to be set.
266 
267   * @param  uint32_t fixed : 0 for physical pages grow with virtual pages, other for virtual pages map to same physical page.
268   *
269   * @return uint32_t: error status
270   *                   0 : mmu set success
271   *                   2 : vaddr or paddr is not aligned
272   *                   3 : psize error
273   *                   4 : vaddr is out of range
274   */
275 int Cache_Dbus_MMU_Set(uint32_t ext_ram, uint32_t vaddr, uint32_t paddr, uint32_t psize, uint32_t num, uint32_t fixed);
276 
277 /**
278   * @brief Count the pages in the bus room address which map to Flash.
279   *        Please do not call this function in your SDK application.
280   *
281   * @param uint32_t bus : the bus to count with.
282   *
283   * @param uint32_t * page0_mapped : value should be initial by user, 0 for not mapped, other for mapped count.
284   *
285   * return uint32_t : the number of pages which map to Flash.
286   */
287 uint32_t Cache_Count_Flash_Pages(uint32_t bus, uint32_t *page0_mapped);
288 
289 /**
290   * @brief Copy Instruction or rodata from Flash to SPIRAM, and remap to SPIRAM.
291   *        Please do not call this function in your SDK application.
292   *
293   * @param uint32_t bus : the bus which need to copy to SPIRAM.
294   *
295   * @param uint32_t bus_start_addr : the start virtual address for the bus.
296   *
297   * @param uint32_t start_page : the start (64KB) page number in SPIRAM.
298   *
299   * @param uint32_t * page0_page : the flash page0 in SPIRAM page number, 0xffff for invalid.
300   *
301   * return uint32_t : the next start page number for SPIRAM not mapped.
302   */
303 uint32_t Cache_Flash_To_SPIRAM_Copy(uint32_t bus, uint32_t bus_start_addr, uint32_t start_page, uint32_t *page0_page);
304 
305 /**
306   * @brief allocate memory to used by ICache.
307   *        Please do not call this function in your SDK application.
308   *
309   * @param cache_array_t icache_low : the data array bank used by icache low part. Due to timing constraint, can only be CACHE_MEMORY_INVALID, CACHE_MEMORY_IBANK0
310   *
311   * @param cache_array_t icache_high : the data array bank used by icache high part. Due to timing constraint, can only be CACHE_MEMORY_INVALID, or CACHE_MEMORY_IBANK1 only if icache_low and icache_high is CACHE_MEMORY_IBANK0
312   *
313   * return none
314   */
315 void Cache_Occupy_ICache_MEMORY(cache_array_t icache_low, cache_array_t icache_high);
316 
317 /**
318   * @brief allocate memory to used by DCache.
319   *        Please do not call this function in your SDK application.
320   *
321   * @param cache_array_t dcache_low : the data array bank used by dcache low part. Due to timing constraint, can only be CACHE_MEMORY_INVALID, CACHE_MEMORY_DBANK1
322   *
323   * @param cache_array_t dcache1_high : the data array bank used by dcache high part. Due to timing constraint, can only be CACHE_MEMORY_INVALID, or CACHE_MEMORY_DBANK0 only if dcache_low0 and dcache_low1 is CACHE_MEMORY_DBANK1
324   *
325   * return none
326   */
327 void Cache_Occupy_DCache_MEMORY(cache_array_t dcache_low, cache_array_t dcache_high);
328 
329 /**
330   * @brief Get cache mode of ICache or DCache.
331   *        Please do not call this function in your SDK application.
332   *
333   * @param struct cache_mode * mode : the pointer of cache mode struct, caller should set the icache field
334   *
335   * return none
336   */
337 void Cache_Get_Mode(struct cache_mode *mode);
338 
339 /**
340   * @brief set ICache modes: cache size, associate ways and cache line size.
341   *        Please do not call this function in your SDK application.
342   *
343   * @param cache_size_t cache_size : the cache size, can be CACHE_SIZE_HALF and CACHE_SIZE_FULL
344   *
345   * @param cache_ways_t ways : the associate ways of cache, can be CACHE_4WAYS_ASSOC and CACHE_8WAYS_ASSOC
346   *
347   * @param cache_line_size_t cache_line_size : the cache line size, can be CACHE_LINE_SIZE_16B and CACHE_LINE_SIZE_32B
348   *
349   * return none
350   */
351 void Cache_Set_ICache_Mode(cache_size_t cache_size, cache_ways_t ways, cache_line_size_t cache_line_size);
352 
353 /**
354   * @brief set DCache modes: cache size, associate ways and cache line size.
355   *        Please do not call this function in your SDK application.
356   *
357   * @param cache_size_t cache_size : the cache size, can be CACHE_SIZE_HALF and CACHE_SIZE_FULL
358   *
359   * @param cache_ways_t ways : the associate ways of cache, can be CACHE_4WAYS_ASSOC and CACHE_8WAYS_ASSOC, only CACHE_4WAYS_ASSOC works
360   *
361   * @param cache_line_size_t cache_line_size : the cache line size, can be CACHE_LINE_SIZE_16B, CACHE_LINE_SIZE_32B and CACHE_LINE_SIZE_64B
362   *
363   * return none
364   */
365 void Cache_Set_DCache_Mode(cache_size_t cache_size, cache_ways_t ways, cache_line_size_t cache_line_size);
366 
367 /**
368   * @brief check if the address is accessed through ICache.
369   *        Please do not call this function in your SDK application.
370   *
371   * @param  uint32_t addr : the address to check.
372   *
373   * @return 1 if the address is accessed through ICache, 0 if not.
374   */
375 uint32_t Cache_Address_Through_ICache(uint32_t addr);
376 
377 /**
378   * @brief check if the address is accessed through DCache.
379   *        Please do not call this function in your SDK application.
380   *
381   * @param  uint32_t addr : the address to check.
382   *
383   * @return 1 if the address is accessed through DCache, 0 if not.
384   */
385 uint32_t Cache_Address_Through_DCache(uint32_t addr);
386 
387 /**
388   * @brief Init Cache for ROM boot, including resetting the Dcache, initializing Owner, MMU, setting DCache mode, Enabling DCache, unmasking bus.
389   *
390   * @param None
391   *
392   * @return None
393   */
394 void ROM_Boot_Cache_Init(void);
395 
396 /**
397   * @brief Init mmu owner register to make i/d cache use half mmu entries.
398   *
399   * @param None
400   *
401   * @return None
402   */
403 void Cache_Owner_Init(void);
404 
405 /**
406   * @brief Invalidate the cache items for ICache.
407   *        Operation will be done CACHE_LINE_SIZE aligned.
408   *        If the region is not in ICache addr room, nothing will be done.
409   *        Please do not call this function in your SDK application.
410   *
411   * @param  uint32_t addr: start address to invalidate
412   *
413   * @param  uint32_t items: cache lines to invalidate, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB)
414   *
415   * @return None
416   */
417 void Cache_Invalidate_ICache_Items(uint32_t addr, uint32_t items);
418 
419 /**
420   * @brief Invalidate the cache items for DCache.
421   *        Operation will be done CACHE_LINE_SIZE aligned.
422   *        If the region is not in DCache addr room, nothing will be done.
423   *        Please do not call this function in your SDK application.
424   *
425   * @param  uint32_t addr: start address to invalidate
426   *
427   * @param  uint32_t items: cache lines to invalidate, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB)
428   *
429   * @return None
430   */
431 void Cache_Invalidate_DCache_Items(uint32_t addr, uint32_t items);
432 
433 /**
434   * @brief Clean the dirty bit of cache Items of DCache.
435   *        Operation will be done CACHE_LINE_SIZE aligned.
436   *        If the region is not in DCache addr room, nothing will be done.
437   *        Please do not call this function in your SDK application.
438   *
439   * @param  uint32_t addr: start address to Clean
440   *
441   * @param  uint32_t items: cache lines to invalidate, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB)
442   *
443   * @return None
444   */
445 void Cache_Clean_Items(uint32_t addr, uint32_t items);
446 
447 /**
448   * @brief Write back the cache items of DCache.
449   *        Operation will be done CACHE_LINE_SIZE aligned.
450   *        If the region is not in DCache addr room, nothing will be done.
451   *        Please do not call this function in your SDK application.
452   *
453   * @param  uint32_t addr: start address to write back
454   *
455   * @param  uint32_t items: cache lines to invalidate, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB)
456   *
457   * @return None
458   */
459 void Cache_WriteBack_Items(uint32_t addr, uint32_t items);
460 
461 /**
462   * @brief Invalidate the Cache items in the region from ICache or DCache.
463   *        If the region is not in Cache addr room, nothing will be done.
464   *        Please do not call this function in your SDK application.
465   *
466   * @param  uint32_t addr : invalidated region start address.
467   *
468   * @param  uint32_t size : invalidated region size.
469   *
470   * @return 0 for success
471   *         1 for invalid argument
472   */
473 int Cache_Invalidate_Addr(uint32_t addr, uint32_t size);
474 
475 /**
476   * @brief Clean the dirty bit of Cache items in the region from DCache.
477   *        If the region is not in DCache addr room, nothing will be done.
478   *        Please do not call this function in your SDK application.
479   *
480   * @param  uint32_t addr : cleaned region start address.
481   *
482   * @param  uint32_t size : cleaned region size.
483   *
484   * @return 0 for success
485   *         1 for invalid argument
486   */
487 int Cache_Clean_Addr(uint32_t addr, uint32_t size);
488 
489 /**
490   * @brief Writeback the Cache items(also clean the dirty bit) in the region from DCache.
491   *        If the region is not in DCache addr room, nothing will be done.
492   *        Please do not call this function in your SDK application.
493   *
494   * @param  uint32_t addr : writeback region start address.
495   *
496   * @param  uint32_t size : writeback region size.
497   *
498   * @return 0 for success
499   *         1 for invalid argument
500   */
501 int Cache_WriteBack_Addr(uint32_t addr, uint32_t size);
502 
503 
504 /**
505   * @brief Invalidate all cache items in ICache.
506   *        Please do not call this function in your SDK application.
507   *
508   * @param  None
509   *
510   * @return None
511   */
512 void Cache_Invalidate_ICache_All(void);
513 
514 /**
515   * @brief Invalidate all cache items in DCache.
516   *        Please do not call this function in your SDK application.
517   *
518   * @param  None
519   *
520   * @return None
521   */
522 void Cache_Invalidate_DCache_All(void);
523 
524 /**
525   * @brief Clean the dirty bit of all cache items in DCache.
526   *        Please do not call this function in your SDK application.
527   *
528   * @param  None
529   *
530   * @return None
531   */
532 void Cache_Clean_All(void);
533 
534 /**
535   * @brief WriteBack all cache items in DCache.
536   *        Please do not call this function in your SDK application.
537   *
538   * @param  None
539   *
540   * @return None
541   */
542 void Cache_WriteBack_All(void);
543 
544 /**
545   * @brief Mask all buses through ICache and DCache.
546   *        Please do not call this function in your SDK application.
547   *
548   * @param  None
549   *
550   * @return None
551   */
552 void Cache_Mask_All(void);
553 
554 /**
555   * @brief UnMask DRam0 bus through DCache.
556   *        Please do not call this function in your SDK application.
557   *
558   * @param  None
559   *
560   * @return None
561   */
562 void Cache_UnMask_Dram0(void);
563 
564 /**
565   * @brief Suspend ICache auto preload operation, then you can resume it after some ICache operations.
566   *        Please do not call this function in your SDK application.
567   *
568   * @param  None
569   *
570   * @return uint32_t : 0 for ICache not auto preload before suspend.
571   */
572 uint32_t Cache_Suspend_ICache_Autoload(void);
573 
574 /**
575   * @brief Resume ICache auto preload operation after some ICache operations.
576   *        Please do not call this function in your SDK application.
577   *
578   * @param uint32_t autoload : 0 for ICache not auto preload before suspend.
579   *
580   * @return None.
581   */
582 void Cache_Resume_ICache_Autoload(uint32_t autoload);
583 
584 /**
585   * @brief Suspend DCache auto preload operation, then you can resume it after some DCache operations.
586   *        Please do not call this function in your SDK application.
587   *
588   * @param  None
589   *
590   * @return uint32_t : 0 for DCache not auto preload before suspend.
591   */
592 uint32_t Cache_Suspend_DCache_Autoload(void);
593 
594 /**
595   * @brief Resume DCache auto preload operation after some DCache operations.
596   *        Please do not call this function in your SDK application.
597   *
598   * @param uint32_t autoload : 0 for DCache not auto preload before suspend.
599   *
600   * @return None.
601   */
602 void Cache_Resume_DCache_Autoload(uint32_t autoload);
603 
604 /**
605   * @brief Start an ICache manual preload, will suspend auto preload of ICache.
606   *        Please do not call this function in your SDK application.
607   *
608   * @param uint32_t addr : start address of the preload region.
609   *
610   * @param uint32_t size : size of the preload region, should not exceed the size of ICache.
611   *
612   * @param uint32_t order : the preload order, 0 for positive, other for negative
613   *
614   * @return uint32_t : 0 for ICache not auto preload before manual preload.
615   */
616 uint32_t Cache_Start_ICache_Preload(uint32_t addr, uint32_t size, uint32_t order);
617 
618 /**
619   * @brief Return if the ICache manual preload done.
620   *        Please do not call this function in your SDK application.
621   *
622   * @param  None
623   *
624   * @return uint32_t : 0 for ICache manual preload not done.
625   */
626 uint32_t Cache_ICache_Preload_Done(void);
627 
628 /**
629   * @brief End the ICache manual preload to resume auto preload of ICache.
630   *        Please do not call this function in your SDK application.
631   *
632   * @param uint32_t autoload : 0 for ICache not auto preload before manual preload.
633   *
634   * @return None
635   */
636 void Cache_End_ICache_Preload(uint32_t autoload);
637 
638 /**
639   * @brief Start an DCache manual preload, will suspend auto preload of DCache.
640   *        Please do not call this function in your SDK application.
641   *
642   * @param uint32_t addr : start address of the preload region.
643   *
644   * @param uint32_t size : size of the preload region, should not exceed the size of DCache.
645   *
646   * @param uint32_t order : the preload order, 0 for positive, other for negative
647   *
648   * @return uint32_t : 0 for DCache not auto preload before manual preload.
649   */
650 uint32_t Cache_Start_DCache_Preload(uint32_t addr, uint32_t size, uint32_t order);
651 
652 /**
653   * @brief Return if the DCache manual preload done.
654   *        Please do not call this function in your SDK application.
655   *
656   * @param  None
657   *
658   * @return uint32_t : 0 for DCache manual preload not done.
659   */
660 uint32_t Cache_DCache_Preload_Done(void);
661 
662 /**
663   * @brief End the DCache manual preload to resume auto preload of DCache.
664   *        Please do not call this function in your SDK application.
665   *
666   * @param uint32_t autoload : 0 for DCache not auto preload before manual preload.
667   *
668   * @return None
669   */
670 void Cache_End_DCache_Preload(uint32_t autoload);
671 
672 /**
673   * @brief Config autoload parameters of ICache.
674   *        Please do not call this function in your SDK application.
675   *
676   * @param struct autoload_config * config : autoload parameters.
677   *
678   * @return None
679   */
680 void Cache_Config_ICache_Autoload(const struct autoload_config *config);
681 
682 /**
683   * @brief Config region autoload parameters of ICache.
684   *        Please do not call this function in your SDK application.
685   *
686   * @param struct autoload_region_config * config : region autoload parameters.
687   *
688   * @return ESP_ROM_ERR_INVALID_ARG : invalid param, 0 : success
689   */
690 int Cache_Config_ICache_Region_Autoload(const struct autoload_region_config *config);
691 
692 /**
693   * @brief Enable auto preload for ICache.
694   *        Please do not call this function in your SDK application.
695   *
696   * @param None
697   *
698   * @return None
699   */
700 void Cache_Enable_ICache_Autoload(void);
701 
702 /**
703   * @brief Disable auto preload for ICache.
704   *        Please do not call this function in your SDK application.
705   *
706   * @param None
707   *
708   * @return None
709   */
710 void Cache_Disable_ICache_Autoload(void);
711 
712 /**
713   * @brief Config autoload parameters of DCache.
714   *        Please do not call this function in your SDK application.
715   *
716   * @param struct autoload_config * config : autoload parameters.
717   *
718   * @return None
719   */
720 void Cache_Config_DCache_Autoload(const struct autoload_config *config);
721 
722 /**
723   * @brief Config region autoload parameters of DCache.
724   *        Please do not call this function in your SDK application.
725   *
726   * @param struct autoload_region_config * config : region autoload parameters.
727   *
728   * @return ESP_ROM_ERR_INVALID_ARG : invalid param, 0 : success
729   */
730 int Cache_Config_DCache_Region_Autoload(const struct autoload_region_config *config);
731 
732 /**
733   * @brief Enable auto preload for DCache.
734   *        Please do not call this function in your SDK application.
735   *
736   * @param None
737   *
738   * @return None
739   */
740 void Cache_Enable_DCache_Autoload(void);
741 
742 /**
743   * @brief Disable auto preload for DCache.
744   *        Please do not call this function in your SDK application.
745   *
746   * @param None
747   *
748   * @return None
749   */
750 void Cache_Disable_DCache_Autoload(void);
751 
752 /**
753   * @brief Config a group of prelock parameters of ICache.
754   *        Please do not call this function in your SDK application.
755   *
756   * @param struct lock_config * config : a group of lock parameters.
757   *
758   * @return None
759   */
760 
761 void Cache_Enable_ICache_PreLock(const struct lock_config *config);
762 
763 /**
764   * @brief Disable a group of prelock parameters for ICache.
765   *        However, the locked data will not be released.
766   *        Please do not call this function in your SDK application.
767   *
768   * @param uint16_t group : 0 for group0, 1 for group1.
769   *
770   * @return None
771   */
772 void Cache_Disable_ICache_PreLock(uint16_t group);
773 
774 /**
775   * @brief Lock the cache items for ICache.
776   *        Operation will be done CACHE_LINE_SIZE aligned.
777   *        If the region is not in ICache addr room, nothing will be done.
778   *        Please do not call this function in your SDK application.
779   *
780   * @param  uint32_t addr: start address to lock
781   *
782   * @param  uint32_t items: cache lines to lock, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB)
783   *
784   * @return None
785   */
786 void Cache_Lock_ICache_Items(uint32_t addr, uint32_t items);
787 
788 /**
789   * @brief Unlock the cache items for ICache.
790   *        Operation will be done CACHE_LINE_SIZE aligned.
791   *        If the region is not in ICache addr room, nothing will be done.
792   *        Please do not call this function in your SDK application.
793   *
794   * @param  uint32_t addr: start address to unlock
795   *
796   * @param  uint32_t items: cache lines to unlock, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB)
797   *
798   * @return None
799   */
800 void Cache_Unlock_ICache_Items(uint32_t addr, uint32_t items);
801 
802 /**
803   * @brief Config a group of prelock parameters of DCache.
804   *        Please do not call this function in your SDK application.
805   *
806   * @param struct lock_config * config : a group of lock parameters.
807   *
808   * @return None
809   */
810 void Cache_Enable_DCache_PreLock(const struct lock_config *config);
811 
812 /**
813   * @brief Disable a group of prelock parameters for DCache.
814   *        However, the locked data will not be released.
815   *        Please do not call this function in your SDK application.
816   *
817   * @param uint16_t group : 0 for group0, 1 for group1.
818   *
819   * @return None
820   */
821 void Cache_Disable_DCache_PreLock(uint16_t group);
822 
823 /**
824   * @brief Lock the cache items for DCache.
825   *        Operation will be done CACHE_LINE_SIZE aligned.
826   *        If the region is not in DCache addr room, nothing will be done.
827   *        Please do not call this function in your SDK application.
828   *
829   * @param  uint32_t addr: start address to lock
830   *
831   * @param  uint32_t items: cache lines to lock, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB)
832   *
833   * @return None
834   */
835 void Cache_Lock_DCache_Items(uint32_t addr, uint32_t items);
836 
837 /**
838   * @brief Unlock the cache items for DCache.
839   *        Operation will be done CACHE_LINE_SIZE aligned.
840   *        If the region is not in DCache addr room, nothing will be done.
841   *        Please do not call this function in your SDK application.
842   *
843   * @param  uint32_t addr: start address to unlock
844   *
845   * @param  uint32_t items: cache lines to unlock, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB)
846   *
847   * @return None
848   */
849 void Cache_Unlock_DCache_Items(uint32_t addr, uint32_t items);
850 
851 /**
852   * @brief Lock the cache items in tag memory for ICache or DCache.
853   *        Please do not call this function in your SDK application.
854   *
855   * @param uint32_t addr : start address of lock region.
856   *
857   * @param uint32_t size : size of lock region.
858   *
859   * @return 0 for success
860   *         1 for invalid argument
861   */
862 int Cache_Lock_Addr(uint32_t addr, uint32_t size);
863 
864 /**
865   * @brief Unlock the cache items in tag memory for ICache or DCache.
866   *        Please do not call this function in your SDK application.
867   *
868   * @param uint32_t addr : start address of unlock region.
869   *
870   * @param uint32_t size : size of unlock region.
871   *
872   * @return 0 for success
873   *         1 for invalid argument
874   */
875 int Cache_Unlock_Addr(uint32_t addr, uint32_t size);
876 
877 /**
878   * @brief Disable ICache access for the cpu.
879   *        This operation will make all ICache tag memory invalid, CPU can't access ICache, ICache will keep idle.
880   *        Please do not call this function in your SDK application.
881   *
882   * @return uint32_t : auto preload enabled before
883   */
884 uint32_t Cache_Disable_ICache(void);
885 
886 /**
887   * @brief Enable ICache access for the cpu.
888   *        Please do not call this function in your SDK application.
889   *
890   * @param  uint32_t autoload : ICache will preload then.
891   *
892   * @return None
893   */
894 void Cache_Enable_ICache(uint32_t autoload);
895 
896 /**
897   * @brief Disable DCache access for the cpu.
898   *        This operation will make all DCache tag memory invalid, CPU can't access DCache, DCache will keep idle
899   *        Please do not call this function in your SDK application.
900   *
901   * @return uint32_t : auto preload enabled before
902   */
903 uint32_t Cache_Disable_DCache(void);
904 
905 /**
906   * @brief Enable DCache access for the cpu.
907   *        Please do not call this function in your SDK application.
908   *
909   * @param  uint32_t autoload : DCache will preload then.
910   *
911   * @return None
912   */
913 void Cache_Enable_DCache(uint32_t autoload);
914 
915 /**
916   * @brief Suspend ICache access for the cpu.
917   *        The ICache tag memory is still there, CPU can't access ICache, ICache will keep idle.
918   *        Please do not change MMU, cache mode or tag memory(tag memory can be changed in some special case).
919   *        Please do not call this function in your SDK application.
920   *
921   * @param  None
922   *
923   * @return uint32_t : auto preload enabled before
924   */
925 uint32_t Cache_Suspend_ICache(void);
926 
927 /**
928   * @brief Resume ICache access for the cpu.
929   *        Please do not call this function in your SDK application.
930   *
931   * @param  uint32_t autoload : ICache will preload then.
932   *
933   * @return None
934   */
935 void Cache_Resume_ICache(uint32_t autoload);
936 
937 /**
938   * @brief Suspend DCache access for the cpu.
939   *        The ICache tag memory is still there, CPU can't access DCache, DCache will keep idle.
940   ×        Please do not change MMU, cache mode or tag memory(tag memory can be changed in some special case).
941   *        Please do not call this function in your SDK application.
942   *
943   * @param  None
944   *
945   * @return uint32_t : auto preload enabled before
946   */
947 uint32_t Cache_Suspend_DCache(void);
948 
949 /**
950   * @brief Resume DCache access for the cpu.
951   *        Please do not call this function in your SDK application.
952   *
953   * @param  uint32_t autoload : DCache will preload then.
954   *
955   * @return None
956   */
957 void Cache_Resume_DCache(uint32_t autoload);
958 
959 /**
960   * @brief Get ICache cache line size
961   *
962   * @param  None
963   *
964   * @return uint32_t: 16, 32, 64 Byte
965   */
966 uint32_t Cache_Get_ICache_Line_Size(void);
967 
968 /**
969   * @brief Get DCache cache line size
970   *
971   * @param  None
972   *
973   * @return uint32_t: 16, 32, 64 Byte
974   */
975 uint32_t Cache_Get_DCache_Line_Size(void);
976 
977 /**
978   * @brief Set default mode from boot, 8KB ICache, 16Byte cache line size.
979   *
980   * @param  None
981   *
982   * @return None
983   */
984 void Cache_Set_Default_Mode(void);
985 
986 /**
987   * @brief Set default mode from boot, 8KB ICache, 16Byte cache line size.
988   *
989   * @param None
990   *
991   * @return None
992   */
993 void Cache_Enable_Defalut_ICache_Mode(void);
994 
995 /**
996   * @brief Occupy the cache items for DCache.
997   *        Operation will be done CACHE_LINE_SIZE aligned.
998   *        If the region is not in DCache addr room, nothing will be done.
999   *        Please do not call this function in your SDK application.
1000   *
1001   * @param uint32_t addr : start address of occupy region
1002   *
1003   * @param uint32_t items : cache lines to occupy, items * cache_line_size should not exceed the cache_size
1004   *
1005   * @return None
1006   */
1007 void Cache_Occupy_Items(uint32_t addr, uint32_t items);
1008 
1009 /**
1010   * @brief Occupy the cache addr for DCache.
1011   *        Operation will be done CACHE_LINE_SIZE aligned.
1012   *        If the region is not in DCache addr room, nothing will be done.
1013   *        Please do not call this function in your SDK application.
1014   *
1015   * @param uint32_t addr : start address of occupy region
1016   *
1017   * @param uint32_t size : size of occupy region, size should not exceed the cache_size
1018   */
1019 int Cache_Occupy_Addr(uint32_t addr, uint32_t size);
1020 
1021 /**
1022   * @brief Enable freeze for ICache.
1023   *        Any miss request will be rejected, including cpu miss and preload/autoload miss.
1024   *        Please do not call this function in your SDK application.
1025   *
1026   * @param cache_freeze_mode_t mode : 0 for assert busy 1 for assert hit
1027   *
1028   * @return None
1029   */
1030 void Cache_Freeze_ICache_Enable(cache_freeze_mode_t mode);
1031 
1032 /**
1033   * @brief Disable freeze for ICache.
1034   *        Please do not call this function in your SDK application.
1035   *
1036   * @return None
1037   */
1038 void Cache_Freeze_ICache_Disable(void);
1039 
1040 /**
1041   * @brief Enable freeze for DCache.
1042   *        Any miss request will be rejected, including cpu miss and preload/autoload miss.
1043   *        Please do not call this function in your SDK application.
1044   *
1045   * @param cache_freeze_mode_t mode : 0 for assert busy 1 for assert hit
1046   *
1047   * @return None
1048   */
1049 void Cache_Freeze_DCache_Enable(cache_freeze_mode_t mode);
1050 
1051 /**
1052   * @brief Disable freeze for DCache.
1053   *        Please do not call this function in your SDK application.
1054   *
1055   * @return None
1056   */
1057 void Cache_Freeze_DCache_Disable(void);
1058 
1059 /**
1060   * @brief Travel tag memory to run a call back function.
1061   *        ICache and DCache are suspend when doing this.
1062   *        The callback will get the parameter tag_group_info, which will include a group of tag memory addresses and cache memory addresses.
1063   *        Please do not call this function in your SDK application.
1064   *
1065   * @param  struct cache_mode * mode : the cache to check and the cache mode.
1066   *
1067   * @param  uint32_t filter_addr : only the cache lines which may include the filter_address will be returned to the call back function.
1068   *                                0 for do not filter, all cache lines will be returned.
1069   *
1070   * @param  void (* process)(struct tag_group_info *) : call back function, which may be called many times, a group(the addresses in the group are in the same position in the cache ways) a time.
1071   *
1072   * @return None
1073   */
1074 void Cache_Travel_Tag_Memory(struct cache_mode * mode, uint32_t filter_addr, void (* process)(struct tag_group_info *));
1075 
1076 /**
1077   * @brief Travel tag memory to run a call back function, using 2nd tag registers.
1078   *        ICache and DCache are suspend when doing this.
1079   *        The callback will get the parameter tag_group_info, which will include a group of tag memory addresses and cache memory addresses.
1080   *        Please do not call this function in your SDK application.
1081   *
1082   * @param  struct cache_mode * mode : the cache to check and the cache mode.
1083   *
1084   * @param  uint32_t filter_addr : only the cache lines which may include the filter_address will be returned to the call back function.
1085   *                                0 for do not filter, all cache lines will be returned.
1086   *
1087   * @param  void (* process)(struct tag_group_info *) : call back function, which may be called many times, a group(the addresses in the group are in the same position in the cache ways) a time.
1088   *
1089   * @return None
1090   */
1091 void Cache_Travel_Tag_Memory2(struct cache_mode * mode, uint32_t filter_addr, void (* process)(struct tag_group_info *));
1092 
1093 /**
1094   * @brief Get the virtual address from cache mode, cache tag and the virtual address offset of cache ways.
1095   *        Please do not call this function in your SDK application.
1096   *
1097   * @param  struct cache_mode * mode : the cache to calculate the virtual address and the cache mode.
1098   *
1099   * @param  uint32_t tag : the tag part fo a tag item, 12-14 bits.
1100   *
1101   * @param  uint32_t addr_offset : the virtual address offset of the cache ways.
1102   *
1103   * @return uint32_t : the virtual address.
1104   */
1105 uint32_t Cache_Get_Virtual_Addr(struct cache_mode *mode, uint32_t tag, uint32_t vaddr_offset);
1106 
1107 /**
1108   * @brief Get cache memory block base address.
1109   *        Please do not call this function in your SDK application.
1110   *
1111   * @param  uint32_t icache : 0 for dcache, other for icache.
1112   *
1113   * @param  uint32_t bank_no : 0 ~ 3 bank.
1114   *
1115   * @return uint32_t : the cache memory block base address, 0 if the block not used.
1116   */
1117 uint32_t Cache_Get_Memory_BaseAddr(uint32_t icache, uint32_t bank_no);
1118 
1119 /**
1120   * @brief Get the cache memory address from cache mode, cache memory offset and the virtual address offset of cache ways.
1121   *        Please do not call this function in your SDK application.
1122   *
1123   * @param  struct cache_mode * mode : the cache to calculate the virtual address and the cache mode.
1124   *
1125   * @param  uint32_t cache_memory_offset : the cache memory offset of the whole cache (ICache or DCache) for the cache line.
1126   *
1127   * @param  uint32_t addr_offset : the virtual address offset of the cache ways.
1128   *
1129   * @return uint32_t : the virtual address.
1130   */
1131 uint32_t Cache_Get_Memory_Addr(struct cache_mode *mode, uint32_t cache_memory_offset, uint32_t vaddr_offset);
1132 
1133 /**
1134   * @brief Get the cache memory value by DRAM address.
1135   *        Please do not call this function in your SDK application.
1136   *
1137   * @param  uint32_t cache_memory_addr : DRAM address for the cache memory, should be 4 byte aligned for IBus address.
1138   *
1139   * @return uint32_t : the word value of the address.
1140   */
1141 uint32_t Cache_Get_Memory_value(uint32_t cache_memory_addr);
1142 /**
1143   * @}
1144   */
1145 
1146 /**
1147   * @brief Get the cache MMU IROM end address.
1148   *        Please do not call this function in your SDK application.
1149   *
1150   * @param  void
1151   *
1152   * @return uint32_t : the word value of the address.
1153   */
1154 uint32_t Cache_Get_IROM_MMU_End(void);
1155 
1156 /**
1157   * @brief Get the cache MMU DROM end address.
1158   *        Please do not call this function in your SDK application.
1159   *
1160   * @param  void
1161   *
1162   * @return uint32_t : the word value of the address.
1163   */
1164 uint32_t Cache_Get_DROM_MMU_End(void);
1165 
1166 /**
1167  * @brief Configure cache MMU page size according to instruction and rodata size
1168  *
1169  * @param irom_size The instruction cache MMU page size
1170  * @param drom_size The rodata data cache MMU page size
1171  */
1172 void Cache_Set_IDROM_MMU_Size(uint32_t irom_size, uint32_t drom_size);
1173 
1174 /**
1175  * @brief Configure cache MMU page information
1176  *
1177  * @param instr_page_num The instruction cache MMU page num
1178  * @param rodata_page_num The rodata cache MMU page num
1179  * @param rodata_start The rodata start cache address
1180  * @param rodata_end The rodata end cache address
1181  * @param i_off The offset of instruction when instruction copied from flash to xip_psram
1182  * @param ro_off The offset of rodata when rodata copied from flash to xip_psram
1183  */
1184 void Cache_Set_IDROM_MMU_Info(uint32_t instr_page_num, uint32_t rodata_page_num, uint32_t rodata_start, uint32_t rodata_end, int i_off, int ro_off);
1185 
1186 /**
1187   * @brief Used by SPI flash mmap
1188   *
1189   */
1190 int flash2spiram_instruction_offset(void);
1191 int flash2spiram_rodata_offset(void);
1192 uint32_t flash_instr_rodata_start_page(uint32_t bus);
1193 uint32_t flash_instr_rodata_end_page(uint32_t bus);
1194 
1195 extern struct cache_internal_stub_table* rom_cache_internal_table_ptr;
1196 extern cache_op_cb_t rom_cache_op_cb;
1197 #ifdef __cplusplus
1198 }
1199 #endif
1200