███████╗       ██████╗ ██████╗ ██████╗ ███████╗
╚══███╔╝      ██╔════╝██╔═══██╗██╔══██╗██╔════╝
  ███╔╝ █████╗██║     ██║   ██║██████╔╝█████╗  
 ███╔╝  ╚════╝██║     ██║   ██║██╔══██╗██╔══╝  
███████╗      ╚██████╗╚██████╔╝██║  ██║███████╗
╚══════╝       ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝

A lightweight RISC-V RV32IM processor

---

Features

• 5-Stage Pipeline - Classic RISC-V 5-stage pipeline implementation

• RV32IM Implementation - Base integer ISA + Multiplication/Division

• AXI4-Lite Interface - Industry-standard memory bus protocol

• Modular Design - Clean separation of concerns with individual modules

• Comprehensive Testbenches - Automated testing for all components

• Well Documented - Extensive documentation and code comments

• Educational Focus - Perfect for learning computer architecture

Block Diagram

^{Z-Core SoC Architecture.}

Z-Core RV32IM Architecture

^{Z-Core RV32IM Architecture Diagram.}

Note: For a more detailed description of the Z-Core architecture, see the Z-Core Architecture Document

Supported Instructions

Type	Instructions	Description
R-Type	ADD, SUB, SLL, SLT, SLTU, XOR, SRL, SRA, OR, AND, MUL, MULH, MULHSU, MULHU, DIV, DIVU, REM, REMU	Register-register operations
I-Type	ADDI, SLTI, SLTIU, XORI, ORI, ANDI, SLLI, SRLI, SRAI	Immediate operations
Load	LB, LH, LW, LBU, LHU	Memory load
Store	SB, SH, SW	Memory store
Branch	BEQ, BNE, BLT, BGE, BLTU, BGEU	Conditional branching
Jump	JAL, JALR	Jump and link
Upper	LUI, AUIPC	Upper immediate

Project Structure

Z-Core/
├── rtl/                       # RTL source files
│   ├── z_core_top_model.v     # Top-level SoC
│   ├── z_core_control_u.v     # Control unit / CPU core
│   ├── z_core_decoder.v       # Instruction decoder
│   ├── z_core_reg_file.v      # 32x32-bit register file
│   ├── z_core_alu.v           # Arithmetic logic unit
│   ├── z_core_alu_ctrl.v      # ALU control
│   ├── z_core_mult_unit.v     # Multiplier unit
│   ├── z_core_div_unit.v      # Divider unit
│   ├── axil_interconnect.v    # AXI-Lite Interconnect
│   ├── axil_master.v          # AXI-Lite Master
│   ├── axil_uart.v            # UART Module
│   ├── axil_gpio.v            # GPIO Module
│   └── axi_mem.v              # AXI-Lite RAM
│
├── tb/                        # Testbenches
│   ├── z_core_control_u_tb.sv # Full system test
│   ├── z_core_alu_tb.v        # ALU unit test
│   ├── z_core_alu_ctrl_tb.v   # ALU control test
│   ├── z_core_decoder_tb.v    # Decoder test
│   ├── z_core_reg_file_tb.v   # Register file test
│   ├── z_core_mult_unit_tb.v  # Multiplier unit test
│   ├── z_core_div_unit_tb.v   # Divider unit test
│   ├── axil_gpio_tb.v         # GPIO testbench
│   └── z_core_riscof_tb.sv    # RISCOF compliance testbench
│
└── doc/                       # Documentation
    ├── AXI_INTERFACE.md       # AXI protocol details
    ├── GPIO.md                # GPIO module documentation
    ├── UART.md                # UART module documentation
    ├── Z_CORE_ARCHITECTURE.md # Architecture overview
    ├── PIPELINE.md            # Pipeline implementation details
    └── VERIFICATION.md        # Verification details

Quick Start

Prerequisites

• Icarus Verilog (iverilog) for simulation
• GTKWave for waveform viewing (optional)

Installation

# Clone the repository
git clone https://github.com/yourusername/Z-Core.git
cd Z-Core

# Create simulation directory
mkdir -p sim

Running Tests

# Run individual module tests
iverilog -o sim/z_core_alu_tb.vvp tb/z_core_alu_tb.v && vvp sim/z_core_alu_tb.vvp

# Run full system test (comprehensive)
iverilog -g2012 -o sim/z_core_control_u_tb.vvp tb/z_core_control_u_tb.sv
vvp sim/z_core_control_u_tb.vvp

Expected Output

╔═══════════════════════════════════════════════════════════╗
║           Z-Core RISC-V Processor Test Suite              ║
║                   RV32I Instruction Set                   ║
╚═══════════════════════════════════════════════════════════╝

--- Loading Test 1: Arithmetic Operations ---
=== Test 1 Results: Arithmetic ===
  [PASS] ADDI x2, x0, 10: x2 = 10
  [PASS] ADD x4, x2, x3: x4 = 17
  ...

╔═══════════════════════════════════════════════════════════╗
║                    TEST SUMMARY                           ║
╠═══════════════════════════════════════════════════════════╣
║  Total Tests:  183                                         ║
║  Passed:       183                                         ║
║  Failed:        0                                          ║
╠═══════════════════════════════════════════════════════════╣
║         ✓ ALL TESTS PASSED SUCCESSFULLY ✓                 ║
╚═══════════════════════════════════════════════════════════╝

Viewing Waveforms

gtkwave sim/z_core_control_u_tb.vcd

Test Coverage

The processor has been verified with 183 comprehensive tests across 17 test suites:

Test Suite	Description	Tests
Arithmetic	ADD, SUB, ADDI	6
Logical	AND, OR, XOR, ANDI, ORI, XORI	8
Shifts	SLL, SRL, SRA, SLLI, SRLI, SRAI	8
Memory	LW, SW with AXI transactions	8
Compare	SLT, SLTU, SLTI, SLTIU	8
Upper Immediate	LUI, AUIPC	4
Integration	Fibonacci sequence	9
Branches	BEQ, BNE, BLT, BGE, BLTU, BGEU	7
Jumps	JAL, JALR, JALR+offset	7
Loop	Backward branch (sum 0..4)	3
IO Access	UART STATUS register	1
GPIO	Bidirectional GPIO	2
Byte/Halfword	LB, LH, LBU, LHU, SB, SH	8
UART Loopback	TX→RX data verification	1
M Extension	MUL, DIV, REM, Forwarding Stress	10
RISCOF Compliance	Official RISC-V RV32IM Architectural Tests	49
Stress Tests	RAW hazards, ALU coverage, Nested Loops, Mem Patterns	53

Performance

Metric	Value
Pipeline Stages	5-Stage (IF, ID, EX, MEM, WB)
Throughput	~1 cycle per instruction (ideal)
Register File	32 x 32-bit
Memory Interface	AXI4-Lite
Memory Size	64KB (configurable)

Note: The processor throughput is now limited by the memory latency (Around 10 cycles per memory access). Therefore, the current processor implementation cannot reach the ideal throughput of 1 cycle per instruction.

Configuration

The processor is parameterizable through top-level parameters:

module z_core_top #(
    parameter DATA_WIDTH = 32,      // Data bus width
    parameter ADDR_WIDTH = 32,      // Address bus width
    parameter MEM_ADDR_WIDTH = 16,  // Memory size (2^16 = 64KB)
    parameter PIPELINE_OUTPUT = 0   // Memory pipeline stage
)(
    input wire clk,
    input wire rstn
);

Documentation

Detailed documentation is available in the doc/ directory:

• Architecture - Detailed architecture overview
• AXI Interface - Complete AXI-Lite protocol documentation
• Pipeline - Pipeline implementation details
• GPIO - Bidirectional GPIO module
• UART - Serial UART module
• Verification - Test coverage and verification methodology

Roadmap

• RV32I base integer instructions
• AXI4-Lite memory interface
• Comprehensive testbench
• Modular IO (UART, GPIO)
• Pipelining for improved throughput
• FPGA synthesis and validation Z-Core-FPGA repository
• M extension (multiply/divide)
• Branch prediction & Instruction Cache
• C extension (compressed instructions)
• Interrupt support
• Extra Peripherals (VGA Controller, Timer, etc.)
• Exception / Trap Handling (e.g., Address Misalignment, mtvec)

Contributing

Contributions are welcome. Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• RISC-V Foundation for the open ISA specification
• Alex Forencich for the AXI-Lite RAM module
• The open-source hardware community

About the Project

The aim of this project is to gain a practical understanding of Computer Architecture and SoC design by building a system-on-chip. The implementation blends custom RTL, written from scratch, with established open-source modules (such as the AXI-Lite infrastructure) and utilizes AI tools to assist in development and verification. This project demonstrates the ability to architect a system, integrate third-party IP, and adopt modern engineering workflows.

---

Built for learning computer architecture and SoC design :D