# 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.