gowin_pack

gowin_pack is a tool that generates bitstreams for Gowin FPGAs from nextpnr-generated JSON netlists. It's part of the Project Apicula toolchain.

Command Line Options

Required Arguments

• --device DEVICE

  • Specifies the target Gowin FPGA family
  • Examples:
    • GW1N-9 for GW1NR-LV9QN88PC6/I5
    • GW1N-9C for GW1NR-LV9QN88C6/I5 (note the C suffix requires specifying the family)
    • GW2A-18 for GW2A-LV18PG256C8/I7
  • Required argument

• netlist

  • Input JSON netlist file generated by nextpnr
  • Required positional argument

Optional Arguments

• --output FILENAME

  • Output bitstream filename
  • Default: pack.fs

• --compress

  • Enable bitstream compression
  • Useful for reducing bitstream size
  • Default: disabled

GPIO Configuration Flags

⚠️ WARNING: Using these flags can soft-brick your FPGA if misused. When dual-mode pins (like JTAG) are configured as GPIO, you may lose the ability to reprogram the device. Only use these flags if you fully understand the implications and have a recovery plan.

These flags allow configuring dual-function pins as GPIO:

• --jtag_as_gpio

  • Configure JTAG pins as GPIO
  • Default: disabled
  • Warning: This disables JTAG programming functionality

• --sspi_as_gpio

  • Configure SSPI pins as GPIO
  • Default: disabled
  • Warning: This disables SSPI programming functionality

• --mspi_as_gpio

  • Configure MSPI pins as GPIO
  • Default: disabled
  • Warning: This disables MSPI programming functionality

• --ready_as_gpio

  • Configure READY pin as GPIO
  • Default: disabled

• --done_as_gpio

  • Configure DONE pin as GPIO
  • Default: disabled

• --reconfign_as_gpio

  • Configure RECONFIG_N pin as GPIO
  • Default: disabled
  • Warning: This disables the reconfiguration functionality

Usage Examples

Basic Usage

Generate an uncompressed bitstream:

gowin_pack --device GW1N-9 design.json

C-suffix Device

Generate a bitstream for a C-suffix device:

gowin_pack --device GW1N-9C design.json

Compressed Bitstream

Generate a compressed bitstream with custom output name:

gowin_pack --device GW2A-18 design.json --output compressed.fs --compress

Dual-Function Pin Configuration

Configure JTAG and MSPI pins as GPIO:

gowin_pack --device GW1N-9 design.json \
  --jtag_as_gpio \
  --mspi_as_gpio

Complete Example with Multiple Options

Generate a compressed bitstream with GPIO configuration:

gowin_pack --device GW1N-9C design.json \
  --output final.fs \
  --compress \
  --jtag_as_gpio \
  --mspi_as_gpio \
  --done_as_gpio

Device Support

Supported device families include:

• GW1N-1
• GW1NZ-1
• GW1N-4
• GW1NS-4
• GW1N-9
• GW1N-9C
• GW2A-18
• GW2A-18C

Note that for devices with a C suffix in their part number (e.g., GW1NR-LV9QN88C6/I5), you must specify the C suffix in the family name (e.g., GW1N-9C).

Notes

1. The tool is designed to work with both legacy nextpnr and nextpnr-himbaechel outputs. It automatically detects the input format.

2. When using compressed bitstreams (--compress flag), ensure your programming tools support compressed format.

3. GPIO configuration flags should be used carefully as they can affect device functionality when these pins are needed for their primary functions.

4. When specifying the device family, remember to include the C suffix if your device has one, as this affects the internal configuration of the bitstream.