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 VexiiRiscv 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 first targets IHP130; 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; generated dual-issue VexiiRiscv HP application hart. Baseline profiles compile LP firmware for RV32IM and select an RV32IMAFDC HP core with Zicbom cache maintenance.
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
IHP130 Tiny	Single-hart wired MCU, 128 KiB SRAM, pin-level Flash boot and automated acceptance.
IHP130 Mini	Manual bring-up with 32 KiB macro-backed SRAM.
GF180 / SKY130	Alternative PDK profiles with 32 KiB macro-backed SRAM.
ICS55	Regression-compatible profile with SRAM and PLL disabled.
Interactive shell	Shell firmware with CSR support enabled.
Hazard3 debug	JTAG acceptance using Verilator, OpenOCD, and GDB.
HP Linux	HP image/bundle flow; outside the supported PR matrix.
APU LP/HP	Audio and KWS evidence flow with ownership handoff to HP.
CoreMark	Fixed LP SRAM benchmark with the product HP core present.
Mini MPW	Legacy C0-C3/user-IP compatibility, separate from the product ABI.

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.