Skip to content

REPRODUCIBILITY.md

Latest commit

 

History

History
211 lines (165 loc) · 9.11 KB

REPRODUCIBILITY.md

File metadata and controls

211 lines (165 loc) · 9.11 KB
Raw

Reproducing the Latest Release with Apptainer

This flow reproduces the current OpenPLL release gate for the 25 MHz-reference Sky130 PLL path. It is intentionally scoped to the latest release evidence: the all-HD coarse DCO, hard top, configured wrapper, target-code rows, direct-RCX hold smokes, direct-RCX near-seed smokes, and make check-sky130-pll-25mhz-release.

Historical v1-v7 diagnostics are not regenerated by this container recipe.

Image Contents

The host needs Apptainer or compatible SingularityCE, network access during the image build, and space for the full physical toolchain. The image installs:

  • Ciel Sky130 PDK versions 7519dfb04400f224f140749cda44ee7de6f5e095 (historical v8 pin) and 1689ac3f2dc763876eaf967227c7dfe831b031ae (current in the image) in /opt/pdk/ciel/sky130.
  • LibreLane commit 0f39aab99009d4a81ee3f863f0da9ca2f0b43a99 and its Nix tool closure in /opt/librelane and /nix.
  • Upstream MPI Xyce 7.10.0, built with Trilinos 14.4, in /opt/xyce.

The wrapper mounts only this OpenPLL checkout at /work/OpenPLL. The bundled Xyce is upstream and does not contain the experimental KLS solver used by the newer acquisition diagnostics. Do not treat those KLS runs as available from this release image. The container wrapper verifies the newer PDK and pinned LibreLane revisions. The newer PDK makes this a fresh release-flow run, not a bit-for-bit reproduction of the historical v8 PDK run.

PDK Compatibility

The historical v8 PDK's libs.tech/openlane configuration cannot be loaded by the pinned LibreLane. The image retains that archive and selects the newer native LibreLane PDK above for physical rebuilds. The DCO configuration uses the PDK's installed HD GDS library instead of paths into an unavailable PDK source build. The new PDK can change physical and timing results, so the release gate must pass on freshly regenerated artifacts before treating the container run as validated. make apptainer-audit-release needs generated signoff artifacts; they are not stored in this checkout.

With the newer PDK, the DCO, BBPD, digital core, hard top, and configured wrapper have completed signoff with zero DRC/LVS violations. The v8 audit still fails its historical physical-count baseline: the rebuilt hard top has 10002 standard cells, while the v8 checker expects 61063. The old C20/fine-93 and C6/fine-234 presets measure about 84.87 and 206.03 MHz, respectively, instead of 100 and 250 MHz. These are new PDK results, not passing v8 target evidence. The historical archive can be made to load in LibreLane, but its missing corner include files and upstream-Xyce model parser errors still prevent an exact analog rerun.

Extracted TT endpoint measurements on the newer PDK show the following DCO bands (MHz). The 300 MHz target sits in a gap between coarse codes 3 and 2:

Coarse code Fine 0 Fine 255
16 100.07 103.78
4 236.15 259.75
3 266.56 295.00
2 306.25 Not yet measured
1 366.02 418.85
0 467.60 549.98

These are standalone extracted-oscillator measurements, not closed-loop PLL lock results. Closing the 300 MHz gap requires a new DCO tuning range and fresh physical characterization before changing the configured presets.

To check the regenerated physical artifacts independently of the historical frequency baseline, run make apptainer-physical-audit. This checks the DCO, BBPD, digital core, hard top, extracted hard-top SPICE, and configured wrapper. Passing this command does not establish the five target frequencies or PLL lock.

Build the Image

make apptainer-build

The image is written to build/apptainer/openpll-release-modern.sif, overwriting any existing generated image at that path. Building Trilinos and Xyce from source and populating the LibreLane Nix closure can take substantial time and disk space. The build also caches openpll-release-base.sif (historical PDK and LibreLane), openpll-xyce-base.sif (Trilinos), and openpll-release.sif (upstream Xyce) in the same directory so later changes to the newer PDK stage do not rebuild those dependencies. If your Apptainer install requires fakeroot or sudo, pass the build flags explicitly:

OPENPLL_APPTAINER_BUILD_FLAGS=--fakeroot make apptainer-build

The run wrapper defaults to --userns --writable-tmpfs. The temporary overlay lets Nix update its profile metadata while the bundled store remains in the read-only SIF. If your site requires setuid execution instead, override the flags with a writable overlay suitable for that installation.

OPENPLL_APPTAINER_RUN_FLAGS=--writable-tmpfs make apptainer-audit-release

Audit Existing Artifacts

If the generated build/ and openlane/*/runs/ artifacts already exist, run:

make apptainer-audit-release

This executes make check-sky130-pll-25mhz-release inside the container.

Rebuild the Release Evidence

To regenerate the latest-release evidence and then audit it:

make apptainer-rebuild-release

For a clean generated-artifact rebuild:

make apptainer-clean-rebuild-release

The clean rebuild removes only ignored/generated release directories:

  • build/*, except build/apptainer/, build/modern_25mhz/, and build/check_modern/
  • openlane/IntegerPLL_DCO_EINVP_COARSE/runs/librelane_signoff/
  • openlane/IntegerPLL_BBPD/runs/librelane_signoff/
  • openlane/IntegerPLL_DigitalCore/runs/librelane_signoff_force127_s4a2/
  • openlane/IntegerPLL_HardMacroTop_EINVP/runs/librelane_signoff/
  • openlane/IntegerPLL_HardMacroTop_EINVP_25MHzConfigured/runs/librelane_signoff/

The historical v8 release gate writes:

build/sky130_pll_25mhz_release/check_summary.json

with "status": "pass" only when the original PDK, target codes, and physical baselines are reproduced. The bundled newer PDK currently fails this gate for the reasons above. Use make apptainer-physical-audit for the passing physical result on the bundled PDK.

Separate modern Ciel five-mode release

The modern release uses the Ciel Sky130 pin 1689ac3f2dc763876eaf967227c7dfe831b031ae. It has its own DCO source, LibreLane configurations and run tags, calibrated mode table, behavioral model, testbenches, and audit. The historical v8 presets and audit remain separate. This release is scoped to TT operation with a 25 MHz reference and near-seed starting codes. Arbitrary-start acquisition and PVT coverage require further work.

The physical DCO uses 16 balanced sky130_fd_sc_hd__nand2_2 fine-load cells; the other 239 fine-load cells are nand2_1. This change closes the measured 300 MHz coarse-band gap on the modern PDK. The five extracted-TT settings are stored in sky130/modern_25mhz_targets.json; the direct-RCX hold measurements are written under build/modern_25mhz/hold_*/:

Both cells come from the Ciel-provided HD standard-cell library. The release does not require a custom HS cell or a separate PDK build.

Target (MHz) Coarse code Fine code Extracted DCO (MHz) Direct-RCX hold output (MHz)
100 16 58 99.886 96.432
250 4 206 249.959 238.029
300 2 12 300.215 295.761
400 1 215 399.366 416.295
500 0 163 500.707 499.792

The DCO frequency gate requires each seed to be within 2 MHz, and checks both endpoints and codes eight steps below and above the seed for monotonic tuning, edge time, and duty ratio. The direct extracted-DCO hold and near-seed drivers also inspect PLL behavior. Their legacy waveform tolerance is 25 MHz, so that driver result is a separate, looser check than the 2 MHz DCO calibration gate. The near-seed check starts four fine codes below and above each seed and requires movement toward the seed within one 25 MHz reference cycle. The hold check keeps the seed fixed and measures the output over one or two reference cycles; 100 MHz uses two to capture enough oscillator edges.

To check existing modern artifacts in the image, run:

make apptainer-audit-modern-release

To rebuild the modern DCO, remeasure all 25 calibration points, regenerate the presets, harden both modern tops, and rerun the behavioral and mixed-signal checks, run:

make apptainer-rebuild-modern-release

This can take hours because each extracted-DCO and direct-RCX case runs Xyce. The script resumes completed measurements when their inputs still match.

The audit writes build/modern_25mhz/check_summary.json only after all five mode and physical checks pass. The generated RTL can be tested separately with make check-pll-25mhz-modern-rtl inside the image. Running python3 scripts/generate_modern_25mhz.py --check reports any mismatch between the measured mode table and its generated RTL, model, or testbenches. Direct-RCX resume skips a passing case only when its log is newer than the extracted DCO, mode table, and driver. The release audit also rejects direct logs older than the extraction or mode table.

The modern release currently reuses the existing BBPD and digital-core macro signoff runs. Its DCO, hard top, and configured wrapper are built from the config_modern.json files under their respective openlane/ directories, using run tags modern_k016, modern_signoff, and modern_signoff.