Skip to content

Branch Merge Roadmap

Jump to bottom
Benjamin Reese edited this page Aug 17, 2026 · 11 revisions

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]
  • #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

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.

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.

Clone this wiki locally