docs: update constraints README with USB_MODE architecture and build guide

Add USB Interface Architecture section documenting the USB_MODE parameter,
generate block mechanism, per-target wrapper pattern, FT2232H pin map, and
build quick-reference. Update top modules table (50T now uses
radar_system_top_50t), bank voltage tables, and signal differences to
reflect the FT2232H/FT601 dual-interface design.

9_Firmware/9_2_FPGA/constraints/README.md

@@ -4,19 +4,19 @@
 
 | File | Device | Package | Purpose |
 |------|--------|---------|---------|
-| `xc7a50t_ftg256.xdc` | XC7A50T-2FTG256I | FTG256 (256-ball BGA) | Upstream author's board (copy of `cntrt.xdc`) |
+| `xc7a50t_ftg256.xdc` | XC7A50T-2FTG256I | FTG256 (256-ball BGA) | 50T production board |
-| `xc7a200t_fbg484.xdc` | XC7A200T-2FBG484I | FBG484 (484-ball BGA) | Production board (new PCB design) |
+| `xc7a200t_fbg484.xdc` | XC7A200T-2FBG484I | FBG484 (484-ball BGA) | 200T premium dev board |
 | `te0712_te0701_minimal.xdc` | XC7A200T-2FBG484I | FBG484 (484-ball BGA) | Trenz dev split target (minimal clock/reset + LEDs/status) |
 | `te0713_te0701_minimal.xdc` | XC7A200T-2FBG484C | FBG484 (484-ball BGA) | Trenz alternate SoM target (minimal clock + FMC status outputs) |
 
 ## Why Four Files
 
-The upstream prototype uses a smaller XC7A50T in an FTG256 package. The production
+The 50T production board uses an XC7A50T in an FTG256 package. The 200T premium
-AERIS-10 radar migrates to the XC7A200T for more logic, BRAM, and DSP resources.
+dev board uses an XC7A200T for more logic, BRAM, and DSP resources. The two
-The two devices have completely different packages and pin names, so each needs its
+devices have completely different packages and pin names, so each needs its own
-own constraint file.
+constraint file.
 
-The Trenz TE0712/TE0701 path uses the same FPGA part as production but different board
+The Trenz TE0712/TE0701 path uses the same FPGA part as the 200T but different board
 pinout and peripherals. The dev target is split into its own top wrapper
 (`radar_system_top_te0712_dev.v`) and minimal constraints file to avoid accidental mixing
 of production pin assignments during bring-up.
@@ -25,9 +25,83 @@ The Trenz TE0713/TE0701 path supports situations where TE0712 lead time is prohi
 TE0713 uses XC7A200T-2FBG484C (commercial temp grade) and requires separate clock mapping,
 so it has its own dev top and XDC.
 
+## USB Interface Architecture (USB_MODE)
+
+The radar system supports two USB data interfaces, selected at **compile time** via
+the `USB_MODE` parameter in `radar_system_top.v`:
+
+| USB_MODE | Interface | Bus Width | Speed | Board Target |
+|----------|-----------|-----------|-------|--------------|
+| 0 (default) | FT601 (USB 3.0) | 32-bit | 100 MHz | 200T premium dev board |
+| 1 | FT2232H (USB 2.0) | 8-bit | 60 MHz | 50T production board |
+
+### How USB_MODE Works
+
+`radar_system_top.v` contains a Verilog `generate` block that instantiates exactly
+one USB interface module based on the `USB_MODE` parameter:
+
+```
+generate
+if (USB_MODE == 0) begin : gen_ft601
+    usb_data_interface usb_inst (...)          // FT601, 32-bit
+    // FT2232H ports tied off to inactive
+end else begin : gen_ft2232h
+    usb_data_interface_ft2232h usb_inst (...)  // FT2232H, 8-bit
+    // FT601 ports tied off to inactive
+end
+endgenerate
+```
+
+Both interfaces share the same internal radar data bus and host command interface.
+The unused interface's I/O pins are tied to safe inactive states (active-low
+signals high, active-high signals low, bidirectional buses high-Z).
+
+### How USB_MODE Is Passed Per Board Target
+
+The parameter is set via a **wrapper module** that overrides the default:
+
+- **50T production**: `radar_system_top_50t.v` instantiates the core with
+  `.USB_MODE(1)` and maps the FT2232H's 60 MHz `CLKOUT` to the shared
+  `ft601_clk_in` port. FT601 inputs are tied inactive; outputs go to `_nc` wires.
+
+  ```verilog
+  // In radar_system_top_50t.v:
+  radar_system_top #(
+      .USB_MODE(1)
+  ) u_core ( ... );
+  ```
+
+- **200T dev board**: `radar_system_top` is used directly as the top module.
+  `USB_MODE` defaults to `0` (FT601). No wrapper needed.
+
+### RTL Files by USB Interface
+
+| File | Purpose |
+|------|---------|
+| `usb_data_interface.v` | FT601 USB 3.0 module (32-bit, USB_MODE=0) |
+| `usb_data_interface_ft2232h.v` | FT2232H USB 2.0 module (8-bit, USB_MODE=1) |
+| `radar_system_top.v` | Core module with USB_MODE generate block |
+| `radar_system_top_50t.v` | 50T wrapper: sets USB_MODE=1, ties off FT601 |
+
+### FT2232H Pin Map (50T, Bank 35, VCCO=3.3V)
+
+All connections are direct between U6 (FT2232HQ) and U42 (XC7A50T). Only
+Channel A is used (245 Synchronous FIFO mode). Channel B is unconnected.
+
+| Signal | FT2232H Pin | FPGA Ball | Direction |
+|--------|-------------|-----------|-----------|
+| FT_D[7:0] | ADBUS[7:0] | K1,J3,H3,G4,F2,D1,C3,C1 | Bidirectional |
+| FT_RXF# | ACBUS0 | A2 | Input (FIFO not empty) |
+| FT_TXE# | ACBUS1 | B2 | Input (FIFO not full) |
+| FT_RD# | ACBUS2 | A3 | Output (read strobe) |
+| FT_WR# | ACBUS3 | A4 | Output (write strobe) |
+| FT_SIWUA | ACBUS4 | A5 | Output (send immediate) |
+| FT_CLKOUT | ACBUS5 | C4 (MRCC) | Input (60 MHz clock) |
+| FT_OE# | ACBUS6 | B7 | Output (bus direction) |
+
 ## Bank Voltage Assignments
 
-### XC7A50T-FTG256 (Upstream)
+### XC7A50T-FTG256 (50T Production)
 
 | Bank | VCCO | Signals |
 |------|------|---------|
@@ -35,9 +109,9 @@ so it has its own dev top and XDC.
 | 14 | 3.3V | ADC LVDS (LVDS_33), SPI flash |
 | 15 | 3.3V | DAC, clocks, STM32 3.3V SPI, DIG bus |
 | 34 | 1.8V | ADAR1000 control, SPI 1.8V side |
-| 35 | 3.3V | Unused (no signal connections) |
+| 35 | 3.3V | FT2232H USB 2.0 (8-bit data + control, 15 signals) |
 
-### XC7A200T-FBG484 (Production)
+### XC7A200T-FBG484 (200T Premium Dev Board)
 
 | Bank | VCCO | Used/Avail | Signals |
 |------|------|------------|---------|
@@ -50,15 +124,46 @@ so it has its own dev top and XDC.
 
 ## Signal Differences Between Targets
 
-| Signal | Upstream (FTG256) | Production (FBG484) |
+| Signal | 50T Production (FTG256) | 200T Dev (FBG484) |
-|--------|-------------------|---------------------|
+|--------|-------------------------|-------------------|
-| FT601 USB | Unwired (chip placed, no nets) | Fully wired, Bank 16 |
+| USB interface | FT2232H USB 2.0 (8-bit, Bank 35) | FT601 USB 3.0 (32-bit, Bank 16) |
+| USB_MODE | 1 (via `radar_system_top_50t` wrapper) | 0 (default in `radar_system_top`) |
+| USB clock | 60 MHz from FT2232H CLKOUT | 100 MHz from FT601 |
 | `dac_clk` | Not connected (DAC clocked by AD9523 directly) | Routed, FPGA drives DAC |
-| `ft601_be` width | `[1:0]` in upstream RTL | `[3:0]` (RTL updated) |
+| `ft601_be` width | N/A (FT601 unused, tied off) | `[3:0]` (RTL updated) |
 | ADC LVDS standard | LVDS_33 (3.3V bank) | LVDS_25 (2.5V bank, better quality) |
 | Status/debug outputs | No physical pins (commented out) | All routed to Banks 35 + 13 |
 
-## How to Select in Vivado
+## How to Build
+
+### Quick Reference
+
+```bash
+# SSH into the build server:
+ssh -i ~/.ssh/gpu_server_key -p 8765 -o StrictHostKeyChecking=no jason-stone@livepeerservice.ddns.net
+source /mnt/bcache/Xilinx/Vivado/2025.2/Vivado/settings64.sh
+cd /home/jason-stone/PLFM_RADAR_work/9_Firmware/9_2_FPGA
+
+# 50T production build (FT2232H, USB_MODE=1):
+vivado -mode batch -source scripts/50t/build_50t.tcl 2>&1 | tee build_50t/vivado.log
+
+# 200T dev build (FT601, USB_MODE=0):
+vivado -mode batch -source scripts/200t/build_200t.tcl \
+  -log build/build.log -journal build/build.jou
+```
+
+The build scripts automatically select the correct top module and constraints:
+
+| Build Script | Top Module | Constraints | USB_MODE |
+|--------------|------------|-------------|----------|
+| `scripts/50t/build_50t.tcl` | `radar_system_top_50t` | `xc7a50t_ftg256.xdc` | 1 (FT2232H) |
+| `scripts/200t/build_200t.tcl` | `radar_system_top` | `xc7a200t_fbg484.xdc` | 0 (FT601) |
+
+You do NOT need to set `USB_MODE` manually. The top module selection handles it:
+- `radar_system_top_50t` forces `USB_MODE=1` internally
+- `radar_system_top` defaults to `USB_MODE=0`
+
+## How to Select Constraints in Vivado
 
 In the Vivado project, only one target XDC should be active at a time:
 
@@ -85,12 +190,12 @@ read_xdc constraints/te0713_te0701_minimal.xdc
 
 ## Top Modules by Target
 
-| Target | Top module | Notes |
+| Target | Top module | USB_MODE | USB Interface | Notes |
-|--------|------------|-------|
+|--------|------------|----------|---------------|-------|
-| Upstream FTG256 | `radar_system_top` | Legacy board support |
+| 50T Production (FTG256) | `radar_system_top_50t` | 1 | FT2232H (8-bit) | Wrapper sets USB_MODE=1, ties off FT601 |
-| Production FBG484 | `radar_system_top` | Main AERIS-10 board |
+| 200T Dev (FBG484) | `radar_system_top` | 0 (default) | FT601 (32-bit) | No wrapper needed |
-| Trenz TE0712/TE0701 | `radar_system_top_te0712_dev` | Minimal bring-up wrapper while pinout/peripherals are migrated |
+| Trenz TE0712/TE0701 | `radar_system_top_te0712_dev` | 0 (default) | FT601 (32-bit) | Minimal bring-up wrapper |
-| Trenz TE0713/TE0701 | `radar_system_top_te0713_dev` | Alternate SoM wrapper (TE0713 clock mapping) |
+| Trenz TE0713/TE0701 | `radar_system_top_te0713_dev` | 0 (default) | FT601 (32-bit) | Alternate SoM wrapper |
 
 ## Trenz Split Status
 
@@ -142,11 +247,19 @@ TE0713 outputs:
 
 ## Notes
 
-- The production XDC pin assignments are **recommended** for the new PCB.
+- **USB_MODE is compile-time only.** You cannot switch USB interfaces at runtime.
+  Each board target has exactly one USB chip physically connected.
+- The 50T production build must use `radar_system_top_50t` as top module. Using
+  `radar_system_top` directly will default to FT601 (USB_MODE=0), which has no
+  physical connection on the 50T board.
+- The 200T XDC pin assignments are **recommended** for the new PCB.
   The PCB designer should follow this allocation.
-- Bank 16 (FT601) is fully utilized at 50/50 pins. No room for expansion
+- Bank 16 on the 200T (FT601) is fully utilized at 50/50 pins. No room for expansion
   on that bank.
-- Bank 35 (status/debug) is also at capacity (50/50). Additional debug
+- Bank 35 on the 200T (status/debug) is also at capacity (50/50). Additional debug
   signals should use Bank 13 spare pins (18 remaining).
+- Bank 35 on the 50T is used for FT2232H (15 signals). Remaining pins are available
+  for future expansion.
 - Clock inputs are placed on MRCC (Multi-Region Clock Capable) pins to
-  ensure proper clock tree access.
+  ensure proper clock tree access. The FT2232H CLKOUT (60 MHz) is on
+  pin C4 (`IO_L12N_T1_MRCC_35`).