Start working on the EAGLE4 RTL
This page takes you from zero to a gated, relayed PDI, in the order you will need it. Every path on it is a real file you can open. Every number carries a label: M measured, D derived (arithmetic on measured data), P projected (a model; still needs a build or a run). read means it was read from source.
/sanctuary/pdi_inbox/. Never remove files (no rm, mv, rename, git clean); work create-only. Label every number measured, derived or projected, and give its evidence (path:line, plus md5 or commit).
01What the system is
EAGLE4 is a speculative-decoding drafter built in hand-written SystemVerilog on two AMD Alveo V80 cards (Versal HBM, part xcv80-lsva4737-2MHP-e-S). The drafter proposes a tree of candidate tokens. An NVIDIA H200 running SGLang verifies the tree in one batched forward pass. The drafter is one transformer layer plus heads with 2-bit weights, held on-chip (URAM/BRAM) and loaded once per session.
HEAD card
Front half of each drafter forward: G1 → G7 (norm, QKV GEMV, RoPE + attention with the KV cache, o-proj, gate/up GEMV, and SiLU in I1 images). It exports its seam block (the activations crossing to the other card) to an HBM out slot.
TAIL card
Back half plus the tree: G7p / G9 / G11 / GLM / G12 / TREE / G8 (SiLU·up, down GEMV, final norm, low-rank LM projection, cheap-head vocabulary sweep, candidate select, exact fp16 rescore from HBM). It returns the level's survivors.
Host relay
The host copies each item HEAD → TAIL over PCIe (a 71,680 B C2H then H2C per item read, in scripts/oneflip_relay_driver.py relay_item). No card-to-card link is in production yet; CP1Q (a QSFP link) is in research.
H200 verify
SGLang's tree verify accepts a prefix of the draft and commits it. Accepted rows are replayed into the FPGA KV cache on the next step (KV-only catch-up, or KVI).
The goal is batch-1 (single-stream) tokens per second. That is the headline number. Any multi-stream figure is labelled "batch 2 / aggregate".
2026-09-28/tracks/repro_diag/BOOT_DIFF.md). Compare A/B results only within one boot.
A GPU-only reference (no FPGA) reaches mt w3 d5 485.79 tok/s M (/shared/rnd_hq/2026-09-27/SESSION_DISTILL_20260927.md). The pair is closing that gap by making each tree level cheaper, so that deeper trees pay off.
02Architecture map
The top FSM is top/top_fsm.sv in each fork. Its state order on the HX1 line read (from /shared/rnd_hq/2026-09-28/CODE_MAP.md §4):
Both cards build from one shared top, top/eagle4_drafter.sv, selected by PIPE_ROLE. The blue states run in the HEAD role and the green ones in the TAIL role. The TAIL role runs G7_SILU as its first step unless the image has I1. Helper states: H_WAIT, PIPE_EXPORT, PIPE_WAIT, PIPE_INGEST, KVL (KVI) and LP_BAR (LEVEL_PIPE).
flowchart LR
subgraph HOST["Host (x86, SGLang process)"]
SG["SGLang step<br/>cost_draft_tree_fpga*.py"] --> MAR["marshaller<br/>root image Q4.12"]
RELAY["relay driver<br/>oneflip_relay_driver.py"]
end
subgraph HEAD["HEAD V80 (G1-G7)"]
G1["G1 RMSnorm"] --> G4["G4 QKV GEMV<br/>2-bit, URAM"] --> G5["G5 RoPE +<br/>24-head attention<br/>KV cache"] --> G6["G6 o-proj"] --> G7["G7G/G7U<br/>gate/up GEMV"] --> HX["PIPE_EXPORT<br/>seam block to HBM"]
end
subgraph TAIL["TAIL V80 (G7p-G8)"]
IN["PIPE_INGEST<br/>70 KB seams"] --> G7p["G7p SiLU x up"] --> G9["G9 down GEMV"] --> G11["G11 fc_out + norm"] --> GLM["GLM low-rank<br/>3072 to 256"] --> G12["G12 cheap-head<br/>vocab sweep"] --> TR["TREE<br/>top-K_C select"] --> G8["G8 exact fp16<br/>rescore (HBM)"]
end
MAR --> RELAY
RELAY -- "level 0: 12 KB H2C + doorbell" --> G1
HX -- "C2H 71,680 B" --> RELAY
RELAY -- "H2C + bell" --> IN
G8 -- "survivors 0x1A0-0x1BC" --> RELAY
RELAY -- "next level: parent a" --> G1
RELAY -- "finished tree (SoA 20,480 B)" --> GPU["H200 verify<br/>SGLang"]
GPU -- "accepted rows: KV catch-up / KVI" --> G5
What each block does
| Phase | Card | What it computes | Where to look |
|---|---|---|---|
| G1 | HEAD | RMSnorm of the input hidden state | top/top_fsm.sv, drafter |
| G4 | HEAD | QKV GEMV, 2-bit group-quantised (group 128) weights, Q3.13 scales. Lanes are CSA trees; on HX1 the E3b packed-DSP lane computes 2 lanes per DSP58 | systolic/gemv_lane_scaled_stream_dual.sv, primitives/e3b_packed_dot.sv |
| G5_ROPE | HEAD | RoPE, then attention with integer softmax against the resident KV cache. Each branch has its own cache rows (write-position addressing), so the tree never copies contexts | attention_head_assembly(_pipe) |
| G6 | HEAD | o-projection plus residual | drafter |
| G7G / G7U | HEAD | Gate and up GEMVs (width 8192) | drafter, GEMV array |
| G7_SILU / G7p | TAIL (HEAD with I1) | r5 = SiLU(gate) ⊙ up, Q6.12. 518 cycles per item M | silu_layer_fix |
| G9 | TAIL | Down GEMV; emits for_reasoning, the hidden state that seeds the next level | layers/g12x9_engine.sv (G9X shares the G12 engine) |
| G11 | TAIL | fc_out plus final norm (EARLY_A exports a here) | drafter |
| GLM | TAIL | Low-rank LM projection 3072 → 256 (Q1.15) | drafter |
| G12 | TAIL | Cheap 2-bit vocabulary head over about 128k logits, streamed | layers/g12x_engine.sv |
| TREE | TAIL | Cheap top-8 plus the top-K_C candidate set; log₂ cumulative scores; the serializer pops one survivor per cycle | layers/tree_cheap_serializer.sv, layers/tree_level_fsm.sv |
| G8 | TAIL | Exact fp16 rescore of the K_C shortlist against the lm-head in HBM. N=4 stripes need a duplicate lm-head copy in HBM | g8_rescore_p; host lab/fb2_dup_lmfull_tail.py |
| tree out | TAIL | Node-major tree → OUT-DMA for the host readback | layers/tree_out_walk.sv |
Where one level's time goes
Critical path per tree level on A5+FA at w2 with EAGER + SPEC0, median of levels 1→2 M (/shared/rnd_hq/2026-09-28/tracks/tail_algo/TAIL_ALGO.md §0):
| Segment | µs | share |
|---|---|---|
| TAIL item 0 done → next HEAD item 0 start (host detect and push) | 28 | 3% |
| HEAD item 0 | 379 | 40% |
| Host relay (HEAD done → TAIL bell) | 81 | 9% |
| TAIL item 0 | 451 | 47% |
| Total (measured level period: 951) | 940 |
ap_clk is 66 MHz, so one cycle is 15.15 ns. The GEMV array can run on a 132 MHz fast clock, and the KVI_FAN HBM path runs at 300 or 312 MHz read (CODE_MAP §4; /shared/scratch/consolidated_hxf/handoff_hxf/GATE_RESULTS_HXF.txt). The one-screen architecture rationale (weight residency, on-chip tree, per-stage numerics) is eagle4-dashboard/site/DRAFTER_ARCHITECTURE_WHITEPAPER.md. The interactive pages are eagle4-dashboard/site/drafter_arch.html and fpga_architecture.html.
Straps: how features are switched
Every feature is a *_V strap in top/eagle4_config.svh. The rule you must keep: strap = 0 must elaborate to exactly the parent image, cycle for cycle. That is gate G0 or G2 in every handoff. The main straps are DOT_E3_V (packed-DSP lanes), LEVEL_PIPE_V, SEAM_WIDE_V, KVI_FAN_V, EARLY_A_V, TREE_STOP_V / TREE_LX_V, SER_SKIP_V, G9X_V / G9Y_V, G8_NCH_V, SEAM_R4_LUTRAM_V (FSL) and PIPE_CUT_SILU_V (I1). The full strap → file → image table is in CODE_MAP §4.
KVONLY_HEAD_BUILDS and EARLY_A_TAIL_BUILDS live in the driver. If an id is missing, the feature quietly stays off. See CODE_MAP §5.2.
03Repo tour
Two copies are relevant. box1 is canonical: /home/y344shi/workspace/eagle4_adaptation/hardware/cleanup_EAGLE on trantor, which you only read. On asgard:
/shared/build/_inputs/workspace/eagle4_adaptation/hardware/cleanup_EAGLEis the build-farm repo (EAGLE-FPGA):rtl/,scripts/,docs/,intents/,aved/,eagle4-dashboard/./shared/workspace/eagle4_adaptation/hardware/cleanup_EAGLEis the asgard snapshot of box1. It hasEAGLE/v80_test_suite,verilog/forks(about 340 forks),scripts/mesh/,docs/MESH_DISPATCH.md, the handoff setdocs/handoff_20260924/,.claude/skills/eagle4-*andSTART_HERE.md.
scripts/oneflip_relay_driver.py (md5 8f1d6838) is not box1's text. The unified and FB2 driver shadows install only over box1's 6b83940f/048d7dbd. On anything else they print "NOT installed" and run the stock driver. The canonical repo's staged RTL is also old (LANES 128). Current RTL lives in the fork tarballs under /shared/scratch/<track>/ (CODE_MAP §5.1).| Path (build-farm repo unless stated) | What it is |
|---|---|
README.md | The "which door" table: setup, RTL-change path, scripts, artifacts |
docs/build_machine_setup/README.md + CHECKLIST.md | Bare Ubuntu → working build box, Stages 0–4, each with a verify gate |
docs/build_machine_setup/launch_build.sh | Detached, parameterised pipeline launcher with a polite-wait guard. It never kills anything |
docs/RUNBOOK_RTL_TO_PDI.md | The linear path: edit → xsim gates → package IP → build → PDI and quarantine |
docs/PACKAGING_SCRIPT_CHAIN.md, RTL_TO_IP_GUIDE.md, BUILD_LAUNCH_README.md, PDI_BUILD_RECIPE.md | Deep reference for packaging and the AVED build |
docs/SCRIPT_INVENTORY.md, docs/REPRODUCIBILITY_GAPS.md | Every script and its caller; what a clean clone could and could not reproduce |
rtl/ | Older RTL lines kept in the repo (pdi23_opt1g_pipe, w_dispatch, treewalk_fix, osprey, …) with their check scripts |
verilog/forks/ | Per-experiment forks: each has src_full/{top,layers,systolic,primitives,…} |
scripts/uni_pipeline_*.sh | One build pipeline per image line: STEP0 gates → STEP1 package → STEP2 clone → STEP3 staged-IP verify → STEP4 build → STEP4c netlist gates → STEP5 FPT PDI |
scripts/preflash_gate.sh | The pre-flash gate: PDI-1..5 (exists, md5, FPT magic 16a5f792, size band, AMC firmware, no .QUARANTINED) plus HOST-1..4. The lab runs it |
scripts/check_*.sh, netlist_check_rules.tsv | Netlist and config "teeth" used by the pipelines |
intents/, reports/results/INTENT_*.env | One intent file per build ticket (the design intent the gates compare against) |
scripts/fpga_tree_marshaller.py, scripts/oneflip_relay_driver.py, pair_sglang_bridge.py, cost_draft_tree_fpga*.py | Host side: marshal, relay, bridge to SGLang (read CODE_MAP §2 for the step-by-step) |
snapshot: EAGLE/v80_test_suite/ | The lab's card toolkit (find device, flash, QDMA setup, HBM and kernel-register tests). Read it to understand the card, but never run it from asgard |
snapshot: scripts/mesh/ | Source of the mesh dispatcher; the installed copy is ~/mesh/ |
eagle4-dashboard/site/ | Whitepaper, architecture pages, build monitor data |
HQ records (the project's memory is files)
Path under /shared/rnd_hq/ | What it holds |
|---|---|
RULES.md | Standing rules: roles, hard rules, where things live, the close-out procedure |
hq_daily/findings.csv + FINDINGS_README.md | Every quantified result (M/D/P) with evidence; rows are superseded, never deleted |
hq_daily/branches.csv | One row per research branch (BRnnn): state, conclusion, links |
hq_daily/images.csv | Every image: build id, contents, WNS/WHS, PDI md5, flash readiness, result |
2026-09-28/CODE_MAP.md | Read this first as an RTL engineer: file → role, one decode step end to end, straps, surprises |
<date>/tracks/<track>/ | Per-track reports (links into /shared/scratch/<track>/) |
2026-09-27/SESSION_DISTILL_20260927.md | Latest distilled HQ state |
lab_mirror/, from_box1/ | Read-only mirror of the lab's results and state (LAB_STATE.md, results/) |
tools/ | add_finding.py, stale_kill.sh, buildmon.sh, … |
04Toolchain setup and build hosts
Vivado 2025.1
Every build and xsim uses Vivado 2025.1. On asgard and the farm the install is /shared/tools/xilinxinstall/2025.1. On midyard it is a local install, ~/workspace/xilinx_install/2025.1. Every working shell needs (from docs/build_machine_setup/README.md §3.1):
export VROOT=/shared/tools/xilinxinstall/2025.1
source $VROOT/Vivado/settings64.sh
export PATH="$VROOT/gnu/armr5/lin/gcc-arm-none-eabi/bin:$PATH"
python3 -m pip install --user numpy safetensorsThe pipelines source this themselves. The AMC firmware step needs the ARM GCC on PATH, and bootgen needs settings64.sh.
Licences
- Licensing is arranged through the project lead. Don't guess licence paths. Setup guide §1.2 covers the account, where the
.licgoes andXILINXD_LICENSE_FILE. - The reference box's licence is node-locked. The Oleg VMs use asgard's floating licence through a tunnel (comment in
~/mesh/mesh_run.sh). - The AVED base needs a separate SMBus IP licence increment (
axi_smbus_rpu). Without it block design fails even though OOC synth works. See the setup guide's "Verifying a new build machine actually builds". - Licensing is proven by a synthesis run that prints
Got license for feature 'Synthesis' and/or device 'xcv80', not by the GUI opening. - No licence files, keys or passwords go into any file, commit or page.
Hosts and what each is for
| Host | Role | Notes |
|---|---|---|
| asgard | R&D HQ: HQ session, design agents, quartermaster (QM). PDI builds and xsim | About 1.5× faster per PDI than the Oleg VMs M (HEAD build 4 h 56 m vs 7 h 16 m; 2026-09-25/tracks/parallel_test/PARALLEL_TEST_20260925.md). Urgent images go here |
| olegvm, olegvm2, olegvm3 | Breadth PDI builds and xsim gate arms | Use the *_vmpar2 pipeline variants; each build on its own slot lock |
| midyard | PDI builds (local Vivado) and CPU/Python work | Disk is tight: keep at least 6 GB free |
| laptop | xsim only | Dropped from the mesh (2026-09-27); too slow for sibling arms |
| box1 (trantor) | Silicon lab: 2 × V80 + H200. Flashes, runs pair tests, reports results as files | Read-only for you. Its own session owns every card action. You only drop into /sanctuary/pdi_inbox/ |
Floors that the guards actually enforce: a full build peaks at 38–64 GB resident. launch_build.sh refuses to start when free RAM is below 38 GB, free disk is below 100 GB, or another Vivado is running. A host with 64–127 GB RAM is single-build only.
Mesh: every xsim or build goes through it
~/mesh/mesh_run.sh admits a job only if the host's available memory, minus what running jobs will still grow into, covers your --peak. It blocks until the job ends. Hosts: asgard olegvm olegvm2 olegvm3 midyard (MESH_HOSTS in the script). Full semantics: snapshot docs/MESH_DISPATCH.md. That file predates the current host list.
~/mesh/mesh_status.sh # one line per host
python3 ~/mesh/mesh_core.py history # measured per-class peaks on this host
~/mesh/mesh_run.sh --peak 2.0 --class my_xsim_gate --host olegvm3 \
--log /shared/scratch/mytrack/gate.log -- bash /shared/scratch/mytrack/run_gate.shNothing is copied: every path in the command, --cwd and --log must exist on the target host. Give an honest --peak and a specific --class name. Judge host health by free -g and real processes, not by mesh reservations.
05Your first build: handoff → PDI
At HQ, designers don't launch builds by hand. A design agent (or you) produces a handoff directory, and the QM builds it through the mesh. A real, recent example you can open is /shared/scratch/tail_fg8/handoff/fg8l/ (TAIL FG8L 0xE4B711E4).
- Fork and strap. Copy the parent fork (create-only) and add your change behind a new
*_Vstrap intop/eagle4_config.svh. Strap 0 must equal the parent. Record aFORK_NOTE_*.mdand an MD5LIST. - Static gates. Run S0 (pyslang elaboration with a planted "tooth" that must be caught), PLIST (
scripts/gen_pkg_param_list.shcarries the strap into the BD re-synthesis), STEP3 checks and a host-kit registration. Write the results toGATE_RESULTS_<NAME>.txt. - Derive the pipeline with per-slot paths (BR085). Every derived
uni_pipelinemust be patched so intent, verdict, log and marker files are per-SLOT. Otherwise two builds on one host overwrite each other's intent and produce false CONFIG MANIFEST FAILs.per-slot patch (create-only; refuses on count mismatch)python3 /shared/rnd_hq/2026-09-27/tracks/build_efficiency/per_slot_paths.py \ uni_pipeline_parent.sh uni_pipeline_mine.sh --expect-total N python3 /shared/rnd_hq/2026-09-27/tracks/build_efficiency/per_slot_paths.py --check uni_pipeline_mine.sh - Package the handoff. Include the fork tarball + MD5LIST, the pipeline (plain and
_vmpar2), arun_0x<id>.shwrapper that exportsSLOT/ROLE/FORK, checks md5s and execs the pipeline,GATE_RESULTS, the host kit and a README with landing and flash criteria. Seefg8l/run_0xE4B711E4.shandfg8l/README_FG8L.md. - Build through the mesh. The exact QM command from
README_FG8L.md:stage and launch (Oleg VM, VM-parallel pipeline)mkdir -p $STAGE/forks && tar xzf fork_tail_fg8l_20260928.tar.gz -C $STAGE/forks cp uni_pipeline_tail_fg8l*_asgard.sh MD5LIST_tail_fg8l_20260928.txt run_0xE4B711E4*.sh $STAGE/ ~/mesh/mesh_run.sh --peak 70 --class pdi_build_tail_fg8l --host olegvm3 \ --log $STAGE/mesh.log -- env FG8L_STAGE=$STAGE bash $STAGE/run_0xE4B711E4_vmpar2.sh # plain pipeline on asgard: --peak 80 and run_0xE4B711E4.sh - Watch it. Look for a Vivado phase line that keeps advancing. The flow is STEP0.x gates (minutes) → STEP1 packaging (~1 h) → STEP2 clone and patch → STEP3 staged-IP verify → STEP4
build_all.sh(3–5 h: synth, place, route, write_device_image) → STEP4c netlist gates → STEP5 final FPT PDI. Gates only report: any FAIL sets QUARANTINE and the PDI is born with a.QUARANTINEDmarker, but the build always runs to a PDI. - Done means STEP5 prints the PDI path, its md5 and
magic=16a5f792. Landed PDIs are namedoneflip_p2s_<role>_<host>_0x<id>_66m_<md5-8>.pdiunder~/eagle4_artifacts/uni_oneflip/on the build host.
Standalone path (a fresh build machine)
To prove a new box, follow the setup guide: T1 xsim gate, T2 packaging byte-identity, then a launcher dry-run. These commands are verbatim from docs/build_machine_setup/README.md §3.2–3.4, run from the repo root:
bash rtl/w_dispatch/scripts/run_treewalk_gate.sh allbash docs/build_machine_setup/launch_build.sh \
-p scripts/uni_pipeline_serial_0x112B_box1.sh \
-i reports/results/INTENT_baseline_0x112B.env \
-I DRYRUN_$(date +%s) --dry-run--dry-run is refused on pipelines that never read STOP_BEFORE_STEP1, because such a pipeline would run a full build. If STEP5 says "no final FPT PDI" but top_wrapper.pdi exists, don't rebuild. Finish the FPT tail by hand (setup guide §4.3, from scripts/finish_from_dcp.sh).
rsync --delete discards hand edits made in a clone. Apply fixes through the pipeline with count-asserted patches. Never edit a running script (bash re-reads it). xsim exits 0 on $fatal, so parse the log for a positive PASS anchor. Seed FREQ_HZ with the measured odd frequency (for example 66001043), never a round number. /tmp/p4 links vanish on reboot.06Simulation: BOOTSKIP xsim and the gates
A full-HEAD xsim gate first replays the L256 boot op-log: 28,672 weight bursts, 66,617 CSR writes and 6 scale DMAs. That boot alone took 3.4–4.5 h per arm on the laptop M. BOOTSKIP (BR084) boots once per config, snapshots the post-boot weight and scale memories, and preloads them in every later arm. It is TB-only: a bind into weight_bank_uram and scale_bram, with the DUT untouched.
- Boot drops from 37.83 to 8.42 ms simulated, and a whole REF arm from 2 h 43 m to 1 h 27 m M. The equivalence proof was 29/29 seams, rdlog and 1,021 monitor lines identical.
- Guards: 1 in 32 skipped bursts is replayed and compared, all scale-DMA writes are compared, and a mismatch is
$fatal. A corrupted preload was caught (15/29 seams differ). A LOAD is refused when the boot op-log md5 differs from the snapshot's. tb_bs5is the proven default. Userun_arm_bs2.sh/arm_job_bs2.sh, which give each run a private xsim.dir.
G=/shared/scratch/sibling_w2/gate; B=/shared/scratch/bootskip
export XX="<the arm's -d list, exactly as in launch_sib3.sh>"
TB=$G/tb_bs5 bash $B/bs_arm.sh <host> <ARM> <src_*> load $B/snap/src_T4h_sib3_L256
TB=$G/tb_bs5 bash $B/bs_arm.sh <host> <ARM2> <src_*> load $B/snap/src_T4h_sib3_L256 $G/build_<ARM>
# new boot stream or weight-path RTL: one full-boot DUMP arm first
TB=$G/tb_bs5 bash $B/bs_arm.sh <host> <REFARM> <src_*> dump $B/snap/<new name>The TAIL uses its own full-chain harness (tail_g9y/tools/run_fb2_gate.sh, 18 items, BOOTSKIP boot ops) with the comparator compare_tail_fast_fullchain.py. See /shared/scratch/tail_fg8/handoff/fg8l/GATE_RESULTS_FG8L.txt.
The gate ladder
Numbering is per handoff, so read each GATE_RESULTS_*.txt. The pattern is always the same:
| Gate | Meaning | Example (HXF / FG8L) |
|---|---|---|
| S0 / FORK / PLIST / STEP3 | Static: elaboration clean, a planted tooth caught, strap carried into packaging, fork diff exactly the intended files | FG8L: diff vs FG8 = exactly 4 files |
| G0 (or G2) | Strap-off equals the parent, cycle-exact: KV rows @time, ITEMMON, rdlog, every seam | HXF DOT_E3 0 vs HMF: 29/29 seams, KV 928/928 |
| G1 (or G3) | Strap-on is functionally identical where it must be (same KV, same seams, same tree) | FG8L LUTRAM seams vs FG8: 18/18 items, 0 mismatches |
| G1x / G2–G6 | Feature-specific checks: cross-harness, TREE_STOP stop depths, pair seams | FG8 TREE_STOP check_f9 stop 9/9 |
| RED (often G4) | A negative control that must diverge. A gate that cannot fail proves nothing | FG8L RED: 2,333,858 mismatches, fired as required |
A flash gate is usually "xsim G0–G4 GREEN + PDI adjudicated clean + WNS/WHS ≥ 0". The handoff README states it explicitly.
07Adjudication and relay: how a PDI becomes flashable
- Adjudicate against the parent.
adjudicate_pdi.shdiffs the anchoredGATE FAILclasses of the child's.QUARANTINEDfile against the parent's (digits and hashes normalised). It also reads route WNS/WHS from impl_1 and checks the FPT magic and that the md5 matches the filename. The rule: 0 NEW FAIL classes vs parent, WNS ≥ 0 and WHS ≥ 0. Anything else is held for the QM, who reads each NEW class; some turn out to be path or relabel artifacts.Output goes toQM tool (read-only on hosts)bash /shared/rnd_hq/2026-09-26/tracks/build_efficiency/adjudicate_pdi.sh \ <host> <pdi_basename> <parent_host> <parent_basename>/shared/build/relay/<basename>/. Verdicts are recorded as…/build_efficiency/extra_checks/0x<id>.ADJUDICATION.txt; see0xE4B711E4.ADJUDICATION.txtfor a clean one. - Check the FPT magic. The flashable image is the final FPT PDI whose first 4 bytes are
16 a5 f7 92, neverimpl_1/top_wrapper.pdi.magic checkxxd -l4 oneflip_p2s_tail_asgard_0xE4B711E4_66m_7124bb8c.pdi # expect 16a5 f792 - Relay to the box1 inbox.
pdi_autorelay.shpolls the build hosts every 5 min and auto-relays only when NEW = 0 and WNS/WHS ≥ 0.relay_pdi.shcopies the PDI create-only intotrantor:/sanctuary/pdi_inbox/, re-verifies md5 and magic on box1, and places the NOTE. Target: relayed within 30 min of landing. - The NOTE. Filename
NOTE_<pdi basename>_<YYYYMMDD>.md, for exampleNOTE_oneflip_p2s_tail_asgard_0xE4B711E4_66m_7124bb8c_20260929.md. Contents: a title line with the PDI and time; the adjudication verdict vs the named parent (labelled measured); the full adjudication output (md5, magic, WNS/WHS, classes); and the flash instruction: "use the host kit named in images.csv; this is an FPT PDI (magic 16a5f792)". Add the pairing constraint (for example "PAIR-ONLY with HX1I1 E6"), the required CONS_HOST version and any host prerequisite, such as the duplicate lm-head H2C for G8 N=4 TAILs. - What box1 does. The lab session runs
scripts/preflash_gate.sh(PDI-1..5 + HOST-1..4). It flashes only with-p 0, during a cold-AC window the user approves. Then it runs the pair protocol with the named CONS_HOST kit (for exampleTAILBID=0xe4b711e4 lab_cp1.sh) and writes/sanctuary/lab/results/<date>/<TEST_ID>/REPORT.mdplus a line inINDEX.csv. HQ mirrors that read-only into/shared/rnd_hq/lab_mirror/. Texts must match the parent (50/50), or the result is invalid. - Close out. Report on disk →
tools/add_finding.pyrow(s) → onehq_daily/branches.csvrow →images.csv→python3 /shared/rnd_hq/hq_daily/build.py→ commit.validate / add a findingpython3 /shared/rnd_hq/tools/add_finding.py --check python3 /shared/rnd_hq/tools/add_finding.py --list-features python3 /shared/rnd_hq/hq_daily/build.py
Hard rules
- Never flash or run cards from asgard or any build host. box1 is read-only for you, except dropping files into
/sanctuary/pdi_inbox/. No FLR, SBR, device_boot or PCIe remove, ever. - No file removals: no rm, mv, rename,
git cleanor worktree remove. Create new files; symlinks are fine. - Label every number measured, derived or projected, with evidence (path:line + md5 + commit).
- Never stop a process you didn't start. A build confirmed stale for 2 h or more is killed only through
bash /shared/rnd_hq/tools/stale_kill.sh <host> <pid>, which verifies itself. - Gates report; they never abort a build. A FAIL quarantines the PDI; the flash decision belongs to the user and the lab.
- Done = positive routed setup AND hold slack. The netlist is the truth, not the RTL: prove intentional changes in the built netlist.
- No secrets in files, commits or pages.
08Resource and timing budget today
These are placed utilisation per SLR, as SLR0 / SLR1 / SLR2 %, all M from place_report_utilization_0.rpt via /shared/rnd_hq/2026-09-28/VIVADO_SLR_SUMMARY_full.txt. Device totals: 2,574,208 CLB LUTs, 5,148,416 registers, 321,776 slices, 1,925 URAM.
| Image (slot) | Role | SLICE % | LUT % | FF % | DSP % | RAMB % | URAM % |
|---|---|---|---|---|---|---|---|
| HX1 (gHX1_e3), record HEAD | HEAD | 60.95 / 99.77 / 49.57 | 34.44 / 46.52 / 25.22 | 11.52 / 48.11 / 12.38 | 60.62 / 84.06 / 82.78 | 18.49 / 79.17 / 73.50 | 64.40 / 62.18 / 60.26 |
| HM (gHM_max), HX1's parent | HEAD | 96.22 / 99.99 / 75.09 | 59.58 / 60.53 / 45.70 | 12.46 / 51.83 / 10.84 | 40.44 / 35.10 / 43.34 | 15.81 / 79.67 / 76.00 | 75.04 / 30.77 / 80.13 |
| A5 (gA5_stack) | HEAD | 50.63 / 82.85 / 84.19 | 34.84 / 44.85 / 42.14 | 8.06 / 28.83 / 28.60 | 14.06 / 26.22 / 60.65 | 30.95 / 60.25 / 78.50 | 78.58 / 58.33 / 28.21 |
| FB2 (tFB2_g8n4) | TAIL | 66.71 / 98.77 / 85.90 | 45.08 / 61.08 / 60.16 | 16.24 / 39.87 / 14.83 | 16.82 / 43.58 / 67.58 | 28.34 / 62.67 / 8.33 | 70.16 / 26.44 / 30.77 |
| FA (tFA_earlya) | TAIL | 52.88 / 99.71 / 71.17 | 38.09 / 64.61 / 49.83 | 8.36 / 51.95 / 11.02 | 16.74 / 38.60 / 71.89 | 27.44 / 55.33 / 13.67 | 63.52 / 14.42 / 39.74 |
TAIL SLR1 CLB LUT on the current lineage (/shared/scratch/tail_fg8/handoff/fg8l/GATE_RESULTS_FG8L.txt): FS 67.81% M (routed); FSL 57.50% M; FG8 74.04% M, which failed route with 48,712 overlaps; FG8L about 63.7% P additive, and it then routed (F0515).
Routed timing of recent images
| Image | Build id | Role | WNS ns | WHS ns | Source |
|---|---|---|---|---|---|
| HX1 | 0xE4B711BD | HEAD | +0.004 | +0.009 | images.csv M |
| HXF-EVAC | 0xE4B711DB | HEAD | 0.000 | +0.010 | images.csv, F0510 M |
| HX1I1 | 0xE4B711E6 | HEAD | +0.001 | +0.009 | images.csv M |
| FSL | 0xE4B711CC | TAIL | +0.210 | +0.010 | images.csv M |
| FS | 0xE4B711EF | TAIL | +0.024 | +0.010 | images.csv M |
| FG8L | 0xE4B711E4 | TAIL | +0.021 | +0.011 | F0515 M |
| HXF (no evac) | 0xE4B711B4 | HEAD | −0.989 | n/a | F0500, failed route M |
What this tells you. Typical passing WNS is only +0.00 to +0.2 ns at 66 MHz, so there is little margin. SLR1 is the wall on both cards. On HX1 the SLR1 slice count is almost all demand: the additive floor (LUT/8 + FF/16) is 94.6% against 99.77% placed, so spread is about 5 pp D (2026-09-28/tracks/slr1_ff/SLR1_FF_REPORT_v2.md). Placer directives buy at most ~5 pp. Real relief removes FF or LUT volume: FSL moved the TAIL R4 seams to LUTRAM (about −295K FF), DOT_E3 cut about −115K SLR1 LUT on HX1, and EVAC moved the R4 seam/SiLU pblock to SLR0. Seam flip-flops (SEAM_FF=1) are about half of all TAIL FFs M (TAIL_ALGO §0).
09Glossary
- SLR
- Super Logic Region: one of the V80's three stacked dies (SLR0/1/2). Signals between SLRs cross on SLL wires, which are limited (18,870 per boundary pair) and slow. SLR1 is the congested middle die on both cards.
- pblock
- A Vivado placement region constraint. Soft pblocks guide placement; hard or EXCLUDE_PLACEMENT pblocks reserve area (for example the QSFP link's X8Y6:X9Y6).
- tooth
- A gate check that has been proven able to fail. A defect is planted (an undeclared net, a wrong row, a flipped strap) and the check must catch it. A gate without a tooth is "vacuous".
- strap
- A
*_Vdefine ineagle4_config.svhthat switches a feature. Strap 0 must equal the parent image. - seam
- The register-file buffer between pipeline phases (r1, r4g/r4u, r5, r8, …). The HEAD → TAIL seam block is 71,680 B per item.
- HEAD / TAIL
- The two V80 roles (
PIPE_ROLE): HEAD runs G1–G7, TAIL runs G7p–G8 plus the tree. - HX1
- HEAD 0xE4B711BD = HM + DOT_E3 (E3b packed-DSP58 lanes, 2 lanes per DSP). The record HEAD.
- E3b / DOT_E3
- One DSP58 computes the 2-bit products of two lanes; −74% LUT per MAC, bit-exact.
- FS / FSL
- FS = TAIL FF + SER_SKIP (the serializer skips records that the G8 threshold rejects). FSL = FS + SEAM_R4_LUTRAM_V (R4 seams in LUTRAM instead of FFs). FSL is the record TAIL.
- FG8 / FG8L
- FG8 overlaps the G8 rescore floor with the TREE sweep (about −49 µs per item P). It failed route in SLR1. FG8L = FG8 on the FSL LUTRAM base, which routes.
- EVAC
- A constraints-only evacuation: the R4 seam/SiLU soft pblock moves from SLR1 to SLR0 to free SLR1. HXF-EVAC 0xE4B711DB is HXF with this plus the CP1Q keep-out.
- I1
- PIPE_CUT_SILU: SiLU moves from the TAIL to the HEAD, so the relay carries r5 instead of r4g+r4u (−69% relay bytes M). It pairs only with a matching TAIL (for example HX1I1 + FG8I1).
- TREE_STOP
- Stops the tree early at a level boundary, using a host rule (commit mass, θ, d_max) that reads per-level LX scores. It lets deep trees (d7) pay: +16.2% at w2 d7 on one boot M (F0517). TSPnn / TSEnn are theta arms.
- EAGER
- The TAIL exposes survivors early (CSRs 0x1D0–0x1F8), so the host can start the next level before the full commit.
- EARLY_A
- The TAIL exports
aat G11 exit, overlapping level L+1's HEAD issue with level L's commit. - SPEC0
- Cross-level speculation on branch 0: the host issues the next level's rank-0 item from ITEM_BEST (0x1F8) before the commit. A miss is retired unrelayed and re-issued. Env
EAGLE4_PAIR_SPEC0=1; it acts only with EAGER. - KVI
- KV ingest: accepted KV rows from the GPU verify are loaded straight into the HEAD's KV cache (KV_LOAD, CSRs 0x1E0–0x1F4, FSM state S_KVL), instead of replaying catch-up items.
- KVI_FAN
- A fan-out KV read path on a separate HBM clock (300/312 MHz).
- CP1 / CP1Q
- CP1 = the consolidated pair (best HEAD + best TAIL, BR093). CP1Q = CP1 plus a QSFP card-to-card link replacing the host relay hop (about +1.5% P,
2026-09-28/consolidation/QSFP_CP1.md). - LEVEL_PIPE
- HEAD pipelining across items within a level (FSM LP_BAR).
- G9X / G9Y
- G9 tiles time-share the G12 engine (G9X); G9Y adds a second engine in SLR0.
- K_F, K_C
- Frontier width (8 nodes, each expanded ×8 = 64 candidates) and the rescore shortlist (64 or 512).
- w / d
- Tree width and depth in test cells, for example "mt w2 d3" = mt_bench, width 2, depth 3.
- FPT PDI
- The final flashable image with the firmware partition table; its first bytes are
16a5f792. - QUARANTINED
- A sidecar marker beside a PDI listing its gate FAIL rows. It blocks the flash until reviewed.
- BOOTSKIP
- The xsim TB preload of the post-boot memories (BR084).
- BR / F / slot
- BRnnn = a branch row in branches.csv; Fnnnn = a finding row; SLOT = a per-build lock and path key (BR085).
- QM
- The quartermaster agent on asgard: owns builds, mesh, image registry and relays to box1.
- CONS_HOST
- The consolidated host kit (sitecustomize shadows plus lab scripts) that registers each build id and drives a pair test. Its version is named in every NOTE.
- M / D / P
- Measured / derived (arithmetic on measured data) / projected (a model).
10Where to ask, what to read next
Who to ask
- HQ main session (asgard): design questions, which experiment is next, reviews of your GATE_RESULTS.
- Quartermaster (QM): build queue, mesh admission, adjudication, relays.
- The lab (box1 session): silicon questions. Ask through files, never by touching box1. Read its reports in
/shared/rnd_hq/lab_mirror/results/. - The project lead (Carrick): decisions only (cold AC, sudo, deletions, permission rules, stopping live long jobs, real trade-offs). They are often away about 03–11 EDT, so batch your questions. Past guidance is logged verbatim in
/shared/rnd_hq/USER_QUOTES.md.
Reading order
/shared/rnd_hq/RULES.md/shared/rnd_hq/2026-09-28/CODE_MAP.mdeagle4-dashboard/site/DRAFTER_ARCHITECTURE_WHITEPAPER.md/shared/rnd_hq/hq_daily/findings.csv→branches.csv→images.csv/shared/rnd_hq/2026-09-27/SESSION_DISTILL_20260927.mddocs/RUNBOOK_RTL_TO_PDI.mdanddocs/build_machine_setup/README.md- One full handoff:
/shared/scratch/tail_fg8/handoff/fg8l/
Recent track reports worth reading
| Report | What you learn |
|---|---|
2026-09-28/tracks/tail_algo/TAIL_ALGO.md | The TAIL algorithm per item, dependency chains, where a level's µs go, ranked cuts |
2026-09-28/tracks/slr1_ff/SLR1_FF_REPORT_v2.md | Why SLR1 is full (demand, not spread), who owns it, how to free it |
2026-09-28/tracks/hbm_g8/HBM_G8.md | What bounds the G8 HBM fetch; the 8-channel FN8 image |
2026-09-28/consolidation/I1_SILU_CUT.md, HX1I1.md | Moving SiLU to the HEAD: pair seams, xsim evidence, SLR1 impact |
2026-09-28/tracks/tail_fg8/FG8L.md | A route failure diagnosed and fixed by combining two deltas |
2026-09-29/tracks/ts_deep/TS_DEEP.md | TREE_STOP at depth ≥ 7: the model, silicon check and lab kit |
2026-09-28/consolidation/QSFP_CP1.md | Fitting a card-to-card link on a full SLR1 |
/shared/scratch/bootskip/README.md | BOOTSKIP design, proof and usage |
Paths starting with a date are under /shared/rnd_hq/; bare repo paths are relative to the build-farm repo root.