Branch Merge Roadmap

Warm-TDM branch merge roadmap

Last updated: 2026-08-17

A single cross-track view of the active development branches and the order to land them. This coordinates work across branches, so it lives on the wiki rather than on any one branch. Integration flow (per docs/RELEASE.md): feature → pre-release → main; the repo is merge-not-rebase.

Live status lives on the board, not here. Per-issue state, assignees, and progress are on the GitHub Project Warm-TDM Roadmap. This page holds only what the board can't: the cross-track picture, the PR-stack shape, and the sequencing decisions with their rationale. When the two disagree, the board wins on status; this page wins on why.

The main PR stack (land bottom-up)

The largest tracks are chained as stacked PRs onto pre-release. Each merges into the one below it, so they land in order from the base up:

pre-release
  └─ #78  wtj-refactor      Jupyter → warm_tdm_api.operations refactor   (#68)   [ready]
       └─ #87  fp-pid       Floating-point PID firmware                  (#70)   [draft]
            └─ #88  cleanup Resource-optimization RTL + legacy-Python removal    [draft]
                 └─ channelization  Self-describing frames + channel cleanup (#82) [not started]

• #78 wtj-refactor → pre-release (#68) — the operations refactor; structural foundation the rest build on. Ready, pending analog-bench hardware validation. It already absorbed the old wtj (PR #61, now closed) and the software half of cleanup.
• #87 fp-pid → wtj-refactor (#70) — floating-point PID firmware (AdcDspFp + accumulator split). Draft; needs hardware validation. Carries the untested RTL, so it sits above the SW refactor rather than gating it.
• #88 cleanup → fp-pid — resource-optimization RTL and legacy-Python removal; the firmware remainder that was unique to cleanup. Draft, tops the stack.

Other open tracks

Track	Issue	PR / Branch	Status	Blocker
Ad9681 DDR ADC readout	#69	test-ad9681-ddr	code done (2026-08-06)	surf release (external)
RTL cocotb/GHDL regression	#90	rtl-cocotb-regression	AdcDsp bench GREEN 5/5 (GHDL); AdcDspFp authored, SKIPPED	FP bench needs a VCS run + compiled Vivado FP-IP sim libs
SW TES bias waveform generator	#55	PR #79 tes-bias-waveform	open	—
Docker build option	—	PR #58 docker	open	—
Setup instructions + CI python bump	—	PR #74 basic_instructions	open	—
maxRows → tree sizing (firmware half)	#73	— (no branch yet)	design agreed; needs FW	expose ROW_ADDR_BITS_G register
Self-describing data frames + channel-layout cleanup	#82	channelization (off cleanup)	worktree created 2026-08-17; work not yet started	rides the FP-PID + resource-cleanup HW gate (see decision below)

rtl-cocotb-regression rides on the fp-pid firmware it tests (Python-first cocotb/GHDL harness; its only RTL edits are the SIMULATION_G inferred-vs-xpm FIFO hooks — hardware still defaults to xpm). Tracked on its own as #90 so the regression capability isn't lost behind the FP-PID track. Status doc: docs/_meta/rtl_regression_progress.md.

Reference branches (keep, never merge)

Deliberately kept as a permanent reference; not merge candidates and not triage. Leave them alone.

• vesper — one-off test project for the Vesper/Boreas amplifier column-board variant (device driver, SA bias/offset variant, Boreas config + aux-DAC wiring, amp-model→config linkage). Never merges; untracked by design.
• artix-us — exploration of an Artix UltraScale+ (AU25P) column-board design (fit + power draw). No board uses this chip today; one is expected years out. Compiles end-to-end, clock tree structurally complete, but timing closure not achieved on ColumnAu25p. Status: docs/plans/artix-usp-port/PROGRESS.md. Two pieces here could be worth mainlining later (only once a second FPGA architecture is actually planned):
  • Platform-split RTL — {7s,Usp} variants of ClockDist / Timing Ser-Des / Timing Tx-Rx PHY / EthPhy / PgpPhy (+ PgpRingRouter).
  • XDC restructure, especially the 1g/10g constraint split (WarmTdmCore2_{7s,usp,1g,10g}.xdc) — potentially mergeable on its own, independent of the AU25P chip.

Key decisions (the "why")

• Software refactor landed before the Jupyter work. The cleanup software refactor (Group split, unified server, PR #67, merged to pre-release 2026-08-10) is a structural foundation independent of the notebook utilities, so it landed first; wtj-refactor then merged pre-release in and reconciled the duplicated content on the further-evolved pre-release side.
• FP-PID stacks above the SW refactor, not beside it. It carries untested RTL needing hardware validation, so it must not gate the software tracks — hence #87→#78 rather than a parallel merge to pre-release.
• cleanup is being split, not merged whole. Its software half is already in wtj-refactor; its firmware remainder lands as #88 on top of #87. Once #88 merges, cleanup is fully absorbed and retires.
• The channelization work (#82) is based on cleanup, not wtj-refactor or fp-pid (decided 2026-08-17). Its read-side code and design doc (operations/streamreader.py, DataChannelization.md) exist only on the wtj-refactor/fp-pid/cleanup line — never on pre-release/main — so those two are not candidate bases. Among the three, cleanup is a superset of fp-pid (it merged both wtj-refactor and fp-pid in) and is the only branch that also carries the resource-optimization firmware the frame work interacts with — notably GEN_PID_DEBUG_G, which is coupled to collapsing the eight per-column PID-debug streams onto one tDest. Basing on cleanup means the RTL frame-builder changes are designed against the final firmware shape rather than an intermediate one, and #82 co-validates with the rest of the stack in a single hardware pass. The cost: #82 inherits the whole FP-PID + resource track's HW-validation gate and cannot reach pre-release until that clears. The host-only file-channel namespacing fix has no firmware coupling and could be cherry-picked earlier onto wtj-refactor if it is needed before the stack lands. Feature branch channelization tops the PR stack above #88.

Cleanup / retirement

Fully captured; delete after the noted event (no unique work remains on any):

• After pre-release → main promotion: cleanup-sw (#67), dup-legends (#75), fix_release_gh_actions (#76), fix-warmtdm-emulate-import (#85), retire-warmtdm-emulate (#84) — all merged via their PRs.
• After the PR stack merges: wtj (⊂ wtj-refactor), and cleanup / fp-pid once #88/#87 land.
• Already merged to main, safe to delete anytime: fpga-board-dev, add_data_path_emulator.
• Not a feature branch — keep: gh-pages (docs-publishing target).

Open items

• Which board is on the bench (→ validates maxRows 256 vs 32 for #68 / #73).
• Confirm the target-cleanup Vivado 2024.1 build ran before relying on main for firmware.