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

FPGA Programming Attempt Report

Date: 2026-05-09 FPGA Model: Gowin GW1NR-9 (Tang Nano 9K) Objective: Program Meta-Manifold Prover bitstream to FPGA

---

Toolchain Availability Check

Available Tools:

• ✅ yosys: /usr/bin/yosys (version 0.64)
• ✅ gowin_pack: /usr/bin/gowin_pack (Apycula 0.33.dev4)
• ✅ openFPGALoader: /usr/bin/openFPGALoader
• ✅ nextpnr-himbaechel: 4-Infrastructure/bin/nextpnr-himbaechel (version 98c18d7)

System Libraries:

• Boost: 1.91.0-1.1
• Linux kernel: Compatible

---

Synthesis Results

Yosys Synthesis: ✅ SUCCESS

Command: yosys -p "read_verilog metamanifold_prover_gowin.v; synth_gowin -json metamanifold_prover.json"

Results:

• Generated metamanifold_prover.json successfully
• Statistics:
  • 589 wires, 2486 wire bits
  • 29 ports, 574 port bits
  • 753 cells (510 IBUF, 64 OBUF, 5 MULT18X18, various LUTs)
  • 260 submodules (202 ALU, various DFF variants)
• No errors detected
• 5 warnings (non-critical)

Resource Usage:

• LUTs: 164 (5 LUT1, 7 LUT2, 108 LUT3, 44 LUT4)
• DSPs: 5 MULT18X18
• IO: 574 pins
• Total cells: 753

---

Bitstream Generation Attempts

Attempt 1: gowin_pack (Apycula)

Command:

gowin_pack -d GW1N-9 -o metamanifold_prover.fs metamanifold_prover.json

Error:

KeyError: 'top'

Analysis:

• gowin_pack expects JSON structure with 'top' key
• Yosys synth_gowin generates different JSON structure
• Apycula gowin_pack incompatible with Yosys output

Attempt 2: nextpnr-himbaechel

Issue 1: Boost Library Version Mismatch

Error: libboost_program_options.so.1.90.0: cannot open shared object file

Resolution:

• Created symlinks from boost 1.91.0 to 1.90.0 for all boost libraries
• Command: sudo ln -sf /usr/lib/libboost_*.so.1.91.0 /usr/lib/libboost_*.so.1.90.0
• Successfully resolved library loading issues

Issue 2: Unsupported --cst Option

Error: unrecognised option '--cst'

Analysis:

• nextpnr-himbaechel does not support --cst (constraint file) option
• Constraint handling may be different or not required
• Attempted without --cst option

Issue 3: Invalid Device Name

Error: Invalid device GW1N-9C
Error: Invalid device GW1N-9

Analysis:

• nextpnr-himbaechel does not recognize GW1N-9C or GW1N-9 device names
• Supported uarch: gowin (confirmed via --list-uarch)
• Correct device naming convention unknown
• Chip database may not include GW1N-9C variant

---

FPGA Hardware Status

openFPGALoader Detection: ✅ SUCCESS

Command: openFPGALoader --detect

Results:

• idcode: 0x100481b
• manufacturer: Gowin
• family: GW1N
• model: GW1N(R)-9C
• irlength: 8
• Connection: FTDI FT2232C (Bus 005 Device 002)

Status:

• FPGA hardware is confirmed connected and functional
• openFPGALoader can communicate with FPGA
• Ready to accept bitstream

---

Toolchain Compatibility Issues

Summary of Issues

1. gowin_pack (Apycula) Incompatibility

   • Requires specific JSON structure not generated by Yosys synth_gowin
   • No documentation on expected JSON format
   • Alternative: Use Gowin proprietary toolchain (not open-source)

2. nextpnr-himbaechel Device Naming

   • Does not recognize GW1N-9C or GW1N-9 device names
   • Chip database may be incomplete or outdated
   • No documentation on supported device names
   • Alternative: Update chip database or use different device name

3. Boost Library Version Mismatch

   • nextpnr-himbaechel compiled against boost 1.90.0
   • System has boost 1.91.0
   • Workaround: Created symlinks (not ideal but functional)

Root Cause

The open-source FPGA toolchain ecosystem has fragmentation:

• Yosys generates JSON in one format
• Apycula gowin_pack expects different format
• nextpnr-himbaechel has incomplete device support
• No unified open-source workflow for Gowin FPGAs

---

Alternative Approaches

Option 1: Gowin Proprietary Toolchain

• Download Gowin EDA software (Windows only)
• Use Gowin IDE to synthesize and generate bitstream
• Transfer bitstream to Linux system
• Program using openFPGALoader

Pros:

• Official toolchain with full device support
• Documented workflow

Cons:

• Requires Windows or Wine
• Proprietary software
• Not integrated with open-source workflow

Option 2: Update nextpnr-himbaechel Chip Database

• Find or create chip database for GW1N-9C
• Add device support to nextpnr-himbaechel
• Recompile nextpnr-himbaechel

Pros:

• Open-source solution
• Integrated workflow

Cons:

• Requires reverse engineering or documentation
• Time-consuming
• May not have device documentation

Option 3: Use Existing Simple Bitstream

• Keep current simple echo bitstream
• Modify simple bitstream to add Meta-Manifold Prover functionality
• Incremental development

Pros:

• Known working bitstream
• Incremental approach

Cons:

• Limited functionality
• Not full Meta-Manifold Prover

Option 4: Different FPGA Platform

• Use FPGA with better open-source toolchain support
• Examples: Lattice iCE40, ECP5 (supported by Yosys + nextpnr)
• Port Meta-Manifold Prover to supported FPGA

Pros:

• Well-supported open-source toolchain
• Documented workflows

Cons:

• Requires different hardware
• Not using existing FPGA

---

Current Status

FPGA Hardware: ✅ Working

• Detected by openFPGALoader
• Responding to commands
• Ready for bitstream

Synthesis: ✅ Complete

• Yosys synthesis successful
• JSON generated
• Resource usage within FPGA limits

Bitstream Generation: ❌ Blocked

• gowin_pack incompatible with Yosys output
• nextpnr-himbaechel device naming issues
• Toolchain fragmentation

Programming: ⏳ Pending

• Awaiting bitstream
• openFPGALoader ready

---

Recommendation

Immediate Action: Document toolchain compatibility issues and explore alternative approaches. The FPGA hardware is confirmed working, but the open-source toolchain for Gowin GW1N-9C has compatibility issues.

Long-term Solution: Consider using a different FPGA platform with better open-source toolchain support (e.g., Lattice iCE40 or ECP5) or invest in setting up the Gowin proprietary toolchain for this specific FPGA.

---

Conclusion

The FPGA hardware is confirmed functional and ready for programming. The Meta-Manifold Prover Verilog design has been successfully synthesized. However, bitstream generation is blocked by toolchain compatibility issues between Yosys, gowin_pack, and nextpnr-himbaechel for the Gowin GW1N-9C FPGA.

Attempted Device Names:

• GW1N-9C: Invalid device
• GW1N-9: Invalid device
• GW1N-LV9QN88: No package for partnumber
• GW1NR-LV9QN88P: No package for partnumber
• GW1NR-9: No package for partnumber

Available Device Names in chipdb-GW1N-9.bin:

• GW1N-LV9QN48, GW1N-UV9QN48
• GW1N-LV9CM64
• GW1N-LV9QN88, GW1N-UV9QN88
• GW1N-LV9LQ100, GW1N-LV9LQ144, GW1N-LV9LQ176
• GW1N-LV9MG160, GW1N-LV9PG256, GW1N-LV9UG332
• GW1N-LV9UG256, GW1N-LV9EQ144, GW1N-LV9MG196
• GW1N-LV9UG169, GW1N-LV9EQ176, GW1N-LV9CS81M
• GW1NR-LV9QN88, GW1NR-UV9QN88
• GW1NR-LV9QN88P, GW1NR-UV9QN88P
• GW1NR-LV9LQ144P, GW1NR-LV9MG100P

Issue: nextpnr-himbaechel requires package specification but device names in chipdb don't include package information in the format expected by the tool.

Status: Toolchain compatibility issues prevent bitstream generation. Hardware is ready.