diff options
Diffstat (limited to 'rv64cpu/docs')
| -rw-r--r-- | rv64cpu/docs/architecture.md | 204 | ||||
| -rw-r--r-- | rv64cpu/docs/isa_support.md | 224 | ||||
| -rw-r--r-- | rv64cpu/docs/memory_map.md | 113 | ||||
| -rw-r--r-- | rv64cpu/docs/naming_convention.md | 197 | ||||
| -rw-r--r-- | rv64cpu/docs/pipeline_diagram.md | 156 |
5 files changed, 894 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..0173a58 --- /dev/null +++ b/rv64cpu/docs/isa_support.md @@ -0,0 +1,224 @@ +# ISA Support Matrix + +## Target ISA String + +``` +RV64GCZicsr_Zifencei +``` + +Equivalent to `RV64IMAFDCZicsr_Zifencei` + +--- + +## Extension Implementation Status + +| Extension | Full Name | Status | Description | +|---|---|---|---| +| **I** | Base Integer (RV64I) | 🟢 Implemented | Strict ACT4 compliance suite passes (`rv64i`) | +| **M** | Multiply/Divide | 🟢 Implemented | Strict ACT4 compliance suite passes (`rv64im`) | +| **A** | Atomic | 🟢 Implemented | Strict ACT4 compliance suite passes (`rv64ia`) | +| **F** | Single-Precision Float | 🟢 Implemented | Strict ACT4 compliance suite passes (`rv64if`) | +| **D** | Double-Precision Float | 🟢 Implemented | Strict ACT4 compliance suite passes (`rv64id`) | +| **C** | Compressed | 🟢 Implemented | Strict ACT4 compliance suite passes (`rv64ic`) | +| **Zicsr** | CSR Instructions | 🟢 Implemented | Full CSR unit with delegation, FCSR, and dedicated testbench ([rtl/core/csr_unit.sv](rtl/core/csr_unit.sv), [tb/unit/tb_csr.cc](tb/unit/tb_csr.cc)) | +| **Zifencei** | Instruction Fence | 🟢 Implemented | Included in strict ACT4 passing suites | + +Privilege-related tests (`S`, `Sm`) also pass through `rv64priv` strict suite. + +--- + +## Recent Progress Highlights (2026-04) + +- `riscv-arch-test` ACT4 flow integrated in `scripts/run_compliance.py`. +- Dedicated `tb/compliance/compliance_runner.cc` executes ELF tests and dumps signatures. +- Strict suite passes with reference comparison enabled (`--require-reference`): + - `rv64i` (51/51) + - `rv64im` (64/64) + - `rv64ia` (51/51) + - `rv64ic` (51/51) + - `rv64if` (133/133) + - `rv64id` (165/165) + - `rv64priv` (2/2) + - `rv64full` aggregate (262/262) + +## Detailed Instruction Tables + +The detailed per-instruction checklist sections below are retained as reference, +but are not the primary source of truth for completion status at this stage. +Current completion is determined by strict ACT4 suite pass results listed above. + +--- + +## 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/naming_convention.md b/rv64cpu/docs/naming_convention.md new file mode 100644 index 0000000..830c5e5 --- /dev/null +++ b/rv64cpu/docs/naming_convention.md @@ -0,0 +1,197 @@ +# RTL Signal Naming Convention + +This document defines the naming rules for all SystemVerilog signals, ports, types, +and modules in the Richard-CPU project. Follow these rules when writing new RTL or +modifying existing code. + +## 1. General Rules + +| Rule | Example | +|---|---| +| All names use `snake_case` (lowercase + underscores) | `alu_result`, `rs1_addr` | +| Names should be descriptive; avoid single-letter names except loop indices | `i` in `for(int i = ...)` is acceptable | +| Abbreviations are allowed **only** from the approved list (Section 7) | `addr` not `address`, `imm` not `immediate` | +| No trailing numbers for disambiguation; use descriptive suffixes instead | `read_port_a` not `read_port_1` | + +### 1.1 Semantic Clarity Priority + +When multiple names are technically valid, prefer the name with the clearest +semantic meaning: + +1. Prefer full words over unclear abbreviations unless listed in Section 7. +2. Prefer domain-accurate nouns over generic placeholders. +3. Prefer names that communicate role and timing (source, destination, stage). + +Examples: +- `interrupt_cause` is preferred over `int_cause` +- `trap_target_pc` is preferred over `trap_next_value` +- `csr_write_data` is preferred over `csr_write_val` + +## 2. Module & Package Names + +| Item | Rule | Example | +|---|---|---| +| Module | `snake_case`, named after function | `alu`, `regfile`, `decoder`, `if_stage` | +| Package | `snake_case` ending in `_pkg` | `rv64_pkg` | +| Typedef | `snake_case` ending in `_t` | `alu_op_t`, `opcode_t` | +| Enum members | `UPPER_SNAKE_CASE` with a common prefix | `ALU_ADD`, `OPCODE_LUI` | +| Parameters / localparams | `UPPER_SNAKE_CASE` | `XLEN`, `INST_WIDTH` | + +## 3. Port & Signal Names + +### 3.1 Standard Suffixes + +Use these suffixes consistently to indicate the **role** of a signal: + +| Suffix | Meaning | Example | +|---|---|---| +| `_addr` | Address (register index or memory address) | `rs1_addr`, `rd_addr` | +| `_data` | Data bus (generic read/write payload) | `mem_rdata`, `mem_wdata` | +| `_rdata` | Read data (output from a storage element) | `rs1_rdata`, `rs2_rdata` | +| `_wdata` | Write data (input to a storage element) | `rd_wdata` | +| `_op` | Operation selector (typically an enum or funct3) | `alu_op`, `branch_op`, `csr_op` | +| `_sel` | Mux select signal | `alu_src1_sel`, `wb_sel` | +| `_en` | Enable (active-high gating signal) | `reg_write_en`, `mem_read_en` | +| `_val` | **Deprecated — do not use for new code.** Use `_rdata`/`_wdata`/`_data` instead | — | + +Additional clarity rules: +- `*_value` is allowed for architectural/state snapshots when `*_data` would be + ambiguous. Example: `csr_mstatus_value`. +- For storage read/write payloads, always prefer `_rdata`/`_wdata`/`_data` over + `_value`. +- `_flag` is deprecated for new boolean signals. Use `is_<noun>`, `has_<noun>`, + or `<adjective>_<noun>`. + +### 3.2 Standard Prefixes + +| Prefix | Meaning | Example | +|---|---|---| +| `is_` | Boolean flag indicating instruction type or state | `is_load`, `is_branch`, `is_csr` | +| `has_` | Boolean flag indicating a condition is met | `has_exception`, `has_interrupt` | + +### 3.3 Rules for Boolean / Control Signals + +All single-bit control signals should follow **one** of these patterns: + +| Pattern | When to Use | Example | +|---|---|---| +| `is_<noun>` | Classifying an instruction or state | `is_load`, `is_jump`, `is_ecall` | +| `<noun>_en` | Enabling a write or action | `reg_write_en`, `mem_write_en` | +| `<adjective>_<noun>` | Describing a property | `illegal_instr`, `branch_taken` | + +> **Consistency rule**: For write-enable signals on storage elements (register file, +> memory, CSR), always use the `_en` suffix. Example: `reg_write_en`, not `reg_write`. + +Additional boolean rules: +- Avoid suffix-only boolean naming such as `*_flag` and `*_bool` in new code. +- `has_` is for condition presence (`has_interrupt`), `is_` is for classification + (`is_interrupt` for a classified event or type). + +### 3.4 Clock & Reset + +| Signal | Name | Description | +|---|---|---| +| Clock | `clk` | Single system clock | +| Reset | `rst_n` (preferred) or `rst` | Active-low (`rst_n`) is preferred; if active-high, use `rst` | + +> Current codebase uses active-high `rst`. If you later switch to active-low, rename +> to `rst_n` everywhere in a single commit. + +## 4. Pipeline Stage Prefixes + +When signals cross pipeline stages, prefix them with the stage abbreviation: + +| Stage | Prefix | Example | +|---|---|---| +| Instruction Fetch | `if_` | `if_pc`, `if_instr` | +| Instruction Decode | `id_` | `id_rs1_addr`, `id_imm` | +| Execute | `ex_` | `ex_alu_result`, `ex_branch_taken` | +| Memory Access | `mem_` | `mem_rdata`, `mem_addr` | +| Write Back | `wb_` | `wb_rd_wdata`, `wb_rd_addr` | + +Inter-stage pipeline registers use a combined prefix: `id_ex_reg_write_en`, +`ex_mem_alu_result`. + +## 5. ALU Port Naming + +The ALU is a **generic compute unit**. Its inputs are not always register values — +they may come from the PC or an immediate after mux selection. Use neutral names: + +| Port | Current (non-conforming) | Recommended | +|---|---|---| +| Operand 1 input | `rs1_val` | `operand_a` | +| Operand 2 input | `rs2_val` | `operand_b` | +| Result output | `alu_res` | `alu_result` | + +## 6. Register File Port Naming + +| Port | Name | Description | +|---|---|---| +| Read address 1 | `rs1_addr` | Source register 1 index | +| Read data 1 | `rs1_rdata` | Source register 1 data output | +| Read address 2 | `rs2_addr` | Source register 2 index | +| Read data 2 | `rs2_rdata` | Source register 2 data output | +| Write address | `rd_addr` | Destination register index | +| Write data | `rd_wdata` | Destination register data input | +| Write enable | `reg_write_en` | Write enable (active high) | + +## 7. Approved Abbreviations + +Only these abbreviations are permitted. All other words should be spelled in full. + +| Abbreviation | Full Form | +|---|---| +| `addr` | address | +| `alu` | arithmetic logic unit | +| `clk` | clock | +| `csr` | control and status register | +| `en` | enable | +| `ex` | execute (pipeline stage only) | +| `fpu` | floating-point unit | +| `id` | instruction decode (pipeline stage only) | +| `if` | instruction fetch (pipeline stage only) | +| `imm` | immediate | +| `instr` | instruction | +| `mem` | memory | +| `mmu` | memory management unit | +| `mux` | multiplexer | +| `op` | operation | +| `pc` | program counter | +| `rd` | destination register | +| `rdata` | read data | +| `reg` | register | +| `res` | **Deprecated — use `result`** | +| `rs1` / `rs2` | source register 1 / 2 | +| `rst` | reset | +| `sel` | select | +| `tlb` | translation lookaside buffer | +| `val` | **Deprecated — use `rdata`/`wdata`/`data`** | +| `wb` | write back (pipeline stage only) | +| `wdata` | write data | + +Not approved for new code: +- `int` (use `interrupt`) +- `flag` suffix for booleans (use Section 3.3 patterns) + +## 7.1 Architecture-Defined Bit Names (Exception) + +Some names come directly from ISA-defined bit semantics and are allowed in narrow +scopes even if they are single-letter: + +- PTE-like permission bits: `u`, `r`, `w`, `x`, `a`, `d`, `g` + +Scope limits: +1. Allowed only inside tightly scoped structs, packed fields, or helper function + parameters tied to ISA semantics. +2. For module ports and cross-module buses, prefer descriptive names such as + `pte_user`, `pte_read`, `pte_write`, `pte_exec`, `pte_accessed`, `pte_dirty`, + `pte_global`. + +## 8. Current Codebase Non-Conformances + +The following table lists signals in the existing codebase that do not yet follow +this convention. These should be renamed during the next refactoring pass. + +| File | Current Name | Recommended Name | Reason | +|---|---|---|---| +|None|None|None|None| 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 │ + └────────────────────────┘ +``` |