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

.smp_stamp

@@ -0,0 +1 @@
+1

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "files.associations": {
+        "unistd.h": "c",
+        "stdbool.h": "c"
+    }
+}

main.c

@@ -342,9 +342,9 @@ static inline sbi_ret_t handle_sbi_ecall_TIMER(hart_t *hart, int32_t fid)
             (((uint64_t) hart->x_regs[RV_R_A1]) << 32) |
             (uint64_t) (hart->x_regs[RV_R_A0]);
         hart->sip &= ~RV_INT_STI_BIT;
-        return (sbi_ret_t){SBI_SUCCESS, 0};
+        return (sbi_ret_t) {SBI_SUCCESS, 0};
     default:
-        return (sbi_ret_t){SBI_ERR_NOT_SUPPORTED, 0};
+        return (sbi_ret_t) {SBI_ERR_NOT_SUPPORTED, 0};
     }
 }
 
@@ -356,9 +356,9 @@ static inline sbi_ret_t handle_sbi_ecall_RST(hart_t *hart, int32_t fid)
         fprintf(stderr, "system reset: type=%u, reason=%u\n",
                 hart->x_regs[RV_R_A0], hart->x_regs[RV_R_A1]);
         data->stopped = true;
-        return (sbi_ret_t){SBI_SUCCESS, 0};
+        return (sbi_ret_t) {SBI_SUCCESS, 0};
     default:
-        return (sbi_ret_t){SBI_ERR_NOT_SUPPORTED, 0};
+        return (sbi_ret_t) {SBI_ERR_NOT_SUPPORTED, 0};
     }
 }
 
@@ -378,13 +378,13 @@ static inline sbi_ret_t handle_sbi_ecall_HSM(hart_t *hart, int32_t fid)
         vm->hart[hartid]->x_regs[RV_R_A1] = opaque;
         vm->hart[hartid]->pc = start_addr;
         vm->hart[hartid]->s_mode = true;
-        return (sbi_ret_t){SBI_SUCCESS, 0};
+        return (sbi_ret_t) {SBI_SUCCESS, 0};
     case SBI_HSM__HART_STOP:
         hart->hsm_status = SBI_HSM_STATE_STOPPED;
-        return (sbi_ret_t){SBI_SUCCESS, 0};
+        return (sbi_ret_t) {SBI_SUCCESS, 0};
     case SBI_HSM__HART_GET_STATUS:
         hartid = hart->x_regs[RV_R_A0];
-        return (sbi_ret_t){SBI_SUCCESS, vm->hart[hartid]->hsm_status};
+        return (sbi_ret_t) {SBI_SUCCESS, vm->hart[hartid]->hsm_status};
     case SBI_HSM__HART_SUSPEND:
         suspend_type = hart->x_regs[RV_R_A0];
         resume_addr = hart->x_regs[RV_R_A1];
@@ -398,11 +398,11 @@ static inline sbi_ret_t handle_sbi_ecall_HSM(hart_t *hart, int32_t fid)
             hart->hsm_resume_pc = resume_addr;
             hart->hsm_resume_opaque = opaque;
         }
-        return (sbi_ret_t){SBI_SUCCESS, 0};
+        return (sbi_ret_t) {SBI_SUCCESS, 0};
     default:
-        return (sbi_ret_t){SBI_ERR_NOT_SUPPORTED, 0};
+        return (sbi_ret_t) {SBI_ERR_NOT_SUPPORTED, 0};
     }
-    return (sbi_ret_t){SBI_ERR_FAILED, 0};
+    return (sbi_ret_t) {SBI_ERR_FAILED, 0};
 }
 
 static inline sbi_ret_t handle_sbi_ecall_IPI(hart_t *hart, int32_t fid)
@@ -421,10 +421,10 @@ static inline sbi_ret_t handle_sbi_ecall_IPI(hart_t *hart, int32_t fid)
                 data->sswi.ssip[i] = hart_mask & 1;
         }
 
-        return (sbi_ret_t){SBI_SUCCESS, 0};
+        return (sbi_ret_t) {SBI_SUCCESS, 0};
         break;
     default:
-        return (sbi_ret_t){SBI_ERR_FAILED, 0};
+        return (sbi_ret_t) {SBI_ERR_FAILED, 0};
     }
 }
 
@@ -439,7 +439,7 @@ static inline sbi_ret_t handle_sbi_ecall_RFENCE(hart_t *hart, int32_t fid)
     uint64_t hart_mask, hart_mask_base;
     switch (fid) {
     case 0:
-        return (sbi_ret_t){SBI_SUCCESS, 0};
+        return (sbi_ret_t) {SBI_SUCCESS, 0};
     case 1:
         hart_mask = (uint64_t) hart->x_regs[RV_R_A0];
         hart_mask_base = (uint64_t) hart->x_regs[RV_R_A1];
@@ -452,16 +452,16 @@ static inline sbi_ret_t handle_sbi_ecall_RFENCE(hart_t *hart, int32_t fid)
                 mmu_invalidate(hart->vm->hart[i]);
             }
         }
-        return (sbi_ret_t){SBI_SUCCESS, 0};
+        return (sbi_ret_t) {SBI_SUCCESS, 0};
     case 2:
     case 3:
     case 4:
     case 5:
     case 6:
     case 7:
-        return (sbi_ret_t){SBI_SUCCESS, 0};
+        return (sbi_ret_t) {SBI_SUCCESS, 0};
     default:
-        return (sbi_ret_t){SBI_ERR_FAILED, 0};
+        return (sbi_ret_t) {SBI_ERR_FAILED, 0};
     }
 }
 
@@ -473,26 +473,26 @@ static inline sbi_ret_t handle_sbi_ecall_BASE(hart_t *hart, int32_t fid)
 {
     switch (fid) {
     case SBI_BASE__GET_SBI_IMPL_ID:
-        return (sbi_ret_t){SBI_SUCCESS, SBI_IMPL_ID};
+        return (sbi_ret_t) {SBI_SUCCESS, SBI_IMPL_ID};
     case SBI_BASE__GET_SBI_IMPL_VERSION:
-        return (sbi_ret_t){SBI_SUCCESS, SBI_IMPL_VERSION};
+        return (sbi_ret_t) {SBI_SUCCESS, SBI_IMPL_VERSION};
     case SBI_BASE__GET_MVENDORID:
-        return (sbi_ret_t){SBI_SUCCESS, RV_MVENDORID};
+        return (sbi_ret_t) {SBI_SUCCESS, RV_MVENDORID};
     case SBI_BASE__GET_MARCHID:
-        return (sbi_ret_t){SBI_SUCCESS, RV_MARCHID};
+        return (sbi_ret_t) {SBI_SUCCESS, RV_MARCHID};
     case SBI_BASE__GET_MIMPID:
-        return (sbi_ret_t){SBI_SUCCESS, RV_MIMPID};
+        return (sbi_ret_t) {SBI_SUCCESS, RV_MIMPID};
     case SBI_BASE__GET_SBI_SPEC_VERSION:
-        return (sbi_ret_t){SBI_SUCCESS, (2 << 24) | 0}; /* version 2.0 */
+        return (sbi_ret_t) {SBI_SUCCESS, (2 << 24) | 0}; /* version 2.0 */
     case SBI_BASE__PROBE_EXTENSION: {
         int32_t eid = (int32_t) hart->x_regs[RV_R_A0];
         bool available = eid == SBI_EID_BASE || eid == SBI_EID_TIMER ||
                          eid == SBI_EID_RST || eid == SBI_EID_HSM ||
                          eid == SBI_EID_IPI || eid == SBI_EID_RFENCE;
-        return (sbi_ret_t){SBI_SUCCESS, available};
+        return (sbi_ret_t) {SBI_SUCCESS, available};
     }
     default:
-        return (sbi_ret_t){SBI_ERR_NOT_SUPPORTED, 0};
+        return (sbi_ret_t) {SBI_ERR_NOT_SUPPORTED, 0};
     }
 }
 
@@ -522,7 +522,7 @@ static void handle_sbi_ecall(hart_t *hart)
         SBI_HANDLE(RFENCE);
         break;
     default:
-        ret = (sbi_ret_t){SBI_ERR_NOT_SUPPORTED, 0};
+        ret = (sbi_ret_t) {SBI_ERR_NOT_SUPPORTED, 0};
     }
     hart->x_regs[RV_R_A0] = (uint32_t) ret.error;
     hart->x_regs[RV_R_A1] = (uint32_t) ret.value;
@@ -1037,8 +1037,8 @@ static int semu_run(emu_state_t *emu)
 #else
                 /* Linux: poll on timerfd and UART */
                 struct pollfd pfds[2];
-                pfds[0] = (struct pollfd){wfi_timer_fd, POLLIN, 0};
-                pfds[1] = (struct pollfd){emu->uart.in_fd, POLLIN, 0};
+                pfds[0] = (struct pollfd) {wfi_timer_fd, POLLIN, 0};
+                pfds[1] = (struct pollfd) {emu->uart.in_fd, POLLIN, 0};
                 poll(pfds, 2, -1);
 
                 /* Consume timerfd event to prevent accumulation */
@@ -1220,7 +1220,7 @@ static int semu_run_debug(emu_state_t *emu)
 
     emu->curr_cpuid = 0;
     if (!gdbstub_init(&gdbstub, &gdbstub_ops,
-                      (arch_info_t){
+                      (arch_info_t) {
                           .smp = vm->n_hart,
                           .reg_num = 33,
                           .target_desc = TARGET_RV32,

riscv.c

@@ -309,9 +309,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
@@ -346,7 +346,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

@@ -69,10 +69,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)
@@ -81,14 +96,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 */