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
