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

FPGA Rainbow Raccoon Q16 Accelerator Setup

Date: 2026-05-09 Board: Tang Nano 9K / Gowin GW1N(R)-9C Status: Bitstream builds and loads to SRAM; USB-UART path is not currently receiving fabric UART responses.

Added Surface

Created a narrow FPGA witness lane for Rainbow Raccoon Compiler fixed-point lowering:

• 4-Infrastructure/hardware/tangnano9k_rrc_q16_accel.v
• 4-Infrastructure/hardware/build_rrc_q16_accel.sh
• 4-Infrastructure/shim/tang9k_rrc_q16_accel.py

This is custom hardware work, not an off-the-shelf Gowin example. The RTL defines a purpose-built Q16.16 arithmetic witness surface for the Rainbow Raccoon pipeline, the build script targets that surface through the open-source Gowin flow, and the host shim emits machine receipts for each deterministic witness operation.

The hardware surface accepts framed UART requests:

A5 02 seq opcode len payload crc8

and returns:

A6 02 seq status len payload crc8

Opcodes

Opcode	Meaning	Lean receipt lane
0x20	x >>> 16 Q16.16 divide-by-65536 witness	shiftRightEqDiv
0x21	(E * alpha) >>> 16 <= E bounded weighted term witness	weightedTermBounded
0x22	monotone arithmetic shift witness	shiftRightMonotone

The FPGA surface is intentionally not a proof authority. It accelerates deterministic arithmetic witnesses only; Lean and the host admission path remain authoritative.

Custom Work Boundary

Accurate claim:

This is a custom hardware witness surface for Lean-linked Q16.16 arithmetic lowering, built for the Rainbow Raccoon pipeline. The bitstream builds and SRAM-loads, and the software witness lane passes. Live FPGA receipts remain blocked by the UART/fabric route, not by the Q16 arithmetic design.

This boundary matters: build success, SRAM load, and software witness receipts are real evidence, but hardware acceleration is not promoted until the UART route returns matching hardware receipts.

Build Evidence

Command:

cd 4-Infrastructure/hardware
./build_rrc_q16_accel.sh

Result:

• Yosys synthesis: pass, 0 check problems
• nextpnr-himbaechel: pass at 27 MHz
• Maximum reported clock frequency after route: 102.13 MHz
• Device usage: 730/8640 LUT4, 269/6480 DFF, 1/5 MULT36X36
• Bitstream SHA-256: cdd8ae8f089c0b6dc5b638b112a3f4662497f2cee1b240cd5fcdb939b67166ff

Programming Evidence

SRAM load succeeds:

openFPGALoader -b tangnano9k 4-Infrastructure/hardware/tangnano9k_rrc_q16_accel.fs

Result:

Load SRAM: 100.00%
CRC check: Success

Flash programming attempt was not accepted as durable:

write Flash: 100.00%
CRC check : FAIL
Read: 0x00000000 checksum: 0x5c15

Use SRAM load for now. Do not claim persistent flash install until the flash readback failure is resolved.

Host Receipts

Software receipt checks pass:

• 4-Infrastructure/shim/tang9k_rrc_q16_accel_shift_software_receipt.json
• 4-Infrastructure/shim/tang9k_rrc_q16_accel_weighted_software_receipt.json
• 4-Infrastructure/shim/tang9k_rrc_q16_accel_monotone_software_receipt.json

USB-UART hardware receipt checks currently fail with no response on /dev/ttyUSB1:

• 4-Infrastructure/shim/tang9k_rrc_q16_accel_shift_hw_receipt.json
• 4-Infrastructure/shim/tang9k_rrc_q16_accel_weighted_hw_receipt.json
• 4-Infrastructure/shim/tang9k_rrc_q16_accel_monotone_hw_receipt.json

A control test with the preexisting UART loopback bitstream also produced no /dev/ttyUSB1 fabric response, while /dev/ttyUSB0 shows FTDI MPSSE/JTAG command echoes such as faXX. Therefore the present blocker is the USB-UART-to-fabric pin path, not Q16 arithmetic synthesis.

A forced JTAG reset and SRAM reload was also tested. The JTAG path detects the Gowin device and reloads bitstreams successfully, but the beacon and Q16 hardware receipts remain silent on the host-visible serial endpoints. This makes the next useful test an external USB-UART adapter on the fabric pins, not another JTAG clear loop.

A PTY-backed virtual serial responder was added as a host-side control. It passes the same shift, weighted, and monotone Q16 operations through the existing serial harness, which confirms the host framing and receipt parser are working independently of the blocked physical UART route.

The UART path is now modeled through a transport route table. The active non-hardware route is virtual://q16-pty, while /dev/ttyUSB0 and /dev/ttyUSB1 remain blocked physical route entries. This lets the Rainbow Raccoon pipeline continue exercising serial receipts without confusing virtual-route success for live FPGA fabric success.

UART Beacon Isolation

To remove the Q16 protocol parser from the failure surface, a TX-only fabric beacon was added:

• 4-Infrastructure/hardware/tangnano9k_uart_beacon.v
• 4-Infrastructure/hardware/build_uart_beacon.sh

The beacon repeatedly emits:

A6 42 51 31 36 0A

which is the byte 0xA6, beacon version byte 0x42, followed by ASCII Q16\n.

Two beacon builds were tested:

Constraint set	TX pin	RX pin	Bitstream SHA-256	Probe receipt	Result
tangnano9k_uart_loopback.cst	17	18	45feef98a527b4b1643dcbee983e1b36f9505a0170e0bd03abee65ccca30db17	4-Infrastructure/shim/tang9k_uart_beacon_probe_receipt.json	no beacon bytes on /dev/ttyUSB0 or /dev/ttyUSB1
tangnano9k_uart_swapped.cst	18	17	46d68bd12371f203839c289e7bd7667ebdc33dafd0d6d2f33f9cc7caacc7b86d	4-Infrastructure/shim/tang9k_uart_beacon_swapped_probe_receipt.json	no beacon bytes on /dev/ttyUSB0 or /dev/ttyUSB1

The second beacon uses an internal reset counter rather than relying on the external reset pin. This means the current blocker is no longer attributable to the Q16 parser, the host framing code, an external reset hold, or a simple TX/RX swap. Treat the live-hardware claim as blocked until the USB-UART bridge mode or physical UART route is verified with board documentation, BL702 bridge configuration, or an external USB-UART adapter on the fabric pins.

See the dedicated route analysis for the current hardware conclusion and external-adapter path:

• 6-Documentation/docs/fpga_uart_route_analysis_2026-05-09.md

Current Claim Boundary

What is ready:

• Open-source Gowin build pipeline for this accelerator
• SRAM-loaded FPGA bitstream
• Host-side framed Q16 receipt harness
• PTY-backed virtual serial control for host protocol validation
• Lean-linked opcode contract

What is not ready:

• Durable flash programming
• Live USB-UART fabric receipts
• Integration into automatic Rainbow Raccoon Compiler routing

Next Fix

Resolve the UART physical route:

1. Confirm Tang Nano 9K USB-UART bridge mode and pins for this board revision.
2. If the onboard USB bridge is not routing fabric UART to /dev/ttyUSB1, attach an external USB-UART adapter to the actual fabric pins and re-run the beacon first.
3. Re-run the simple loopback or TX-only beacon bitstream before testing the Q16 accelerator.
4. Once the beacon responds, re-run:

python3 4-Infrastructure/shim/tang9k_uart_beacon_probe.py --port /dev/ttyUSB2
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

Use the actual external adapter path if it enumerates as a different device, for example /dev/ttyACM0.