retroSoC
An open-source RISC-V SoC platform, from SystemVerilog RTL and firmware to reproducible verification and release artifacts.
Overview · Quick start · Configurations · Documentation · Validation · Contributing
Platform overview
Mini and Tiny have independent integration flows. Mini combines a low-power Hazard3 management hart and a T-Head OpenC906 application hart; its separate MPW profile retains selectable-core compatibility. Tiny is a wired MCU with one Hazard3 RV32IMC hart, 128 KiB SRAM, AXI4/APB4 and no wireless IP. Tiny defaults to ICS55 SAFE24 with a parked PLL and retains IHP130 compatibility; Std and Pro remain roadmap products. Qualification is determined by each profile's retained verification and physical reports.
The Tiny Gen1 datasheet provides the independent product, register, software and evidence reference using the established publication layout. Its build does not require Mini's HP or multimedia inputs.
| Area | Mini platform |
|---|---|
| Compute | Hazard3 LP management hart; locked pre-generated T-Head OpenC906 HP application hart. Baseline profiles compile LP firmware for RV32IM and use the OpenC906 DEFAULT RV64GC configuration with T-Head custom cache-maintenance instructions. |
| Memory and interconnect | Native AXI4 data plane, APB4 control, configurable on-chip SRAM, SDRAM, PSRAM/OPI-PSRAM, and XPI flash integration. |
| Control and I/O | GPIO, timers, UART, I2C, I2S, PWM, RTC, watchdog, storage interfaces, DMA, interrupt routing, and fixed EXT-L/EXT-H extension slots. |
| Software | Freestanding C runtime and HAL, board support, diagnostic and shell applications, CoreMark, and HP boot/bundle tooling. |
| Development | Locked toolchains and dependencies; Icarus Verilog and Verilator simulation, Yosys synthesis, OpenSTA timing analysis, and structured verification artifacts. |
The accelerator integrations include:
- APU — LP-loaded audio microcode, WAV/PCM and native FLAC decoding, I2S streaming, and optional keyword spotting (KWS). MP3 decoding is deferred.
- NPU — an INT8 inference engine with 64 dense MAC lanes, 64 KiB of private banked SRAM, offline compilation, and bare-metal deployment.
- GA2D — 2D fill, copy, pixel conversion, and alpha blending with opaque output and A8 foreground masks; no scaler or Linux driver.
- JPEG and crypto — dedicated image and cryptographic blocks with their own interface and verification contracts.
Capabilities depend on the selected profile and each IP's implementation and qualification status. Linux boot and performance qualification remain separate from baseline CI coverage. The integrated RNG uses an unqualified deterministic source for diagnostics; it does not provide production entropy. See the architecture and engineering guide for these boundaries.
Quick start
1. Prepare the development environment
Use the development environment guide to prepare the locked tools before building. The native environment targets Linux x86_64. Docker supports a Linux/amd64 environment, including emulation on Apple Silicon; Nix support is Linux x86_64 only.
| Environment | Setup instructions |
|---|---|
| Docker | Build and enter the development image. |
| Nix | Open the repository development shell. |
| Manual Ubuntu 22.04 | Bootstrap and activate the locked tools. |
For manual Ubuntu installs, first install the host packages from the
apt-get install list in docker/Dockerfile, including
Java 17. The bootstrap checks these tools but does not install OS packages.
Tools and checkout inputs are separate: the environment provides compilers and
EDA tools, while make setup retrieves the profile's managed sources, PDK,
and application inputs. Tool versions come from the
dependency lock.
2. Build and simulate Mini
From the repository root, inside the prepared environment:
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG setup
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG doctor
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG firmware sim
This runs the IHP130 profile's manual bringup application. It is not the
exact PR regression: automated Verilator runs select ci_smoke, while Icarus
regressions use the assembly self-test. See
supported flows for the overrides.
Keep firmware sim in the same Make invocation so both use one build variant.
Outputs live under build/<profile>-<YYYY-MM-DD-HH-MM>-<config-hash>/.
Check the flow logs and result JSON; UART startup text alone is not a pass.
Build and simulate Tiny
make CONFIG=configs/ci/ihp130-tiny.mk setup
make CONFIG=configs/ci/ihp130-tiny.mk doctor
make CONFIG=configs/ci/ihp130-tiny.mk firmware sim
make CONFIG=configs/ci/ihp130-tiny.mk SIMU=IVERILOG firmware sim
Tiny uses its own source lists and product maps under rtl/tiny. Its firmware
loads into on-chip SRAM without PSRAM/SDRAM initialization. The first release
uses a fixed 24 MHz clock and disables atomic instructions. Wireless, external
RAM, HP cores, accelerators and advanced low-power modes remain deferred.
Configurations and common flows
Start from a committed profile. These are selected entry points, not the complete profile or application inventory.
| Profile | Purpose |
|---|---|
| ICS55 Tiny | Default Tiny platform: 128 KiB SRAM, SAFE24 boot, PLL present but held off. |
| IHP130 Tiny | Explicit Tiny compatibility, 128 KiB SRAM, 24 MHz/no PLL. |
| IHP130 Mini | Manual bring-up with 32 KiB macro-backed SRAM. |
| GF180 / SKY130 | Alternative PDK profiles with 32 KiB macro-backed SRAM. |
| ICS55 Mini | Regression-compatible Mini profile with locked SRAM and PLL disabled. |
| Interactive shell | Shell firmware with CSR support enabled. |
| Hazard3 debug | JTAG acceptance using Verilator, OpenOCD, and GDB. |
| HP Linux | LP RV32IM / HP RV64IMAFDC Linux image/bundle flow and HP RTL validation; outside the supported PR matrix. |
| HP RT-Thread | Locked RT-Thread v5.3.0 M-mode kernel/platform acceptance on HP hart 1. |
| APU LP/HP | Audio and KWS evidence flow with ownership handoff to HP. |
| CoreMark | Fixed LP SRAM benchmark with the RV64 product HP core present. |
| Mini MPW | Legacy MPW C0-C3/user-IP compatibility, separate from the product ABI. |
Tiny's 2026-10-07 target refreeze
selects ICS55 with HAVE_PLL=YES and SAFE24 startup as the default.
The PLL starts parked off. The R2-P7 implementation
adds software-controlled SYS transitions; acceptance evidence is tracked in
the Tiny ledger and physical qualification remains pending. IHP130 remains
explicit compatibility.
Locked PLL views can be acquired
with python3 physical/pdk/setup.py --pdk ICS55 --component pll independently
of platform implementation or timing qualification.
After the corresponding setup, use these common commands:
# Build the interactive shell firmware
make CONFIG=configs/ci/ihp130-shell.mk firmware
# Inspect the effective configuration and available targets
make CONFIG=configs/ci/ihp130.mk config
make help
# Check source formatting and embedded C policy/host tests
make format-check
make sw-policy-check sw-host-test
| Validation flow | Command |
|---|---|
| IHP130 smoke: RTL lint, firmware, SVA compilation, Icarus self-test | make regress-smoke |
| IHP130 behavioral flows, including debug acceptance | make regress-rtl |
| Full local PR matrix across four PDKs | make regress-pr |
| Extended local regression | make regress-nightly |
Prepare the multi-PDK inputs with make setup-regression before the full PR
matrix. Profile setup does not install every optional reference corpus; follow
any additional prerequisites in the affected IP or test guide. For debugging,
benchmarks, and HP software, use the dedicated guides linked below.
Advanced local flows: netlist simulation and licensed VCS
These flows require the relevant synthesis/timing tools and PDK inputs, or a licensed VCS environment. Keep one timestamp across dependent commands:
export BUILD_TIMESTAMP=$(date +%Y-%m-%d-%H-%M)
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG RTL_SIM_TIMEOUT=5200000 sim-asm
make CONFIG=configs/ci/ihp130.mk SYNTH=YOSYS synth
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG \
SIM_FIRMWARE_NAME=retrosoc_asm RTL_SIM_TIMEOUT=5200000 netsim
make CONFIG=configs/ci/ihp130.mk STA=OPENSTA sta
VCS defaults to bsub -Is for licensed cluster runs. Disable LSF for a licensed
local run, or set VCS_RUNNER to the site's wrapper:
make CONFIG=configs/ci/ihp130.mk SIMU=VCS VCS_USE_LSF=NO firmware sim
After this sequence, unset BUILD_TIMESTAMP to restore automatic timestamps.
See build layout and
result policy for artifacts and verdicts.
Documentation and repository
| Start here | Guides |
|---|---|
| Understand the platform | LP/HP architecture, IP specifications, datasheet workflow. |
| Develop firmware | SDK, applications, HP software. |
| Debug and measure | Hazard3 debug, CoreMark, engineering workflow. |
| Change RTL or tooling | RTL conventions, MISRA policy, agent contract. |
| Explore further | Documentation index, build profiles, contribution process. |
| Directory | Contents |
|---|---|
| rtl/ | SoC integration, IP, interfaces, simulation, and technology wrappers. |
| crt/ / app/ | Freestanding SDK, firmware applications, and software integrations. |
| configs/ / dependencies/ | Reproducible profiles and locked external inputs. |
| tests/ / scripts/ / quality/ | Verification, build helpers, and executable quality policy. |
| physical/ / fpga/ | Physical-design flows and FPGA integration. |
| docs/ / publications/ | Engineering specifications and manually built datasheets. |
| .github/ / docker/ | Automation and the container development environment. |
Validation and reproducibility
The status badges above track main, not the current checkout. Other runs:
GF180,
ICS55,
SKY130,
and nightly.
The quality gate checks source policy and runs script/RTL fixture tests.
Hosted SoC regression and development-environment workflows use
--behavioral-only: they do not run the full SoC synthesis, netlist simulation,
or OpenSTA stages. Local full-flow commands retain those stages. Neither CI
status nor core timing analysis establishes physical or silicon signoff.
Dependencies and tool archives are pinned by revision or checksum. Each build
variant records its configuration and lock digest, and EDA flows produce logs
and structured results. Warning and metric policies remain defined by the
engineering guide; no performance claim is implied by
a badge. Maintainer-published v* tags trigger
release packaging, including the source
archive, manifest, dependency lock, SBOM, and checksums.
Contributing
Start with the contribution guide, follow the
Git workflow, and use the
PR template. Ordinary contributions target
dev and preserve meaningful commits through merge-commit integration.
Please follow the Code of Conduct.
retroSoC is licensed under Mulan PSL v2. Third-party terms are recorded in NOTICE, ATTRIBUTIONS, and licenses/. See the existing security policy for its current reporting information.
Thanks to everyone contributing to retroSoC.