mirror of
https://github.com/retroSoC/retroSoC.git
synced 2026-11-04 22:32:36 +00:00
Merge branch 'dev' of github.com:retroSoC/retroSoC into dev
This commit is contained in:
maksyuki committed
commit
d084002bfe
9 files changed
+262
-282
No files matched your search
@@ -1,70 +1,22 @@
|
||||
# retroSoC
|
||||
|
||||
An open-source RISC-V SoC platform, from SystemVerilog RTL and firmware to reproducible verification and release artifacts.
|
||||
|
||||
[](LICENSE)
|
||||
[](rtl)
|
||||
[](configs/ci/ihp130.mk)
|
||||
[](configs/ci/ihp130.mk)
|
||||
[](dependencies/dependencies.lock.json)<br>
|
||||
[](https://github.com/retroSoC/retroSoC/actions/workflows/regression-ihp130.yml)
|
||||
[](https://github.com/retroSoC/retroSoC/actions/workflows/regression-gf180.yml)
|
||||
[](https://github.com/retroSoC/retroSoC/actions/workflows/regression-ics55.yml)
|
||||
[](https://github.com/retroSoC/retroSoC/actions/workflows/regression-sky130.yml)
|
||||
[](https://github.com/retroSoC/retroSoC/actions/workflows/regression-sky130.yml)<br>
|
||||
[](https://github.com/retroSoC/retroSoC/actions/workflows/quality.yml)
|
||||
[](https://github.com/retroSoC/retroSoC/actions/workflows/nightly.yml)
|
||||
[](https://github.com/retroSoC/retroSoC/actions/workflows/development-environment.yml?query=branch%3Amain)
|
||||
|
||||
retroSoC is a fully open-source RISC-V SoC project. The repository brings together
|
||||
SystemVerilog RTL, a freestanding embedded C SDK and applications, simulation, synthesis,
|
||||
static timing analysis, reproducible dependencies, and release packaging. It is licensed
|
||||
under the [Mulan Permissive Software License, Version 2](LICENSE).
|
||||
[Overview](#platform-overview) · [Quick start](#quick-start) · [Configurations](#configurations-and-common-flows) · [Documentation](#documentation-and-repository) · [Validation](#validation-and-reproducibility) · [Contributing](#contributing)
|
||||
|
||||
## Highlights
|
||||
|
||||
- A fixed asymmetric dual-core Mini product: Hazard3 is the LP management hart
|
||||
and generated dual-issue RV64IMAFDC VexiiRiscv is the HP application hart.
|
||||
The C0-C3 selectable cores remain only in the explicit Mini MPW profile.
|
||||
- A product [LP/HP architecture](docs/lp-hp-architecture.md) with independent
|
||||
AON, LP, HP, PCLK, memory, audio, pixel, JTAG, and ULPI clock/reset contracts,
|
||||
a native AXI64 HP data plane, fixed EXT-L/EXT-H slots,
|
||||
HP CLINT/PLIC, UART1, mailbox, locked OpenSBI/Linux/Buildroot inputs, and a
|
||||
CRC-checked direct-Linux boot bundle. Linux boot and performance evidence are
|
||||
release gates, not yet baseline CI claims.
|
||||
- A documented [Tiny/Mini/Std/Pro product direction](docs/soc-family-positioning.md)
|
||||
anchored by Mini and a trusted Hazard3 management model. The higher Linux,
|
||||
graphics, AI, and RV64 configurations are roadmap targets, not supported
|
||||
build profiles.
|
||||
- A standard five-pad JTAG Debug Transport Module for the Hazard3 management
|
||||
core, with a reproducible Verilator, OpenOCD, and GDB acceptance flow.
|
||||
- Configurable GF180, SKY130, IHP130, and ICS55 implementation targets with
|
||||
open-source CI coverage.
|
||||
- A memory-mapped peripheral subsystem with GPIO, UART,
|
||||
[dual general timers](docs/ip/timer.md),
|
||||
[PWM V2](rtl/managed/clusterip/pwm/doc/datasheet.md),
|
||||
[dual I2C controllers](docs/ip/i2c.md), I2S,
|
||||
[bidirectional PS/2](docs/ip/ps2.md),
|
||||
WS2812, SPI/QSPI, SDIO, PSRAM/[OPI-PSRAM](docs/ip/opipsram.md), SDRAM, DMA, LCD, RTC, an
|
||||
independent-clock window watchdog, CRC, and a
|
||||
management-only RNG entropy controller. The P5 [GA2D](docs/ip/ga2d.md) is an
|
||||
ownership-routed, PCLK-controlled, direct single-job private-AXI64 2D engine
|
||||
with FILL, COPY, bit-exact CONVERT, opaque alpha BLEND, A8 fixed-color
|
||||
foreground masks, and exact equal background/destination in-place composition.
|
||||
Color surfaces are RGB565, RGB888, XRGB8888, and ARGB8888; A8 is BLEND
|
||||
foreground-only. It retains pitch, byte-edge, snapshot, and IRQ support at
|
||||
the existing APB4_GA2D window. It does not provide transparent-background or
|
||||
premultiplied-alpha modes, a scaler or renderer, descriptors/rings/queues,
|
||||
cache coherency, or a Linux graphics driver.
|
||||
The current deterministic RNG integration source is
|
||||
explicitly unqualified and intended only for diagnostics until a PDK-qualified entropy source is integrated.
|
||||
support. Available interfaces depend on the selected SoC configuration.
|
||||
- A standalone RISC-V runtime, HAL, board support, middleware, and `benchmark`, `bringup`,
|
||||
`coremark`, `debug`, and `shell` applications.
|
||||
- Open-source behavioral simulation with Icarus Verilog and Verilator,
|
||||
synthesis with Yosys, netlist simulation with Icarus Verilog, and timing
|
||||
analysis with OpenSTA.
|
||||
- Read-only ARCHINFO ABI discovery for build/configuration provenance, SoC
|
||||
topology, technology capabilities, and lifecycle-gated device identity.
|
||||
- Checksum-verified dependency and toolchain locks, structured flow results, warning
|
||||
baselines, metrics collection, SBOM generation, and checksummed release packages.
|
||||
|
||||
## Repository Layout
|
||||
## Platform overview
|
||||
|
||||
**Mini and Tiny have independent integration flows.** Mini combines a
|
||||
low-power Hazard3 management hart and a VexiiRiscv application hart; its separate
|
||||
@@ -79,148 +31,75 @@ independent product, register, software and evidence reference using the
|
||||
established publication layout. Its build does not require Mini's HP or
|
||||
multimedia inputs.
|
||||
|
||||
| Path | Contents |
|
||||
| Area | Mini platform |
|
||||
| --- | --- |
|
||||
| [`rtl/`](rtl) | SoC RTL, CPU integration, peripherals, interfaces, testbenches, and technology wrappers. |
|
||||
| [`dependencies/`](dependencies) | Locked external repositories, archives, toolchains, and environment inputs. |
|
||||
| [`crt/`](crt) | Freestanding RISC-V startup code, linker scripts, runtime library, core services, and HAL headers. |
|
||||
| [`app/`](app) | Applications, board support, media, middleware, networking, ports, and benchmarks. |
|
||||
| [`configs/`](configs) | Versioned build profiles for CI, nightly, and cluster flows. |
|
||||
| [`physical/`](physical) | Physical-design entry points, managed PDK integration, and smoke synthesis/STA flows. |
|
||||
| [`scripts/`](scripts) and [`quality/`](quality) | Build helpers, regression orchestration, checks, warning baselines, and metric policy. |
|
||||
| [`.github/`](.github) | GitHub automation, Dependabot configuration, and CI/release workflows; see [`GUIDE.md`](.github/GUIDE.md). |
|
||||
| [`docs/`](docs) | Engineering workflow and release-process documentation. |
|
||||
| [`publications/`](publications) | Manually built Typst datasheets and versioned publication media. |
|
||||
| Compute | Hazard3 LP management hart; generated dual-issue VexiiRiscv HP application hart. Baseline profiles compile LP firmware for RV32IM and select an RV64IMAFDC 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. |
|
||||
|
||||
## Supported Configurations
|
||||
The accelerator integrations include:
|
||||
|
||||
The committed profiles are the supported starting points. They select an ISA,
|
||||
PDK, application, linker layout, and optional features as one reproducible
|
||||
configuration. Product profiles set `MINI_MODE=PRODUCT`, fix both CPU harts,
|
||||
and report zero selectable user cores. `configs/cluster/mini-mpw.mk` is the
|
||||
separate `MINI_MODE=MPW` compatibility profile for C0-C3.
|
||||
`SRAM_SIZE_KIB` selects a generated 4/16/32/64/128 KiB native-AXI4 on-chip
|
||||
SRAM window. The IHP130, GF180, and SKY130 CI profiles enable a 32 KiB macro-backed
|
||||
window; committed ICS55 regression profiles deliberately keep SRAM and PLL
|
||||
disabled. `configs/local/ics55.example.mk` documents the ignored local profile
|
||||
used with commercial 32 KiB SRAM and PLL simulation models.
|
||||
- **[APU](docs/ip/apu.md)** — LP-loaded audio microcode, WAV/PCM and native FLAC
|
||||
decoding, I2S streaming, and optional keyword spotting (KWS). MP3 decoding
|
||||
is deferred.
|
||||
- **[NPU](docs/ip/npu.md)** — an INT8 inference engine with 64 dense MAC lanes,
|
||||
64 KiB of private banked SRAM, offline compilation, and bare-metal deployment.
|
||||
- **[GA2D](docs/ip/ga2d.md)** — 2D fill, copy, pixel conversion, and alpha
|
||||
blending with opaque output and A8 foreground masks; no scaler or Linux driver.
|
||||
- **[JPEG](docs/ip/jpeg.md) and [crypto](docs/ip/crypto.md)** — dedicated image
|
||||
and cryptographic blocks with their own interface and verification contracts.
|
||||
|
||||
| Profile | ISA | Application | Coverage |
|
||||
| --- | --- | --- | --- |
|
||||
| [`configs/ci/ihp130.mk`](configs/ci/ihp130.mk) | RV32IM | `bringup` | Firmware and behavioral regression with a 32 KiB IHP SRAM; local full-flow commands also support Yosys, netlist Icarus, and OpenSTA. |
|
||||
| [`configs/ci/gf180.mk`](configs/ci/gf180.mk) | RV32IM | `bringup` | Firmware and behavioral regression with a 32 KiB SRAM assembled from GF180 macros; local full-flow commands support synthesis and timing. |
|
||||
| [`configs/ci/ics55.mk`](configs/ci/ics55.mk) | RV32IM | `bringup` | Firmware and behavioral regression without a public SRAM macro; local full-flow commands support synthesis and core timing. |
|
||||
| [`configs/ci/sky130.mk`](configs/ci/sky130.mk) | RV32IM | `bringup` | Firmware and behavioral regression with a 32 KiB OpenRAM SRAM; local full-flow commands support synthesis and timing. |
|
||||
| [`configs/ci/ihp130-shell.mk`](configs/ci/ihp130-shell.mk) | RV32IM | `shell` | Pull-request firmware build with CSR support enabled. |
|
||||
| [`configs/ci/ihp130-debug.mk`](configs/ci/ihp130-debug.mk) | RV32IM | `debug` | Verilator remote-bitbang acceptance of the Hazard3 JTAG DTM, Debug Module, OpenOCD, and GDB. |
|
||||
| [`configs/ci/ihp130-hp.mk`](configs/ci/ihp130-hp.mk) | LP RV32IM / HP RV64IMAFDC | `hp_boot` | Linux image/bundle flow and HP RTL validation on the fixed product topology. |
|
||||
| [`configs/ci/ihp130-rtthread.mk`](configs/ci/ihp130-rtthread.mk) | LP RV32IM / HP RV64IMAFDC | `hp_boot` | Locked RT-Thread v5.3.0 M-mode kernel/platform acceptance on HP hart 1. |
|
||||
| [`configs/benchmark/ihp130-hazard3-coremark.mk`](configs/benchmark/ihp130-hazard3-coremark.mk) | LP RV32IM / HP RV64IMAFDC+Zicbom | `coremark` | Fixed four-iteration LP SRAM CoreMark measurement with the product HP core present. |
|
||||
| [`configs/cluster/ics55.mk`](configs/cluster/ics55.mk) | LP RV32IM / HP RV64IMAFDC+Zicbom | `bringup` | Site profile with PLL/SRAM intentionally disabled for regression compatibility. |
|
||||
| [`configs/cluster/mini-mpw.mk`](configs/cluster/mini-mpw.mk) | RV32IM | `bringup` | Legacy MPW C0-C3/user-IP selection profile; not part of the Mini product ABI. |
|
||||
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](docs/lp-hp-architecture.md) and [engineering guide](docs/engineering.md)
|
||||
for these boundaries.
|
||||
|
||||
CI Verilator firmware simulations explicitly select the `ci_smoke`
|
||||
application, which checks UART, archinfo APB readback, macro-backed on-chip SRAM,
|
||||
the GA2D direct 2D route including CONVERT/BLEND/A8 in-place acceptance, RNG
|
||||
fail-closed behavior, and test-status completion without the verbose startup
|
||||
report. ARCHINFO checks include its
|
||||
ABI and the build/configuration identifiers generated for that variant. The
|
||||
IHP130 PR run links this image into the 32 KiB SRAM, explicitly enables the
|
||||
fast-flash backend, and allows 360 seconds; Icarus keeps the real serial XPI
|
||||
boot-model check. The profiles retain `bringup`
|
||||
as their default for manual diagnostics. To run the full report in Verilator,
|
||||
use:
|
||||
## Quick start
|
||||
|
||||
### 1. Prepare the development environment
|
||||
|
||||
Use the [development environment guide](docs/development-environment.md) 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](docs/development-environment.md#docker). |
|
||||
| Nix | [Open the repository development shell](docs/development-environment.md#nix). |
|
||||
| Manual Ubuntu 22.04 | [Bootstrap and activate the locked tools](docs/development-environment.md#shared-bootstrap). |
|
||||
|
||||
For manual Ubuntu installs, first install the host packages from the
|
||||
`apt-get install` list in [docker/Dockerfile](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](dependencies/dependencies.lock.json).
|
||||
|
||||
### 2. Build and simulate Mini
|
||||
|
||||
From the repository root, inside the prepared environment:
|
||||
|
||||
```sh
|
||||
make CONFIG=configs/ci/ihp130.mk APP=bringup SIMU=VERILATOR SOC_SIM_TIME=300 firmware sim
|
||||
|
||||
# Firmware, RTL lint, debug, and behavioral simulation without synthesis/STA
|
||||
make regress-rtl
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The open-source development environment contains the exact Ubuntu 22.04 tool bundles, Python
|
||||
quality tools, compiler, formatters, simulators, synthesis, STA, and formal tools used by the
|
||||
current regression. It does not contain PDKs, managed RTL, or application archives; those remain
|
||||
checkout-local inputs installed and verified through the existing setup targets. Linux x86_64 is
|
||||
the supported host for the full native environment. On macOS, use Docker with linux/amd64
|
||||
emulation. Nix support is Linux x86_64 only.
|
||||
|
||||
Choose one of the following installation methods. Each uses the locked versions in
|
||||
[dependencies/dependencies.lock.json](dependencies/dependencies.lock.json) and creates or reuses the local
|
||||
cache at .cache/retrosoc/development.
|
||||
|
||||
### Nix
|
||||
|
||||
Install Nix with flakes enabled, then run the development application from the repository root.
|
||||
It builds a Linux FHS environment and invokes the same locked bootstrap script as Docker and the
|
||||
manual method.
|
||||
|
||||
~~~sh
|
||||
nix run .#dev -- make setup-regression
|
||||
nix run .#dev -- make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG doctor
|
||||
nix run .#dev -- make regress-pr
|
||||
~~~
|
||||
|
||||
Use nix run .#dev without a command to open an interactive shell. The pinned nixpkgs revision is
|
||||
recorded in flake.lock and cross-checked against the dependency lock.
|
||||
|
||||
### Docker
|
||||
|
||||
Build the local image once. The base image is immutable by digest and the image bootstrap installs
|
||||
the same locked tools into an image-local cache. Mount the checkout so generated files, PDKs, and
|
||||
managed sources remain on the host volume.
|
||||
|
||||
~~~sh
|
||||
docker build --tag retrosoc-dev --file docker/Dockerfile .
|
||||
docker run --rm --init --platform linux/amd64 --user "$(id -u):$(id -g)" -it \
|
||||
-v "$PWD:/workspace/retrosoc" retrosoc-dev \
|
||||
make setup-regression
|
||||
docker run --rm --init --platform linux/amd64 --user "$(id -u):$(id -g)" -it \
|
||||
-v "$PWD:/workspace/retrosoc" retrosoc-dev \
|
||||
make regress-pr
|
||||
~~~
|
||||
|
||||
### Manual Installation
|
||||
|
||||
On Ubuntu 22.04, install the host packages used by CI, then run the shared bootstrap script. It
|
||||
downloads only checksum-verified tool bundles and Python packages pinned by the repository.
|
||||
|
||||
~~~sh
|
||||
sudo apt-get update
|
||||
sudo apt-get install --no-install-recommends --yes \
|
||||
bzip2 ca-certificates ccache clang-format-14 g++ git libfl2 libgoogle-perftools4 \
|
||||
libunwind8 make mold numactl python3 python3-pip python3-venv xz-utils zlib1g
|
||||
python3 scripts/development_environment.py bootstrap
|
||||
source .cache/retrosoc/development/activate.sh
|
||||
make setup-regression
|
||||
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG setup
|
||||
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG doctor
|
||||
~~~
|
||||
|
||||
Run python3 scripts/development_environment.py check after a lock update or when diagnosing a
|
||||
local tool issue. The lock file also pins external RTL, PDK, benchmark, and application sources.
|
||||
Their setup scripts verify full Git revisions or SHA-256 checksums before use. See the
|
||||
[engineering workflow](docs/engineering.md#reproducible-inputs) for the dependency update
|
||||
procedure.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Start with the CI-verified IHP130 `bringup` profile. `setup` retrieves the pinned
|
||||
source dependencies, and `doctor` reports any missing local executables or setup inputs.
|
||||
|
||||
```sh
|
||||
make CONFIG=configs/ci/ihp130.mk setup
|
||||
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG doctor
|
||||
make CONFIG=configs/ci/ihp130.mk firmware
|
||||
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG sim
|
||||
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG firmware sim
|
||||
```
|
||||
|
||||
Select the interactive shell application without editing source files:
|
||||
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](docs/engineering.md#supported-profiles) for the overrides.
|
||||
|
||||
```sh
|
||||
make CONFIG=configs/ci/ihp130-shell.mk firmware
|
||||
```
|
||||
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
|
||||
|
||||
@@ -249,120 +128,122 @@ points, not the complete profile or application inventory.
|
||||
| [ICS55](configs/ci/ics55.mk) | Regression-compatible profile with SRAM and PLL disabled. |
|
||||
| [Interactive shell](configs/ci/ihp130-shell.mk) | Shell firmware with CSR support enabled. |
|
||||
| [Hazard3 debug](configs/ci/ihp130-debug.mk) | JTAG acceptance using Verilator, OpenOCD, and GDB. |
|
||||
| [HP Linux](configs/ci/ihp130-hp.mk) | HP image/bundle flow; outside the supported PR matrix. |
|
||||
| [HP Linux](configs/ci/ihp130-hp.mk) | LP RV32IM / HP RV64IMAFDC Linux image/bundle flow and HP RTL validation; outside the supported PR matrix. |
|
||||
| [HP RT-Thread](configs/ci/ihp130-rtthread.mk) | Locked RT-Thread v5.3.0 M-mode kernel/platform acceptance on HP hart 1. |
|
||||
| [APU LP/HP](configs/ci/ihp130-apu.mk) | Audio and KWS evidence flow with ownership handoff to HP. |
|
||||
| [CoreMark](configs/benchmark/ihp130-hazard3-coremark.mk) | Fixed LP SRAM benchmark with the product HP core present. |
|
||||
| [Mini MPW](configs/cluster/mini-mpw.mk) | Legacy C0-C3/user-IP compatibility, separate from the product ABI. |
|
||||
| [CoreMark](configs/benchmark/ihp130-hazard3-coremark.mk) | Fixed LP SRAM benchmark with the RV64 product HP core present. |
|
||||
| [Mini MPW](configs/cluster/mini-mpw.mk) | Legacy MPW C0-C3/user-IP compatibility, separate from the product ABI. |
|
||||
|
||||
After the corresponding setup, use these common commands:
|
||||
|
||||
## Common Flows
|
||||
|
||||
All commands use a committed profile. `make config` prints the effective configuration and
|
||||
variant identifier; `make help` lists all available targets. Netlist simulation and timing
|
||||
analysis consume the Yosys netlist, so run the synthesis command first. The CI-proven netlist
|
||||
regression uses the assembly self-test image:
|
||||
|
||||
Verilator simulations run for 180 seconds by default. The IHP130 `ci_smoke`
|
||||
regression explicitly uses 360 seconds because its LP memory accesses traverse
|
||||
the asynchronous data gateway. Set `SOC_SIM_TIME` explicitly only when an
|
||||
exploratory local run needs a different limit.
|
||||
|
||||
VCS flow commands use `bsub -Is` by default: this includes parse-time Python helpers used to
|
||||
calculate the variant and dependency-lock digest, generated-flow Python helpers, VCS, `simv`, and
|
||||
Verdi. In a licensed local VCS environment, run without LSF submission using `VCS_USE_LSF=NO`; an
|
||||
explicit `VCS_RUNNER` takes precedence when a site-specific queue or wrapper is required:
|
||||
|
||||
```sh
|
||||
make CONFIG=configs/ci/ihp130.mk SIMU=VCS VCS_USE_LSF=NO sim
|
||||
make CONFIG=configs/ci/ihp130.mk SIMU=VCS VCS_RUNNER='bsub -q vcs -Is' sim
|
||||
# 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.
|
||||
|
||||
<details>
|
||||
<summary>Advanced local flows: netlist simulation and licensed VCS</summary>
|
||||
|
||||
These flows require the relevant synthesis/timing tools and PDK inputs, or a
|
||||
licensed VCS environment. Keep one timestamp across dependent commands:
|
||||
|
||||
```sh
|
||||
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
|
||||
SIM_FIRMWARE_NAME=retrosoc_asm RTL_SIM_TIMEOUT=5200000 netsim
|
||||
make CONFIG=configs/ci/ihp130.mk STA=OPENSTA sta
|
||||
```
|
||||
|
||||
| Goal | Command |
|
||||
| --- | --- |
|
||||
| Icarus behavioral simulation | `make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG sim` |
|
||||
| Verilator behavioral simulation | `make CONFIG=configs/ci/ihp130.mk SIMU=VERILATOR sim` |
|
||||
| Hazard3 JTAG debug acceptance | `make CONFIG=configs/ci/ihp130-debug.mk SIMU=VERILATOR debug-sim` |
|
||||
| Assembly self-test with Icarus | `make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG RTL_SIM_TIMEOUT=5200000 sim-asm` |
|
||||
| Yosys synthesis | `make CONFIG=configs/ci/ihp130.mk SYNTH=YOSYS synth` |
|
||||
| Icarus netlist simulation after synthesis | `make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG netsim` |
|
||||
| OpenSTA core timing analysis after synthesis | `make CONFIG=configs/ci/ihp130.mk STA=OPENSTA sta` |
|
||||
| Strict Verilator RTL lint | `make CONFIG=configs/ci/ihp130.mk SIMU=VERILATOR HAVE_SVA=YES check-rtl-lint` |
|
||||
| Hazard3 CoreMark quick report | `make CONFIG=configs/benchmark/ihp130-hazard3-coremark.mk SIMU=VERILATOR SOC_SIM_TIME=7200 coremark-report` |
|
||||
| Generate the untracked HP core RTL | `make CONFIG=configs/ci/ihp130-hp.mk vexii-generate` |
|
||||
| Build and package the HP Linux flash image | `make setup-hp-linux && make CONFIG=configs/ci/ihp130-hp.mk hp-bundle` |
|
||||
| IHP130 fast smoke suite | `make regress-smoke` |
|
||||
| Pull-request regression suite | `make regress-pr` |
|
||||
| Nightly regression suite | `make regress-nightly` |
|
||||
| Format C, Makefile, and RTL sources | `make format` |
|
||||
| Check C, Makefile, and RTL formatting | `make format-check` |
|
||||
| Script and policy checks | `make sw-policy-check sw-host-test` |
|
||||
|
||||
`make regress-smoke` builds the IHP130 firmware, compiles the Verilator SVA
|
||||
configuration, and runs the Icarus assembly self-test. It runs strict RTL lint
|
||||
before those flows and omits synthesis,
|
||||
timing, and netlist simulation for fast feedback. `make regress-pr` runs the
|
||||
supported IHP130, GF180, ICS55, and SKY130 PR matrices in sequence, including
|
||||
slow-corner OpenSTA core timing analysis for each PDK.
|
||||
|
||||
GitHub-hosted regression workflows currently pass `--behavioral-only` to avoid
|
||||
the unresolved JPEG Yosys memory peak. They retain RTL lint, firmware, Verilator,
|
||||
and Icarus behavioral coverage; local `make regress-pr` remains the complete
|
||||
synthesis, netlist simulation, and OpenSTA flow.
|
||||
|
||||
Build outputs are isolated below `build/<profile>-<YYYY-MM-DD-HH-MM>-<config-hash>/`. Each variant keeps its
|
||||
firmware, generated sources, simulator output, synthesis and timing reports, manifest, warning
|
||||
analysis, and metrics separate from other configurations. Use `make clean` to remove the
|
||||
selected backend, `make clean-all` to remove all build output, and `make purge-cache` to remove
|
||||
download and compiler caches.
|
||||
|
||||
`BUILD_TIMESTAMP` defaults to the local build-start time. Set it explicitly when separate Make
|
||||
commands must reuse one variant:
|
||||
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:
|
||||
|
||||
```sh
|
||||
export BUILD_TIMESTAMP=2026-07-21-10-39
|
||||
make CONFIG=configs/ci/ihp130.mk firmware
|
||||
make CONFIG=configs/ci/ihp130.mk SIMU=IVERILOG sim
|
||||
make CONFIG=configs/ci/ihp130.mk SIMU=VCS VCS_USE_LSF=NO firmware sim
|
||||
```
|
||||
|
||||
## Reproducibility And CI
|
||||
After this sequence, `unset BUILD_TIMESTAMP` to restore automatic timestamps.
|
||||
See [build layout](docs/engineering.md#build-layout) and
|
||||
[result policy](docs/engineering.md#result-policy) for artifacts and verdicts.
|
||||
|
||||
[`dependencies/dependencies.lock.json`](dependencies/dependencies.lock.json) is the source of truth for
|
||||
external repositories, application archives, and Ubuntu 22.04 toolchain bundles. The lock digest
|
||||
is part of each build variant, and every download is checksum verified. GitHub Actions pins its
|
||||
actions by commit, validates the lock and engineering scripts, and runs pull-request and nightly
|
||||
regression matrices.
|
||||
</details>
|
||||
|
||||
Every EDA command is recorded with a log and a machine-readable result JSON. The regression
|
||||
policy checks warning deltas against committed baselines and collects metrics for later gate
|
||||
promotion. Tags matching `v*` produce a flattened SystemVerilog export, source archive, build
|
||||
manifest, dependency lock, CycloneDX SBOM, and `SHA256SUMS`. Run `make package` to create the
|
||||
same local deliverables under `dist/<variant>/`.
|
||||
## Documentation and repository
|
||||
|
||||
See [`docs/engineering.md`](docs/engineering.md) for supported-flow details, artifact layout,
|
||||
warning and metric policy, CI behavior, and release contents.
|
||||
| Start here | Guides |
|
||||
| --- | --- |
|
||||
| Understand the platform | [LP/HP architecture](docs/lp-hp-architecture.md), [IP specifications](docs/ip/README.md), [datasheet workflow](publications/README.md). |
|
||||
| Develop firmware | [SDK](crt/README.md), [applications](app/README.md), [HP software](app/ports/linux/README.md). |
|
||||
| Debug and measure | [Hazard3 debug](docs/hazard3-debug.md), [CoreMark](docs/coremark.md), [engineering workflow](docs/engineering.md). |
|
||||
| Change RTL or tooling | [RTL conventions](docs/rtl-coding-style.md), [MISRA policy](docs/misra-c-2012.md), [agent contract](AGENTS.md). |
|
||||
| Explore further | [Documentation index](docs/README.md), [build profiles](configs/README.md), [contribution process](CONTRIBUTING.md). |
|
||||
|
||||
| Directory | Contents |
|
||||
| --- | --- |
|
||||
| [rtl/](rtl/README.md) | SoC integration, IP, interfaces, simulation, and technology wrappers. |
|
||||
| [crt/](crt/README.md) / [app/](app/README.md) | Freestanding SDK, firmware applications, and software integrations. |
|
||||
| [configs/](configs/README.md) / [dependencies/](dependencies/README.md) | Reproducible profiles and locked external inputs. |
|
||||
| [tests/](tests/README.md) / [scripts/](scripts/README.md) / [quality/](quality/README.md) | Verification, build helpers, and executable quality policy. |
|
||||
| [physical/](physical/README.md) / [fpga/](fpga/README.md) | Physical-design flows and FPGA integration. |
|
||||
| [docs/](docs/README.md) / [publications/](publications/README.md) | Engineering specifications and manually built datasheets. |
|
||||
| [.github/](.github/GUIDE.md) / [docker/](docker/README.md) | Automation and the container development environment. |
|
||||
|
||||
## Validation and reproducibility
|
||||
|
||||
The status badges above track **`main`**, not the current checkout. Other runs:
|
||||
[GF180](https://github.com/retroSoC/retroSoC/actions/workflows/regression-gf180.yml),
|
||||
[ICS55](https://github.com/retroSoC/retroSoC/actions/workflows/regression-ics55.yml),
|
||||
[SKY130](https://github.com/retroSoC/retroSoC/actions/workflows/regression-sky130.yml),
|
||||
and [nightly](https://github.com/retroSoC/retroSoC/actions/workflows/nightly.yml).
|
||||
|
||||
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](docs/engineering.md); no performance claim is implied by
|
||||
a badge. Maintainer-published `v*` tags trigger
|
||||
[release packaging](docs/engineering.md#ci-and-releases), including the source
|
||||
archive, manifest, dependency lock, SBOM, and checksums.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome. If you want to improve the RTL, software, verification,
|
||||
documentation, or development flows, open an issue or submit a pull request after
|
||||
reading [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
Start with the [contribution guide](CONTRIBUTING.md), follow the
|
||||
[Git workflow](docs/git-workflow.md), and use the
|
||||
[PR template](.github/pull_request_template.md). Ordinary contributions target
|
||||
`dev` and preserve meaningful commits through merge-commit integration.
|
||||
Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).
|
||||
|
||||
- Report vulnerabilities according to [`Security.md`](Security.md).
|
||||
- Review retained third-party notices in [`NOTICE`](NOTICE) and
|
||||
[`ATTRIBUTIONS.md`](ATTRIBUTIONS.md).
|
||||
- The project is distributed under [Mulan PSL v2](LICENSE).
|
||||
retroSoC is licensed under [Mulan PSL v2](LICENSE). Third-party terms are
|
||||
recorded in [NOTICE](NOTICE), [ATTRIBUTIONS](ATTRIBUTIONS.md), and
|
||||
[licenses/](licenses/README.md). See the existing [security policy](Security.md)
|
||||
for its current reporting information.
|
||||
|
||||
A big **thank you** goes out to everyone who has contributed to retroSoC:
|
||||
Thanks to everyone contributing to retroSoC.
|
||||
|
||||
<a href="https://github.com/retroSoC/retroSoC/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=retroSoC/retroSoC" alt="retroSoC contributors" />
|
||||
</a>
|
||||
[](https://github.com/retroSoC/retroSoC/graphs/contributors)
|
||||
Vendored
+5
@@ -55,3 +55,8 @@ verification inputs. Install them with `make setup-apu-reference`; neither is
|
||||
linked into firmware, RTL, or the shipped APUMC bundle. Run
|
||||
`make CONFIG=configs/ci/ihp130.mk apu-p5-corpus` to produce the checksum-pinned
|
||||
per-file profile and independent PCM manifest.
|
||||
|
||||
The NPU Visual Wake Words archive is mirrored as an unmodified release asset in
|
||||
`retroSoC/artifact`, with the original Silicon Labs URL retained as a fallback.
|
||||
Both locations resolve to the same required SHA-256; setup accepts neither a
|
||||
different archive nor a fallback with a non-HTTPS URL.
|
||||
Vendored
+4
-1
@@ -239,7 +239,10 @@
|
||||
"license": "CC-BY-4.0"
|
||||
},
|
||||
"npu_vww_dataset": {
|
||||
"url": "https://www.silabs.com/public/files/github/machine_learning/benchmarks/datasets/vw_coco2014_96.tar.gz",
|
||||
"url": "https://github.com/retroSoC/artifact/releases/download/npu-vww-dataset-f8746b9e44f8/vw_coco2014_96.tar.gz",
|
||||
"fallback_urls": [
|
||||
"https://www.silabs.com/public/files/github/machine_learning/benchmarks/datasets/vw_coco2014_96.tar.gz"
|
||||
],
|
||||
"sha256": "f8746b9e44f8a7a4293f73be9ba6e8da9239fe69798d42364aae62b915cfab58",
|
||||
"destination": ".cache/retrosoc/downloads/npu/vw-coco2014-96.tar.gz",
|
||||
"license": "NOASSERTION"
|
||||
|
||||
@@ -63,6 +63,8 @@ Only raw model parsing is shared with the NPU compiler. Run
|
||||
`make CONFIG=configs/ci/ihp130.mk npu-p0-qualify` after
|
||||
`make CONFIG=configs/ci/ihp130.mk setup-npu-reference` to compare both complete
|
||||
1000-input corpora against the Python graph reference and compiled executor.
|
||||
The VWW archive is fetched from the ordered HTTPS URLs in the dependency lock;
|
||||
every mirror must produce the same locked SHA-256 before extraction.
|
||||
The selected variant's `npu/p0/` directory retains oracle build provenance,
|
||||
per-input golden tensors, three-way hashes, logs and `qualification-p0.json`.
|
||||
The runner uses at most 16 workers (`JOBS`); missing sources/tools, numerical
|
||||
|
||||
@@ -82,6 +82,16 @@ def _validate_archive(kind: str, name: str, value: dict[str, Any]) -> None:
|
||||
_require_fields(kind, name, value, ("url", "sha256", "destination", "license"))
|
||||
_validate_sha(f"{kind} {name}", value["sha256"])
|
||||
_validate_url(f"{kind} {name}", value["url"])
|
||||
fallback_urls = value.get("fallback_urls", [])
|
||||
if not isinstance(fallback_urls, list):
|
||||
raise LockError(f"{kind} {name} fallback_urls must be a list")
|
||||
for index, url in enumerate(fallback_urls):
|
||||
if not isinstance(url, str):
|
||||
raise LockError(f"{kind} {name} fallback_urls must contain URLs")
|
||||
_validate_url(f"{kind} {name} fallback_urls[{index}]", url)
|
||||
urls = [value["url"], *fallback_urls]
|
||||
if len(set(urls)) != len(urls):
|
||||
raise LockError(f"{kind} {name} download URLs must be unique")
|
||||
_validate_relative_path(f"{kind} {name} destination", value["destination"])
|
||||
|
||||
|
||||
|
||||
@@ -148,6 +148,38 @@ def download_file(
|
||||
raise RuntimeError(f"failed to download {url}: {last_error}")
|
||||
|
||||
|
||||
def download_file_from_urls(
|
||||
urls: Iterable[str],
|
||||
destination: Path,
|
||||
expected_sha256: str,
|
||||
*,
|
||||
update: bool = False,
|
||||
retries: int = 3,
|
||||
timeout: int = 30,
|
||||
resume: bool = False,
|
||||
) -> None:
|
||||
candidates = tuple(urls)
|
||||
if not candidates:
|
||||
raise ValueError("at least one download URL is required")
|
||||
failures: list[str] = []
|
||||
for url in candidates:
|
||||
try:
|
||||
download_file(
|
||||
url,
|
||||
destination,
|
||||
expected_sha256,
|
||||
update=update,
|
||||
retries=retries,
|
||||
timeout=timeout,
|
||||
resume=resume,
|
||||
)
|
||||
return
|
||||
except RuntimeError as error:
|
||||
failures.append(str(error))
|
||||
print(f"[dependency] mirror failed: {url}: {error}")
|
||||
raise RuntimeError("all download mirrors failed: " + "; ".join(failures))
|
||||
|
||||
|
||||
def atomic_write(path: Path, content: str) -> bool:
|
||||
path = path.resolve()
|
||||
if path.exists() and path.read_text(encoding="utf-8") == content:
|
||||
|
||||
@@ -14,7 +14,12 @@ ROOT = Path(__file__).resolve().parents[1]
|
||||
sys.path.insert(0, str(ROOT))
|
||||
|
||||
from scripts.dependency_lock import archive, source # noqa: E402
|
||||
from scripts.setup_helpers import atomic_write, download_file, ensure_git_repo, sha256 # noqa: E402
|
||||
from scripts.setup_helpers import ( # noqa: E402
|
||||
atomic_write,
|
||||
download_file_from_urls,
|
||||
ensure_git_repo,
|
||||
sha256,
|
||||
)
|
||||
|
||||
MLCOMMONS_TINY = "apu_mlperf_tiny"
|
||||
KWS_MFCC = "apu_kws_mfcc"
|
||||
@@ -151,7 +156,10 @@ def install(build_dir: Path, *, update: bool) -> dict[str, object]:
|
||||
ensure_git_repo(spec["url"], ROOT / spec["destination"], spec["revision"], update=update)
|
||||
dataset = archive(VWW_DATASET)
|
||||
archive_path = ROOT / dataset["destination"]
|
||||
download_file(dataset["url"], archive_path, dataset["sha256"], update=update, timeout=600)
|
||||
urls = (dataset["url"], *dataset.get("fallback_urls", ()))
|
||||
download_file_from_urls(
|
||||
urls, archive_path, dataset["sha256"], update=update, timeout=600
|
||||
)
|
||||
|
||||
models = verify_models(tiny)
|
||||
kws_names = verify_kws_features(mfcc)
|
||||
|
||||
@@ -22,7 +22,14 @@ def test_lock_carries_npu_vww_dataset_entry() -> None:
|
||||
dataset["sha256"]
|
||||
== "f8746b9e44f8a7a4293f73be9ba6e8da9239fe69798d42364aae62b915cfab58"
|
||||
)
|
||||
assert dataset["url"].endswith("vw_coco2014_96.tar.gz")
|
||||
assert dataset["url"] == (
|
||||
"https://github.com/retroSoC/artifact/releases/download/"
|
||||
"npu-vww-dataset-f8746b9e44f8/vw_coco2014_96.tar.gz"
|
||||
)
|
||||
assert dataset["fallback_urls"] == [
|
||||
"https://www.silabs.com/public/files/github/machine_learning/benchmarks/"
|
||||
"datasets/vw_coco2014_96.tar.gz"
|
||||
]
|
||||
|
||||
|
||||
def test_model_hash_constants_match_extraction_module() -> None:
|
||||
|
||||
@@ -59,7 +59,11 @@ from scripts.regress import ( # noqa: E402
|
||||
)
|
||||
from scripts import setup_helpers # noqa: E402
|
||||
from scripts import setup_apu_reference # noqa: E402
|
||||
from scripts.setup_helpers import download_file, ensure_git_repo # noqa: E402
|
||||
from scripts.setup_helpers import ( # noqa: E402
|
||||
download_file,
|
||||
download_file_from_urls,
|
||||
ensure_git_repo,
|
||||
)
|
||||
|
||||
|
||||
def run(*command: str, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
|
||||
@@ -935,6 +939,22 @@ def test_dependency_helpers_are_idempotent(tmp_path: Path) -> None:
|
||||
assert not partial.exists()
|
||||
|
||||
|
||||
def test_dependency_helper_uses_fallback_url(tmp_path: Path) -> None:
|
||||
payload = tmp_path / "payload.bin"
|
||||
payload.write_bytes(b"verified fallback")
|
||||
digest = hashlib.sha256(payload.read_bytes()).hexdigest()
|
||||
downloaded = tmp_path / "downloaded.bin"
|
||||
|
||||
download_file_from_urls(
|
||||
((tmp_path / "missing.bin").as_uri(), payload.as_uri()),
|
||||
downloaded,
|
||||
digest,
|
||||
retries=1,
|
||||
)
|
||||
|
||||
assert downloaded.read_bytes() == payload.read_bytes()
|
||||
|
||||
|
||||
def test_dependency_helper_limits_recursive_submodules(monkeypatch, tmp_path: Path) -> None:
|
||||
commands: list[tuple[str, ...]] = []
|
||||
revision = "a" * 40
|
||||
@@ -1164,6 +1184,18 @@ def test_dependency_lock_and_config_key_include_a_fixed_timestamp(tmp_path: Path
|
||||
else:
|
||||
raise AssertionError("invalid toolchain download timeout was accepted")
|
||||
|
||||
invalid_fallback = json.loads(json.dumps(lock))
|
||||
invalid_fallback["archives"]["npu_vww_dataset"]["fallback_urls"] = [
|
||||
"http://example.com/vww.tar.gz"
|
||||
]
|
||||
broken.write_text(json.dumps(invalid_fallback), encoding="utf-8")
|
||||
try:
|
||||
load_lock(broken)
|
||||
except LockError as error:
|
||||
assert "fallback_urls[0] URL must use HTTPS" in str(error)
|
||||
else:
|
||||
raise AssertionError("invalid archive fallback URL was accepted")
|
||||
|
||||
|
||||
def test_development_environment_contract_is_lock_pinned(tmp_path: Path) -> None:
|
||||
lock_path = ROOT / "dependencies/dependencies.lock.json"
|
||||
|
||||
Reference in new issue
Block a user