Install

Packages are available for Linux distributions, Windows (MSYS2) and macOS:

More instructions for other installation scenarios are available in Installing openFPGALoader.

Programming a development board

Just simply replace my_fpga_board with any FPGA board from Boards (or openFPGALoader --list-boards) in any of the two commands below, depending on if you want to program the volatile part of your FPGA (faster but not persistent) or the flash part of your FPGA (slower but persistent):

openFPGALoader -b my_fpga_board my_bitstream.bit # Program to SRAM
openFPGALoader -b my_fpga_board -f my_bitstream.bit # Program to flash

NOTE:

Programming an “standalone” FPGA

If your FPGA doesn’t come with a built-in programmer or if you prefer to use an external cable, you can specify a cable to use from Cables (or openFPGALoader --list-cables):

openFPGALoader -c my_cable my_bitstream.bit # Program to SRAM
openFPGALoader -c my_cable -f my_bitstream.bit # Program to flash

NOTE:

HINT:

openFPGALoader -d /dev/ttyUSBX

Troubleshooting

Please refer to Troubleshooting.

Linux

Debian/Ubuntu

openFPGALoader is available in the default repositories:

sudo apt install openfpgaloader

Guix

openFPGALoader is available in the default repositories:

guix install openfpgaloader

Arch Linux

openFPGALoader is available in the default repositories:

sudo pacman -S openfpgaloader

Alternatively, you could build from source. First: install required libraries:

sudo pacman -S git cmake make gcc pkgconf libftdi libusb zlib hidapi gzip

Build step is similar as Debian

Fedora

openFPGALoader is available as a Copr repository:

sudo dnf copr enable mobicarte/openFPGALoader
sudo dnf install openFPGALoader

From source

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

sudo apt install \


  git \


  gzip \


  libftdi1-2 \


  libftdi1-dev \


  libhidapi-hidraw0 \


  libhidapi-dev \


  libudev-dev \


  zlib1g-dev \


  cmake \


  pkg-config \


  make \


  g++

HINT:

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

By default, cmsisdap support is enabled (used for colorlight I5, I9). If you don’t want this option, use:

-DENABLE_CMSISDAP=OFF

Alternatively you can manually specify the location of libusb and libftdi1:

-DUSE_PKGCONFIG=OFF \
-DLIBUSB_LIBRARIES=<path_to_libusb> \
-DLIBFTDI_LIBRARIES=<path_to_libftdi> \
-DLIBFTDI_VERSION=<version> \
-DCMAKE_CXX_FLAGS="-I<libusb_include_dir> -I<libftdi1_include_dir>"

You may also need to add this if you see link errors between libusb and pthread:

-DLINK_CMAKE_THREADS=ON

By default, libgpiod support is enabled If you don’t want this option, use:

-DENABLE_LIBGPIOD=OFF

Additionaly you have to install libgpiod

To build the app:

git clone https://github.com/trabucayre/openFPGALoader
cd openFPGALoader
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


         # add -DENABLE_CMSISDAP=OFF to disable CMSIS DAP support
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.

Udev rules

By default, users have no access to converters. A rule file (99-openfpgaloader.rules) for udev is provided at the root directory of this repository. These rules set access right and group (plugdev) when a converter is plugged.

sudo cp 99-openfpgaloader.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger # force udev to take new rule
sudo usermod -a $USER -G plugdev # add user to plugdev group

After that you need to unplug and replug your device.

HINT:

macOS

openFPGALoader is available as a Homebrew formula:

brew install openfpgaloader

Alternatively, if you want to build it by hand:

brew install --only-dependencies openfpgaloader
brew install cmake pkg-config zlib gzip
git clone https://github.com/trabucayre/openFPGALoader
cd openFPGALoader
mkdir build
cd build
cmake ..
make -j

Windows

Common

Bitstreams for XC2C (coolrunner-II) needs to be remapped using .map shipped with ISE. ISE path is set at configure time using:

-DISE_PATH=/somewhere/Xilinx/ISE_VERS/

default: /opt/Xilinx/14.7.

I installed openFPGALoader but it says command not found when I try to launch it

The correct spelling of the program is openFPGALoader with FPGA and the “L” of “Loader” in uppercase. Ensure the spelling of the program is correct.

Gowin device could not communicate since last bitstream flashed. (issue #206)

Gowin’s FPGA may fails to be detected if JTAGSEL_N (pin 08 for GW1N-4K) is used as a GPIO. To recover you have to pull down this pin (before power up) to recover JTAG interface (UG292 - JTAGSELL_N section).

JTAG init failed

Avoid using USB hubs and connect it directly to your PC USB port.

Tang Primer 20k program slow and stucked (issue #250)

Check your openFPGALoader version:

openFPGALoader -V

If it is older than release then v0.9.0, install the most recent version (from commit f5b89bff68a5e2147404a895c075773884077438 or later).

Cannot flash Tang Nano 9k (issue #251)

This is a device issue, erase its Embedded Flash using Official GoWin Programmer (preferentially in Windows) and SRAM too, then you can use openFPGALoader again.

Unable to open FTDI device: -4 (usb_open() failed) (issue #245)

Edit your /etc/udev/rules.d/99-ftdi.rules file exchanging your programming device permissions.

For more information, check the udev section from this guide

Resetting an FPGA

openFPGALoader [options] -r

Using negative edge for TDO’s sampling

If transaction are unstable you can try to change read edge by using

openFPGALoader [options] --invert-read-edge

Reading the bitstream from STDIN

cat /path/to/bitstream.ext | openFPGALoader --file-type ext [options]

--file-type is required to detect file type.

NOTE:

# FPGA side
nc -lp port | openFPGALoader --file-type xxx [option
# Bitstream side
nc -q 0 host port < /path/to/bitstream.ext

Automatic file type detection bypass

Default behavior is to use file extension to determine file parser. To avoid this mechanism --file-type type must be used.

FT231/FT232 bitbang mode and pins configuration

FT232R and ft231X may be used as JTAG programmer. JTAG communications are emulated in bitbang mode.

To use these devices user needs to provides both the cable and the pin mapping:

openFPGALoader [options] -cft23XXX --pins=TDI:TDO:TCK:TMS /path/to/bitstream.ext

where:

allowed values are:

Writing to an arbitrary address in flash memory

With FPGA using an external SPI flash (xilinx, lattice ECP5/nexus/ice40, anlogic, efinix) option -o allows one to write raw binary file to an arbitrary adress in FLASH.

Using an alternative directory for spiOverJtag

By setting OPENFPGALOADER_SOJ_DIR it’s possible to override default spiOverJtag bitstreams directory:

export OPENFPGALOADER_SOJ_DIR=/somewhere
openFPGALoader xxxx

or

OPENFPGALOADER_SOJ_DIR=/somewhere openFPGALoader xxxx

Sipeed Lichee Tang

For this target, openFPGALoader supports svf and bit.

bit file load (memory)

openFPGALoader -m -b licheeTang /somewhere/project/prj/*.bit

Since -m is the default, this argument is optional.

bit file load (spi flash)

openFPGALoader -f -b licheeTang /somewhere/project/prj/*.bit

svf file load

It’s possible to produce this file by using TD:

or by using prjtang project:

mkdir build
cd build
cmake ../
make

Now a file called tangbit is present in current directory and has to be used as follows:

tangbit --input /somewhere.bit --svf bitstream.svf

openFPGALoader -b licheeTang /somewhere/*.svf

Supported Boards/Cables

Programming Modes

Supported configuration files are bitfiles *.bit and it’s ASCII equivalents *.cfg.

JTAG Configuration

Performs an active hardware reset and writes the configuration into the FPGA latches via JTAG. The configuration mode pins CFG_MD[3:0] must be set to 0xC (JTAG).

openFPGALoader -b gatemate_evb_jtag <bitfile>.cfg.bit

openFPGALoader -c gatemate_pgm <bitfile>.cfg.bit

SPI Configuration

Performs an active hardware reset and writes the configuration into the FPGA latches via SPI. The configuration mode pins CFG_MD[3:0] must be set to 0x4 (SPI passive).

openFPGALoader -b gatemate_evb_spi <bitfile>.cfg.bit

openFPGALoader -b gatemate_pgm_spi <bitfile>.cfg.bit

JTAG Flash Access

It is possible to access external flashes via the internal JTAG-SPI-bypass. The configuration mode pins CFG_MD[3:0] must be set to 0xC (JTAG). Note that the FPGA will not start automatically.

openFPGALoader -b gatemate_evb_jtag <bitfile>.cfg.bit

openFPGALoader -c gatemate_pgm -f <bitfile>.cfg.bit

The offset parameter can be used to store data at any point in the flash, e.g.:

openFPGALoader -b gatemate_evb_jtag -o <offset> <bitfile>.cfg.bit

SPI Flash Access

If the programming device and FPGA share the same SPI signals, it is possible to hold the FPGA in reset and write data to the flash. The configuration mode can be set as desired. If the FPGA should start from the external memory after reset, the configuration mode pins CFG_MD[3:0] set to 0x0 (SPI active).

openFPGALoader -b gatemate_evb_spi -f <bitfile>.cfg.bit

openFPGALoader -b gatemate_pgm_spi -f <bitfile>.cfg.bit

The offset parameter can be used to store data at any point in the flash, e.g.:

openFPGALoader -b gatemate_evb_spi -o <offset> <bitfile>.cfg.bit

Firant and Xyloni boards (efinix trion T8)

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

openFPGALoader supports only active mode (SPI) (JTAG is WIP).

hex file load

openFPGALoader -b fireant /somewhere/project/outflow/*.hex

or, for xyloni board

openFPGALoader -b xyloni_spi /somewhere/project/outflow/*.hex

Since openFPGALoader access the flash directly in SPI mode the -b fireant, -b xyloni_spi is required (no autodetection possible).

Trion and Titanium JTAG usage

openFPGALoader supports loading to RAM and SPI Flash with JTAG

Tested with J-Link BASE

bin file load

openFPGALoader --cable jlink_base -m  /somewhere/project/outflow/*.bin

hex file flash

Example for ti60f225. NOTE: JTAG chains with more than one device (eg –index-chain) are currently not supported for writing to SPI flash

openFPGALoader --cable jlink_base --fpga-part ti60f225 -f  /somewhere/project/outflow/*.hex

GOWIN GW1N

NOTE:

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

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

where BOARD_NAME is:

Flash

ATTENTION:

with -f, file load:

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

where BOARD_NAME is:

It's possible to flash external SPI Flash (connected to MSPI) in bscan mode by using --external-flash instead of -f.

NOTE:

User Flash

ATTENTION:

Gowin FPGA come with extra flash space that can be read and written from the programmable logic ("User Flash"). This flash section can also be programmed via the JTAG interface:

openFPGALoader --write-flash /path/to/bitstream.fs --user-flash /path/to/flash.bin

Intel/Altera

NOTE:

Loading a bitstream

SVF and RBF files are supported.

sof to svf generation:

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

sof to rbf generation:

quartus_cpf  --option=bitstream_compression=off -c project_name.sof project_name.rbf

WARNING:

You can have Quartus automatically generate SVF and RBF files by adding these lines to the qsf file, or include them in a tcl file in FuseSoC

set_global_assignment -name ON_CHIP_BITSTREAM_DECOMPRESSION OFF
set_global_assignment -name GENERATE_RBF_FILE ON
set_global_assignment -name GENERATE_SVF_FILE ON

file load:

openFPGALoader -b boardname project_name.svf
# or
openFPGALoader -b boardname project_name.rbf

with boardname = de0, cyc1000, c10lp-refkit, de0nano, de0nanoSoc or qmtechCycloneV.

SPI flash

RPD and RBF are supported. POF is only supported for MAX10 (internal flash).

pof to rpd:

quartus_cpf -c project_name.pof project_name.rpd

sof to rpd:

# CYC1000
quartus_cpf -o auto_create_rpd=on -c -d EPCQ16A -s 10CL025YU256C8G project_name.svf project_name.jic
# C10LP-RefKit
quartus_cpf -o auto_create_rpd=on -c -d EPCQ16A -s 10CL055YU484C8G project_name.svf project_name.jic

file load:

openFPGALoader -b boardname -r project_name_auto.rpd
# or
openFPGALoader -b boardname -r project_name.rbf

with boardname = cyc1000, c10lp-refkit.

MAX10:

Intel/Altera (Old Boards)

NOTE:

Loading a Serial Vector Format (.svf)

SVF files are supported.

To load the file:

openFPGALoader -c usb-blaster project_name.svf

MachXO2/MachXO3

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 yourboard] [--flash-sector CFG0] impl1/*.jed

where yourboard may be:

and where --flash-sector CFG0 is needed for the MachXO3D Breakout Board.

.bit may also be used for machXO2

SRAM

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

File load:

openFPGALoader [-b yourboard] impl1/*.bit

where yourboard may be:

iCE40

.bin is the default format generated by nextpnr, so nothing special must be done.

Since most ice40 boards uses the same pinout between FTDI and SPI flash a generic ice40_generic board is provided.

For the specific case of the iCE40HXXK-EVB where no onboard programmer is present, please use this:

Bin file load:

openFPGALoader -b ice40_generic /somewhere/*.bin

Since it's a direct access to the flash (SPI) the -b option is required.

ECP5/Crosslink-NX

SRAM

openFPGALoader [-b yourBoard] [-c yourCable] -m project_name/*.bit

HINT:

SPI Flash

BIT:

openFPGALoader [-b yourBoard] [-c yourCable] -f project_name/*.bit # or *.bin

MCS:

To generate .mcs file PROM File must be checked under Exports Files in Lattice Diamond left panel.

openFPGALoader [-b yourBoard] [-c yourCable] project_name/*.mcs

Loading a bitstream

.bit and .bin are allowed to be loaded in memory.

File load:

openFPGALoader [-m] -b arty *.runs/impl_1/*.bit (or *.bin)

or

openFPGALoader [-m] -b spartanEdgeAccelBoard -c digilent_hs2 *.runs/impl_1/*.bit (or *.bin)

SPI flash

NOTE:

.mcs must be generated through Vivado with a tcl script like:

WARNING:

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:

The tcl script is used with:

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

File load:

openFPGALoader [--fpga-part xxxx] -f -b arty *.runs/impl_1/*.mcs (or .bit / .bin)

NOTE:

NOTE:

Some boards with UltraScale FPGAs, like the VCU118 and KCU16, support the SPIx8 (Dual Quad SPI) configuration. In this case, the spix8 option write_cfgmem on the above example can be used to generate two .mcs files, to fit bigger designs or for faster programming. Only .mcs files can be used to program the FPGA in this case.

In this case, to load the two .mcs files:

openFPGALoader --board vcu118 -f --target-flash both --bitstream *.runs/impl_1/*_primary.mcs --secondary-bitstream *.runs/impl_1/*_secondary.mcs

On these boards, each SPI flash can be programmed independently with the --target-flash option. The default target is the primary flash.

For example, to program only the secondary flash with arbitrary data not related to FPGA configuration:

openFPGALoader --board vcu118 -f --target-flash secondary --bitstream arbitrary_data

Global

Cable

Devices/boards

Misc