1 /* 2 * SPDX-FileCopyrightText: 2022-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 #include "esp_bit_defs.h" 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /** \defgroup cache_apis, cache operation related apis 17 * @brief cache apis 18 */ 19 20 /** @addtogroup cache_apis 21 * @{ 22 */ 23 #define MIN_ICACHE_SIZE 16384 24 #define MAX_ICACHE_SIZE 16384 25 #define MIN_ICACHE_WAYS 8 26 #define MAX_ICACHE_WAYS 8 27 #define MAX_CACHE_WAYS 8 28 #define MIN_CACHE_LINE_SIZE 32 29 #define TAG_SIZE 4 30 #define MIN_ICACHE_BANK_NUM 1 31 #define MAX_ICACHE_BANK_NUM 1 32 #define CACHE_MEMORY_BANK_NUM 1 33 #define CACHE_MEMORY_IBANK_SIZE 0x4000 34 35 #define MAX_ITAG_BANK_ITEMS (MAX_ICACHE_SIZE / MAX_ICACHE_BANK_NUM / MIN_CACHE_LINE_SIZE) 36 #define MAX_ITAG_BLOCK_ITEMS (MAX_ICACHE_SIZE / MAX_ICACHE_BANK_NUM / MAX_ICACHE_WAYS / MIN_CACHE_LINE_SIZE) 37 #define MAX_ITAG_BANK_SIZE (MAX_ITAG_BANK_ITEMS * TAG_SIZE) 38 #define MAX_ITAG_BLOCK_SIZE (MAX_ITAG_BLOCK_ITEMS * TAG_SIZE) 39 40 typedef enum { 41 CACHE_SIZE_HALF = 0, /*!< 8KB for icache and dcache */ 42 CACHE_SIZE_FULL = 1, /*!< 16KB for icache and dcache */ 43 } cache_size_t; 44 45 typedef enum { 46 CACHE_4WAYS_ASSOC = 0, /*!< 4 way associated cache */ 47 CACHE_8WAYS_ASSOC = 1, /*!< 8 way associated cache */ 48 } cache_ways_t; 49 50 typedef enum { 51 CACHE_LINE_SIZE_16B = 0, /*!< 16 Byte cache line size */ 52 CACHE_LINE_SIZE_32B = 1, /*!< 32 Byte cache line size */ 53 CACHE_LINE_SIZE_64B = 2, /*!< 64 Byte cache line size */ 54 } cache_line_size_t; 55 56 typedef enum { 57 CACHE_AUTOLOAD_POSITIVE = 0, /*!< cache autoload step is positive */ 58 CACHE_AUTOLOAD_NEGATIVE = 1, /*!< cache autoload step is negative */ 59 } cache_autoload_order_t; 60 61 #define CACHE_AUTOLOAD_STEP(i) ((i) - 1) 62 63 typedef enum { 64 CACHE_AUTOLOAD_MISS_TRIGGER = 0, /*!< autoload only triggered by cache miss */ 65 CACHE_AUTOLOAD_HIT_TRIGGER = 1, /*!< autoload only triggered by cache hit */ 66 CACHE_AUTOLOAD_BOTH_TRIGGER = 2, /*!< autoload triggered both by cache miss and hit */ 67 } cache_autoload_trigger_t; 68 69 typedef enum { 70 CACHE_FREEZE_ACK_BUSY = 0, /*!< in this mode, cache ack busy to CPU if a cache miss happens*/ 71 CACHE_FREEZE_ACK_ERROR = 1, /*!< in this mode, cache ack wrong data to CPU and trigger an error if a cache miss happens */ 72 } cache_freeze_mode_t; 73 74 typedef enum { 75 MMU_PAGE_MODE_64KB = 0, 76 MMU_PAGE_MODE_32KB = 1, 77 MMU_PAGE_MODE_16KB = 2, 78 MMU_PAGE_MODE_8KB = 3, 79 MMU_PAGE_MODE_INVALID, 80 } mmu_page_mode_t; 81 82 struct cache_mode { 83 uint32_t cache_size; /*!< cache size in byte */ 84 uint16_t cache_line_size; /*!< cache line size in byte */ 85 uint8_t cache_ways; /*!< cache ways, always 4 */ 86 uint8_t ibus; /*!< the cache index, 0 for dcache, 1 for icache */ 87 }; 88 89 struct icache_tag_item { 90 uint32_t valid:1; /*!< the tag item is valid or not */ 91 uint32_t lock:1; /*!< the cache line is locked or not */ 92 uint32_t fifo_cnt:3; /*!< fifo cnt, 0 ~ 3 for 4 ways cache */ 93 uint32_t tag:13; /*!< the tag is the high part of the cache address, however is only 16MB (8MB Ibus + 8MB Dbus) range, and without low part */ 94 uint32_t reserved:14; 95 }; 96 97 struct autoload_config { 98 uint8_t order; /*!< autoload step is positive or negative */ 99 uint8_t trigger; /*!< autoload trigger */ 100 uint8_t ena0; /*!< autoload region0 enable */ 101 uint8_t ena1; /*!< autoload region1 enable */ 102 uint32_t addr0; /*!< autoload region0 start address */ 103 uint32_t size0; /*!< autoload region0 size */ 104 uint32_t addr1; /*!< autoload region1 start address */ 105 uint32_t size1; /*!< autoload region1 size */ 106 }; 107 108 struct tag_group_info { 109 struct cache_mode mode; /*!< cache and cache mode */ 110 uint32_t filter_addr; /*!< the address that used to generate the struct */ 111 uint32_t vaddr_offset; /*!< virtual address offset of the cache ways */ 112 uint32_t tag_addr[MAX_CACHE_WAYS]; /*!< tag memory address, only [0~mode.ways-1] is valid to use */ 113 uint32_t cache_memory_offset[MAX_CACHE_WAYS]; /*!< cache memory address, only [0~mode.ways-1] is valid to use */ 114 }; 115 116 struct lock_config { 117 uint32_t addr; /*!< manual lock address*/ 118 uint16_t size; /*!< manual lock size*/ 119 uint16_t group; /*!< manual lock group, 0 or 1*/ 120 }; 121 122 struct cache_internal_stub_table { 123 uint32_t (* icache_line_size)(void); 124 uint32_t (* icache_addr)(uint32_t addr); 125 uint32_t (* dcache_addr)(uint32_t addr); 126 void (* invalidate_icache_items)(uint32_t addr, uint32_t items); 127 void (* lock_icache_items)(uint32_t addr, uint32_t items); 128 void (* unlock_icache_items)(uint32_t addr, uint32_t items); 129 uint32_t (* suspend_icache_autoload)(void); 130 void (* resume_icache_autoload)(uint32_t autoload); 131 void (* freeze_icache_enable)(cache_freeze_mode_t mode); 132 void (* freeze_icache_disable)(void); 133 int (* op_addr)(uint32_t start_addr, uint32_t size, uint32_t cache_line_size, uint32_t max_sync_num, void(* cache_Iop)(uint32_t, uint32_t)); 134 }; 135 136 /* Defined in the interface file, default value is rom_default_cache_internal_table */ 137 extern const struct cache_internal_stub_table* rom_cache_internal_table_ptr; 138 139 typedef void (* cache_op_start)(void); 140 typedef void (* cache_op_end)(void); 141 142 typedef struct { 143 cache_op_start start; 144 cache_op_end end; 145 } cache_op_cb_t; 146 147 /* Defined in the interface file, default value is NULL */ 148 extern const cache_op_cb_t* rom_cache_op_cb; 149 150 #define ESP_ROM_ERR_INVALID_ARG 1 151 #define MMU_SET_ADDR_ALIGNED_ERROR 2 152 #define MMU_SET_PASE_SIZE_ERROR 3 153 #define MMU_SET_VADDR_OUT_RANGE 4 154 155 #define CACHE_OP_ICACHE_Y 1 156 #define CACHE_OP_ICACHE_N 0 157 158 /** 159 * @brief Initialise cache mmu, mark all entries as invalid. 160 * Please do not call this function in your SDK application. 161 * 162 * @param None 163 * 164 * @return None 165 */ 166 void Cache_MMU_Init(void); 167 168 /** 169 * @brief Init Cache for ROM boot, including resetting the Icache, initializing MMU, Enabling ICache, unmasking bus. 170 * 171 * @param None 172 * 173 * @return None 174 */ 175 void ROM_Boot_Cache_Init(void); 176 177 /** 178 * @brief Set ICache mmu mapping. 179 * Please do not call this function in your SDK application. 180 * 181 * @param uint32_t senitive : Config this page should apply flash encryption or not 182 * 183 * @param uint32_t ext_ram : DPORT_MMU_ACCESS_FLASH for flash, DPORT_MMU_INVALID for invalid. In 184 * esp32c6, external memory is always flash 185 * 186 * @param uint32_t vaddr : virtual address in CPU address space. 187 * Can be Iram0,Iram1,Irom0,Drom0 and AHB buses address. 188 * Should be aligned by psize. 189 * 190 * @param uint32_t paddr : physical address in external memory. 191 * Should be aligned by psize. 192 * 193 * @param uint32_t psize : page size of ICache, in kilobytes. Should be 64 here. 194 * 195 * @param uint32_t num : pages to be set. 196 * 197 * @param uint32_t fixed : 0 for physical pages grow with virtual pages, other for virtual pages map to same physical page. 198 * 199 * @return uint32_t: error status 200 * 0 : mmu set success 201 * 2 : vaddr or paddr is not aligned 202 * 3 : psize error 203 * 4 : vaddr is out of range 204 */ 205 int Cache_MSPI_MMU_Set(uint32_t sensitive, uint32_t ext_ram, uint32_t vaddr, uint32_t paddr, uint32_t psize, uint32_t num, uint32_t fixed); 206 207 /** 208 * @brief Set DCache mmu mapping. 209 * Please do not call this function in your SDK application. 210 * 211 * @param uint32_t ext_ram : DPORT_MMU_ACCESS_FLASH for flash, DPORT_MMU_INVALID for invalid. In 212 * esp32c6, external memory is always flash 213 * 214 * @param uint32_t vaddr : virtual address in CPU address space. 215 * Can be DRam0, DRam1, DRom0, DPort and AHB buses address. 216 * Should be aligned by psize. 217 * 218 * @param uint32_t paddr : physical address in external memory. 219 * Should be aligned by psize. 220 * 221 * @param uint32_t psize : page size of DCache, in kilobytes. Should be 64 here. 222 * 223 * @param uint32_t num : pages to be set. 224 225 * @param uint32_t fixed : 0 for physical pages grow with virtual pages, other for virtual pages map to same physical page. 226 * 227 * @return uint32_t: error status 228 * 0 : mmu set success 229 * 2 : vaddr or paddr is not aligned 230 * 3 : psize error 231 * 4 : vaddr is out of range 232 */ 233 int Cache_Dbus_MMU_Set(uint32_t ext_ram, uint32_t vaddr, uint32_t paddr, uint32_t psize, uint32_t num, uint32_t fixed); 234 235 236 /** 237 * @brief Get cache mode of ICache or DCache. 238 * Please do not call this function in your SDK application. 239 * 240 * @param struct cache_mode * mode : the pointer of cache mode struct, caller should set the icache field 241 * 242 * return none 243 */ 244 void Cache_Get_Mode(struct cache_mode * mode); 245 246 /** 247 * @brief Set cache page mode. 248 * 249 * @param mmu_page_mode_t 250 * 251 * @return None 252 */ 253 void MMU_Set_Page_Mode(mmu_page_mode_t pg_mode); 254 255 /** 256 * @brief Get cache page mode. 257 * 258 * @param None 259 * 260 * @return page mode 261 */ 262 mmu_page_mode_t MMU_Get_Page_Mode(void); 263 264 /** 265 * @brief Invalidate the cache items for ICache. 266 * Operation will be done CACHE_LINE_SIZE aligned. 267 * If the region is not in ICache addr room, nothing will be done. 268 * Please do not call this function in your SDK application. 269 * 270 * @param uint32_t addr: start address to invalidate 271 * 272 * @param uint32_t items: cache lines to invalidate, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB) 273 * 274 * @return None 275 */ 276 void Cache_Invalidate_ICache_Items(uint32_t addr, uint32_t items); 277 278 /** 279 * @brief Invalidate the Cache items in the region from ICache or DCache. 280 * If the region is not in Cache addr room, nothing will be done. 281 * Please do not call this function in your SDK application. 282 * 283 * @param uint32_t addr : invalidated region start address. 284 * 285 * @param uint32_t size : invalidated region size. 286 * 287 * @return 0 for success 288 * 1 for invalid argument 289 */ 290 int Cache_Invalidate_Addr(uint32_t addr, uint32_t size); 291 292 /** 293 * @brief Invalidate all cache items in ICache. 294 * Please do not call this function in your SDK application. 295 * 296 * @param None 297 * 298 * @return None 299 */ 300 void Cache_Invalidate_ICache_All(void); 301 302 /** 303 * @brief Mask all buses through ICache and DCache. 304 * Please do not call this function in your SDK application. 305 * 306 * @param None 307 * 308 * @return None 309 */ 310 void Cache_Mask_All(void); 311 312 /** 313 * @brief Suspend ICache auto preload operation, then you can resume it after some ICache operations. 314 * Please do not call this function in your SDK application. 315 * 316 * @param None 317 * 318 * @return uint32_t : 0 for ICache not auto preload before suspend. 319 */ 320 uint32_t Cache_Suspend_ICache_Autoload(void); 321 322 /** 323 * @brief Resume ICache auto preload operation after some ICache operations. 324 * Please do not call this function in your SDK application. 325 * 326 * @param uint32_t autoload : 0 for ICache not auto preload before suspend. 327 * 328 * @return None. 329 */ 330 void Cache_Resume_ICache_Autoload(uint32_t autoload); 331 332 /** 333 * @brief Start an ICache manual preload, will suspend auto preload of ICache. 334 * Please do not call this function in your SDK application. 335 * 336 * @param uint32_t addr : start address of the preload region. 337 * 338 * @param uint32_t size : size of the preload region, should not exceed the size of ICache. 339 * 340 * @param uint32_t order : the preload order, 0 for positive, other for negative 341 * 342 * @return uint32_t : 0 for ICache not auto preload before manual preload. 343 */ 344 uint32_t Cache_Start_ICache_Preload(uint32_t addr, uint32_t size, uint32_t order); 345 346 /** 347 * @brief Return if the ICache manual preload done. 348 * Please do not call this function in your SDK application. 349 * 350 * @param None 351 * 352 * @return uint32_t : 0 for ICache manual preload not done. 353 */ 354 uint32_t Cache_ICache_Preload_Done(void); 355 356 /** 357 * @brief End the ICache manual preload to resume auto preload of ICache. 358 * Please do not call this function in your SDK application. 359 * 360 * @param uint32_t autoload : 0 for ICache not auto preload before manual preload. 361 * 362 * @return None 363 */ 364 void Cache_End_ICache_Preload(uint32_t autoload); 365 366 /** 367 * @brief Config autoload parameters of ICache. 368 * Please do not call this function in your SDK application. 369 * 370 * @param struct autoload_config * config : autoload parameters. 371 * 372 * @return None 373 */ 374 void Cache_Config_ICache_Autoload(const struct autoload_config * config); 375 376 /** 377 * @brief Enable auto preload for ICache. 378 * Please do not call this function in your SDK application. 379 * 380 * @param None 381 * 382 * @return None 383 */ 384 void Cache_Enable_ICache_Autoload(void); 385 386 /** 387 * @brief Disable auto preload for ICache. 388 * Please do not call this function in your SDK application. 389 * 390 * @param None 391 * 392 * @return None 393 */ 394 void Cache_Disable_ICache_Autoload(void); 395 396 /** 397 * @brief Config a group of prelock parameters of ICache. 398 * Please do not call this function in your SDK application. 399 * 400 * @param struct lock_config * config : a group of lock parameters. 401 * 402 * @return None 403 */ 404 405 void Cache_Enable_ICache_PreLock(const struct lock_config *config); 406 407 /** 408 * @brief Disable a group of prelock parameters for ICache. 409 * However, the locked data will not be released. 410 * Please do not call this function in your SDK application. 411 * 412 * @param uint16_t group : 0 for group0, 1 for group1. 413 * 414 * @return None 415 */ 416 void Cache_Disable_ICache_PreLock(uint16_t group); 417 418 /** 419 * @brief Lock the cache items for ICache. 420 * Operation will be done CACHE_LINE_SIZE aligned. 421 * If the region is not in ICache addr room, nothing will be done. 422 * Please do not call this function in your SDK application. 423 * 424 * @param uint32_t addr: start address to lock 425 * 426 * @param uint32_t items: cache lines to lock, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB) 427 * 428 * @return None 429 */ 430 void Cache_Lock_ICache_Items(uint32_t addr, uint32_t items); 431 432 /** 433 * @brief Unlock the cache items for ICache. 434 * Operation will be done CACHE_LINE_SIZE aligned. 435 * If the region is not in ICache addr room, nothing will be done. 436 * Please do not call this function in your SDK application. 437 * 438 * @param uint32_t addr: start address to unlock 439 * 440 * @param uint32_t items: cache lines to unlock, items * cache_line_size should not exceed the bus address size(16MB/32MB/64MB) 441 * 442 * @return None 443 */ 444 void Cache_Unlock_ICache_Items(uint32_t addr, uint32_t items); 445 446 /** 447 * @brief Lock the cache items in tag memory for ICache or DCache. 448 * Please do not call this function in your SDK application. 449 * 450 * @param uint32_t addr : start address of lock region. 451 * 452 * @param uint32_t size : size of lock region. 453 * 454 * @return 0 for success 455 * 1 for invalid argument 456 */ 457 int Cache_Lock_Addr(uint32_t addr, uint32_t size); 458 459 /** 460 * @brief Unlock the cache items in tag memory for ICache or DCache. 461 * Please do not call this function in your SDK application. 462 * 463 * @param uint32_t addr : start address of unlock region. 464 * 465 * @param uint32_t size : size of unlock region. 466 * 467 * @return 0 for success 468 * 1 for invalid argument 469 */ 470 int Cache_Unlock_Addr(uint32_t addr, uint32_t size); 471 472 /** 473 * @brief Disable ICache access for the cpu. 474 * This operation will make all ICache tag memory invalid, CPU can't access ICache, ICache will keep idle. 475 * Please do not call this function in your SDK application. 476 * 477 * @return uint32_t : auto preload enabled before 478 */ 479 uint32_t Cache_Disable_ICache(void); 480 481 /** 482 * @brief Enable ICache access for the cpu. 483 * Please do not call this function in your SDK application. 484 * 485 * @param uint32_t autoload : ICache will preload then. 486 * 487 * @return None 488 */ 489 void Cache_Enable_ICache(uint32_t autoload); 490 491 /** 492 * @brief Suspend ICache access for the cpu. 493 * The ICache tag memory is still there, CPU can't access ICache, ICache will keep idle. 494 * Please do not change MMU, cache mode or tag memory(tag memory can be changed in some special case). 495 * Please do not call this function in your SDK application. 496 * 497 * @param None 498 * 499 * @return uint32_t : auto preload enabled before 500 */ 501 uint32_t Cache_Suspend_ICache(void); 502 503 /** 504 * @brief Resume ICache access for the cpu. 505 * Please do not call this function in your SDK application. 506 * 507 * @param uint32_t autoload : ICache will preload then. 508 * 509 * @return None 510 */ 511 void Cache_Resume_ICache(uint32_t autoload); 512 513 /** 514 * @brief Get ICache cache line size 515 * 516 * @param None 517 * 518 * @return uint32_t: 16, 32, 64 Byte 519 */ 520 uint32_t Cache_Get_ICache_Line_Size(void); 521 522 /** 523 * @brief Enable freeze for ICache. 524 * Any miss request will be rejected, including cpu miss and preload/autoload miss. 525 * Please do not call this function in your SDK application. 526 * 527 * @param cache_freeze_mode_t mode : 0 for assert busy 1 for assert hit 528 * 529 * @return None 530 */ 531 void Cache_Freeze_ICache_Enable(cache_freeze_mode_t mode); 532 533 /** 534 * @brief Disable freeze for ICache. 535 * Please do not call this function in your SDK application. 536 * 537 * @return None 538 */ 539 void Cache_Freeze_ICache_Disable(void); 540 541 /** 542 * @brief Travel tag memory to run a call back function. 543 * ICache and DCache are suspend when doing this. 544 * The callback will get the parameter tag_group_info, which will include a group of tag memory addresses and cache memory addresses. 545 * Please do not call this function in your SDK application. 546 * 547 * @param struct cache_mode * mode : the cache to check and the cache mode. 548 * 549 * @param uint32_t filter_addr : only the cache lines which may include the filter_address will be returned to the call back function. 550 * 0 for do not filter, all cache lines will be returned. 551 * 552 * @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. 553 * 554 * @return None 555 */ 556 void Cache_Travel_Tag_Memory(struct cache_mode * mode, uint32_t filter_addr, void (* process)(struct tag_group_info *)); 557 558 /** 559 * @brief Get the virtual address from cache mode, cache tag and the virtual address offset of cache ways. 560 * Please do not call this function in your SDK application. 561 * 562 * @param struct cache_mode * mode : the cache to calculate the virtual address and the cache mode. 563 * 564 * @param uint32_t tag : the tag part fo a tag item, 12-14 bits. 565 * 566 * @param uint32_t addr_offset : the virtual address offset of the cache ways. 567 * 568 * @return uint32_t : the virtual address. 569 */ 570 uint32_t Cache_Get_Virtual_Addr(struct cache_mode *mode, uint32_t tag, uint32_t vaddr_offset); 571 572 /** 573 * @} 574 */ 575 576 /** 577 * @brief Get the cache MMU IROM end address. 578 * Please do not call this function in your SDK application. 579 * 580 * @param void 581 * 582 * @return uint32_t : the word value of the address. 583 */ 584 uint32_t Cache_Get_IROM_MMU_End(void); 585 586 /** 587 * @brief Get the cache MMU DROM end address. 588 * Please do not call this function in your SDK application. 589 * 590 * @param void 591 * 592 * @return uint32_t : the word value of the address. 593 */ 594 uint32_t Cache_Get_DROM_MMU_End(void); 595 596 /** 597 * @brief Configure cache MMU page size according to instruction and rodata size 598 * 599 * @param irom_size The instruction cache MMU page size 600 * @param drom_size The rodata data cache MMU page size 601 */ 602 void Cache_Set_IDROM_MMU_Size(uint32_t irom_size, uint32_t drom_size); 603 604 #define Cache_Dbus_MMU_Set(ext_ram, vaddr, paddr, psize, num, fixed) \ 605 Cache_MSPI_MMU_Set(ets_efuse_cache_encryption_enabled() ? MMU_SENSITIVE : 0, ext_ram, vaddr, paddr, psize, num, fixed) 606 607 #ifdef __cplusplus 608 } 609 #endif 610
