Branch Merge Roadmap

Warm-TDM branch merge roadmap

Last updated: 2026-08-15

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

Live status lives on the board, not here. Per-issue task state, assignees, and progress are tracked on the GitHub Project Warm-TDM Roadmap via the roadmap issues (#68 / #69 / #70 / #73). This page holds only what the board can't: the integrated cross-track picture, branch topology, and the sequencing decisions with their rationale. When the two disagree, the board wins on status; this page wins on why.

Already merged (context — no action)

• target-cleanup — firmware target reorg (shared code → common/warm_tdm/, 160/325 tokens, targets/legacy/). In main (9f90cb0, c3424bc). Plan: docs/plans/target-cleanup/. Def-of-done included a Vivado 2024.1 build of the four release targets — see Open items to confirm it ran.
• release-infra (#63) + v1.0.0 (#65) — release automation + first tag.
• Software cleanup refactor (PR #67) — merged to pre-release 2026-08-10 (c23135c); GroupTb cosim passes. The structural foundation the other tracks build on (see decision below). Analysis: docs/plans/wtj-refactor/MERGE-cleanup.md. Shipped wider than "software-only": also threads firmware maxRows/rowAddrBits and did the RowMapTest→RowMap / NumRows→MaxRows renames. The remaining firmware half of that maxRows wiring is now tracked as #73.

Active tracks

Status column is a summary snapshot — the board is authoritative. "Order" is the cross-track landing sequence this roadmap exists to coordinate.

Track	Issue	Branch	vs main	Status (see board)	Blocker	Order
Jupyter → operations refactor	#68	wtj-refactor	+74/−1	in PR #78, open — pending hardware validation; SW TES-bias generator split out to PR #79 (#55)	analog-bench tune (internal)	next
maxRows → tree sizing (firmware half)	#73	—	—	design agreed; needs FW + wire-up	expose ROW_ADDR_BITS_G register	with Track C
Ad9681 DDR ADC readout	#69	test-ad9681-ddr	+4/−1	code done (2026-08-06)	surf release (external)	parallel
Floating-point PID firmware	#70	cleanup / fp-pid / fp-dsp	large	untested	HW validation + merge from main	last (own track)

Cross-track decisions (the "why")

• PR #67 lands first, on its own (2026-08-06). The software cleanup refactor is a structural foundation (Group split, unified server) independent of wtj, so it landed as its own PR before the jupyter/operations work rather than riding in with it. wtj-refactor then merges pre-release in (this repo is merge-not-rebase — see docs/RELEASE.md); the duplicated Task-2 content is reconciled in the merge commit (98abf67, 2026-08-10), resolving to the further-evolved pre-release side.
• #68 supersedes PR #61 (2026-08-06). On #68's merge, close PR #61 — replace, don't merge — pointing it at #68. Then retire wtj-cleanup-sw and wtj (see topology below).
• #70 is its own track, last. It carries the untested firmware remainder and needs hardware validation, so it does not gate the software tracks.

Branch topology (verified 2026-08-06)

Which branch contains what, and which are now redundant — the reasoning git branches and issue cards can't represent.

• wtj (PR #61) is fully contained in wtj-refactor — 0 unique commits. wtj-refactor also absorbed cleanup's software half by content port.
• wtj-cleanup-sw was the intermediate port branch; already merged into wtj-refactor (0491e7b). Retire it (on #68 merge).
• cleanup's software refactor now lives in wtj-refactor. What remains unique to cleanup is untested firmware (AdcDspFp FP PID rewrite, accumulator split) — the same intent as fp-pid/fp-dsp (Track C, #70) and the docs/plans/fp-dsp-pid/
  • pipelined-dsp-accumulator plans on that branch. Retire cleanup once its firmware intent is captured in #70.
• test-ad9681-ddr branches off main (8341626), +4/−1, independent of #68.

Reference branches (keep, never merge)

Branches deliberately kept as a permanent reference but that will not be merged to main. Not triage candidates — leave them alone.

• vesper — one-off test project (Vesper/Boreas amplifier column-board variant): device driver, SA bias/offset variant, Boreas config + aux-DAC wiring, amp-model→config linkage. Kept for reference; never merges to main. Not tracked by any issue by design.
• fp-dsp (superset of artix-us; artix-us is redundant, 0 unique commits) — exploration of an Artix UltraScale+ (AU25P) column-board firmware design: how it would fit and its power draw. No board currently uses this chip; one is expected eventually (years out), so the work is kept for reference and does not merge to main as-is. Status per docs/plans/artix-usp-port/PROGRESS.md: compiles end-to-end, clock tree structurally complete, but timing closure not achieved on ColumnAu25p. Also carries a power-strategy-exploration Vivado multi-run harness (power_explore.tcl), distinct from cleanup's SAIF-based power flow.
  • The floating-point-PID half of this branch is not unique to it — it is captured in cleanup / #70 (this branch holds the earlier lineage).
  • Extractable pieces worth considering for mainline later (neither currently planned; both would pay off only when a second FPGA architecture is actually on the roadmap):
    • Platform-split RTL — {7s,Usp} variants of ClockDist / Timing Ser-Des / Timing Tx-Rx PHY / EthPhy / PgpPhy (+ PgpRingRouter). Sets a better foundation for supporting other architectures; merge undecided.
    • XDC restructure, particularly the 1g / 10g constraint split (WarmTdmCore2_{7s,usp,1g,10g}.xdc) — potentially worth merging to mainline on its own, independent of the AU25P chip.

Open items

• Which board is on the bench (→ validates maxRows 256 vs 32 for #68 / #73).
• Confirm the target-cleanup Vivado 2024.1 build actually ran before relying on main for firmware.
• Stale/other branches to triage later (not part of this roadmap): row-v2, adc-delay, pwr-sync, pydm-widgets, fpga-board-dev, and the rest of the long branch list. Decide keep / merge / delete for each.