OpenFPGALoader

OpenFPGALoader is a versatile tool for programming FPGA boards. This guide focuses on its usage with Gowin FPGA boards supported by Project Apicula.

Supported Boards and Configuration

Board	FPGA Model	Board Flag	Cable Type
Tang Nano	GW1N-LV1QN48C6/I5	tangnano	ch552_jtag
Tang Nano 1K	GW1NZ-LV1QN48C6/I5	tangnano1k	ft2232
Tang Nano 4K	GW1NSR-LV4CQN48PC7/I6	tangnano4k	ft2232
Tang Nano 9K	GW1NR-LV9QN88PC6/I5	tangnano9k	ft2232
Tang Nano 20K	GW2AR-LV18QN88C8/I7	tangnano20k	ft2232
Tang Primer 20K	GW2A-LV18PG256C8/I7	tangprimer20k	ft2232
RUNBER	GW1N-UV4LQ144C6/I5	runber	ft232
Trenz TEC0117	GW1NR-UV9QN881C6/I5	tec0117	ft2232
szfpga	GW1NR-LV9LQ144PC6/I5	szfpga	ft2232

Basic Usage

Writing to SRAM (Volatile)

SRAM programming is temporary - the configuration will be lost when power is removed. This is the default mode.

openFPGALoader -b <board_flag> <bitstream.fs>

Example:

openFPGALoader -b tangnano9k your_design.fs

Writing to Flash (Non-volatile)

Flash programming persists across power cycles. Use the -f flag to write to flash.

openFPGALoader -b <board_flag> -f <bitstream.fs>

Example:

openFPGALoader -b tangnano9k -f your_design.fs

Additional Options

Common Flags

• -r: Reset FPGA after programming
• -v: Verbose output
• --verify: Verify write operation (SPI Flash only)
• --quiet: Suppress progress bar output

Flash Operations

• --bulk-erase: Erase entire flash
• --offset <bytes>: Specify start address for flash operations
• --unprotect-flash: Remove flash protection
• --protect-flash: Enable flash protection

Device Selection

• -d, --device <path>: Specify device path (e.g., /dev/ttyUSBx)
• --vid <id>: Vendor ID for probe selection
• --pid <id>: Product ID for probe selection

Tips

1. Always ensure proper board connection before programming
2. Use -v flag for debugging if programming fails
3. Consider using SRAM programming during development for faster iterations
4. Verify successful programming with the --verify option when writing to flash

Typical Development Workflow

1. Program SRAM for testing:

openFPGALoader -b tangnano9k design.fs

2. Once design is verified, program to flash:

openFPGALoader -b tangnano9k -f --verify design.fs

---

For complete command-line options, use openFPGALoader --help.