Toolchain reproducibility policy

This document is the source of truth for how the e1-chip toolchain is pinned. Every external dependency that affects RTL generation, simulation, synthesis, or physical design must be referenced by an immutable identifier (image digest, git commit SHA, or version-pinned lockfile entry).

The release-gate CI workflow (.github/workflows/ci.yml) uploads the evidence generated by these pins as artifacts under build/reports/ so any release candidate can be reproduced from a single commit + the recorded manifests.

Scope and pinned surfaces

Surface	Pin mechanism	Source of truth
Container base image	OCI digest (`sha256:...`)	`Dockerfile` (`UBUNTU_DIGEST` build arg)
apt package set	Resolved manifest archive baked into the image at `/var/log/apt-manifest/`	`Dockerfile` post-install step
Python dependencies	Versioned ranges with upper bounds	`requirements.txt`
Nix dev shell	`nixpkgs` flake input revision (lockfile)	`flake.nix`, `flake.lock`
Chipyard (RTL generators)	Commit SHA	`scripts/bootstrap_chipyard.sh` (`CHIPYARD_SHA`)
OpenLane2 (PD repo)	Git tag, optionally SHA	`scripts/bootstrap_openlane2.sh` (`OPENLANE2_TAG`, `OPENLANE2_SHA`)
OpenLane2 runtime image	OCI digest	`scripts/install_openlane_image.sh` (`OPENLANE_IMAGE_DIGEST`)
Release-gate host tools	Recorded version manifest	`scripts/record_tool_versions.sh` -> `build/reports/tool_versions.txt`

Required release-gate tools

The release-gate CI must record a version (or MISSING marker) for each of the following tools. The set is enumerated in scripts/record_tool_versions.sh and any addition or removal MUST update both this document and that script in lockstep.

python3
gcc
riscv64-unknown-elf-gcc (RISC-V GNU toolchain)
verilator
yosys
nextpnr-ecp5
ecppack
sby (SymbiYosys)
qemu-system-riscv64

Missing tools are recorded as MISSING and treated as BLOCK (not FAIL) by scripts/check_mvp_status.py so that an under-provisioned host can still emit evidence without masking a real test failure.

How to refresh a pin

Ubuntu base image digest

docker manifest inspect --verbose ubuntu:24.04 \
    | jq -r '.Descriptor.digest // .manifests[0].digest'

Paste the resulting sha256:... into Dockerfile's UBUNTU_DIGEST ARG, replacing the TODO_PIN_UBUNTU_24_04_DIGEST placeholder. Rebuild the image and confirm /var/log/apt-manifest/installed-packages.tsv updated.

Chipyard SHA

git ls-remote https://github.com/ucb-bar/chipyard.git refs/tags/'*'

Pick a tagged release commit, edit scripts/bootstrap_chipyard.sh's CHIPYARD_SHA default, and record the selection in docs/three-week-prototype-workstreams.md and the project critical-gap log.

OpenLane2 SHA + image digest

Update both in lockstep:

scripts/bootstrap_openlane2.sh -> OPENLANE2_TAG and OPENLANE2_SHA.
scripts/install_openlane_image.sh -> OPENLANE_IMAGE and OPENLANE_IMAGE_DIGEST (also referenced in scripts/tool_versions.sh).

After update, run scripts/install_openlane_image.sh to verify the digest preflight matches the manifest.

Python packages

Edit requirements.txt and re-run make venv. The CI image rebuild will pick up the new pins. Note: requirements use versioned ranges; for true reproducibility we plan to add a pip-compile-generated lockfile (tracked in the toolchain workstream gap log).

CI evidence

.github/workflows/ci.yml uploads build/reports/ as a e1-chip-regression artifact (continue-on-error: true to keep the upload non-fatal). The artifact must contain at least:

tool_versions.txt and tool_versions_release_gate.txt
mvp_status.json (emitted by make mvp-status-json, includes evidence_class per subsystem distinguishing PASS / BLOCK / FAIL)

Regenerating everything locally

make tool-versions          # full host probe + release-gate sidecar
make record-tool-versions   # release-gate sidecar only
make mvp-status-json        # writes build/reports/mvp_status.json
make pipeline-check         # final fail-closed gate

If any of these report BLOCK, the missing dependency is captured in evidence_class (one of tool_blocker, regen_required, scaffold_only, missing_source, release_blocker) so reviewers can act without re-running.