SoCeteer - A framework for designing and running RISC-V-based SoCs on FPGA and in Simulation, built on top of Chisel.
From a Scala design to a Linux shell on your board.
Important
This project is in early development and is NOT ready for any serious use. We recommend using SoCeteer for experimentation and learning purposes only at this time. For a more stable experience, please use the tagged releases.
| RocketChip | The reference RISC-V core generator: in-order cores with caches, MMU and supervisor support; the default config |
| BOOM | A superscalar out-of-order RISC-V core, for when single-thread performance matters |
| Shuttle | A superscalar in-order RISC-V core - more throughput than RocketChip without going out-of-order |
| Saturn | A RISC-V vector unit (RVV) that attaches to RocketChip and Shuttle cores |
| Gemmini | A systolic-array ML accelerator, attached to a core as a RoCC coprocessor |
| L2 cache | SiFive's inclusive last-level cache, shared by all cores and added through a single config |
| Nail | A fault-injection and reliability-evaluation framework (built on Chiffre): bit flips and stuck-at faults injected into the running design, controlled from software. Not a submodule - clone it into generators/ and the build picks it up |
| Configs | Cores are picked, sized and combined through Chisel configs; both Chisel generations are supported (edu.berkeley.cs 3.6.1, org.chipsalliance 7.13.0) |
| Block-design DSL | Components, connections, clock domains and timing constraints written in Scala - every line of Vivado TCL is generated |
| Memory | --ext-mem-part names the DIMM you inserted; capacity, device tree and address decode follow - including modules the board's preset does not know |
| Boards | ZCU104, VCU118 - a new board is one Scala definition |
| Simulation | The design runs under Verilator: host-bridged syscalls, waveform tracing, and live GDB debugging of the simulated SoC |
| FPGA builds | The launcher drives Vivado from project generation to the finished bitstream, locally or on a remote build server |
| Runs anywhere | Docker images for x86_64 and ARM64; native on Linux, macOS and Windows |
| Boot image | One BOOT.ELF - firmware, kernel and BusyBox userspace - loaded from the SD card or over JTAG; device tree, memory map and console come from the design, so one kernel serves every design |
| Shell image | Boots into a BusyBox shell on the serial console and the monitor alike; reboot works |
| Persistent storage | soct keeps a persistent environment on the SD card or a USB stick - files and shell history survive reboots |
| Drivers | Out-of-tree kernel modules build with the rest in one CMake target and land in the boot image; an SD-card driver ships in-tree (/dev/mmcblk0) |
| Toolchains | CMake projects for boot ROMs and bare-metal programs; a separate LLVM/musl project for everything Linux - toolchains are fetched or auto-detected |
| Display | The Linux console on a DisplayPort monitor (guide, internals), with a display that CPU load cannot starve |
| Video tools | Runtime resolution switching (fbmode) and a framebuffer image viewer (fbimg) ship in the image |
| USB | Host controller on by default on MPSoC boards: keyboard plus monitor make the board a self-contained terminal, and USB sticks can carry the persistent environment |
git clone --recurse-submodules https://github.com/soct-org/SoCeteer.git
# If already cloned without submodules: git submodule update --init --recursiveThen follow Setting up SoCeteer: host packages, the IDE projects and a first generated design. Alternatively, the prebuilt Docker image carries every host dependency (Dockerfile):
docker run --rm -it -u $(id -u):$(id -g) -v "$PWD":/soceteer -w /soceteer ghcr.io/soct-org/soceteer:latest bashGuides - step-by-step example runs:
- Setting up SoCeteer - from the clone to the IDE projects and a first generated design
- Running a Design in Simulation - the design in Verilator: no board needed, console on the terminal, waveforms on demand
- From Design to Bitstream - generate a design and let the launcher drive Vivado to a bitstream
- Remote Development - build and flash through a server that has Vivado and the board
- Monitor & Linux Programs - the full run: Linux from SD, a DisplayPort console, persistent storage on the card
Systems - per-subsystem internals and reference: the hardware flow, the block-design
DSL, memory, the Linux boot chain, the video pipeline and more, plus the glossary and the
Scaladoc API reference. Everything is on the documentation site
(rendered through htmlpreview) - or open docs/docs.html from the clone (sbt buildDocs
regenerates the API reference). All launcher options: sbt "runMain soct.SOCTLauncher --help".