Install

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

More instructions for other installation scenarios are available in Installing openFPGALoader <#install>.

Programming a development board

Just simply replace my_fpga_board with any FPGA board from Boards <#compatibility-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 <#compatibility-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 <#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

To use openFPGALoader under GuixSystem without root privileges it is necessary to install the necessary udev rules. This can be done by extending udev-service-type in the operating-system configuration file with this package

(udev-rules-service 'openfpgaloader openfpgaloader #:groups '(\"plugdev\")

Additionally, plugdev group should be registered in the supplementary-groups field of your user-account``declaration. Refer to ``Base Services section in the manual for examples.

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. Two rule files are provided at the root directory of this repository:

First, check if plugdev exists:

grep -w plugdev /etc/group

Option 1 (recommended): create system group plugdev (if required) and use 99-openfpgaloader.rules:

sudo groupadd --system plugdev # only required if plugdev is absent
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

Option 2: if plugdev does not exist (or you do not want to create it), use 70-openfpgaloader.rules and ensure your user is in dialout:

sudo cp 70-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 dialout # add user to dialout group

After that you need to unplug and replug your device.

Hint:

macOS

openFPGALoader is available as a Homebrew <https://brew.sh> 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

MSYS2 (Native Build)

openFPGALoader can be installed via MSYS2:

pacman -S mingw-w64-ucrt-x86_64-openFPGALoader

Cross-compilation from Linux

openFPGALoader can be cross-compiled for Windows from Linux using MinGW-w64 toolchains (GCC or Clang). The build system will automatically download and build the required dependencies (libusb, libftdi).

Prerequisites (Debian/Ubuntu):

sudo apt install \


  mingw-w64 \


  libz-mingw-w64-dev \


  clang \


  lld \


  cmake \


  pkg-config \


  p7zip-full

Prerequisites (Fedora/RHEL/Rocky):

sudo dnf install \


  mingw64-gcc \


  mingw64-gcc-c++ \


  mingw64-zlib \


  mingw64-zlib-static \


  clang \


  lld \


  cmake \


  p7zip \


  p7zip-plugins

Build (shared steps):

git clone https://github.com/trabucayre/openFPGALoader
cd openFPGALoader
mkdir build-win64
cd build-win64

Configure + build with GCC (MinGW-w64):

cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-x86_64-w64-mingw32.cmake ..
cmake --build . --parallel

Configure + build with Clang (MinGW-w64 target):

cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-x86_64-w64-mingw32-clang.cmake ..
cmake --build . --parallel

The resulting openFPGALoader.exe will be a statically-linked executable that only depends on standard Windows system DLLs (KERNEL32, msvcrt, WS2_32).

Note:

Optional: Strip debug symbols to reduce size:

x86_64-w64-mingw32-strip openFPGALoader.exe
# or
llvm-strip openFPGALoader.exe

Cross-compilation options:

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.

Disabling/Enabling Cable or Vendor Drivers

With the default cmake .. configuration, openFPGALoader enables ENABLE_CABLE_ALL=ON and ENABLE_VENDORS_ALL=ON. This means all cable and vendor drivers are enabled by default, then filtered only by OS capabilities and available dependencies.

To reduce binary size, speed up the build, or keep support limited to selected cables/vendors, you can explicitly enable or disable options.

These commands are equivalent:

cmake -DENABLE_CABLE_ALL=ON -DENABLE_VENDORS_ALL=ON ..
# and
cmake ..  # Implicit default values

To disable all cable and vendor support:

cmake -DENABLE_CABLE_ALL=OFF -DENABLE_VENDORS_ALL=OFF ..

This produces an openFPGALoader binary with no cable/vendor support. Then re-enable only what you need by adding one or more options below.

Each item in the following lists is a CMake option name. Use them with -D<OPTION>=ON to enable or -D<OPTION>=OFF to disable.

Note:

Example (enable FTDI-based cables and Xilinx devices only):

cmake \


  -DENABLE_CABLE_ALL=OFF \


  -DENABLE_VENDORS_ALL=OFF \


  -DENABLE_FTDI_BASED_CABLE=ON \


  -DENABLE_XILINX_SUPPORT=ON \


  ..

Cable options

Vendor options

Note:

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 <https://github.com/trabucayre/openFPGALoader/issues/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 <https://github.com/trabucayre/openFPGALoader/issues/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 <https://github.com/trabucayre/openFPGALoader/commit/fe259fb78d185b3113661d04cd7efa9ae0232425> or later).

Cannot flash Tang Nano 20k (issue #251 <https://github.com/trabucayre/openFPGALoader/issues/511>)

Some firmware version cannot be flashed on Linux-based systems. Version 2024122312 is such an example. It seems this version was not published on the SiPeed website <https://api.dl.sipeed.com/TANG/Debugger/onboard/BL616/>, however some boards sold have this firmware.

The cause of the problem is the debugger on the Tang Nano, specifically the firmware of this debugger. This firmware can be easily updated by following these <https://wiki.sipeed.com/hardware/en/tang/common-doc/update_debugger.html> steps.

Cannot flash Tang Nano 9k (issue #251 <https://github.com/trabucayre/openFPGALoader/issues/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 <https://github.com/trabucayre/openFPGALoader/issues/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 <install.rst>

Converter cannot be opened: fails to open device (issue #626 <https://github.com/trabucayre/openFPGALoader/issues/626>)

This is usually a permissions issue on Linux.

Check your current groups:

id $USER

Verify device node access rights:

ls -l /dev/ttyUSB* /dev/ttyACM*

Then verify udev rules are installed correctly (70-openfpgaloader.rules or 99-openfpgaloader.rules), and that your user is in the expected group (dialout or plugdev).

After changing groups or rules, reload udev rules, then unplug/replug the converter and log out/login again.

Reference: install guide (udev rules section) <https://trabucayre.github.io/openFPGALoader/guide/install.html#udev-rules>.

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.

Detect/read/write on primary/secondary flash memories

With FPGA using two external SPI flash (some xilinx boards) option --target-flash allows to select the QSPI chip.

To detect:

openFPGALoader -b kcu105 -f --target-flash {primary,secondary} --detect

To read the primary flash memory:

openFPGALoader -b kcu105 -f --target-flash primary --dump-flash --file-size N_BYTES mydump.bin

and the second flash memory:

openFPGALoader -b kcu105 -f --target-flash secondary --dump-flash --file-size N_BYTES --secondary-bitstream mydump.bin

To write on secondary flash memory:

openFPGALoader -b kcu105 -f --target-flash secondary --secondary-bitstream mySecondaryBitstream.bin

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 <https://github.com/mmicko/prjtang>:

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: FPGA Programming Guide

Supported Boards:

Supported File Types:

Internal Flash Organization

The internal flash is divided into five sections:

Flash usage depends on the configuration mode. In all modes:

Using svf

This method is the simplest (and slowest) way to load or write a bitstream.

Note:

openFPGALoader [-b boardname] -c cablename the_svf_file.svf

Parameters:

Using pof

To write a bitstream into the internal flash, using a pof file is the fastest approach.

openFPGALoader [-b boardname] [--flash-sector] -c cablename the_pof_file.pof

Parameters:

Accepted Flash Sectors:

Example:

openFPGALoader -c usb-blaster --flash-sector UFM1,CFM0,CFM2 the_pof_file.pof

This command updates UFM1, CFM0, and CFM2, leaving all other sectors unchanged.

Using an arbitrary binary file

Unlike Altera Quartus, it supports any binary format without limitations (not limited to a .bin). With this feature, it's not required to provides the file at gateware build time: it may be updated at any time without gateware modification/rebuild.

Note:

Basic usage:

openFPGALoader [-b boardname] -c cablename [--offset $OFFSET] the_bin_file.bin

This command erases and writes the contents of the_bin_file.bin into UFM1 and UFM0. If --offset is specified, the binary content is written starting from that offset.

Depending on the max10 configuration mode (see picture), it's possible to extend User Flash Memory area by using CFM2 and CFM1. This is not the default behavior and user must explictly change this by using --flash-sector argument:

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/ECP3/Certus-NX/CertusPro-NX/Crosslink-NX

SRAM

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

Hint:

SPI Flash

Note:

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