grahamedgecombe / icicle

32-bit RISC-V system on chip for iCE40 FPGAs
ISC License
299 stars 52 forks source link
fpga ice40 icestorm risc-v

Icicle 2

Introduction

Icicle is a 32-bit RISC-V soft processor and system-on-chip, primarily designed for iCE40 (including the UltraPlus series) FPGAs. It can be built with open-source tools.

The original version of Icicle was written in SystemVerilog. This version is written in Amaranth, making the code cleaner and more flexible. Changes to the microarchitecture have made the core significantly smaller and faster.

The Pipeline and Stage classes are inspired by Minerva's pipeline system, though there are some significant differences.

Features

Microarchitecture

Icicle uses a 6-stage pipeline, similar to a classic RISC pipeline. The main differences are summarized below:

The pipeline is fully interlocked. Adding bypassing support would be complicated by the multiplexer changes described above. Furthermore, enabling bypassing in the previous version of Icicle increased the size of the core and reduced the clock frequency by a relatively significant amount on iCE40 FPGAs, which are the primary target.

Icicle is theoretically capable of issuing and retiring one instruction per cycle, if the memory bus can keep up. In reality, the IPC will be slightly lower than this due to stalls and flushes caused by data hazards and branch mispredictions.

The system-on-chip examples distributed with Icicle are currently only capable of issuing one instruction every two cycles, as:

This could be improved with:

Dependencies

Building

Run the following command to install Icicle locally, including its dependencies:

pip install -e .

The icicle command is a thin wrapper around amaranth.cli. Run the following command to compile the Icicle processor core to Verilog:

icicle generate -t v > icicle.v

The icicle command has some flags for customizing the generated core. Run icicle --help for full usage information.

System-on-chip examples

Icicle ships with example system-on-chip designs for several development boards. A single command will build and flash the system-on-chip to your FPGA. Simply connect the development board to your computer and run the appropriate command from the table below, appending the --flash flag:

Board Command Notes
iCEBreaker icicle-icebreaker
iCE40-HX8K Breakout Board icicle-ice40-hx8k-b-evn Configure jumpers for SRAM programming.
ECP5 Evaluation Board icicle-ecp5-5g-evn

For example, run the following command to build and flash to the iCEBreaker board:

icicle-icebreaker --flash

The iCEBreaker board is Icicle's primary target. It is inexpensive, beginner-friendly and fully compatible with the open-source toolchain.

Example programs

Icicle also ships with some example programs to demonstrate the system-on-chip. Run the following commands to build them and flash the blinky example to the iCEBreaker board:

make -C examples PLATFORM=icebreaker
iceprog -o 1M examples/blinky.bin

Testing

There are a small number of non-exhaustive tests that simulate portions of the processor core. These were primarily used to test standalone modules during development before the full formal verification infrastructure was ready.

They are still useful as they are significantly quicker than verifying the entire core - providing a quicker feedback cycle during development. Use the following command to run them:

python -m unittest

However, despite the existence of the unit tests, formally verifying the core after a change is completed is still strongly recommended.

Formal verification

Icicle supports the RISC-V Formal Interface (RVFI), allowing it to be formally verified with riscv-formal.

Clone the riscv-formal repository:

git clone https://github.com/SymbioticEDA/riscv-formal.git

Clone Icicle in the cores subdirectory:

cd riscv-formal/cores && git clone https://github.com/grahamedgecombe/icicle.git

Run the following commands to verify the processor core:

cd icicle
../../checks/genchecks.py
make -C checks -j $(nproc)
sby complete.sby
./equiv.sh

Size and performance

FPGA family Logic cells Frequency
iCE40 HX ~1,000 ~75 MHz
iCE40 UP ~1,000 ~30 MHz
ECP5 8_5G ~900 ~140 MHz

The numbers in the table above refer to the processor core in its default configuration only. The rest of the system-on-chip is not included.

License

This project is available under the terms of the ISC license, which is similar to the 2-clause BSD license. See the LICENSE file for the copyright information and licensing terms.