EAGLE4 RTL Onboarding
Handbook for new FPGA/RTL engineers · compiled 2026-09-29 from HQ records

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.

Three rules before you touch anything Never flash or run a card from asgard or any build host; box1 (trantor) is read-only for you except /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".

Batch-1 record, mt_bench w2 d3
323.30 M
HX1+FSL + full host stack + EAGER + EARLY_A + SPEC0, 3 rounds, fast boot. findings.csv F0511
Previous record (A5+FA)
307.67 M
+5.1% to the record. F0511 baseline
HX1+FSL humaneval w1 d4
382.53 M
F0514
TREE_STOP TSP12B on HX1+FSL
344.3 P
model, F0522; 2026-09-29/tracks/ts_deep/TS_DEEP.md
Boot class matters Pair speed depends on how the host booted. On a SLOW boot the HEAD root port logs 14 correctable errors at POST and the pair runs about 7% slower, with identical card cycles (F0507, 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):

IDLE→G1→G4→G5_ROPE→G6→G7G→G7U→G7_SILU→G9→G11→GLM→G12→TREE→G8→DONE

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

PhaseCardWhat it computesWhere to look
G1HEADRMSnorm of the input hidden statetop/top_fsm.sv, drafter
G4HEADQKV 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 DSP58systolic/gemv_lane_scaled_stream_dual.sv, primitives/e3b_packed_dot.sv
G5_ROPEHEADRoPE, 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 contextsattention_head_assembly(_pipe)
G6HEADo-projection plus residualdrafter
G7G / G7UHEADGate and up GEMVs (width 8192)drafter, GEMV array
G7_SILU / G7pTAIL (HEAD with I1)r5 = SiLU(gate) ⊙ up, Q6.12. 518 cycles per item Msilu_layer_fix
G9TAILDown GEMV; emits for_reasoning, the hidden state that seeds the next levellayers/g12x9_engine.sv (G9X shares the G12 engine)
G11TAILfc_out plus final norm (EARLY_A exports a here)drafter
GLMTAILLow-rank LM projection 3072 → 256 (Q1.15)drafter
G12TAILCheap 2-bit vocabulary head over about 128k logits, streamedlayers/g12x_engine.sv
TREETAILCheap top-8 plus the top-K_C candidate set; log₂ cumulative scores; the serializer pops one survivor per cyclelayers/tree_cheap_serializer.sv, layers/tree_level_fsm.sv
G8TAILExact fp16 rescore of the K_C shortlist against the lm-head in HBM. N=4 stripes need a duplicate lm-head copy in HBMg8_rescore_p; host lab/fb2_dup_lmfull_tail.py
tree outTAILNode-major tree → OUT-DMA for the host readbacklayers/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µsshare
TAIL item 0 done → next HEAD item 0 start (host detect and push)283%
HEAD item 037940%
Host relay (HEAD done → TAIL bell)819%
TAIL item 045147%
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.

Build-id allowlists drive host behaviour silently Every new HEAD or TAIL build id must be registered in the host kit (currently CONS_HOST) before it is paired. 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_EAGLE is the build-farm repo (EAGLE-FPGA): rtl/, scripts/, docs/, intents/, aved/, eagle4-dashboard/.
  • /shared/workspace/eagle4_adaptation/hardware/cleanup_EAGLE is the asgard snapshot of box1. It has EAGLE/v80_test_suite, verilog/forks (about 340 forks), scripts/mesh/, docs/MESH_DISPATCH.md, the handoff set docs/handoff_20260924/, .claude/skills/eagle4-* and START_HERE.md.
The snapshot is stale for host codeThe asgard snapshot's 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.mdThe "which door" table: setup, RTL-change path, scripts, artifacts
docs/build_machine_setup/README.md + CHECKLIST.mdBare Ubuntu → working build box, Stages 0–4, each with a verify gate
docs/build_machine_setup/launch_build.shDetached, parameterised pipeline launcher with a polite-wait guard. It never kills anything
docs/RUNBOOK_RTL_TO_PDI.mdThe 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.mdDeep reference for packaging and the AVED build
docs/SCRIPT_INVENTORY.md, docs/REPRODUCIBILITY_GAPS.mdEvery 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_*.shOne 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.shThe 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.tsvNetlist and config "teeth" used by the pipelines
intents/, reports/results/INTENT_*.envOne 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*.pyHost 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.mdStanding rules: roles, hard rules, where things live, the close-out procedure
hq_daily/findings.csv + FINDINGS_README.mdEvery quantified result (M/D/P) with evidence; rows are superseded, never deleted
hq_daily/branches.csvOne row per research branch (BRnnn): state, conclusion, links
hq_daily/images.csvEvery image: build id, contents, WNS/WHS, PDI md5, flash readiness, result
2026-09-28/CODE_MAP.mdRead 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.mdLatest 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):

shell environment
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 safetensors

The 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 .lic goes and XILINXD_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

HostRoleNotes
asgardR&D HQ: HQ session, design agents, quartermaster (QM). PDI builds and xsimAbout 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, olegvm3Breadth PDI builds and xsim gate armsUse the *_vmpar2 pipeline variants; each build on its own slot lock
midyardPDI builds (local Vivado) and CPU/Python workDisk is tight: keep at least 6 GB free
laptopxsim onlyDropped 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 filesRead-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 basics
~/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.sh

Nothing 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).

  1. Fork and strap. Copy the parent fork (create-only) and add your change behind a new *_V strap in top/eagle4_config.svh. Strap 0 must equal the parent. Record a FORK_NOTE_*.md and an MD5LIST.
  2. Static gates. Run S0 (pyslang elaboration with a planted "tooth" that must be caught), PLIST (scripts/gen_pkg_param_list.sh carries the strap into the BD re-synthesis), STEP3 checks and a host-kit registration. Write the results to GATE_RESULTS_<NAME>.txt.
  3. Derive the pipeline with per-slot paths (BR085). Every derived uni_pipeline must 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
  4. Package the handoff. Include the fork tarball + MD5LIST, the pipeline (plain and _vmpar2), a run_0x<id>.sh wrapper that exports SLOT/ROLE/FORK, checks md5s and execs the pipeline, GATE_RESULTS, the host kit and a README with landing and flash criteria. See fg8l/run_0xE4B711E4.sh and fg8l/README_FG8L.md.
  5. 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
  6. 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 .QUARANTINED marker, but the build always runs to a PDI.
  7. Done means STEP5 prints the PDI path, its md5 and magic=16a5f792. Landed PDIs are named oneflip_p2s_<role>_<host>_0x<id>_66m_<md5-8>.pdi under ~/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:

T1 xsim gate (minutes). Expect "TREEWALK GATE VERDICT: GREEN"
bash rtl/w_dispatch/scripts/run_treewalk_gate.sh all
launcher dry-run (STEP0 gates only, no Vivado)
bash 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).

Gotchas that cost real builds STEP2's 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_bs5 is the proven default. Use run_arm_bs2.sh / arm_job_bs2.sh, which give each run a private xsim.dir.
BOOTSKIP arms (from /shared/scratch/bootskip/README.md)
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:

GateMeaningExample (HXF / FG8L)
S0 / FORK / PLIST / STEP3Static: elaboration clean, a planted tooth caught, strap carried into packaging, fork diff exactly the intended filesFG8L: diff vs FG8 = exactly 4 files
G0 (or G2)Strap-off equals the parent, cycle-exact: KV rows @time, ITEMMON, rdlog, every seamHXF 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–G6Feature-specific checks: cross-harness, TREE_STOP stop depths, pair seamsFG8 TREE_STOP check_f9 stop 9/9
RED (often G4)A negative control that must diverge. A gate that cannot fail proves nothingFG8L 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

  1. Adjudicate against the parent. adjudicate_pdi.sh diffs the anchored GATE FAIL classes of the child's .QUARANTINED file 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.
    QM 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>
    Output goes to /shared/build/relay/<basename>/. Verdicts are recorded as …/build_efficiency/extra_checks/0x<id>.ADJUDICATION.txt; see 0xE4B711E4.ADJUDICATION.txt for a clean one.
  2. Check the FPT magic. The flashable image is the final FPT PDI whose first 4 bytes are 16 a5 f7 92, never impl_1/top_wrapper.pdi.
    magic check
    xxd -l4 oneflip_p2s_tail_asgard_0xE4B711E4_66m_7124bb8c.pdi   # expect 16a5 f792
  3. Relay to the box1 inbox. pdi_autorelay.sh polls the build hosts every 5 min and auto-relays only when NEW = 0 and WNS/WHS ≥ 0. relay_pdi.sh copies the PDI create-only into trantor:/sanctuary/pdi_inbox/, re-verifies md5 and magic on box1, and places the NOTE. Target: relayed within 30 min of landing.
  4. The NOTE. Filename NOTE_<pdi basename>_<YYYYMMDD>.md, for example NOTE_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.
  5. 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 example TAILBID=0xe4b711e4 lab_cp1.sh) and writes /sanctuary/lab/results/<date>/<TEST_ID>/REPORT.md plus a line in INDEX.csv. HQ mirrors that read-only into /shared/rnd_hq/lab_mirror/. Texts must match the parent (50/50), or the result is invalid.
  6. Close out. Report on disk → tools/add_finding.py row(s) → one hq_daily/branches.csv row → images.csv → python3 /shared/rnd_hq/hq_daily/build.py → commit.
    validate / add a finding
    python3 /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 clean or 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)RoleSLICE %LUT %FF %DSP %RAMB %URAM %
HX1 (gHX1_e3), record HEADHEAD60.95 / 99.77 / 49.5734.44 / 46.52 / 25.2211.52 / 48.11 / 12.3860.62 / 84.06 / 82.7818.49 / 79.17 / 73.5064.40 / 62.18 / 60.26
HM (gHM_max), HX1's parentHEAD96.22 / 99.99 / 75.0959.58 / 60.53 / 45.7012.46 / 51.83 / 10.8440.44 / 35.10 / 43.3415.81 / 79.67 / 76.0075.04 / 30.77 / 80.13
A5 (gA5_stack)HEAD50.63 / 82.85 / 84.1934.84 / 44.85 / 42.148.06 / 28.83 / 28.6014.06 / 26.22 / 60.6530.95 / 60.25 / 78.5078.58 / 58.33 / 28.21
FB2 (tFB2_g8n4)TAIL66.71 / 98.77 / 85.9045.08 / 61.08 / 60.1616.24 / 39.87 / 14.8316.82 / 43.58 / 67.5828.34 / 62.67 / 8.3370.16 / 26.44 / 30.77
FA (tFA_earlya)TAIL52.88 / 99.71 / 71.1738.09 / 64.61 / 49.838.36 / 51.95 / 11.0216.74 / 38.60 / 71.8927.44 / 55.33 / 13.6763.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

ImageBuild idRoleWNS nsWHS nsSource
HX10xE4B711BDHEAD+0.004+0.009images.csv M
HXF-EVAC0xE4B711DBHEAD0.000+0.010images.csv, F0510 M
HX1I10xE4B711E6HEAD+0.001+0.009images.csv M
FSL0xE4B711CCTAIL+0.210+0.010images.csv M
FS0xE4B711EFTAIL+0.024+0.010images.csv M
FG8L0xE4B711E4TAIL+0.021+0.011F0515 M
HXF (no evac)0xE4B711B4HEAD−0.989n/aF0500, 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 *_V define in eagle4_config.svh that 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 a at 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

  1. /shared/rnd_hq/RULES.md
  2. /shared/rnd_hq/2026-09-28/CODE_MAP.md
  3. eagle4-dashboard/site/DRAFTER_ARCHITECTURE_WHITEPAPER.md
  4. /shared/rnd_hq/hq_daily/findings.csv → branches.csv → images.csv
  5. /shared/rnd_hq/2026-09-27/SESSION_DISTILL_20260927.md
  6. docs/RUNBOOK_RTL_TO_PDI.md and docs/build_machine_setup/README.md
  7. One full handoff: /shared/scratch/tail_fg8/handoff/fg8l/

Recent track reports worth reading

ReportWhat you learn
2026-09-28/tracks/tail_algo/TAIL_ALGO.mdThe TAIL algorithm per item, dependency chains, where a level's µs go, ranked cuts
2026-09-28/tracks/slr1_ff/SLR1_FF_REPORT_v2.mdWhy SLR1 is full (demand, not spread), who owns it, how to free it
2026-09-28/tracks/hbm_g8/HBM_G8.mdWhat bounds the G8 HBM fetch; the 8-channel FN8 image
2026-09-28/consolidation/I1_SILU_CUT.md, HX1I1.mdMoving SiLU to the HEAD: pair seams, xsim evidence, SLR1 impact
2026-09-28/tracks/tail_fg8/FG8L.mdA route failure diagnosed and fixed by combining two deltas
2026-09-29/tracks/ts_deep/TS_DEEP.mdTREE_STOP at depth ≥ 7: the model, silicon check and lab kit
2026-09-28/consolidation/QSFP_CP1.mdFitting a card-to-card link on a full SLR1
/shared/scratch/bootskip/README.mdBOOTSKIP 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.

Ask HQ about this page

For the project lead: ask for supporting data, a clarification or a re-test. The answerer can only read HQ records and queue a re-test for the lab; it cannot build, flash or change anything. Answers arrive within a few minutes.