🚀 RISC-V 32IMAC 5-Stage Pipelined Processor & SoC

A fully functional, highly optimized 32-bit RISC-V Processor (RV32IMAC instruction set) written from scratch in SystemVerilog. Features a classic 5-Stage Pipeline architecture with full hazard resolution, L1 Harvard caches, AXI4 bus, dynamic branch prediction (BTB + RAS), Machine-Mode CSR trap handling, and UART peripherals. Designed for simulation with Verilator and synthesis on FPGA.

---

🌟 Key Features

Feature	Description
Architecture	5-Stage Pipeline (IF → ID → EX → MEM → WB)
ISA Extensions	RV32IMAC: Base Integer + M (Math) + A (Atomics) + C (16-bit Compressed) + Zicsr
Performance	0.995 IPC (Native Core) / 0.979 IPC (Full AXI SoC)
Hardware Math	1-cycle Combinational Multiplier & 33-cycle Iterative Divider (RV32M)
Atomics	Atomic Memory Operations & LR/SC Reservation Station (RV32A)
Compressed ISA	16-bit Instruction Pre-Decoder with 2-cycle Cross-Boundary Fetch (RV32C)
Data Forwarding	MEM→EX and WB→EX forwarding resolves RAW hazards with zero stalls
Load-Use Stall	Automatic 1-cycle stall for memory-dependent data
Branch Prediction	Dynamic 64-entry Bimodal Branch Target Buffer (BTB) + Return Address Stack (RAS) with Redirection Guard
Privileged Mode	Machine-Mode CSRs (mstatus, mtvec, mepc, mcause, mie, mip, mcycle, minstret)
Traps & Interrupts	Single-pulse masked hardware interrupts + precise exception traps (ecall, ebreak, illegal instr)
Memory Subsystem	Advanced LSU supporting Byte/Halfword/Word accesses (Signed & Unsigned)
L1 Caches	Direct-Mapped 1KB I-Cache and 1KB Write-Back D-Cache with Burst Fetch/Evict
SoC & Interconnect	Single-Master AXI4-FULL CPU Interface + Centralized Crossbar Router (riscv_axi_interconnect)
Peripherals	Memory-Mapped UART (0x1001_3000) with TX/RX FIFOs
Verification	100% Strict Hardware Register Assertions across all 13 testcases
BRAM Ready	(* ram_style = "block" *) attributes for FPGA synthesis

---

📂 Project Structure

RISCV-basic/
├── HDL/
│   ├── Core/
│   │   ├── riscv_core.sv              # Top-Level Pipeline Integration
│   │   └── riscv_csr.sv               # Machine-Mode CSRs & Interrupt/Trap Unit
│   ├── Front_End/
│   │   ├── IF_Stage/                  # Instruction Fetch & Pre-Decoder
│   │   │   ├── riscv_if_stage.sv      # IF Stage with Redirection Guard
│   │   │   ├── riscv_c_decoder.sv     # 16-bit Compressed Instruction Decoder
│   │   │   ├── riscv_btb.sv           # Branch Target Buffer (BTB)
│   │   │   ├── riscv_ras.sv           # Return Address Stack (RAS)
│   │   │   ├── riscv_pc_unit.sv
│   │   │   └── riscv_imem.sv
│   │   └── ID_Stage/                  # Instruction Decode
│   │       ├── riscv_id_stage.sv
│   │       ├── riscv_controller.sv
│   │       ├── riscv_regfile.sv
│   │       └── riscv_extend.sv
│   ├── Back_End/
│   │   ├── EX_Stage/                  # Execute
│   │   │   ├── riscv_ex_stage.sv
│   │   │   ├── riscv_alu.sv
│   │   │   ├── riscv_multdiv.sv       # Hardware Multiplier/Divider
│   │   │   └── riscv_branch_eval.sv
│   │   ├── MEM_Stage/                 # Memory Access
│   │   │   ├── riscv_mem_stage.sv
│   │   │   ├── riscv_lsu.sv           # Load/Store Unit
│   │   │   └── riscv_dmem.sv
│   │   └── WB_Stage/                  # Write Back
│   │       └── riscv_wb_stage.sv
│   ├── Pipeline_Control/
│   │   ├── riscv_pipeline_regs.sv     # IF/ID, ID/EX, EX/MEM, MEM/WB
│   │   └── riscv_hazard_unit.sv       # Forwarding, Stalling, Flushing
│   ├── Cache/
│   │   ├── riscv_l1_cache.sv          # Unified L1 Cache Wrapper
│   │   ├── riscv_icache.sv            # L1 Instruction Cache
│   │   └── riscv_dcache.sv            # L1 Write-Back Data Cache
│   ├── Bus_Interface/
│   │   └── AXI4/
│   │       ├── riscv_axi_arbiter.sv   # Generic 2-to-1 AXI4-FULL Arbiter
│   │       ├── riscv_axi_interconnect.sv # SoC AXI4 Crossbar Router
│   │       ├── riscv_axi_master.sv    # AXI4-FULL Uncached Bypass Master
│   │       ├── riscv_axi_memory_slave.sv # AXI4-FULL SRAM Slave
│   │       └── riscv_axi_top.sv       # Single-Master CPU AXI4 Wrapper
│   └── SoC/
│       ├── riscv_soc_top.sv           # Complete SoC Top Level
│       └── Protocol/UART/             # Memory-Mapped UART
├── docs/
│   ├── trap_and_pipeline_postmortem.md        # Bug Fix & Technical Post-Mortem
│   ├── DeviceTree.md                          # SoC Memory Map & Architecture
│   ├── CSR_Privileged_Architecture_Class.md   # CSR Documentation
│   └── RISCV32I_Zicsr_Technical_Documentation.md # Technical Docs
├── include/
│   ├── config.vh                      # Global defines (XLEN, MEM_DEPTH)
│   └── riscv_axi_pkg.sv               # AXI4-FULL struct and enum definitions
├── sim/
│   ├── asm/                           # 📝 Assembly test sources (.s)
│   │   ├── testcase_alu.s
│   │   ├── testcase_branch.s
│   │   ├── testcase_ls.s
│   │   ├── testcase_hazards.s
│   │   ├── testcase_irq.s
│   │   ├── testcase_csr.s
│   │   ├── testcase_multdiv.s
│   │   ├── testcase_trap.s
│   │   ├── testcase_compressed.s
│   │   ├── testcase_ras.s
│   │   ├── testcase_benchmark.s
│   │   ├── testcase_atomics.s
│   │   └── testcase_uart.s
│   ├── hex/                           # Auto-generated .mem & .expect.mem files
│   ├── scripts/
│   │   ├── link.ld                    # Bare-metal linker script
│   │   ├── bin2mem.py                 # Binary to Verilog hex converter
│   │   └── gen_expected.py            # Parses expected registers from assembly
│   ├── tb_riscv_core.sv               # Native core testbench
│   ├── tb_riscv_soc.sv                # Full SoC testbench (Bit-for-bit assertion checking)
│   ├── tb_riscv_axi.sv                # AXI wrapper testbench
│   └── tb_riscv_alu.sv                # ALU unit test
├── Makefile                           # 🔧 Automated build system
└── README.md

---

🛠 Prerequisites

Tool	Purpose	Command
Verilator	RTL simulation	sudo apt install verilator
RISC-V GCC	Cross-compiler for .s → .elf	sudo apt install gcc-riscv64-unknown-elf
Python 3	.bin → .mem & expect file generation	Pre-installed
GTKWave	Waveform viewer (optional)	sudo apt install gtkwave
Make	Build automation	sudo apt install make

---

🚀 Quick Start

# Run the complete SoC automated test suite (Tests all 13 testcases with bit-level register assertions)
make test_all TOP_MODULE=tb_riscv_soc

# Run benchmark on Native Core:
make all TEST=testcase_benchmark TOP_MODULE=tb_riscv_core

# Run benchmark on Full SoC:
make all TEST=testcase_benchmark TOP_MODULE=tb_riscv_soc

# View disassembly of any test
make disasm TEST=testcase_trap

# List all available tests
make list_tests

---

🧬 Test Suite Matrix (100% Real Hardware Assertions)

Testcase	Verified Functionality	Register Assertions	Status
testcase_alu	R-type, I-type ALU ops, LUI, AUIPC	17 Registers Checked	✅ PASSED
testcase_branch	BEQ, BNE, BLT, BGE, BLTU, BGEU, JAL, JALR	9 Registers Checked	✅ PASSED
testcase_ls	SW/LW, SH/LH/LHU, SB/LB/LBU, Little-Endian alignment	12 Registers Checked	✅ PASSED
testcase_hazards	RAW Forwarding (MEM→EX, WB→EX), Load-Use Stalls	10 Registers Checked	✅ PASSED
testcase_irq	Timer & External Hardware Interrupt Masking	1 Register Checked	✅ PASSED
testcase_csr	CSRRW, CSRRS, CSRRC, CSRRWI, CSRRSI, CSRRCI	9 Registers Checked	✅ PASSED
testcase_multdiv	Hardware Multiplication & Division (RV32M)	7 Registers Checked	✅ PASSED
testcase_trap	ECALL, EBREAK, MRET, Precise Exceptions	6 Registers Checked	✅ PASSED
testcase_compressed	RV32C 16-bit Compressed Decoding	5 Registers Checked	✅ PASSED
testcase_ras	Return Address Stack for subroutines	3 Registers Checked	✅ PASSED
testcase_benchmark	Performance Workload (0.979 IPC on SoC)	2 Registers Checked	✅ PASSED
testcase_atomics	LR/SC and Atomic Memory Operations (RV32A)	9 Registers Checked	✅ PASSED
testcase_uart	AXI Crossbar Routing & MMIO UART Peripheral	3 Registers Checked	✅ PASSED

---

📊 Benchmark Comparison

Environment	Module	Total Instructions	Total Cycles	IPC
Native Core	tb_riscv_core	708	711	0.995
Full SoC	tb_riscv_soc	708	723	0.979

---

🗺 Future Roadmap

• Single-Master AXI4-FULL CPU Interface & Interconnect Crossbar
• L1 Instruction & Data Caches (Burst Support, Write-Back)
• Machine-Mode Privileged Architecture & Zicsr Extension
• Hardware Multiplier/Divider (RV32M)
• Atomic Operations (RV32A) & Reservation Station
• RV32C Compressed Instructions & 2-Cycle Cross-Boundary Fetch
• Dynamic Branch Prediction (Bimodal BTB + RAS with Redirection Guard)
• SoC Integration with AXI Crossbar & MMIO UART
• Strict Bit-Level Hardware Register Assertions across 100% of Testcases
• Core Local Interruptor (CLINT) & Timer Interrupts
• Multi-Core Cache Coherence (MOESI Protocol)

---

Designed & Verified by KhoaNguyenT ❤️.