1 /*
2  * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef _ROM_CACHE_H_
8 #define _ROM_CACHE_H_
9 
10 
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14 
15 /** \defgroup cache_apis, cache operation related apis
16   * @brief cache apis
17   */
18 
19 /** @addtogroup cache_apis
20   * @{
21   */
22 
23 #define MIN_CACHE_SIZE                  8192
24 #define MAX_CACHE_SIZE                  16384
25 #define MIN_CACHE_WAYS                  4
26 #define MAX_CACHE_WAYS                  4
27 #define MIN_CACHE_LINE_SIZE             16
28 //normally should be (MAX_CACHE_SIZE / MIN_CACHE_WAYS / MIN_CACHE_LINE_SIZE), however, the items not all in one tag memory block.
29 #define MAX_TAG_BLOCK_ITEMS             (MAX_CACHE_SIZE / 8 / MIN_CACHE_LINE_SIZE)
30 #define TAG_SIZE                        4
31 #define MAX_TAG_BLOCK_SIZE              (MAX_TAG_BLOCK_ITEMS * TAG_SIZE)
32 
33 #define ESP_CACHE_TEMP_ADDR DROM0_ADDRESS_LOW
34 #define CACHE_MAX_OPERATION_SIZE BUS_ADDR_SIZE
35 
36 
37 typedef enum {
38     CACHE_DCACHE = 0,
39     CACHE_ICACHE = 1,
40 } cache_t;
41 
42 typedef enum {
43     CACHE_MEMORY_INVALID = 0,
44     CACHE_MEMORY_ICACHE_LOW = 1<<0,
45     CACHE_MEMORY_ICACHE_HIGH = 1<<1,
46     CACHE_MEMORY_DCACHE_LOW = 1<<2,
47     CACHE_MEMORY_DCACHE_HIGH = 1<<3,
48 } cache_layout_t;
49 
50 #define CACHE_SIZE_0KB  99 // unique value used for logging only
51 #define CACHE_SIZE_8KB  CACHE_SIZE_HALF
52 #define CACHE_SIZE_16KB CACHE_SIZE_FULL
53 typedef enum {
54     CACHE_SIZE_HALF = 0,                /*!< 8KB for icache and dcache */
55     CACHE_SIZE_FULL = 1,                /*!< 16KB for icache and dcache */
56 } cache_size_t;
57 
58 typedef enum {
59     CACHE_4WAYS_ASSOC = 0,              /*!< 4 way associated cache */
60 } cache_ways_t;
61 
62 typedef enum {
63     CACHE_LINE_SIZE_16B = 0,            /*!< 16 Byte cache line size */
64     CACHE_LINE_SIZE_32B = 1,            /*!< 32 Byte cache line size */
65 } cache_line_size_t;
66 
67 typedef enum {
68     CACHE_AUTOLOAD_POSITIVE = 0,        /*!< cache autoload step is positive */
69     CACHE_AUTOLOAD_NEGATIVE = 1,        /*!< cache autoload step is negative */
70 } cache_autoload_order_t;
71 
72 #define CACHE_AUTOLOAD_STEP(i) ((i) - 1)
73 
74 typedef enum {
75     CACHE_AUTOLOAD_MISS_TRIGGER = 0,    /*!< autoload only triggered by cache miss */
76     CACHE_AUTOLOAD_HIT_TRIGGER  = 1,    /*!< autoload only triggered by cache hit */
77     CACHE_AUTOLOAD_BOTH_TRIGGER = 2,    /*!< autoload triggered both by cache miss and hit */
78 } cache_autoload_trigger_t;
79 
80 struct cache_mode {
81     uint32_t cache_size;                /*!< cache size in byte */
82     uint16_t cache_line_size;           /*!< cache line size in byte */
83     uint8_t cache_ways;                 /*!< cache ways, always 4 */
84     uint8_t icache;                     /*!< the cache index, 0 for dcache, 1 for icache */
85 };
86 
87 struct tag_item {
88     uint32_t dirty:1;                   /*!< the cache line value is dirty or not */
89     uint32_t tag:14;                    /*!< the tag is the high part of the cache address, however is only 16MB range, and with out low part */
90     uint32_t valid:1;                   /*!< the tag item is valid or not */
91     uint32_t fifo_cnt:3;                /*!< fifo cnt, 0 ~ 3 for 4 ways cache, 0 ~ 7 for 8 ways cache */
92     uint32_t lock:1;                    /*!< the cache line is locked or not */
93     uint32_t attr:3;                    /*!< the attribute of the external memory physical address */
94     uint32_t access:1;                  /*!< software accessable, used by hardware */
95     uint32_t reserved:8;
96 };
97 
98 struct autoload_config {
99     uint8_t order;                      /*!< autoload step is positive or negative */
100     uint8_t trigger;                    /*!< autoload trigger */
101     uint8_t ena0;                       /*!< autoload region0 enable */
102     uint8_t ena1;                       /*!< autoload region1 enable */
103     uint32_t addr0;                     /*!< autoload region0 start address */
104     uint32_t size0;                     /*!< autoload region0 size */
105     uint32_t addr1;                     /*!< autoload region1 start address */
106     uint32_t size1;                     /*!< autoload region1 size */
107 };
108 
109 struct tag_group_info {
110     struct cache_mode mode;                         /*!< cache and cache mode */
111     uint32_t filter_addr;                           /*!< the address that used to generate the struct */
112     uint32_t vaddr_offset;		            /*!< virtual address offset of the cache ways */
113     uint32_t tag_addr[MAX_CACHE_WAYS];              /*!< tag memory address, only [0~mode.ways-1] is valid to use */
114     uint32_t cache_memory_offset[MAX_CACHE_WAYS];   /*!< cache memory address, only [0~mode.ways-1] is valid to use */
115 };
116 
117 struct lock_config {
118     uint32_t addr;                                  /*!< manual lock address*/
119     uint16_t size;                                  /*!< manual lock size*/
120     uint16_t group;                                 /*!< manual lock group, 0 or 1*/
121 };
122 
123 #define ESP_ROM_ERR_INVALID_ARG         1
124 #define MMU_SET_ADDR_ALIGNED_ERROR      2
125 #define MMU_SET_PASE_SIZE_ERROR         3
126 #define MMU_SET_VADDR_OUT_RANGE         4
127 
128 /**
129   * @brief Initialise cache mmu, mark all entries as invalid.
130   *        Please do not call this function in your SDK application.
131   *
132   * @param  None
133   *
134   * @return None
135   */
136 void Cache_MMU_Init(void);
137 
138 /**
139   * @brief Set ICache mmu mapping.
140   *        Please do not call this function in your SDK application.
141   *
142   * @param  uint32_t ext_ram : DPORT_MMU_ACCESS_FLASH for flash, DPORT_MMU_ACCESS_SPIRAM for spiram, DPORT_MMU_INVALID for invalid.
143   *
144   * @param  uint32_t vaddr : virtual address in CPU address space.
145   *                              Can be Iram0,Iram1,Irom0,Drom0 and AHB buses address.
146   *                              Should be aligned by psize.
147   *
148   * @param  uint32_t paddr : physical address in external memory.
149   *                              Should be aligned by psize.
150   *
151   * @param  uint32_t psize : page size of ICache, in kilobytes. Should be 64 here.
152   *
153   * @param  uint32_t num : pages to be set.
154   *
155   * @param  uint32_t fixed : 0 for physical pages grow with virtual pages, other for virtual pages map to same physical page.
156   *
157   * @return uint32_t: error status
158   *                   0 : mmu set success
159   *                   2 : vaddr or paddr is not aligned
160   *                   3 : psize error
161   *                   4 : vaddr is out of range
162   */
163 int Cache_Ibus_MMU_Set(uint32_t ext_ram, uint32_t vaddr, uint32_t paddr,  uint32_t psize, uint32_t num, uint32_t fixed);
164 
165 /**
166   * @brief Set DCache mmu mapping.
167   *        Please do not call this function in your SDK application.
168   *
169   * @param  uint32_t ext_ram : DPORT_MMU_ACCESS_FLASH for flash, DPORT_MMU_ACCESS_SPIRAM for spiram, DPORT_MMU_INVALID for invalid.
170   *
171   * @param  uint32_t vaddr : virtual address in CPU address space.
172   *                              Can be DRam0, DRam1, DRom0, DPort and AHB buses address.
173   *                              Should be aligned by psize.
174   *
175   * @param  uint32_t paddr : physical address in external memory.
176   *                              Should be aligned by psize.
177   *
178   * @param  uint32_t psize : page size of DCache, in kilobytes. Should be 64 here.
179   *
180   * @param  uint32_t num : pages to be set.
181 
182   * @param  uint32_t fixed : 0 for physical pages grow with virtual pages, other for virtual pages map to same physical page.
183   *
184   * @return uint32_t: error status
185   *                   0 : mmu set success
186   *                   2 : vaddr or paddr is not aligned
187   *                   3 : psize error
188   *                   4 : vaddr is out of range
189   */
190 int Cache_Dbus_MMU_Set(uint32_t ext_ram, uint32_t vaddr, uint32_t paddr, uint32_t psize, uint32_t num, uint32_t fixed);
191 
192 /**
193   * @brief Count the pages in the bus room address which map to Flash.
194   *        Please do not call this function in your SDK application.
195   *
196   * @param uint32_t bus : the bus to count with.
197   *
198   * @param uint32_t * page0_mapped : value should be initial by user, 0 for not mapped, other for mapped count.
199   *
200   * return uint32_t : the number of pages which map to Flash.
201   */
202 uint32_t Cache_Count_Flash_Pages(uint32_t bus, uint32_t * page0_mapped);
203 
204 /**
205   * @brief Copy Instruction or rodata from Flash to SPIRAM, and remap to SPIRAM.
206   *        Please do not call this function in your SDK application.
207   *
208   * @param uint32_t bus : the bus which need to copy to SPIRAM.
209   *
210   * @param uint32_t bus_start_addr : the start virtual address for the bus.
211   *
212   * @param uint32_t start_page : the start (64KB) page number in SPIRAM.
213   *
214   * @param uint32_t * page0_page : the flash page0 in SPIRAM page number, 0xffff for invalid.
215   *
216   * return uint32_t : the next start page number for SPIRAM not mapped.
217   */
218 uint32_t Cache_Flash_To_SPIRAM_Copy(uint32_t bus, uint32_t bus_start_addr, uint32_t start_page, uint32_t * page0_page);
219 
220 
221 /**
222   * @brief allocate memory to used by ICache and DCache.
223   *        Please do not call this function in your SDK application.
224   *
225   * @param cache_layout_t sram0_layout : the usage of first 8KB internal memory block, can be CACHE_MEMORY_INVALID, CACHE_MEMORY_ICACHE_LOW, CACHE_MEMORY_ICACHE_HIGH, CACHE_MEMORY_DCACHE_LOW and CACHE_MEMORY_DCACHE_HIGH
226   *
227   * @param cache_layout_t sram1_layout : the usage of second 8KB internal memory block
228   *
229   * @param cache_layout_t sram2_layout : the usage of third 8KB internal memory block
230   *
231   * @param cache_layout_t sram3_layout : the usage of forth 8KB internal memory block
232   *
233   * return none
234   */
235 void Cache_Allocate_SRAM(cache_layout_t sram0_layout, cache_layout_t sram1_layout, cache_layout_t sram2_layout, cache_layout_t sram3_layout);
236 
237 /**
238   * @brief Get cache mode of ICache or DCache.
239   *        Please do not call this function in your SDK application.
240   *
241   * @param struct cache_mode * mode : the pointer of cache mode struct, caller should set the icache field
242   *
243   * return none
244   */
245 void Cache_Get_Mode(struct cache_mode * mode);
246 
247 /**
248   * @brief set ICache modes: cache size, associate ways and cache line size.
249   *        Please do not call this function in your SDK application.
250   *
251   * @param cache_size_t cache_size : the cache size, can be CACHE_SIZE_HALF and CACHE_SIZE_FULL
252   *
253   * @param cache_ways_t ways : the associate ways of cache, can only be CACHE_4WAYS_ASSOC
254   *
255   * @param cache_line_size_t cache_line_size : the cache line size, can be CACHE_LINE_SIZE_16B, CACHE_LINE_SIZE_32B
256   *
257   * return none
258   */
259 void Cache_Set_ICache_Mode(cache_size_t cache_size, cache_ways_t ways, cache_line_size_t cache_line_size);
260 
261 /**
262   * @brief set DCache modes: cache size, associate ways and cache line size.
263   *        Please do not call this function in your SDK application.
264   *
265   * @param cache_size_t cache_size : the cache size, can be CACHE_SIZE_HALF and CACHE_SIZE_FULL
266   *
267   * @param cache_ways_t ways : the associate ways of cache, can only be CACHE_4WAYS_ASSOC
268   *
269   * @param cache_line_size_t cache_line_size : the cache line size, can be CACHE_LINE_SIZE_16B, CACHE_LINE_SIZE_32B
270   *
271   * return none
272   */
273 void Cache_Set_DCache_Mode(cache_size_t cache_size, cache_ways_t ways, cache_line_size_t cache_line_size);
274 
275 /**
276   * @brief check if the address is accessed through ICache.
277   *        Please do not call this function in your SDK application.
278   *
279   * @param  uint32_t addr : the address to check.
280   *
281   * @return 1 if the address is accessed through ICache, 0 if not.
282   */
283 uint32_t Cache_Address_Through_ICache(uint32_t addr);
284 
285 /**
286   * @brief check if the address is accessed through DCache.
287   *        Please do not call this function in your SDK application.
288   *
289   * @param  uint32_t addr : the address to check.
290   *
291   * @return 1 if the address is accessed through DCache, 0 if not.
292   */
293 uint32_t Cache_Address_Through_DCache(uint32_t addr);
294 
295 /**
296   * @brief Invalidate the cache items for ICache.
297   *        Operation will be done CACHE_LINE_SIZE aligned.
298   *        If the region is not in ICache addr room, nothing will be done.
299   *        Please do not call this function in your SDK application.
300   *
301   * @param  uint32_t addr: start address to invalidate
302   *
303   * @param  uint32_t items: cache lines to invalidate, items * cache_line_size should not exceed the bus address size(4MB)
304   *
305   * @return None
306   */
307 void Cache_Invalidate_ICache_Items(uint32_t addr, uint32_t items);
308 
309 /**
310   * @brief Invalidate the cache items for DCache.
311   *        Operation will be done CACHE_LINE_SIZE aligned.
312   *        If the region is not in DCache addr room, nothing will be done.
313   *        Please do not call this function in your SDK application.
314   *
315   * @param  uint32_t addr: start address to invalidate
316   *
317   * @param  uint32_t items: cache lines to invalidate, items * cache_line_size should not exceed the bus address size(4MB)
318   *
319   * @return None
320   */
321 void Cache_Invalidate_DCache_Items(uint32_t addr, uint32_t items);
322 
323 /**
324   * @brief Clean the dirty bit of cache Items of DCache.
325   *        Operation will be done CACHE_LINE_SIZE aligned.
326   *        If the region is not in DCache addr room, nothing will be done.
327   *        Please do not call this function in your SDK application.
328   *
329   * @param  uint32_t addr: start address to Clean
330   *
331   * @param  uint32_t items: cache lines to invalidate, items * cache_line_size should not exceed the bus address size(4MB)
332   *
333   * @return None
334   */
335 void Cache_Clean_Items(uint32_t addr, uint32_t items);
336 
337 /**
338   * @brief Write back the cache items of DCache.
339   *        Operation will be done CACHE_LINE_SIZE aligned.
340   *        If the region is not in DCache addr room, nothing will be done.
341   *        Please do not call this function in your SDK application.
342   *
343   * @param  uint32_t addr: start address to write back
344   *
345   * @param  uint32_t items: cache lines to invalidate, items * cache_line_size should not exceed the bus address size(4MB)
346   *
347   * @return None
348   */
349 void Cache_WriteBack_Items(uint32_t addr, uint32_t items);
350 
351 /**
352   * @brief Invalidate the Cache items in the region from ICache or DCache.
353   *        If the region is not in Cache addr room, nothing will be done.
354   *        Please do not call this function in your SDK application.
355   *
356   * @param  uint32_t addr : invalidated region start address.
357   *
358   * @param  uint32_t size : invalidated region size.
359   *
360   * @return 0 for success
361   *         1 for invalid argument
362   */
363 int Cache_Invalidate_Addr(uint32_t addr, uint32_t size);
364 
365 /**
366   * @brief Clean the dirty bit of Cache items in the region from DCache.
367   *        If the region is not in DCache addr room, nothing will be done.
368   *        Please do not call this function in your SDK application.
369   *
370   * @param  uint32_t addr : cleaned region start address.
371   *
372   * @param  uint32_t size : cleaned region size.
373   *
374   * @return 0 for success
375   *         1 for invalid argument
376   */
377 int Cache_Clean_Addr(uint32_t addr, uint32_t size);
378 
379 /**
380   * @brief Writeback the Cache items(also clean the dirty bit) in the region from DCache.
381   *        If the region is not in DCache addr room, nothing will be done.
382   *        Please do not call this function in your SDK application.
383   *
384   * @param  uint32_t addr : writeback region start address.
385   *
386   * @param  uint32_t size : writeback region size.
387   *
388   * @return 0 for success
389   *         1 for invalid argument
390   */
391 int Cache_WriteBack_Addr(uint32_t addr, uint32_t size);
392 
393 
394 /**
395   * @brief Invalidate all cache items in ICache.
396   *        Please do not call this function in your SDK application.
397   *
398   * @param  None
399   *
400   * @return None
401   */
402 void Cache_Invalidate_ICache_All(void);
403 
404 /**
405   * @brief Invalidate all cache items in DCache.
406   *        Please do not call this function in your SDK application.
407   *
408   * @param  None
409   *
410   * @return None
411   */
412 void Cache_Invalidate_DCache_All(void);
413 
414 /**
415   * @brief Clean the dirty bit of all cache items in DCache.
416   *        Please do not call this function in your SDK application.
417   *
418   * @param  None
419   *
420   * @return None
421   */
422 void Cache_Clean_All(void);
423 
424 /**
425   * @brief WriteBack all cache items in DCache.
426   *        Please do not call this function in your SDK application.
427   *
428   * @param  None
429   *
430   * @return None
431   */
432 void Cache_WriteBack_All(void);
433 
434 /**
435   * @brief Mask all buses through ICache and DCache.
436   *        Please do not call this function in your SDK application.
437   *
438   * @param  None
439   *
440   * @return None
441   */
442 void Cache_Mask_All(void);
443 
444 /**
445   * @brief UnMask DRom0 bus through ICache.
446   *        Please do not call this function in your SDK application.
447   *
448   * @param  None
449   *
450   * @return None
451   */
452 void Cache_UnMask_Drom0(void);
453 
454 /**
455   * @brief Suspend ICache auto preload operation, then you can resume it after some ICache operations.
456   *        Please do not call this function in your SDK application.
457   *
458   * @param  None
459   *
460   * @return uint32_t : 0 for ICache not auto preload before suspend.
461   */
462 uint32_t Cache_Suspend_ICache_Autoload(void);
463 
464 /**
465   * @brief Resume ICache auto preload operation after some ICache operations.
466   *        Please do not call this function in your SDK application.
467   *
468   * @param uint32_t autoload : 0 for ICache not auto preload before suspend.
469   *
470   * @return None.
471   */
472 void Cache_Resume_ICache_Autoload(uint32_t autoload);
473 
474 /**
475   * @brief Suspend DCache auto preload operation, then you can resume it after some DCache operations.
476   *        Please do not call this function in your SDK application.
477   *
478   * @param  None
479   *
480   * @return uint32_t : 0 for DCache not auto preload before suspend.
481   */
482 uint32_t Cache_Suspend_DCache_Autoload(void);
483 
484 /**
485   * @brief Resume DCache auto preload operation after some DCache operations.
486   *        Please do not call this function in your SDK application.
487   *
488   * @param uint32_t autoload : 0 for DCache not auto preload before suspend.
489   *
490   * @return None.
491   */
492 void Cache_Resume_DCache_Autoload(uint32_t autoload);
493 
494 /**
495   * @brief Start an ICache manual preload, will suspend auto preload of ICache.
496   *        Please do not call this function in your SDK application.
497   *
498   * @param uint32_t addr : start address of the preload region.
499   *
500   * @param uint32_t size : size of the preload region, should not exceed the size of ICache.
501   *
502   * @param uint32_t order : the preload order, 0 for positive, other for negative
503   *
504   * @return uint32_t : 0 for ICache not auto preload before manual preload.
505   */
506 uint32_t Cache_Start_ICache_Preload(uint32_t addr, uint32_t size, uint32_t order);
507 
508 /**
509   * @brief Return if the ICache manual preload done.
510   *        Please do not call this function in your SDK application.
511   *
512   * @param  None
513   *
514   * @return uint32_t : 0 for ICache manual preload not done.
515   */
516 uint32_t Cache_ICache_Preload_Done(void);
517 
518 /**
519   * @brief End the ICache manual preload to resume auto preload of ICache.
520   *        Please do not call this function in your SDK application.
521   *
522   * @param uint32_t autoload : 0 for ICache not auto preload before manual preload.
523   *
524   * @return None
525   */
526 void Cache_End_ICache_Preload(uint32_t autoload);
527 
528 /**
529   * @brief Start an DCache manual preload, will suspend auto preload of DCache.
530   *        Please do not call this function in your SDK application.
531   *
532   * @param uint32_t addr : start address of the preload region.
533   *
534   * @param uint32_t size : size of the preload region, should not exceed the size of DCache.
535   *
536   * @param uint32_t order : the preload order, 0 for positive, other for negative
537   *
538   * @return uint32_t : 0 for DCache not auto preload before manual preload.
539   */
540 uint32_t Cache_Start_DCache_Preload(uint32_t addr, uint32_t size, uint32_t order);
541 
542 /**
543   * @brief Return if the DCache manual preload done.
544   *        Please do not call this function in your SDK application.
545   *
546   * @param  None
547   *
548   * @return uint32_t : 0 for DCache manual preload not done.
549   */
550 uint32_t Cache_DCache_Preload_Done(void);
551 
552 /**
553   * @brief End the DCache manual preload to resume auto preload of DCache.
554   *        Please do not call this function in your SDK application.
555   *
556   * @param uint32_t autoload : 0 for DCache not auto preload before manual preload.
557   *
558   * @return None
559   */
560 void Cache_End_DCache_Preload(uint32_t autoload);
561 
562 /**
563   * @brief Config autoload parameters of ICache.
564   *        Please do not call this function in your SDK application.
565   *
566   * @param struct autoload_config * config : autoload parameters.
567   *
568   * @return None
569   */
570 void Cache_Config_ICache_Autoload(const struct autoload_config * config);
571 
572 /**
573   * @brief Enable auto preload for ICache.
574   *        Please do not call this function in your SDK application.
575   *
576   * @param None
577   *
578   * @return None
579   */
580 void Cache_Enable_ICache_Autoload(void);
581 
582 /**
583   * @brief Disable auto preload for ICache.
584   *        Please do not call this function in your SDK application.
585   *
586   * @param None
587   *
588   * @return None
589   */
590 void Cache_Disable_ICache_Autoload(void);
591 
592 /**
593   * @brief Config autoload parameters of DCache.
594   *        Please do not call this function in your SDK application.
595   *
596   * @param struct autoload_config * config : autoload parameters.
597   *
598   * @return None
599   */
600 void Cache_Config_DCache_Autoload(const struct autoload_config * config);
601 
602 /**
603   * @brief Enable auto preload for DCache.
604   *        Please do not call this function in your SDK application.
605   *
606   * @param None
607   *
608   * @return None
609   */
610 void Cache_Enable_DCache_Autoload(void);
611 
612 /**
613   * @brief Disable auto preload for DCache.
614   *        Please do not call this function in your SDK application.
615   *
616   * @param None
617   *
618   * @return None
619   */
620 void Cache_Disable_DCache_Autoload(void);
621 
622 /**
623   * @brief Config a group of prelock parameters of ICache.
624   *        Please do not call this function in your SDK application.
625   *
626   * @param struct lock_config * config : a group of lock parameters.
627   *
628   * @return None
629   */
630 
631 void Cache_Enable_ICache_PreLock(const struct lock_config *config);
632 
633 /**
634   * @brief Disable a group of prelock parameters for ICache.
635   *        However, the locked data will not be released.
636   *        Please do not call this function in your SDK application.
637   *
638   * @param uint16_t group : 0 for group0, 1 for group1.
639   *
640   * @return None
641   */
642 void Cache_Disable_ICache_PreLock(uint16_t group);
643 
644 /**
645   * @brief Lock the cache items for ICache.
646   *        Operation will be done CACHE_LINE_SIZE aligned.
647   *        If the region is not in ICache addr room, nothing will be done.
648   *        Please do not call this function in your SDK application.
649   *
650   * @param  uint32_t addr: start address to lock
651   *
652   * @param  uint32_t items: cache lines to lock, items * cache_line_size should not exceed the bus address size(4MB)
653   *
654   * @return None
655   */
656 void Cache_Lock_ICache_Items(uint32_t addr, uint32_t items);
657 
658 /**
659   * @brief Unlock the cache items for ICache.
660   *        Operation will be done CACHE_LINE_SIZE aligned.
661   *        If the region is not in ICache addr room, nothing will be done.
662   *        Please do not call this function in your SDK application.
663   *
664   * @param  uint32_t addr: start address to unlock
665   *
666   * @param  uint32_t items: cache lines to unlock, items * cache_line_size should not exceed the bus address size(4MB)
667   *
668   * @return None
669   */
670 void Cache_Unlock_ICache_Items(uint32_t addr, uint32_t items);
671 
672 /**
673   * @brief Config a group of prelock parameters of DCache.
674   *        Please do not call this function in your SDK application.
675   *
676   * @param struct lock_config * config : a group of lock parameters.
677   *
678   * @return None
679   */
680 void Cache_Enable_DCache_PreLock(const struct lock_config *config);
681 
682 /**
683   * @brief Disable a group of prelock parameters for DCache.
684   *        However, the locked data will not be released.
685   *        Please do not call this function in your SDK application.
686   *
687   * @param uint16_t group : 0 for group0, 1 for group1.
688   *
689   * @return None
690   */
691 void Cache_Disable_DCache_PreLock(uint16_t group);
692 
693 /**
694   * @brief Lock the cache items for DCache.
695   *        Operation will be done CACHE_LINE_SIZE aligned.
696   *        If the region is not in DCache addr room, nothing will be done.
697   *        Please do not call this function in your SDK application.
698   *
699   * @param  uint32_t addr: start address to lock
700   *
701   * @param  uint32_t items: cache lines to lock, items * cache_line_size should not exceed the bus address size(4MB)
702   *
703   * @return None
704   */
705 void Cache_Lock_DCache_Items(uint32_t addr, uint32_t items);
706 
707 /**
708   * @brief Unlock the cache items for DCache.
709   *        Operation will be done CACHE_LINE_SIZE aligned.
710   *        If the region is not in DCache addr room, nothing will be done.
711   *        Please do not call this function in your SDK application.
712   *
713   * @param  uint32_t addr: start address to unlock
714   *
715   * @param  uint32_t items: cache lines to unlock, items * cache_line_size should not exceed the bus address size(4MB)
716   *
717   * @return None
718   */
719 void Cache_Unlock_DCache_Items(uint32_t addr, uint32_t items);
720 
721 /**
722   * @brief Lock the cache items in tag memory for ICache or DCache.
723   *        Please do not call this function in your SDK application.
724   *
725   * @param uint32_t addr : start address of lock region.
726   *
727   * @param uint32_t size : size of lock region.
728   *
729   * @return 0 for success
730   *         1 for invalid argument
731   */
732 int Cache_Lock_Addr(uint32_t addr, uint32_t size);
733 
734 /**
735   * @brief Unlock the cache items in tag memory for ICache or DCache.
736   *        Please do not call this function in your SDK application.
737   *
738   * @param uint32_t addr : start address of unlock region.
739   *
740   * @param uint32_t size : size of unlock region.
741   *
742   * @return 0 for success
743   *         1 for invalid argument
744   */
745 int Cache_Unlock_Addr(uint32_t addr, uint32_t size);
746 
747 /**
748   * @brief Disable ICache access for the cpu.
749   *        This operation will make all ICache tag memory invalid, CPU can't access ICache, ICache will keep idle.
750   *        Please do not call this function in your SDK application.
751   *
752   * @return uint32_t : auto preload enabled before
753   */
754 uint32_t Cache_Disable_ICache(void);
755 
756 /**
757   * @brief Enable ICache access for the cpu.
758   *        Please do not call this function in your SDK application.
759   *
760   * @param  uint32_t autoload : ICache will preload then.
761   *
762   * @return None
763   */
764 void Cache_Enable_ICache(uint32_t autoload);
765 
766 /**
767   * @brief Disable DCache access for the cpu.
768   *        This operation will make all DCache tag memory invalid, CPU can't access DCache, DCache will keep idle
769   *        Please do not call this function in your SDK application.
770   *
771   * @return uint32_t : auto preload enabled before
772   */
773 uint32_t Cache_Disable_DCache(void);
774 
775 /**
776   * @brief Enable DCache access for the cpu.
777   *        Please do not call this function in your SDK application.
778   *
779   * @param  uint32_t autoload : DCache will preload then.
780   *
781   * @return None
782   */
783 void Cache_Enable_DCache(uint32_t autoload);
784 
785 /**
786   * @brief Suspend ICache access for the cpu.
787   *        The ICache tag memory is still there, CPU can't access ICache, ICache will keep idle.
788   *        Please do not change MMU, cache mode or tag memory(tag memory can be changed in some special case).
789   *        Please do not call this function in your SDK application.
790   *
791   * @param  None
792   *
793   * @return uint32_t : auto preload enabled before
794   */
795 uint32_t Cache_Suspend_ICache(void);
796 
797 /**
798   * @brief Resume ICache access for the cpu.
799   *        Please do not call this function in your SDK application.
800   *
801   * @param  uint32_t autoload : ICache will preload then.
802   *
803   * @return None
804   */
805 void Cache_Resume_ICache(uint32_t autoload);
806 
807 /**
808   * @brief Suspend DCache access for the cpu.
809   *        The ICache tag memory is still there, CPU can't access DCache, DCache will keep idle.
810   ×        Please do not change MMU, cache mode or tag memory(tag memory can be changed in some special case).
811   *        Please do not call this function in your SDK application.
812   *
813   * @param  None
814   *
815   * @return uint32_t : auto preload enabled before
816   */
817 uint32_t Cache_Suspend_DCache(void);
818 
819 /**
820   * @brief Resume DCache access for the cpu.
821   *        Please do not call this function in your SDK application.
822   *
823   * @param  uint32_t autoload : DCache will preload then.
824   *
825   * @return None
826   */
827 void Cache_Resume_DCache(uint32_t autoload);
828 
829 /**
830   * @brief Get ICache cache line size
831   *
832   * @param  None
833   *
834   * @return uint32_t: 16, 32 Byte
835   */
836 uint32_t Cache_Get_ICache_Line_Size(void);
837 
838 /**
839   * @brief Get DCache cache line size
840   *
841   * @param  None
842   *
843   * @return uint32_t: 16, 32 Byte
844   */
845 uint32_t Cache_Get_DCache_Line_Size(void);
846 
847 /**
848   * @brief Set default mode from boot, 8KB ICache, 16Byte cache line size.
849   *
850   * @param  None
851   *
852   * @return None
853   */
854 void Cache_Set_Default_Mode(void);
855 
856 /**
857   * @brief Set default mode from boot, 8KB DCache, 16Byte cache line size.
858   *
859   * @param None
860   *
861   * @return None
862   */
863 void Cache_Enable_Defalut_DCache_Mode(void);
864 
865 /**
866   * @brief Travel tag memory to run a call back function.
867   *        ICache and DCache are suspend when doing this.
868   *        The callback will get the parameter tag_group_info, which will include a group of tag memory addresses and cache memory addresses.
869   *        Please do not call this function in your SDK application.
870   *
871   * @param  struct cache_mode * mode : the cache to check and the cache mode.
872   *
873   * @param  uint32_t filter_addr : only the cache lines which may include the filter_address will be returned to the call back function.
874   *                                0 for do not filter, all cache lines will be returned.
875   *
876   * @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.
877   *
878   * @return None
879   */
880 void Cache_Travel_Tag_Memory(struct cache_mode * mode, uint32_t filter_addr, void (* process)(struct tag_group_info *));
881 
882 /**
883   * @brief Get the virtual address from cache mode, cache tag and the virtual address offset of cache ways.
884   *        Please do not call this function in your SDK application.
885   *
886   * @param  struct cache_mode * mode : the cache to calculate the virtual address and the cache mode.
887   *
888   * @param  uint32_t tag : the tag part fo a tag item, 12-14 bits.
889   *
890   * @param  uint32_t addr_offset : the virtual address offset of the cache ways.
891   *
892   * @return uint32_t : the virtual address.
893   */
894 uint32_t Cache_Get_Virtual_Addr(struct cache_mode *mode, uint32_t tag, uint32_t vaddr_offset);
895 
896 /**
897   * @brief Get cache memory block base address.
898   *        Please do not call this function in your SDK application.
899   *
900   * @param  uint32_t icache : 0 for dcache, other for icache.
901   *
902   * @param  uint32_t high : 0 for low part block, 1 for high part block.
903   *
904   * @return uint32_t : the cache memory block base address, 0 if the block not used.
905   */
906 uint32_t Cache_Get_Memory_BaseAddr(uint32_t icache, uint32_t high);
907 
908 /**
909   * @brief Get the cache memory address from cache mode, cache memory offset and the virtual address offset of cache ways.
910   *        Please do not call this function in your SDK application.
911   *
912   * @param  struct cache_mode * mode : the cache to calculate the virtual address and the cache mode.
913   *
914   * @param  uint32_t cache_memory_offset : the cache memory offset of the whole cache (ICache or DCache) for the cache line.
915   *
916   * @param  uint32_t addr_offset : the virtual address offset of the cache ways.
917   *
918   * @return uint32_t : the virtual address.
919   */
920 uint32_t Cache_Get_Memory_Addr(struct cache_mode *mode, uint32_t cache_memory_offset, uint32_t vaddr_offset);
921 
922 /**
923   * @brief Get the cache memory value by DRAM address.
924   *        Please do not call this function in your SDK application.
925   *
926   * @param  uint32_t cache_memory_addr : DRAM address for the cache memory.
927   *
928   * @return uint32_t : the word value of the address.
929   */
930 uint32_t Cache_Get_Memory_value(uint32_t cache_memory_addr);
931 /**
932   * @}
933   */
934 
935 #ifdef __cplusplus
936 }
937 #endif
938 
939 #endif /* _ROM_CACHE_H_ */
940