Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 105 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,12 @@ jobs:
CELL: ${{ matrix.category }}-${{ matrix.driver }}-${{ matrix.xlen }}${{ matrix.shards && format('-{0}of{1}', matrix.shard, matrix.shards) || '' }}
steps:
- uses: actions/checkout@v4
with:
# logic_gate builds its pull request's merge base, so it needs history and
# the submodules' git data (the third_party cache holds only their working
# trees, whose .git files point into an uncached .git/modules).
fetch-depth: ${{ matrix.category == 'logic_gate' && github.event_name == 'pull_request' && '0' || '1' }}
submodules: ${{ matrix.category == 'logic_gate' && github.event_name == 'pull_request' && 'recursive' || 'false' }}
- name: Setup Vortex
uses: ./.github/actions/setup-vortex
with:
Expand Down Expand Up @@ -292,6 +298,51 @@ jobs:
run: |
(cd build${{ matrix.xlen }} && bash ci/toolchain_install.sh --foldsim)
pip install --quiet "pyslang>=11,<13"
# logic_gate on a pull request: every build is also compared with the
# same build on the merge base's RTL (ci/logic_gate.py --against-rev,
# through BEACON_AGAINST_REV). The checkout is the merge of the pull
# request into its target, so the merge base is the target's head this
# run merged into, and the diff is exactly what the pull request adds.
# The reference's builds are cached by that SHA and the flow it was
# measured under, so the pull request's next push reuses them.
#
# A maintainer may grant the label `beacon-skip-reference` (a reviewed
# decision) when a flow change cannot elaborate the merge base's RTL,
# which would otherwise read REF-FAIL on every push. The label is read
# from the event's payload, so it takes effect on the next push.
- name: Merge base
id: mb
if: matrix.category == 'logic_gate' && github.event_name == 'pull_request' && !contains(github.event.pull_request.labels.*.name, 'beacon-skip-reference')
env:
TARGET: ${{ github.base_ref }}
run: |
set -euo pipefail
git fetch --no-tags origin "+refs/heads/$TARGET:refs/remotes/origin/$TARGET"
base=$(git merge-base HEAD "origin/$TARGET")
flow=$(python3 -c "import sys; sys.path.insert(0, 'ci'); import synth_gate; print(synth_gate.flow_fingerprint('.'))")
echo "merge base: $base (origin/$TARGET), flow $flow"
echo "BEACON_AGAINST_REV=$base" >> "$GITHUB_ENV"
echo "base=$base" >> "$GITHUB_OUTPUT"
echo "flow=$flow" >> "$GITHUB_OUTPUT"
- name: Merge base skipped
if: matrix.category == 'logic_gate' && github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'beacon-skip-reference')
run: |
msg="beacon-skip-reference: the merge-base comparison is SKIPPED by a maintainer's label; logic_gate's verdict is against the baselines only"
echo "::warning title=logic_gate::$msg"
printf '> [!WARNING]\n> %s\n\n' "$msg" >> "$GITHUB_STEP_SUMMARY"
# The newest entry for this merge base and flow; a later save only ever
# adds one with more finished reference builds (see the save below).
- name: Restore the merge base's Beacon builds
id: refcache
if: steps.mb.outputs.base
uses: actions/cache/restore@v4
with:
path: .beacon_ref
key: beacon-ref-${{ steps.mb.outputs.base }}-${{ steps.mb.outputs.flow }}-
restore-keys: beacon-ref-${{ steps.mb.outputs.base }}-${{ steps.mb.outputs.flow }}-
- name: List the restored reference builds
if: steps.mb.outputs.base
run: python3 -c "import sys; sys.path.insert(0, 'ci'); import synth_gate; print('\n'.join(synth_gate.reference_cache_done('.beacon_ref')))" > "$RUNNER_TEMP/beacon_ref_done"
- name: Run cell
run: |
cd build${{ matrix.xlen }}
Expand All @@ -309,6 +360,60 @@ jobs:
with:
name: junit-${{ env.CELL }}
path: junit-*.xml
# The gate's verdicts in the job summary, and per build the evidence a
# verdict names: the diff against the merge base, the area by unit, the
# calibrated risk, the deepest paths.
- name: Summarize logic_gate
if: always() && matrix.category == 'logic_gate'
run: |
for r in build${{ matrix.xlen }}/logic_gate.json build${{ matrix.xlen }}/logic_gate_asic.json; do
[ -f "$r" ] && python3 ci/synth_report.py "$r" >> "$GITHUB_STEP_SUMMARY" || true
done
- uses: actions/upload-artifact@v4
if: always() && matrix.category == 'logic_gate'
with:
name: logic-gate-${{ env.CELL }}
path: |
build${{ matrix.xlen }}/logic_gate*.json
build${{ matrix.xlen }}_logic_gate/hw/syn/xilinx/dut/logic_gate_*/build.log
build${{ matrix.xlen }}_logic_gate/hw/syn/xilinx/dut/logic_gate_*/beacon_*.txt
build${{ matrix.xlen }}_logic_gate/hw/syn/xilinx/dut/logic_gate_*/beacon_*.json
build${{ matrix.xlen }}_logic_gate_asic/hw/syn/yosys/logic_gate_asic_*/build.log
build${{ matrix.xlen }}_logic_gate_asic/hw/syn/yosys/logic_gate_asic_*/beacon_diff.*
build${{ matrix.xlen }}_logic_gate_asic/hw/syn/yosys/logic_gate_asic_*/beacon/report.txt
build${{ matrix.xlen }}_logic_gate_asic/hw/syn/yosys/logic_gate_asic_*/beacon/area.txt
if-no-files-found: ignore
# Saved even when the cell fails, so a pull request's next push reuses
# every reference build that finished. The cache keeps what a later
# comparison reads (end points, instances, area, the stamps); a build
# that did not finish is dropped whole, so it reruns clean. A new entry
# is saved only when the finished set grew past what was restored, keyed
# by that set: cache entries are immutable, and none with fewer builds
# than the one restored is added after it.
- name: Trim the merge base's Beacon builds
id: refsave
if: always() && steps.mb.outputs.base
run: |
python3 - <<'PY'
import os, sys
sys.path.insert(0, "ci")
import synth_gate
synth_gate.trim_reference_cache(".beacon_ref")
with open(os.path.join(os.environ["RUNNER_TEMP"], "beacon_ref_done")) as fh:
before = {line for line in fh.read().splitlines() if line}
after = synth_gate.reference_cache_done(".beacon_ref")
grew = set(after) > before
print("reference builds: %d restored, %d finished%s"
% (len(before), len(after), "" if grew else "; nothing new to save"))
with open(os.environ["GITHUB_OUTPUT"], "a") as fh:
fh.write("id=%s\n" % (synth_gate.reference_cache_id(after) if grew else ""))
PY
- name: Save the merge base's Beacon builds
if: always() && steps.refsave.outputs.id
uses: actions/cache/save@v4
with:
path: .beacon_ref
key: beacon-ref-${{ steps.mb.outputs.base }}-${{ steps.mb.outputs.flow }}-${{ steps.refsave.outputs.id }}

complete:
runs-on: ubuntu-22.04
Expand Down
38 changes: 28 additions & 10 deletions .github/workflows/logic_gate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@
#
# The gate itself runs in ci.yml, as the logic_gate cell planned with
# perf_gate's rtlsim cells. This workflow is the manual entry point: a subset of
# the catalog on a hosted runner, or the full-GPU builds (group gpu), which need
# the catalog on a hosted runner, on the FPGA or the ASIC flow, optionally
# against another revision; or the full-GPU builds (group gpu), which need
# ~95 GB per build and run only on the self-hosted machine.
#
# See docs/designs/continuous_integration.md §4.6.
Expand All @@ -23,6 +24,13 @@ on:
builds:
description: "build ids/groups, space separated (blank = all)"
default: ""
asic:
description: "measure asic_gate.yaml's builds on the ASIC flow (case gate_asic) instead"
type: boolean
default: false
against:
description: "also compare each build with the same build on this revision's RTL (blank = none)"
default: ""
gpu:
description: "run the full-GPU builds (group gpu) on the self-hosted machine instead"
type: boolean
Expand All @@ -40,10 +48,14 @@ jobs:
if: ${{ !inputs.gpu }}
runs-on: ubuntu-22.04
timeout-minutes: 90
env:
CASE: ${{ inputs.asic && 'gate_asic' || 'gate' }}
REPORT: ${{ inputs.asic && 'logic_gate_asic.json' || 'logic_gate.json' }}
steps:
- uses: actions/checkout@v4
with:
submodules: recursive
fetch-depth: ${{ inputs.against && '0' || '1' }}

# Restores the prebuilt toolchain (CIRCT among it) and exports TOOLDIR;
# prepare=true installs it on a cache miss.
Expand All @@ -60,50 +72,56 @@ jobs:
../configure --tooldir=$TOOLDIR
ci/toolchain_install.sh --foldsim

# The command is the one the catalog declares (the `gate` case of
# ci/testcases/logic_gate.yaml), so what CI runs and what the catalog
# says cannot drift apart.
# The command is the one the catalog declares (the `gate` or `gate_asic`
# case of ci/testcases/logic_gate.yaml), so what CI runs and what the
# catalog says cannot drift apart.
- name: Gate
id: run
env:
IN_BUILDS: ${{ github.event.inputs.builds }}
IN_AGAINST: ${{ github.event.inputs.against }}
run: |
set -uo pipefail
CMD=$(python3 -c "import yaml; print(next(t['run'] for t in yaml.safe_load(open('ci/testcases/logic_gate.yaml'))['tests'] if t['id'] == 'gate'))")
CMD=$(python3 -c "import os, yaml; print(next(t['run'] for t in yaml.safe_load(open('ci/testcases/logic_gate.yaml'))['tests'] if t['id'] == os.environ['CASE']))")
# Dispatch inputs reach the shell through an env var, never
# interpolated into the script.
ARGS=()
for b in ${IN_BUILDS:-}; do ARGS+=(-b "$b"); done
[ -n "${IN_AGAINST:-}" ] && ARGS+=(--against-rev "$IN_AGAINST")
rc=0
$CMD "${ARGS[@]}" --timeout 3600 --report logic_gate.json || rc=$?
$CMD "${ARGS[@]}" --timeout 3600 || rc=$?
echo "rc=$rc" >> "$GITHUB_OUTPUT"
exit 0

- name: Summarize
if: always()
run: |
set -uo pipefail
python3 ci/synth_report.py --annotate error logic_gate.json \
python3 ci/synth_report.py --annotate error "$REPORT" \
> logic_gate_report.md || true
cat logic_gate_report.md >> "$GITHUB_STEP_SUMMARY"

- uses: actions/upload-artifact@v4
if: always()
with:
name: logic-gate
name: logic-gate${{ inputs.asic && '-asic' || '' }}
path: |
logic_gate.json
logic_gate*.json
logic_gate_report.md
build32_logic_gate/hw/syn/xilinx/dut/logic_gate_*/build.log
build32_logic_gate/hw/syn/xilinx/dut/logic_gate_*/beacon_*
build32_logic_gate/hw/syn/xilinx/dut/logic_gate_*/beacon/report.txt
build32_logic_gate_asic/hw/syn/yosys/logic_gate_asic_*/build.log
build32_logic_gate_asic/hw/syn/yosys/logic_gate_asic_*/beacon_*
build32_logic_gate_asic/hw/syn/yosys/logic_gate_asic_*/beacon/report.txt
build32_logic_gate_asic/hw/syn/yosys/logic_gate_asic_*/beacon/area.txt
if-no-files-found: warn

- name: Verdict
run: |
case "${{ steps.run.outputs.rc }}" in
0) echo "logic_gate passed" ;;
1) echo "::error::logic_gate FAILED — a unit got deeper than its baseline"; exit 1 ;;
1) echo "::error::logic_gate FAILED — a unit got deeper or the design grew (see the summary)"; exit 1 ;;
*) echo "::error::logic_gate build error (see logs)"; exit 1 ;;
esac

Expand Down
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,9 +88,9 @@ See [docs/testing.md](docs/testing.md) and [docs/debugging.md](docs/debugging.md
- **RTL coverage path is `xrt`, not `rtlsim`.** When discussing or planning RTL verification, `xrt` is the canonical path — `rtlsim` bypasses the AFU surface. `rtlsim` remains useful for fast iteration on processor RTL; `xrt` is what proves the full integration.
- **`ci/regression.sh` is the canonical source of tested configurations.** Use it to discover supported parameter combinations before inventing ad hoc ones.
- **Perf-regression baselines (`ci/baselines/perf/*.json`) are golden data — never hand-edit them, and never "fix" a red perf gate by bumping the number.** They are regenerated only by `pytest ci -m perf_gate --update-baselines` (a human-run, reviewed step), and CI must never pass that flag. A `perf_gate` failure means real cycles moved: root-cause it, or — if the change is intended — regenerate the baseline so the diff shows the perf delta for review. Same rule as image goldens and `known_issue:`.
- **Synthesis baselines (`ci/baselines/synthesis/{xilinx,yosys,beacon}/*.json`) are golden data under the same rule** — never hand-edited, regenerated only by a human running `ci/fpga_gate.py --update-baseline` / `ci/asic_gate.py --update-baseline` / `ci/logic_gate.py --update-baseline`, never by CI. A red `fpga_gate`/`asic_gate` means real Fmax or area moved; a red `logic_gate` means a unit got deeper or the design's area grew past 5 %, and its reasons name the unit or the resource (`beacon_area.txt` has the area by unit and each memory's placement). Note the two gates measure the *same* `hw/unittest/*/VX_*_top.sv` wrappers through different flows, so a divergence between them is a finding, not noise — keep `hw/syn/{xilinx,yosys}/dut/catalog.mk` in step when you add or rename a DUT. See [docs/designs/continuous_integration.md §3.5](docs/designs/continuous_integration.md).
- **Beacon first for any RTL change that can move timing; synthesis only to confirm.** A change to a pipeline, arbiter, queue, interface or datapath can add logic levels that only the nightly `fpga_gate` would find, hours later. Beacon finds them in minutes, so iterate on it, not on Vivado or Yosys: run `ci/logic_gate.py -b <dut>` on the parent revision once (its own build tree, e.g. `git worktree add ../ref HEAD` and `--build-dir build32_beacon_ref`), then `ci/logic_gate.py -b <dut> --against build32_beacon_ref` after each edit, and fix what `<build>/beacon_diff.txt` reports until nothing fails (`ci/beacon.py paths` shows a deep unit's paths op by op). Run synthesis once per change, on the DUTs whose depth moved, and feed the result back with `ci/beacon.py validate`. A change to the cluster, socket, L2 or anything only the whole GPU assembles also runs the `gpu` group (`ci/logic_gate.py -b gpu -j 1`, ~30 min and ~95 GB per build). A unit that gets deeper is fixed or, if intended, re-recorded with the reason in the commit message. `beacon_diff.txt` also lists each resource of the design (LUT, FF, distributed and block RAM, DSP) and the units whose area moved, so a memory that leaves block RAM shows in minutes. Beacon does not see wires, placement or congestion; a change that moves those still needs synthesis. See [docs/designs/beacon.md §6.3](docs/designs/beacon.md).
- **`logic_gate` runs with `perf_gate`, and is treated the same way.** CI plans its cell whenever it plans perf_gate's rtlsim cells (every pull request, every push that touches the RTL or the config): perf_gate guards cycles, logic_gate guards logic depth and area. A red logic_gate means a unit got deeper or the design grew; fix it, or re-record with `ci/logic_gate.py --update-baseline` on the final tree, with the reason in the commit message. A change of CIRCT or foldsim reads `STALE` and needs the same re-record.
- **Synthesis baselines (`ci/baselines/synthesis/{xilinx,yosys,beacon,beacon_asic}/*.json`) are golden data under the same rule** — never hand-edited, regenerated only by a human running `ci/fpga_gate.py --update-baseline` / `ci/asic_gate.py --update-baseline` / `ci/logic_gate.py --update-baseline`, never by CI. A red `fpga_gate`/`asic_gate` means real Fmax or area moved; a red `logic_gate` means a unit got deeper or the design's area grew past 5 %, and its reasons name the unit or the resource (`beacon_area.txt` has the area by unit and each memory's placement). Note the two gates measure the *same* `hw/unittest/*/VX_*_top.sv` wrappers through different flows, so a divergence between them is a finding, not noise — keep `hw/syn/{xilinx,yosys}/dut/catalog.mk` in step when you add or rename a DUT. See [docs/designs/continuous_integration.md §3.5](docs/designs/continuous_integration.md).
- **Beacon first for any RTL change that can move timing; synthesis only to confirm.** A change to a pipeline, arbiter, queue, interface or datapath can add logic levels that only the nightly `fpga_gate` would find, hours later. Beacon finds them in minutes, so iterate on it, not on Vivado or Yosys: run `ci/logic_gate.py -b <dut> --against-rev HEAD` after each edit (the parent's reference is built once, under `.beacon_ref/`; `--tool beacon_asic` for the ASIC flow, which alone elaborates the STD FPU and the ASIC multiplier), and fix what `<build>/beacon_diff.txt` reports until nothing fails (`ci/beacon.py paths` shows a deep unit's paths op by op). Run synthesis once per change, on the DUTs whose depth moved, and feed the result back with `ci/beacon.py validate`. A change to the cluster, socket, L2 or anything only the whole GPU assembles also runs the `gpu` group (`ci/logic_gate.py -b gpu -j 1`, ~30 min and ~95 GB per build). A unit that gets deeper is fixed or, if intended, re-recorded with the reason in the commit message. `beacon_diff.txt` also lists each resource of the design (LUT, FF, distributed and block RAM, DSP) and the units whose area moved, so a memory that leaves block RAM shows in minutes. Beacon does not see wires, placement or congestion; a change that moves those still needs synthesis. See [docs/designs/beacon.md §6.3](docs/designs/beacon.md).
- **`logic_gate` runs with `perf_gate`, and is treated the same way.** CI plans its cell whenever it plans perf_gate's rtlsim cells (every pull request, every push that touches the RTL or the config): perf_gate guards cycles, logic_gate guards logic depth and area. A red logic_gate means a unit got deeper, the design grew, or a harness changed what it ties off; fix it, or re-record with `ci/logic_gate.py --update-baseline` (and `--tool beacon_asic`) on the final tree, with the reason in the commit message. On a pull request the cell also compares every build with the merge base, so a re-record there must run with `--against-rev $(git merge-base HEAD origin/master)`: that writes the accepted regressions into the baseline, and the baseline diff is their review. A change of CIRCT or foldsim reads `STALE` and needs the same re-record.
- **SimX is the RTL's timing model — keep them in lockstep.** Any change that moves RTL cycles (pipeline structure, arbitration, queue depths, cache/memory behavior) must land together with the matching SimX timing-model update, and vice-versa. The `model_parity` CI gate enforces this: a `check: model_parity` case (`ci/testcases/core.yaml` + per-extension parity categories) runs the same app/args/configs on simx and rtlsim and asserts exact retired-instruction match plus cycle agreement within the case tolerance (default 5%). Never widen a tolerance to absorb a divergence — model the behavior. When adding a hardware feature, add or extend a parity case that exercises it.
- **When RTL debugging stalls, switch to the SimX-as-oracle pattern.** For numerical bugs, deep pipeline races, or any failure mode where rtlsim is "close but wrong": (1) build/extend the SimX C++ model so it mirrors the *new* RTL architecture and gets to PASS; (2) add matching trace dumps to both SimX and RTL (cycle, FU events, SRAM addresses+data, hazards) — same CSV format on both sides; (3) diff trace files — the first divergence is the bug. Don't keep guessing from output values; localize via trace diff. See [docs/debugging.md](docs/debugging.md#simx-as-oracle-for-rtl-debug).

Expand Down
Loading
Loading