Refactor and document I-cache, fix tag calculation

- Rename I-cache structures from ic to icache to avoid ambiguity.
- Add explanations for instruction-cache definitions and masks, and align
  the macro names with the terminology used in the comments.
- Fix tag calculation to use the precomputed tag rather than shifting the
  physical address.

Author: yy214123

riscv.c

@@ -318,9 +318,9 @@ static void mmu_fence(hart_t *vm, uint32_t insn UNUSED)
 static void mmu_fetch(hart_t *vm, uint32_t addr, uint32_t *value)
 {
     /* cache hit */
-    uint32_t idx = (addr >> IC_SHIFT) & IC_INDEX_MASK;
-    uint32_t tag = addr >> (IC_SHIFT + IC_INDEX_BITS);
-    ic_block_t *blk = &vm->ic.block[idx];
+    uint32_t idx = (addr >> IC_OFFSET_BITS) & IC_INDEX_MASK;
+    uint32_t tag = addr >> (IC_OFFSET_BITS + IC_INDEX_BITS);
+    icache_block_t *blk = &vm->ic.block[idx];
 
     if (likely(blk->valid && blk->tag == tag)) {
 #ifdef MMU_CACHE_STATS
@@ -355,7 +355,7 @@ static void mmu_fetch(hart_t *vm, uint32_t addr, uint32_t *value)
     /* fill into the cache */
     uint32_t block_off = (addr & RV_PAGE_MASK) & ~IC_BLOCK_MASK;
     blk->base = (const uint8_t *) vm->cache_fetch.page_addr + block_off;
-    blk->tag = addr >> (IC_SHIFT + IC_INDEX_BITS);
+    blk->tag = tag;
     blk->valid = true;
 }
 

riscv.h

@@ -75,10 +75,25 @@ typedef struct {
 typedef struct __hart_internal hart_t;
 typedef struct __vm_internel vm_t;
 
+/* IC_BLOCKS_SIZE: Size of one instruction-cache block (line).
+ * IC_BLOCKS: Number of blocks (lines) in the instruction cache.
+ *
+ * The cache address is decomposed into [ tag | index | offset ] fields:
+ *   - block-offset bits = log2(IC_BLOCKS_SIZE)
+ *   - index bits        = log2(IC_BLOCKS)
+ *
+ * For power-of-two values, log2(x) equals the number of trailing zero bits in
+ * x. Therefore, we use __builtin_ctz(x) (count trailing zeros) to compute these
+ * log2 values at compile time.
+ */
 #define IC_BLOCKS_SIZE 256
 #define IC_BLOCKS 256
-#define IC_SHIFT (__builtin_ctz((IC_BLOCKS_SIZE)))
+#define IC_OFFSET_BITS (__builtin_ctz((IC_BLOCKS_SIZE)))
 #define IC_INDEX_BITS (__builtin_ctz((IC_BLOCKS)))
+
+/* For power-of-two sizes, (size - 1) sets all low bits to 1,
+ * allowing fast extraction of an address.
+ */
 #define IC_INDEX_MASK (IC_BLOCKS - 1)
 #define IC_BLOCK_MASK (IC_BLOCKS_SIZE - 1)
 #define RV_PAGE_MASK (RV_PAGE_SIZE - 1)
@@ -87,14 +102,14 @@ typedef struct {
     uint32_t tag;
     const uint8_t *base;
     bool valid;
-} ic_block_t;
+} icache_block_t;
 
 typedef struct {
-    ic_block_t block[IC_BLOCKS];
-} ic_t;
+    icache_block_t block[IC_BLOCKS];
+} icache_t;
 
 struct __hart_internal {
-    ic_t ic;
+    icache_t ic;
     uint32_t x_regs[32];
 
     /* LR reservation virtual address. last bit is 1 if valid */