[DO NOT REVIEW] yosys 0.65 + bazel-orfs bump + sweep/yosys-idempotency README — investigation record

.bazelrc

@@ -9,4 +9,12 @@ build --cxxopt "-std=c++20" --host_cxxopt "-std=c++20"
 # bazel-orfs itself does (its own .bazelrc:7).
 common --lockfile_mode=off
 
+# Test yosys 0.65 via the BCR PR (bazelbuild/bazel-central-registry#8863).
+# Upstream BCR doesn't have 0.65 yet, so point at oharboe's fork branch
+# as an additional registry; combined with single_version_override(yosys,
+# "0.65") in MODULE.bazel this resolves yosys to 0.65 with the
+# WRAPCELL/RTLIL-identifier corruption fix that was missing in 0.63.
+common --registry=https://raw.githubusercontent.com/oharboe/bazel-central-registry/yosys-0.65/
+common --registry=https://bcr.bazel.build/
+
 try-import %workspace%/user.bazelrc

MODULE.bazel

@@ -18,6 +18,13 @@ bazel_dep(name = "rules_shell", version = "0.6.1")
 # dev_dependency = True makes those declarations no-ops in that case, so
 # our MODULE.bazel doesn't need to be patched at non-root consumption
 # time.
+#
+# Exception: bazel_dep(name = "bazel-orfs") is intentionally NOT dev-only,
+# because flow/BUILD has `load("@bazel-orfs//:openroad.bzl", "orfs_pdk")`
+# and load-visibility requires the bazel_dep to be honoured at non-root
+# consumption time too. The companion git_override below is silently
+# ignored by Bazel when @orfs is non-root, so the downstream module's
+# own bazel-orfs pin still wins.
 
 bazel_dep(name = "toolchains_llvm", version = "1.5.0", dev_dependency = True)
 bazel_dep(name = "openroad", dev_dependency = True)
@@ -33,25 +40,26 @@ git_override(
     remote = "https://github.com/The-OpenROAD-Project/qt_bazel_prebuilts",
 )
 
-bazel_dep(name = "bazel-orfs", dev_dependency = True)
+bazel_dep(name = "bazel-orfs")
+
 bazel_dep(name = "bazel-orfs-verilog", dev_dependency = True)
 
-BAZEL_ORFS_COMMIT = "ce6efd96dfe39a9c4ef244f8712386f071545d77"
+BAZEL_ORFS_COMMIT = "3a5ddd7eb48c363717e65903ae4573d528327fd3"
 
 BAZEL_ORFS_REMOTE = "https://github.com/The-OpenROAD-Project/bazel-orfs.git"
 
 # To bump version, run: bazelisk run @bazel-orfs//:bump
+#
+# `patches =` keeps small bazel-orfs fixes vendored in this repo
+# while we iterate, instead of round-tripping every change through a
+# bazel-orfs PR + pin bump.  When a patch lands upstream, drop the
+# entry here and bump BAZEL_ORFS_COMMIT.
 git_override(
     module_name = "bazel-orfs",
     commit = BAZEL_ORFS_COMMIT,
     patch_strip = 1,
     patches = [
-        # Adds orfs_design(user_sources=[VAR,...]) / orfs_flow(user_sources={...})
-        # so design-private SOURCE_VARS path hooks (e.g. SDC_FILE_EXTRA in
-        # flow/designs/asap7/mock-cpu) bypass the variables.yaml validator
-        # without polluting the ORFS-wide variable schema. Drop once upstream
-        # bazel-orfs lands the user_sources= API.
-        "//bazel:0001-orfs_design-add-user_sources.patch",
+        "//patches/bazel-orfs:0001-render_gds-monkey-patch-PDK_CONFIGS-not-gdsii_use_custom_config.patch",
     ],
     remote = BAZEL_ORFS_REMOTE,
 )
@@ -63,6 +71,16 @@ git_override(
     strip_prefix = "verilog",
 )
 
+# Force yosys to 0.65 (from BCR PR #8863, picked up via the custom
+# registry in .bazelrc).  0.65 fixes the WRAPCELL/RTLIL-identifier
+# memory corruption that produces garbage like `\<garbage>_KOGGE_STONE`
+# strings in cva6 / ibex synthesis on 0.63.  bazel-orfs pins yosys=0.63
+# in its MODULE.bazel; this root override wins.
+single_version_override(
+    module_name = "yosys",
+    version = "0.65",
+)
+
 # yosys-slang is not on BCR. Pin to a commit on povik/yosys-slang master
 # that has the upstream Bazel build (povik/yosys-slang#310) and the
 # slang.so visibility fix (povik/yosys-slang#311). Submodules pull in

flow/README.md

@@ -56,3 +56,91 @@ the generated targets get `tags = ["manual"]`.
 Each OpenROAD invocation takes `-threads <nproc>`. A wildcard
 `bazelisk test` runs designs in parallel and overcommits the host. Cap
 with `--jobs=N`.
+
+## Running a full sweep without overburdening the host
+
+To verify every design under one or more platforms (e.g. before
+bumping `bazel-orfs` or `tools/yosys`), drive `bazelisk test` per
+platform with `--keep_going` so one failure doesn't mask the rest,
+and split big designs into their own invocations so routing/synth
+don't overcommit RAM.
+
+```bash
+# 1. Install the make-flow toolchain too, so failures can be
+#    cross-checked against `make DESIGN_CONFIG=...`.
+(cd tools/OpenROAD && bazelisk run //:install)
+
+# 2. List actual test targets per platform (capture before running
+#    so the sweep is reproducible).
+bazelisk query 'tests(//flow/designs/asap7/...)'
+bazelisk query 'tests(//flow/designs/sky130hd/...)'
+
+# 3. Small/fast designs in one parallel invocation; each big design
+#    in its own sequential invocation. 16-core / 30 GiB box:
+bazelisk test --keep_going \
+  //flow/designs/asap7/aes/... //flow/designs/asap7/gcd/... \
+  //flow/designs/asap7/uart/... //flow/designs/sky130hd/gcd/...   # etc.
+
+for big in cva6 ibex jpeg riscv32i swerv_wrapper; do
+  bazelisk test --keep_going //flow/designs/asap7/${big}/...
+done
+```
+
+Heuristic: hierarchical / RISC-V cores / image-processing designs
+run solo; everything else batches. Use `--jobs=N` to cap parallel
+OpenROAD invocations if the host still thrashes.
+
+## Triaging a failing `_test`
+
+For each failing `<design>_test`, decide which bucket it falls into:
+
+1. **Trivial config fix.** Missing variable in
+   `flow/scripts/variables.yaml`, a typo in `config.mk`, a missing
+   `exports_files()` for a cross-design SDC/Verilog reference, etc.
+   Fix in place; `variables.yaml` is the single source of truth
+   bazel-orfs validates against.
+
+2. **Yosys-environment false positive (OpenROAD is idempotent given
+   the same netlist).** `rules-base.json` carries three SHA-1
+   fingerprints of yosys' internal state at warning level so a
+   bazel-yosys vs make-yosys drift surfaces in `checkMetadata.py`
+   as three buckets:
+
+       [WARN] synth__canonical_netlist__hash differs test: <bazel> == <make>   # front-end + opt_clean
+       [WARN] synth__preabc_netlist__hash    differs test: <bazel> == <make>   # mid-level synth, immediately pre-ABC
+       [WARN] synth__netlist__hash           differs test: <bazel> == <make>   # post-ABC `1_2_yosys.v`
+
+   The bucket(s) that DIFFER bisect where drift entered: front-end
+   already differing means iteration-order non-determinism is firing
+   in `read_design_sources`/`hierarchy`/`opt_clean`; pre-ABC matching
+   but post-ABC diverging means the bazel-pinned vs make-pulled ABC
+   are different revisions. A QoR threshold breaking together with
+   any of these is almost always yosys-env drift. Confirm with the per-stage `.odb` SHA
+   matrix from `@bazel-orfs//:make-yosys-netlist` (feeds make's
+   netlist into bazel) or its reverse-direction sibling
+   `@bazel-orfs//:yosys-check` (bazel's netlist into make):
+
+   ```bash
+   bazelisk run @bazel-orfs//:make-yosys-netlist \
+       //flow/designs/asap7/<design>:<design>_test
+   ```
+
+   All stages MATCH → yosys-only drift, relax the threshold; any
+   DIFFER → real bazel-vs-make OpenROAD divergence, file the matrix
+   as an issue. Full workflow lives in
+   [`@bazel-orfs//:TESTING.md`](https://github.com/The-OpenROAD-Project/bazel-orfs/blob/main/TESTING.md)
+   under "Debugging OpenROAD determinism (bazel vs make)".
+
+3. **Real bug (both flows fail at the same stage).** `.odb` SHAs may
+   still differ (yosys version) but the failure mode matches.
+   Generate an issue tarball from the make flow:
+
+   ```bash
+   cd flow
+   make <stage>_issue DESIGN_CONFIG=designs/<plat>/<design>/config.mk \
+                      ISSUE_TAG=<plat>-<design>-<short>
+   ```
+
+   `flow/util/utils.mk` auto-generates `<script>_issue` targets for
+   every script in `flow/scripts/` (`floorplan_issue`,
+   `global_route_issue`, `detail_route_issue`, `final_issue`, …).

flow/designs/asap7/aes-block/rules-base.json

@@ -28,11 +28,11 @@
         "compare": "<="
     },
     "cts__timing__setup__ws": {
-        "value": -113.0,
+        "value": -118.3,
         "compare": ">="
     },
     "cts__timing__setup__tns": {
-        "value": -7390.0,
+        "value": -7549.7,
         "compare": ">="
     },
     "cts__timing__hold__ws": {
@@ -99,4 +99,4 @@
         "value": 7205,
         "compare": "<="
     }
-}
+}

flow/designs/asap7/ethmac_lvt/rules-base.json

@@ -28,11 +28,11 @@
         "compare": "<="
     },
     "cts__timing__setup__ws": {
-        "value": -21.7,
+        "value": -22.7,
         "compare": ">="
     },
     "cts__timing__setup__tns": {
-        "value": -113.0,
+        "value": -310.4,
         "compare": ">="
     },
     "cts__timing__hold__ws": {
@@ -52,7 +52,7 @@
         "compare": ">="
     },
     "globalroute__timing__setup__tns": {
-        "value": -263.0,
+        "value": -344.0,
         "compare": ">="
     },
     "globalroute__timing__hold__ws": {
@@ -84,7 +84,7 @@
         "compare": ">="
     },
     "finish__timing__setup__tns": {
-        "value": -94.2,
+        "value": -199.8,
         "compare": ">="
     },
     "finish__timing__hold__ws": {
@@ -99,4 +99,4 @@
         "value": 8537,
         "compare": "<="
     }
-}
+}