Production-grade, 5-stage pipelined 32-bit RISC-V Core (RV32IM)

graph LR
    IF[Fetch] -->|Instr| ID[Decode]
    ID -->|Control/Op| EX[Execute]
    EX -->|Addr/Data| MEM[Memory]
    MEM -->|Read Data| WB[Writeback]
    WB -->|Reg Write| ID
    style IF fill:#f9f,stroke:#333
    style ID fill:#bbf,stroke:#333
    style EX fill:#bfb,stroke:#333
    style MEM fill:#fbb,stroke:#333
    style WB fill:#bff,stroke:#333

IronCore is a synthesizable, lint-clean, and coverage-driven 32-bit RISC-V processor core (RV32IM). It is designed to demonstrate a complete digital design lifecycle, moving beyond "toy" implementations to a production-ready engineering portfolio artifact.

Key Capabilities:

• ISA: RV32I + M Extension (Integer Mul/Div).
• Pipeline: 5-stage in-order (IF, ID, EX, MEM, WB) with precise exceptions.
• System Integration: Supports variable-latency memory (stall/backpressure), standard bus interfaces (Wishbone/AXI4-Lite), and bare-metal C runtime.
• Verification: Comprehensive suite including unit tests, cocotb integration tests, and official RISC-V compliance suites.
• Physical implementation: FPGA-ready (Artix-7) and ASIC-feasible (Sky130/OpenLane flow).

The fastest way to start is using the provided Docker environment to ensure reproducible tooling.

1. Build the Docker environment:

   make docker-build

2. Enter the development shell:

   make docker-shell

3. Run full regression (Lint + Unit + Integration + Compliance):

   make regress

• Architecture:

  • 32-bit RISC-V (RV32IM)
  • Machine Mode (M-Mode) with Precise Exceptions
  • CSR Support (mstatus, mie, mtvec, mepc, mcause, mip)
  • Performance Counters (cycle, instret)

• Microarchitecture:

  • 5-Stage In-Order Pipeline (Single Issue)
  • Hazard Unit: Full bypassing/forwarding (EX->EX, MEM->EX, WB->EX) + Load-Use Stalls
  • Branch Prediction: Bimodal or Static (configurable)
  • Multi-cycle iterative Multiplier/Divider (pipeline-integrated)

• Interfaces:

  • Instruction/Data Memory Interfaces with Backpressure Support
  • Interrupt Support (Timer/External)

• RTL Language: SystemVerilog (Synthesizable subset, always_ff/always_comb)
• Simulation: Verilator (fast C++ simulation)
• Verification Framework: Python cocotb + pytest
• Linting: Verible (Google SystemVerilog Linter)
• Synthesis: Yosys (Open Source Synthesis)
• Infrastructure: Docker, Make

The core implements a classic 5-stage RISC-V pipeline.

1. IF (Fetch): Generates PC, fetches instruction from memory.
2. ID (Decode): Decodes opcode, reads Register File, generates controls.
3. EX (Execute): ALU operations, Branch calculation, Mul/Div execution.
4. MEM (Memory): Load/Store operations, talks to data memory/bus.
5. WB (Writeback): Writes results back to Register File.

• Data Hazards: Solved via forwarding network (e.g., ALU result forwarded to next instruction) or stalls (Load-Use).
• Control Hazards: Resolved in EX stage with flush penalty.

.
├── rtl/            # SystemVerilog Source Code (Synthesizable)
├── tb/             # Verification Suite
│   ├── unit/       # Pytest Unit Tests
│   ├── cocotb/     # Integration Tests
│   └── compliance/ # RISC-V Compliance Tests
├── sw/             # Software / Bare-metal C Tests
├── scripts/        # Build and Synthesis Scripts
├── asic/           # ASIC Feasibility (OpenLane)
├── docs/           # Architecture & Design Documentation
├── Makefile        # Canonical Build System
└── Dockerfile      # Reproducible Environment

• Docker (Recommended)
• Or manually install: Verilator, Python 3.8+, cocotb, pytest, verible, yosys, RISC-V GCC Toolchain.

If not using Docker, ensure all tools are in $PATH.

pip install -r requirements.txt

All commands are run from the project root.

• Privilege Modes: Only Machine Mode (M-Mode) is implemented. User/Supervisor modes are not supported.
• Virtual Memory: No MMU or biochemical memory support.
• Debug: JTAG/DM is not currently implemented.
• Caches: No I-Cache or D-Cache (direct bus access).

Contributions are welcome. Please ensure:

1. Lint Cleanliness: Code must pass make lint.
2. Test Passing: New features must include tests; make regress must pass.
3. Code Style: Follow the existing SystemVerilog coding style (enforced by Verible).

See repository root for license information.

• Hardware visuals: High-quality renders or block diagrams are currently missing from the media folder.
• Detailed Waveforms: Example specific waveform screenshots for bus transactions.