initial commit: project architecture

4 files changed, 673 insertions, 0 deletions

diff --git a/rv64cpu/docs/architecture.md b/rv64cpu/docs/architecture.md
new file mode 100644
index 0000000..9df23d4
--- /dev/null
+++ b/rv64cpu/docs/architecture.md
@@ -0,0 +1,204 @@
+# Microarchitecture Design Document
+
+## Overview
+
+| Parameter | Value |
+|---|---|
+| ISA | RV64GCZicsr_Zifencei (I+M+A+F+D+C) |
+| Pipeline | 5-stage in-order single-issue (IF → ID → EX → MEM → WB) |
+| Privilege Levels | M / S / U |
+| Virtual Memory | Sv39 (39-bit VA, 56-bit PA, three-level page table) |
+| Bus | AXI4-Full (Cache) + AXI4-Lite (Peripherals) |
+| Cache | I-Cache 4KB + D-Cache 4KB (direct-mapped, upgradeable to set-associative) |
+| Debug | JTAG Debug (reserved) |
+
+---
+
+## Pipeline Timing
+
+```
+Cycle:    1     2     3     4     5     6     7
+         ┌─────┬─────┬─────┬─────┬─────┐
+Instr 1  │ IF  │ ID  │ EX  │ MEM │ WB  │
+         └─────┼─────┼─────┼─────┼─────┼─────┐
+Instr 2        │ IF  │ ID  │ EX  │ MEM │ WB  │
+               └─────┼─────┼─────┼─────┼─────┼─────┐
+Instr 3              │ IF  │ ID  │ EX  │ MEM │ WB  │
+                     └─────┴─────┴─────┴─────┴─────┘
+```
+
+### Stage Functions
+
+| Stage | Module | Description |
+|---|---|---|
+| **IF** | `if_stage.sv` | PC generation, iTLB virtual-to-physical translation, I-Cache read, instruction alignment, branch prediction interface |
+| **ID** | `id_stage.sv` | Instruction decode (`decoder.sv`), register file read (`regfile.sv`), immediate extension, CSR read, control signal generation |
+| **EX** | `ex_stage.sv` | ALU operations (`alu.sv`), branch resolution (`branch_unit.sv`), multiply/divide (`muldiv.sv`), FPU operations (`fpu.sv`), effective address calculation |
+| **MEM** | `mem_stage.sv` | dTLB virtual-to-physical translation, D-Cache read/write, load data alignment/sign extension, exception detection |
+| **WB** | `wb_stage.sv` | Register file writeback, CSR writeback, final exception/interrupt handling |
+
+### Hazard Handling (`hazard_unit.sv`)
+
+| Type | Strategy |
+|---|---|
+| RAW Data Hazard | EX→EX forwarding, MEM→EX forwarding |
+| Load-use | Stall 1 cycle (insert bubble at IF/ID stage) |
+| Control Hazard | Static not-taken prediction; branch resolved at EX stage, flush IF/ID on misprediction |
+| Structural Hazard | Eliminated by separate I-Cache / D-Cache |
+| FPU Long Latency | Stall EX stage until FPU result ready (or multi-cycle EX) |
+
+---
+
+## Privilege Level Architecture
+
+### Mode Switching
+
+```mermaid
+stateDiagram-v2
+    [*] --> M_Mode : Reset
+    M_Mode --> S_Mode : mret (mstatus.MPP=S)
+    M_Mode --> U_Mode : mret (mstatus.MPP=U)
+    S_Mode --> M_Mode : ecall / exception / interrupt (not delegated)
+    S_Mode --> U_Mode : sret (sstatus.SPP=U)
+    U_Mode --> S_Mode : ecall / exception / interrupt (delegated)
+    U_Mode --> M_Mode : ecall / exception / interrupt (not delegated)
+```
+
+### CSR Register List
+
+#### M-Mode CSRs
+| CSR | Address | Purpose |
+|---|---|---|
+| `mstatus` | 0x300 | Global status (MIE, MPIE, MPP, FS, etc.) |
+| `misa` | 0x301 | ISA capability descriptor (RV64IMAFD) |
+| `medeleg` | 0x302 | Exception delegation to S-mode |
+| `mideleg` | 0x303 | Interrupt delegation to S-mode |
+| `mie` | 0x304 | Interrupt enable |
+| `mtvec` | 0x305 | Trap vector base address |
+| `mscratch` | 0x340 | M-mode scratch register |
+| `mepc` | 0x341 | Exception PC |
+| `mcause` | 0x342 | Trap cause |
+| `mtval` | 0x343 | Trap value |
+| `mip` | 0x344 | Interrupt pending |
+| `mcycle` | 0xB00 | Cycle counter |
+| `minstret` | 0xB02 | Retired instruction counter |
+| `mvendorid` | 0xF11 | Vendor ID |
+| `marchid` | 0xF12 | Architecture ID |
+| `mimpid` | 0xF13 | Implementation ID |
+| `mhartid` | 0xF14 | Hart ID |
+
+#### S-Mode CSRs
+| CSR | Address | Purpose |
+|---|---|---|
+| `sstatus` | 0x100 | S-mode status (subset of mstatus) |
+| `sie` | 0x104 | S-mode interrupt enable |
+| `stvec` | 0x105 | S-mode trap vector |
+| `sscratch` | 0x140 | S-mode scratch register |
+| `sepc` | 0x141 | S-mode exception PC |
+| `scause` | 0x142 | S-mode trap cause |
+| `stval` | 0x143 | S-mode trap value |
+| `sip` | 0x144 | S-mode interrupt pending |
+| `satp` | 0x180 | Page table base address + MODE (Sv39) |
+
+---
+
+## MMU (Sv39)
+
+### Address Translation
+
+```
+63        39 38        30 29        21 20        12 11         0
+┌──────────┬────────────┬────────────┬────────────┬────────────┐
+│  (sign)  │  VPN[2]    │  VPN[1]    │  VPN[0]    │  Offset    │
+│ 25 bits  │  9 bits    │  9 bits    │  9 bits    │  12 bits   │
+└──────────┴────────────┴────────────┴────────────┴────────────┘
+                    39-bit Virtual Address
+```
+
+- **iTLB** (IF stage): 16-entry fully associative, for instruction fetch virtual-to-physical translation
+- **dTLB** (MEM stage): 16-entry fully associative, for Load/Store virtual-to-physical translation
+- **PTW** (`ptw.sv`): On TLB miss, hardware walks the three-level page table, reading page table entries via D-Cache
+- **sfence.vma**: Flush TLB (all entries or selective by ASID/VPN)
+
+### Module Organization
+
+```
+mmu/
+├── mmu_top.sv      ← Top-level: arbitrates iTLB/dTLB PTW requests
+├── tlb.sv          ← Parameterized TLB: ENTRIES, ASSOC, ASID support
+└── ptw.sv          ← Page Table Walker: three-level lookup state machine
+```
+
+---
+
+## FPU Architecture (F+D Extensions)
+
+### Module Organization
+
+```
+rtl/core/fpu/
+├── fpu_top.sv          ← FPU top-level (dispatch + result selection)
+├── fp_regfile.sv       ← Floating-point register file f0-f31 (64-bit)
+├── fp_add.sv           ← Addition/subtraction unit
+├── fp_mul.sv           ← Multiplication unit
+├── fp_div_sqrt.sv      ← Division/square root (multi-cycle)
+├── fp_fma.sv           ← Fused multiply-add (optional, high performance)
+├── fp_conv.sv          ← Format conversion (int↔fp, f32↔f64)
+├── fp_cmp.sv           ← Compare/classify (FEQ/FLT/FLE/FCLASS)
+└── include/
+    └── fp_pkg.sv       ← Floating-point types, rounding modes, exception flags
+```
+
+> **Note**: FPU operations typically require multiple cycles (especially division/square root), requiring FPU long-latency stall handling in hazard_unit. CSRs `fcsr` / `frm` / `fflags` are implemented in `csr_unit.sv`.
+
+---
+
+## Cache Subsystem
+
+See [memory_map.md](memory_map.md) for address mapping.
+
+| Parameter | I-Cache | D-Cache |
+|---|---|---|
+| Capacity | 4 KB | 4 KB |
+| Line Size | 64 B (8 × 64-bit) | 64 B |
+| Associativity | Direct-mapped (initial) | Direct-mapped (initial) |
+| Write Policy | N/A | Write-back + write-allocate |
+| Refill Bus | AXI4-Full Burst | AXI4-Full Burst |
+
+### Cache Line Calculation
+
+- 4 KB / 64 B = 64 lines
+- Tag = PA[55:12], Index = PA[11:6], Offset = PA[5:0]
+
+---
+
+## Bus Interconnect
+
+```
+┌────────────────┐     ┌────────────────┐
+│   I-Cache      │     │   D-Cache      │
+│  AXI4 Master   │     │  AXI4 Master   │
+└───────┬────────┘     └───────┬────────┘
+        │                      │
+        └──────┐    ┌──────────┘
+               ▼    ▼
+        ┌──────────────┐
+        │  AXI4 Arbiter │
+        └──────┬───────┘
+               ▼
+        ┌──────────────┐
+        │  AXI4 Xbar   │ ← Address decode
+        └──┬───┬───┬───┘
+           │   │   │
+    ┌──────┘   │   └──────┐
+    ▼          ▼          ▼
+┌───────┐ ┌───────────┐ ┌─────────────────┐
+│ SRAM  │ │AXI4→Lite  │ │ (Expandable     │
+│  Ctrl │ │  Bridge   │ │      Slave)     │
+└───────┘ └─────┬─────┘ └─────────────────┘
+                │
+        ┌───┬───┴───┬───┐
+        ▼   ▼       ▼   ▼
+     CLINT PLIC   UART GPIO
+     (AXI4-Lite Slaves)
+```
diff --git a/rv64cpu/docs/isa_support.md b/rv64cpu/docs/isa_support.md
new file mode 100644
index 0000000..e56eac6
--- /dev/null
+++ b/rv64cpu/docs/isa_support.md
@@ -0,0 +1,200 @@
+# ISA Support Matrix
+
+## Target ISA String
+
+```
+RV64GCZicsr_Zifencei
+```
+
+Equivalent to `RV64IMAFDCZicsr_Zifencei`
+
+---
+
+## Extension Implementation Status
+
+| Extension | Full Name | Status | Description |
+|---|---|---|---|
+| **I** | Base Integer (RV64I) | 🔴 Not implemented | 64-bit base integer instruction set |
+| **M** | Multiply/Divide | 🔴 Not implemented | Multiply, divide, remainder |
+| **A** | Atomic | 🔴 Not implemented | LR/SC, AMO atomic instructions |
+| **F** | Single-Precision Float | 🔴 Not implemented | 32-bit IEEE 754 floating-point |
+| **D** | Double-Precision Float | 🔴 Not implemented | 64-bit IEEE 754 floating-point |
+| **C** | Compressed | 🔴 Not implemented | 16-bit compressed instructions |
+| **Zicsr** | CSR Instructions | 🔴 Not implemented | CSRRW/CSRRS/CSRRC/CSRRWI/CSRRSI/CSRRCI |
+| **Zifencei** | Instruction Fence | 🔴 Not implemented | FENCE.I instruction |
+
+---
+
+## RV64I Instruction List
+
+### R-type Arithmetic/Logic
+| Instruction | Operation | Status |
+|---|---|---|
+| ADD | rd = rs1 + rs2 | ⬜ |
+| SUB | rd = rs1 - rs2 | ⬜ |
+| AND | rd = rs1 & rs2 | ⬜ |
+| OR | rd = rs1 \| rs2 | ⬜ |
+| XOR | rd = rs1 ^ rs2 | ⬜ |
+| SLL | rd = rs1 << rs2[5:0] | ⬜ |
+| SRL | rd = rs1 >> rs2[5:0] (logical) | ⬜ |
+| SRA | rd = rs1 >> rs2[5:0] (arith) | ⬜ |
+| SLT | rd = (rs1 < rs2) ? 1 : 0 (signed) | ⬜ |
+| SLTU | rd = (rs1 < rs2) ? 1 : 0 (unsigned) | ⬜ |
+
+### R-type RV64 Word Operations
+| Instruction | Operation | Status |
+|---|---|---|
+| ADDW | rd = sext((rs1+rs2)[31:0]) | ⬜ |
+| SUBW | rd = sext((rs1-rs2)[31:0]) | ⬜ |
+| SLLW | rd = sext((rs1 << rs2[4:0])[31:0]) | ⬜ |
+| SRLW | rd = sext((rs1[31:0] >> rs2[4:0])) | ⬜ |
+| SRAW | rd = sext((rs1[31:0] >>> rs2[4:0])) | ⬜ |
+
+### I-type Immediate Arithmetic
+| Instruction | Operation | Status |
+|---|---|---|
+| ADDI | rd = rs1 + imm | ⬜ |
+| ANDI | rd = rs1 & imm | ⬜ |
+| ORI | rd = rs1 \| imm | ⬜ |
+| XORI | rd = rs1 ^ imm | ⬜ |
+| SLLI | rd = rs1 << shamt[5:0] | ⬜ |
+| SRLI | rd = rs1 >> shamt[5:0] (logical) | ⬜ |
+| SRAI | rd = rs1 >> shamt[5:0] (arith) | ⬜ |
+| SLTI | rd = (rs1 < imm) ? 1 : 0 (signed) | ⬜ |
+| SLTIU | rd = (rs1 < imm) ? 1 : 0 (unsigned) | ⬜ |
+| ADDIW | rd = sext((rs1+imm)[31:0]) | ⬜ |
+| SLLIW | rd = sext((rs1 << shamt[4:0])[31:0]) | ⬜ |
+| SRLIW | rd = sext((rs1[31:0] >> shamt[4:0])) | ⬜ |
+| SRAIW | rd = sext((rs1[31:0] >>> shamt[4:0])) | ⬜ |
+
+### Load
+| Instruction | Width | Sign Extension | Status |
+|---|---|---|---|
+| LB | 8-bit | Signed | ⬜ |
+| LBU | 8-bit | Zero-extended | ⬜ |
+| LH | 16-bit | Signed | ⬜ |
+| LHU | 16-bit | Zero-extended | ⬜ |
+| LW | 32-bit | Signed | ⬜ |
+| LWU | 32-bit | Zero-extended | ⬜ |
+| LD | 64-bit | — | ⬜ |
+
+### Store
+| Instruction | Width | Status |
+|---|---|---|
+| SB | 8-bit | ⬜ |
+| SH | 16-bit | ⬜ |
+| SW | 32-bit | ⬜ |
+| SD | 64-bit | ⬜ |
+
+### Branch
+| Instruction | Condition | Status |
+|---|---|---|
+| BEQ | rs1 == rs2 | ⬜ |
+| BNE | rs1 != rs2 | ⬜ |
+| BLT | rs1 < rs2 (signed) | ⬜ |
+| BGE | rs1 >= rs2 (signed) | ⬜ |
+| BLTU | rs1 < rs2 (unsigned) | ⬜ |
+| BGEU | rs1 >= rs2 (unsigned) | ⬜ |
+
+### Upper Immediate / Jump
+| Instruction | Operation | Status |
+|---|---|---|
+| LUI | rd = imm << 12 | ⬜ |
+| AUIPC | rd = pc + (imm << 12) | ⬜ |
+| JAL | rd = pc+4; pc = pc + imm | ⬜ |
+| JALR | rd = pc+4; pc = (rs1 + imm) & ~1 | ⬜ |
+
+### System
+| Instruction | Status |
+|---|---|
+| ECALL | ⬜ |
+| EBREAK | ⬜ |
+| MRET | ⬜ |
+| SRET | ⬜ |
+| WFI | ⬜ |
+| FENCE | ⬜ |
+| FENCE.I | ⬜ |
+| SFENCE.VMA | ⬜ |
+
+---
+
+## M Extension (Multiply/Divide)
+
+| Instruction | Operation | Status |
+|---|---|---|
+| MUL | rd = (rs1 × rs2)[63:0] | ⬜ |
+| MULH | rd = (rs1 × rs2)[127:64] signed | ⬜ |
+| MULHSU | rd = (rs1 × rs2)[127:64] signed×unsigned | ⬜ |
+| MULHU | rd = (rs1 × rs2)[127:64] unsigned | ⬜ |
+| DIV | rd = rs1 / rs2 signed | ⬜ |
+| DIVU | rd = rs1 / rs2 unsigned | ⬜ |
+| REM | rd = rs1 % rs2 signed | ⬜ |
+| REMU | rd = rs1 % rs2 unsigned | ⬜ |
+| MULW | rd = sext((rs1×rs2)[31:0]) | ⬜ |
+| DIVW / DIVUW | 32-bit division | ⬜ |
+| REMW / REMUW | 32-bit remainder | ⬜ |
+
+---
+
+## A Extension (Atomic Instructions)
+
+| Instruction | Status |
+|---|---|
+| LR.W / LR.D | ⬜ |
+| SC.W / SC.D | ⬜ |
+| AMOSWAP.W/D | ⬜ |
+| AMOADD.W/D | ⬜ |
+| AMOAND.W/D | ⬜ |
+| AMOOR.W/D | ⬜ |
+| AMOXOR.W/D | ⬜ |
+| AMOMAX[U].W/D | ⬜ |
+| AMOMIN[U].W/D | ⬜ |
+
+---
+
+## F/D Extension (Floating-Point)
+
+| Category | F (32-bit) Instructions | D (64-bit) Instructions | Status |
+|---|---|---|---|
+| Load/Store | FLW, FSW | FLD, FSD | ⬜ |
+| Arithmetic | FADD.S, FSUB.S, FMUL.S, FDIV.S, FSQRT.S | FADD.D, ... | ⬜ |
+| Fused Multiply-Add | FMADD.S, FMSUB.S, FNMADD.S, FNMSUB.S | FMADD.D, ... | ⬜ |
+| Sign Manipulation | FSGNJ[N/X].S | FSGNJ[N/X].D | ⬜ |
+| Compare | FEQ.S, FLT.S, FLE.S | FEQ.D, FLT.D, FLE.D | ⬜ |
+| Classify | FCLASS.S | FCLASS.D | ⬜ |
+| Conversion | FCVT.W/WU/L/LU.S, FCVT.S.W/WU/L/LU | FCVT.*.D | ⬜ |
+| F↔D Conversion | — | FCVT.S.D, FCVT.D.S | ⬜ |
+| Move | FMV.X.W, FMV.W.X | FMV.X.D, FMV.D.X | ⬜ |
+| MIN/MAX | FMIN.S, FMAX.S | FMIN.D, FMAX.D | ⬜ |
+
+### Floating-Point CSRs
+| CSR | Address | Description |
+|---|---|---|
+| `fflags` | 0x001 | Floating-point exception flags (NV, DZ, OF, UF, NX) |
+| `frm` | 0x002 | Floating-point rounding mode |
+| `fcsr` | 0x003 | fflags + frm combined |
+
+---
+
+## C Extension (Compressed Instructions)
+
+16-bit encoded subset of common instructions, improving code density. Requires handling 16/32-bit mixed instruction stream alignment at the IF stage.
+
+| Quadrant | Selected Instructions | Status |
+|---|---|---|
+| C0 | C.LW, C.LD, C.SW, C.SD, C.ADDI4SPN | ⬜ |
+| C1 | C.ADDI, C.LI, C.LUI, C.SRLI, C.SRAI, C.ANDI, C.SUB, C.XOR, C.OR, C.AND, C.J, C.BEQZ, C.BNEZ | ⬜ |
+| C2 | C.SLLI, C.LDSP, C.LWSP, C.JR, C.MV, C.JALR, C.ADD, C.SDSP, C.SWSP | ⬜ |
+
+---
+
+## Zicsr Instructions
+
+| Instruction | Operation | Status |
+|---|---|---|
+| CSRRW | t=CSR; CSR=rs1; rd=t | ⬜ |
+| CSRRS | t=CSR; CSR=t\|rs1; rd=t | ⬜ |
+| CSRRC | t=CSR; CSR=t&~rs1; rd=t | ⬜ |
+| CSRRWI | t=CSR; CSR=zimm; rd=t | ⬜ |
+| CSRRSI | t=CSR; CSR=t\|zimm; rd=t | ⬜ |
+| CSRRCI | t=CSR; CSR=t&~zimm; rd=t | ⬜ |
diff --git a/rv64cpu/docs/memory_map.md b/rv64cpu/docs/memory_map.md
new file mode 100644
index 0000000..9bf529b
--- /dev/null
+++ b/rv64cpu/docs/memory_map.md
@@ -0,0 +1,113 @@
+# Memory Map
+
+## Physical Address Space
+
+```
+0xFFFF_FFFF_FFFF_FFFF ┌─────────────────────────┐
+                      │                         │
+                      │      (unused)            │
+                      │                         │
+0x0000_0000_1000_2000 ├─────────────────────────┤
+                      │  GPIO          4 KB     │
+0x0000_0000_1000_1000 ├─────────────────────────┤
+                      │  UART0         4 KB     │
+0x0000_0000_1000_0000 ├─────────────────────────┤
+                      │                         │
+                      │      (unused)            │
+                      │                         │
+0x0000_0000_0C00_0000 ├─────────────────────────┤
+                      │  PLIC          64 MB    │
+0x0000_0000_0BFF_FFFF ├─────────────────────────┤
+                      │                         │
+                      │      (unused)            │
+                      │                         │
+0x0000_0000_0200_FFFF ├─────────────────────────┤
+                      │  CLINT         64 KB    │
+0x0000_0000_0200_0000 ├─────────────────────────┤
+                      │                         │
+                      │      (unused)            │
+                      │                         │
+0x0000_0000_0FFF_FFFF ├─────────────────────────┤
+                      │                         │
+                      │  SRAM / RAM    ~256 MB  │
+                      │  (Boot ROM at lowest    │
+                      │        64KB)            │
+                      │                         │
+0x0000_0000_0000_0000 └─────────────────────────┘
+```
+
+## Address Decode Table
+
+| Start Address | End Address | Size | Peripheral | Bus | Description |
+|---|---|---|---|---|---|
+| `0x0000_0000` | `0x0FFF_FFFF` | 256 MB | SRAM Controller | AXI4-Full | Boot ROM (0x0~0xFFFF) + RAM |
+| `0x0200_0000` | `0x0200_FFFF` | 64 KB | CLINT | AXI4-Lite | mtime, mtimecmp, MSIP |
+| `0x0C00_0000` | `0x0FFF_FFFF` | 64 MB | PLIC | AXI4-Lite | External interrupt controller |
+| `0x1000_0000` | `0x1000_0FFF` | 4 KB | UART0 | AXI4-Lite | 16550 compatible |
+| `0x1000_1000` | `0x1000_1FFF` | 4 KB | GPIO | AXI4-Lite | General-purpose I/O |
+
+> **Note**: The address ranges for CLINT and PLIC follow the RISC-V community recommended layout, compatible with Linux/OpenSBI.
+
+## CLINT Register Layout
+
+| Offset | Register | Description |
+|---|---|---|
+| `0x0000` | `msip[0]` | Machine software interrupt pending |
+| `0x4000` | `mtimecmp[0]` | Machine timer compare value (64-bit) |
+| `0xBFF8` | `mtime` | Machine timer current value (64-bit) |
+
+## PLIC Register Layout (Simplified)
+
+| Offset | Register | Description |
+|---|---|---|
+| `0x000000` | `priority[1..N]` | Interrupt source priority |
+| `0x001000` | `pending[0..N/32]` | Interrupt pending bitfield |
+| `0x002000` | `enable[ctx][0..N/32]` | Interrupt enable bitfield |
+| `0x200000` | `threshold[ctx]` | Priority threshold |
+| `0x200004` | `claim/complete[ctx]` | Interrupt claim/complete |
+
+## UART0 Register Layout (16550)
+
+| Offset | Register | Read/Write | Description |
+|---|---|---|---|
+| `0x00` | RBR / THR | R / W | Receive/transmit data |
+| `0x01` | IER | R/W | Interrupt enable |
+| `0x02` | IIR / FCR | R / W | Interrupt identification / FIFO control |
+| `0x03` | LCR | R/W | Line control |
+| `0x05` | LSR | R | Line status |
+
+## Linker Script Correspondence
+
+The MEMORY regions in `sw/common/link.ld` correspond to this table:
+- `ROM`: `0x0000_0000`, 64 KB
+- `RAM`: `0x0001_0000`, 256 MB - 64 KB
+
+## Address Decode Implementation
+
+The address decode logic in RTL is located in `rtl/soc/mem_map.sv` and `rtl/bus/axi4_xbar.sv`.
+
+Constants are defined in `mem_map.sv`:
+
+```systemverilog
+package mem_map_pkg;
+    // SRAM
+    localparam logic [63:0] SRAM_BASE   = 64'h0000_0000;
+    localparam logic [63:0] SRAM_SIZE   = 64'h1000_0000;   // 256 MB
+
+    // CLINT
+    localparam logic [63:0] CLINT_BASE  = 64'h0200_0000;
+    localparam logic [63:0] CLINT_SIZE  = 64'h0001_0000;   // 64 KB
+
+    // PLIC
+    localparam logic [63:0] PLIC_BASE   = 64'h0C00_0000;
+    localparam logic [63:0] PLIC_SIZE   = 64'h0400_0000;   // 64 MB
+
+    // UART0
+    localparam logic [63:0] UART0_BASE  = 64'h1000_0000;
+    localparam logic [63:0] UART0_SIZE  = 64'h0000_1000;   // 4 KB
+
+    // GPIO
+    localparam logic [63:0] GPIO_BASE   = 64'h1000_1000;
+    localparam logic [63:0] GPIO_SIZE   = 64'h0000_1000;   // 4 KB
+endpackage
+```
diff --git a/rv64cpu/docs/pipeline_diagram.md b/rv64cpu/docs/pipeline_diagram.md
new file mode 100644
index 0000000..e2f6bdb
--- /dev/null
+++ b/rv64cpu/docs/pipeline_diagram.md
@@ -0,0 +1,156 @@
+# Pipeline Timing and Datapath
+
+## Five-Stage Pipeline Datapath
+
+```
+                 ┌────────────────────────────────────────────────────────────────┐
+                 │                    HAZARD UNIT                                 │
+                 │  Forward A/B, Stall, Flush, FPU interlock                     │
+                 └──┬─────────┬──────────┬──────────┬──────────┬────────────────┘
+                    │         │          │          │          │
+              ┌─────▼──┐ ┌───▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼─────┐
+              │   IF   │ │  ID   │ │   EX   │ │  MEM   │ │   WB   │
+              │        │ │       │ │        │ │        │ │        │
+  ┌──────┐    │ PC Gen │ │Decode │ │  ALU   │ │D-Cache │ │ Write  │
+  │ iTLB ├───►│   ↓    │ │   ↓   │ │ Branch │ │  LSU   │ │  Back  │
+  │      │    │I-Cache │ │RegFile│ │ MulDiv │ │  dTLB  │ │        │
+  └──────┘    │ Fetch  │ │ Read  │ │  FPU   │ │        │ │        │
+              │        │ │ ImmEx │ │        │ │        │ │        │
+              └───┬────┘ └───┬───┘ └────┬───┘ └───┬────┘ └───┬────┘
+                  │          │          │          │          │
+              ┌───▼──────────▼──┐ ┌─────▼──────────▼──┐ ┌────▼─────┐
+              │  IF/ID Reg     │ │  EX/MEM Reg       │ │  MEM/WB  │
+              │                │ │                    │ │   Reg    │
+              └────────────────┘ └────────────────────┘ └──────────┘
+                                      ↑
+                              ┌───────┴───────┐
+                              │   CSR Unit    │
+                              │  Trap Ctrl    │
+                              └───────────────┘
+```
+
+---
+
+## Inter-Stage Registers
+
+### IF/ID Register
+
+| Field | Width | Description |
+|---|---|---|
+| `pc` | 64 | Current instruction PC |
+| `instr` | 32 | Fetched instruction |
+| `valid` | 1 | Instruction valid |
+| `exception` | 1 | IF stage exception (e.g., instruction page fault) |
+| `exc_code` | 4 | Exception code |
+| `predicted_taken` | 1 | Branch prediction result |
+| `predicted_target` | 64 | Predicted target address |
+
+### ID/EX Register
+
+| Field | Width | Description |
+|---|---|---|
+| `pc` | 64 | |
+| `rs1_data` | 64 | Register source 1 value |
+| `rs2_data` | 64 | Register source 2 value |
+| `rs3_data` | 64 | FPU source 3 value (FMA) |
+| `imm` | 64 | Sign-extended immediate |
+| `rd_addr` | 5 | Destination register address |
+| `rs1_addr` | 5 | Source 1 address (for forwarding) |
+| `rs2_addr` | 5 | Source 2 address (for forwarding) |
+| `ctrl` | struct | Control signal bundle (ALU op, mem r/w, branch type, etc.) |
+| `valid` | 1 | |
+| `is_fp` | 1 | Floating-point instruction flag |
+
+### EX/MEM Register
+
+| Field | Width | Description |
+|---|---|---|
+| `pc` | 64 | |
+| `alu_result` | 64 | ALU/FPU computation result |
+| `rs2_data` | 64 | Store data |
+| `rd_addr` | 5 | |
+| `ctrl_mem` | struct | Memory access control (read/write, size, sign_ext) |
+| `ctrl_wb` | struct | Writeback control (reg_write, wb_sel) |
+| `valid` | 1 | |
+
+### MEM/WB Register
+
+| Field | Width | Description |
+|---|---|---|
+| `pc` | 64 | |
+| `alu_result` | 64 | |
+| `mem_data` | 64 | Data read from D-Cache |
+| `rd_addr` | 5 | |
+| `ctrl_wb` | struct | Writeback control |
+| `valid` | 1 | |
+
+---
+
+## Forwarding Paths
+
+```
+          EX Stage                MEM Stage               WB Stage
+         ┌────────┐             ┌─────────┐             ┌────────┐
+         │ ALU    │             │alu_result│             │ wb_data│
+         │ result ├────────┐   │ or       ├────────┐   │        │
+         └────────┘        │   │ mem_data │        │   └────┬───┘
+                           │   └─────────┘        │        │
+                     ┌─────▼──────────────────────▼────────▼─┐
+                     │           Forward MUX                  │
+                     │  sel = hazard_unit.forward_a/b         │
+                     └─────────────────┬─────────────────────┘
+                                       │
+                                       ▼
+                              EX Stage rs1/rs2 input
+```
+
+| Forwarding Source | Condition |
+|---|---|
+| EX→EX | `ex_mem.rd == id_ex.rs1/rs2` and `ex_mem.reg_write` |
+| MEM→EX | `mem_wb.rd == id_ex.rs1/rs2` and `mem_wb.reg_write` and no EX forwarding |
+| Load-use | `id_ex.mem_read` and `id_ex.rd == if_id.rs1/rs2` → **stall** |
+
+---
+
+## Branch Handling Timing
+
+```
+Cycle:    1     2     3     4     5
+         ┌─────┬─────┬─────┬─────┬─────┐
+Branch   │ IF  │ ID  │ EX  │ MEM │ WB  │  ← Branch resolved at EX stage
+         └─────┼─────┼─────┼─────┼─────┘
+Instr+1        │ IF  │ ID  │ ██  │        ← Misprediction: flush (2-cycle penalty)
+               └─────┼─────┼─────┘
+Instr+2              │ IF  │ ██  │        ← flush
+                     └─────┴─────┘
+Target                     │ IF  │ ID  │ EX  │ ...  ← Correct path begins
+                           └─────┴─────┴─────┘
+```
+
+---
+
+## Cache Miss Timing
+
+```
+Cycle:   1    2    3    4    5    6    7    8    ...   N    N+1
+        ┌────┬────┬────┬────────────────────────────┬────┬────┐
+Instr   │ IF │ ID │ EX │ MEM (D-Cache MISS)         │    │ WB │
+        └────┴────┴────┤    Stall pipeline...        ├────┴────┘
+                       │    AXI4 Burst read (8 beats)│
+                       │    Fill cache line           │
+                       └─────────────────────────────┘
+```
+
+---
+
+## TLB Miss → PTW Timing
+
+```
+Cycle:   1    2    3    ...        N    N+1   N+2
+        ┌────┬────────────────────────┬────┬────┐
+Instr   │ IF │ iTLB MISS → PTW walk  │ IF │ ID │ ...
+        └────┤  (3-level page table   ├────┴────┘
+             │   × memory latency)    │
+             │  Pipeline stalled      │
+             └────────────────────────┘
+```