Research-Stack/6-Documentation/docs/fpga_uart_route_analysis_2026-05-09.md

FPGA UART Route Analysis

Date: 2026-05-09 Board: Tang Nano 9K / Gowin GW1N(R)-9C Status: USB-UART bridge path blocked; external adapter solution required

Current Situation

Problem Summary

The Tang Nano 9K USB-UART bridge is not routing fabric UART to /dev/ttyUSB0 or /dev/ttyUSB1. Both standard and swapped pin configurations have been tested with TX-only beacon bitstreams, and no fabric UART bytes were observed on either device.

This route failure does not erase the custom FPGA work already completed. The Q16.16 accelerator RTL, open-source build script, Lean-linked opcodes, host receipt harness, and TX-only beacon are custom surfaces for this stack. The current blocker is specifically the live serial route from host to fabric.

Evidence of Blockage

Beacon Test Results:

• Standard pin config (TX=17, RX=18): No beacon bytes on /dev/ttyUSB0 or /dev/ttyUSB1
• Swapped pin config (TX=18, RX=17): No beacon bytes on /dev/ttyUSB0 or /dev/ttyUSB1
• Beacon pattern: A6 42 51 31 36 0A (0xA6 + beacon version 0x42 + ASCII "Q16\n")

Control Test Results:

• Preexisting UART loopback bitstream also produced no /dev/ttyUSB1 fabric response
• /dev/ttyUSB0 shows FTDI MPSSE/JTAG command echoes (faXX patterns)
• This confirms the blocker is the USB-UART-to-fabric pin path, not Q16 arithmetic synthesis

Forced JTAG Clear Results:

• openFPGALoader --detect sees the Gowin GW1N(R)-9C over the FT2232 JTAG path
• JTAG reset and SRAM reload of the TX-only beacon complete with CRC check: Success
• Beacon probe after forced JTAG reset/reload still reads zero bytes on /dev/ttyUSB0 and /dev/ttyUSB1
• Loading the loopback bitstream after the JTAG clear produced faXX-style bytes on /dev/ttyUSB0, matching FTDI/MPSSE bridge behavior rather than the expected fabric beacon payload
• Reloading the Q16 accelerator to SRAM succeeds, but hardware receipts still return empty/short frames

JTAG Clear Conclusion: The forced JTAG clear confirms that the USB-UART bridge issue is not a stale state or configuration problem that can be resolved by JTAG reset. The faXX patterns are definitively FTDI/MPSSE bridge behavior, not fabric UART responses. The BL702 bridge appears to be operating in JTAG/MPSSE mode only, not transparent UART bridge mode for fabric communication.

Virtual Serial Control:

• A PTY-backed virtual serial responder was added to exercise the same Q16 host framing and receipt parser without live FPGA fabric
• The virtual serial probe passes shift, weighted, and monotone Q16 operations
• This narrows the remaining failure to the physical/JTAG-bridge-to-fabric route, not the host protocol encoder, parser, or opcode semantics
• Machine receipt: shared-data/data/stack_solidification/tang9k_rrc_q16_virtual_serial_probe.json

Transport Router Control:

• The UART routes are now represented as a route table rather than loose device paths
• The active non-hardware route is virtual://q16-pty
• Onboard FTDI routes remain visible as blocked physical entries, and the external USB-UART route remains the required live-hardware closure path
• Machine receipt: shared-data/data/stack_solidification/tang9k_uart_transport_routes.json

Current Pin Assignments

Standard Configuration (tangnano9k_uart_loopback.cst)

IO_LOC "uart_tx_pin" 17;
IO_LOC "uart_rx_pin" 18;

Swapped Configuration (tangnano9k_uart_swapped.cst)

IO_LOC "uart_tx_pin" 18;
IO_LOC "uart_rx_pin" 17;

Sparkle Project Reference

// USB-UART via onboard BL702.
IO_LOC "uart_tx" 17;

Root Cause Analysis

Likely Issue: BL702 Bridge Configuration

The Tang Nano 9K uses an onboard BL702 microcontroller as a USB-UART bridge. The BL702 may be:

1. Configured for JTAG/MPSSE mode only (not UART bridge mode)
2. Not routing the expected fabric pins to the USB UART endpoints
3. Requiring specific configuration commands to enable UART bridging

Alternative Issue: Pin Multiplexing

The physical pins 17/18 may be multiplexed with other functions:

• Could be configured as GPIO instead of UART
• May require BL702 firmware configuration
• Bridge may not be in transparent UART mode

Proposed Solution: External USB-UART Adapter

Rationale

Since the onboard BL702 bridge is not functioning as expected, the most reliable path forward is to bypass it entirely and use an external USB-UART adapter connected directly to the fabric pins.

Implementation Plan

Hardware Required

• External USB-UART adapter (FTDI or CP210x based)
• Connection wires (female-to-female dupont cables)
• Access to Tang Nano 9K GPIO header pins 17 and 18

Connection Diagram

External USB-UART Adapter    Tang Nano 9K
------------------------    --------------
TX (adapter)  -------->  RX (pin 18)
RX (adapter)  <--------  TX (pin 17)
GND           -------->  GND

Software Steps

1. Identify external USB-UART device (e.g., /dev/ttyUSB2 or /dev/ttyACM0)
2. Modify probe scripts to use external device path
3. Rebuild beacon bitstream with standard pin assignment (TX=17, RX=18)
4. Load beacon bitstream to FPGA via SRAM
5. Test beacon reception on external UART device
6. If beacon succeeds, proceed to Q16 accelerator testing

Modified Probe Commands

# Test beacon with external adapter
python3 4-Infrastructure/shim/tang9k_uart_beacon_probe.py --port /dev/ttyUSB2

# Test Q16 operations with external adapter
python3 4-Infrastructure/shim/tang9k_rrc_q16_accel.py --op shift --x 0x00038000 --port /dev/ttyUSB2
python3 4-Infrastructure/shim/tang9k_rrc_q16_accel.py --op weighted --energy 0x000a0000 --alpha 0x00008000 --port /dev/ttyUSB2
python3 4-Infrastructure/shim/tang9k_rrc_q16_accel.py --op monotone --a 0x00010000 --b 0x00030000 --port /dev/ttyUSB2

Fallback: BL702 Bridge Investigation

If external adapter is not available, investigate BL702 bridge configuration:

Investigation Steps

1. Obtain Tang Nano 9K board schematic and BL702 documentation
2. Check if BL702 requires firmware update or configuration
3. Test with Gowin official toolchain to see if they use different pin assignments
4. Examine BL702 USB descriptors to determine current mode
5. Research if BL702 can be reconfigured or if alternative bridge mode exists

Risk Assessment

• BL702 configuration may be board-specific and not publicly documented
• Firmware updates may brick the bridge if not done correctly
• Time investment may be high with uncertain success probability

Recommendation

Primary Path: Use external USB-UART adapter

• Higher probability of success
• Bypasses undocumented BL702 behavior
• Provides direct fabric access for debugging
• Minimal configuration required

Secondary Path: BL702 bridge investigation

• Only pursue if external adapter unavailable
• Requires board documentation research
• May need Gowin vendor support
• Higher risk and time investment

Next Actions

1. Immediate: Acquire or locate external USB-UART adapter
2. Hardware: Connect adapter to Tang Nano 9K pins 17 (TX) and 18 (RX)
3. Software: Identify adapter device path and modify probe scripts
4. Test: Run beacon probe with external adapter
5. Validate: If beacon succeeds, proceed to Q16 accelerator testing
6. Document: Update FPGA setup documentation with external adapter procedure

Success Criteria

• Beacon pattern A6 42 51 31 36 0A received on external UART device
• Q16 shift operation returns correct hardware receipt
• Q16 weighted term operation returns correct hardware receipt
• Q16 monotone operation returns correct hardware receipt
• All operations match software receipt expectations

References

• Original FPGA setup: 6-Documentation/docs/fpga_rrc_q16_accel_setup_2026-05-09.md
• Superseded probe report: 6-Documentation/docs/fpga_direct_probe_report_2026-05-09.md
• Hardware constraint files: 4-Infrastructure/hardware/tangnano9k_uart_*.cst