kost / openFPGALoader

Universal utility for programming FPGA

openFPGALoader

Universal utility for programming FPGA

Current support kits:

• Trenz cyc1000 Cyclone 10 LP 10CL025 (memory and spi flash)
• Colorlight 5A-75B (version 7)
• Digilent arty Artix xc7a35ti (memory and spi flash)
• Lattice MachXO3LF Starter Kit LCMX03LF-6900C (memory and flash)
• Lattice ECP5 5G Evaluation Board (LFE5UM5G-85F-EVN)
• Trenz Gowin LittleBee (TEC0117)
• SeeedStudio Spartan Edge Accelerator Board (memory)
• Sipeed Tang Nano (memory)

Supported (tested) FPGA:

• Gowin GW1N (GW1N-1, GW1N-4, GW1NR-9) (SRAM and Flash (flash mode only tested with GW1NR-9))
• Lattice MachXO3LF (SRAM and Flash)
• Lattice ECP5 (25F, 5G 85F (SRAM)
• Xilinx Artix 7 xc7a35ti, xc7a100t (memory (all) and spi flash (xc7a35ti)
• Xilinx Spartan 7 xc7s15 (memory)
• Intel Cyclone 10 LP 10CL025

Supported cables:

• digilent_hs2: jtag programmer cable from digilent
• JTAG-HS3: jtag programmer cable from digilent
• FT2232: generic programmer cable based on Ftdi FT2232
• Tang Nano USB-JTAG interface: FT2232C clone based on CH552 microcontroler (with some limitations and workaround)

compile and install

This application uses libftdi1, so this library must be installed (and, depending of the distribution, headers too)

apt-get install libftdi1-2 libftdi1-dev libudev-dev cmake

libudev-dev is optional, may be replaced by eudev-dev or just not installed.

By default, (e)udev support is enabled (used to open a device by his /dev/xx node). If you don't want this option, use:

-DENABLE_UDEV=OFF

For distributions using non-glibc (musl, uClibc) argp-standalone must be installed.

And if not already done, install pkg-config, make and g++.

To build the app:

$ mkdir build
$ cd build
$ cmake ../ # add -DBUILD_STATIC=ON to build a static version
            # add -DENABLE_UDEV=OFF to disable udev support and -d /dev/xxx
$ cmake --build .
or
$ make -j$(nproc)

To install

$ sudo make install

The default install path is /usr/local, to change it, use -DCMAKE_INSTALL_PREFIX=myInstallDir in cmake invokation.

Usage

openFPGALoader --help
Usage: openFPGALoader [OPTION...] BIT_FILE
openFPGALoader -- a program to flash cyclone10 LP FPGA

  -b, --board=BOARD          board name, may be used instead of cable
  -c, --cable=CABLE          jtag interface
  -d, --device=DEVICE        device to use (/dev/ttyUSBx)
      --detect               detect FPGA
  -f, --write-flash          write bitstream in flash (default: false, only for
                             Gowin devices)
      --list-boards          list all supported boards
      --list-cables          list all supported cables
      --list-fpga            list all supported FPGA
  -m, --write-sram           write bitstream in SRAM (default: true, only for
                             Gowin devices)
  -o, --offset=OFFSET        start offset in EEPROM
  -r, --reset                reset FPGA after operations
  -v, --verbose              Produce verbose output
  -?, --help                 Give this help list
      --usage                Give a short usage message
  -V, --version              Print program version

To have complete help

Generic usage

display FPGA

With board name:

openFPGALoader -b theBoard

(see openFPGALoader --list-boards)

With cable:

openFPGALoader -c theCable

(see openFPGALoader --list-cables)

With device node:

openFPGALoader -d /dev/ttyUSBX

Note: for some cable (like digilent adapters) signals from the converter are not just directly to the FPGA. For this case, the -c must be added.

Note: when -d is not provided, openFPGALoader will opens the first ftdi found, if more than one converter is connected to the computer, the -d option is the better solution

Reset device

openFPGALoader [options] -r

load bitstream device (memory or flash)

openFPGALoader [options] /path/to/bitstream.ext

CYC1000

loading in memory:

sof to svf generation:

quartus_cpf -c -q -g 3.3 -n 12.0MHz p project_name.sof project_name.svf

file load:

openFPGALoader -b cyc1000 project_name.svf

SPI flash:

sof to rpd:

quartus_cpf -o auto_create_rpd=on -c -d EPCQ16A -s 10CL025YU256C8G project_name.svf project_name.jic

file load:

openFPGALoader -b cyc1000 -r project_name_auto.rpd

Note about SPI flash: svf file used to write in flash is just a bridge between FT2232 interfaceB configured in SPI mode and sfl primitive used to access EPCQ SPI flash.

Note about FT2232 interfaceB: This interface is used for SPI communication only when the dedicated svf is loaded in RAM, rest of the time, user is free to use for what he want.

ARTY and Spartan Edge Accelerator Board

To simplify further explanations, we consider the project is generated in the current directory.

Note: Spartan Edge Accelerator Board has only pinheader, so the cable must be provided

loading in memory:

.bit file is the default format generated by vivado, so nothing special task must be done to generates this bitstream.

file load:

openFPGALoader -b arty *.runs/impl_1/*.bit

or

openFPGALoader -b spartanEdgeAccelBoard -c digilent_hs2 *.runs/impl_1/*.bit

SPI flash (only for ARTY):

.mcs must be generates through vivado with a tcl script like

set project [lindex $argv 0]

set bitfile "${project}.runs/impl_1/${project}.bit"
set mcsfile "${project}.runs/impl_1/${project}.mcs"

write_cfgmem -format mcs -interface spix4 -size 16 \
    -loadbit "up 0x0 $bitfile" -loaddata "" \
    -file $mcsfile -force

Note: -interface spix4 and -size 16 depends on SPI flash capability and size.

The tcl script is used with:

vivado -nolog -nojournal -mode batch -source script.tcl -tclargs myproject

file load:

openFPGALoader -b arty *.runs/impl_1/*.mcs

MachXO3 Starter Kit

Flash memory:

.jed file is the default format generated by Lattice Diamond, so nothing special must be done to generates this file.

file load:

openFPGALoader -b machXO3SK impl1/*.jed

SRAM:

To generates .bit file Bitstream file must be checked under Exports Files in Lattice Diamond left panel.

file load:

openFPGALoader -b machXO3SK impl1/*.bit

Trenz GOWIN LittleBee (TEC0117) and Sipeed Tang Nano

.fs file is the default format generated by Gowin IDE, so nothing special must be done to generates this file.

Since the same file is used for SRAM and Flash a CLI argument is used to specify the destination.

Flash SRAM:

with -m

file load (Trenz):

openFPGALoader -m -b littleBee impl/pnr/*.fs

file load (Tang Nano):

openFPGALoader -m -b tangnano impl/pnr/*.fs

Flash (only with Trenz board):

with -f

file load:

openFPGALoader -f -b littleBee impl/pnr/*.fs