🎮 RISCBoy: A Custom-Built Open-Source Handheld

RISCBoy is a comprehensive, open-source project to create a portable gaming machine designed entirely from the ground up. It isn't just a software project; it encompasses the CPU, the graphics engine, the PCB, and everything in between.

"It is a Gameboy Advance from a parallel universe alternate reality where RISC-V existed in 2001. A love letter to the handhelds of my youth, and a 3AM drunk text to the tech that made them possible."

---

🛠️ System Architecture

The project is implemented using synthesisable Verilog 2005. The primary target is the iCE40-HX8k FPGA. Because this chip only provides $\approx 7680$ logic elements (LUT4-based), fitting a full 32-bit console is a tight squeeze—requiring either a crowbar and some vaseline extremely meticulous design.

Hardware Components

• CPU: A custom RISC-V compatible processor.
• Graphics: A dedicated raster graphics pipeline and display controller.
• Infrastructure:
  • Bus fabric
  • Memory controllers
  • GPIO and UART interfaces
• Physical: A full PCB layout designed in KiCad.

High-Level Logic Flow

---

💻 Processor Specifications

The heart of the RISCBoy is a processor supporting the RV32IMC instruction set. It has been rigorously validated using the RISC-V compliance suite, the riscv-formal verification tool, and custom formal property checks to ensure bus compliance and frontend consistency.

Feature Set

• M-mode CSRs
• Exception handling
• Compliant extension for vectored external interrupts

ISA Variants

Depending on the FPGA size, you can choose between different processor configurations:

Warning: Linking an RV32I executable against an RV32IMC standard library on an RV32I-only chip will ruin your day!

---

🚀 Getting Started

1. Cloning the Repository

Since the project relies on submodules for the HDL and test suites, you must clone recursively:

# Option A: Direct recursive clone
git clone --recursive https://github.com/Wren6991/RISCBoy.git riscboy

# Option B: Manual submodule update
git clone https://github.com/Wren6991/RISCBoy.git riscboy
cd riscboy
git submodule update --init --recursive

2. Building the RV32IMC Toolchain

To compile software tests, you need the RISC-V GNU Toolchain. For Ubuntu 20.04, follow these steps:

• Install prerequisites
• Clone the toolchain
• Configure and build

# Install dependencies
sudo apt install -y autoconf automake autotools-dev curl python3 libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev

# Setup toolchain
cd /tmp
git clone --recursive https://github.com/riscv/riscv-gnu-toolchain
cd riscv-gnu-toolchain

# Critical configuration for RISCBoy
./configure --prefix=/opt/riscv --with-arch=rv32imc --with-abi=ilp32 --with-multilib-generator="rv32i-ilp32--;rv32ic-ilp32--;rv32im-ilp32--;rv32imc-ilp32--"

sudo mkdir /opt/riscv
sudo chown $(whoami) /opt/riscv
make -j $(nproc)

---

🧪 Simulation & Debugging

The simulation environment is powered by Xilinx ISIM 14.x. Makefiles are located in the scripts/ directory.

Running HDL Tests:

1. Source the environment: . sourceme
2. Navigate to tests: cd test
3. Execute: ./runtests

Note: If ISIM is not in the default path, you may need to edit the sourceme file.

Graphical Debugging: To debug a specific test (e.g., helloworld) via GUI:

cd system
make TEST=helloworld gui

---

🔌 Physical Hardware (PCB)

The current Rev A board is a $5 \times 5\text{ cm}$ design compatible with iTead's 4-layer prototyping service.

• Schematics: Available via PDF.
• Current Status: Rev B is in planning; the author is waiting for the bootloader and gateware to stabilize.
• Dev Hardware: Currently resembles the Snowflake FPGA board.

---

⚡ Synthesis

The project utilizes an open-source toolchain for iCE40 synthesis. This is primarily supported on Linux.

Required Tools

1. Yosys (Synthesis)
2. nextpnr (Place and Route)
3. Project Icestorm (Bitstream generation)

Generating Bitstreams

To create an image for the Lattice HX8k Evaluation Board:

. sourceme
cd synth
make -f HX8k-EVN.mk bit

To create a full build for the Lattice LEF5UM5G-85F-EVN (ECP5):

make -f ECP5-EVN.mk BUILD=full bit