openFPGALoader

Universal utility for programming FPGAs.

Current supported kits:

board name	description	FPGA	memory	flash
acornCle215	Acorn CLE 215+	Artix xc7a200tsbg484	OK	OK
alchitry_au	Alchitry Au	Artix xc7a35tftg256	OK	OK
arty	Digilent Arty A7	Artix xc7a35ticsg324	OK	OK
	Digilent Arty S7	Spartan7 xc7s50csga324	OK	OK
	Digilent Analog Discovery 2	Spartan6 xc6slx25	OK	NT
	Digilent Digital Discovery	Spartan6 xc6slx25	OK	NT
basys3	Digilent Basys3	Artix xc7a35tcpg236	OK	OK
colorlight	Colorlight 5A-75B (version 7)	ECP5 LFE5U-25F-6BG256C	OK	OK
colorlight_i5	Colorlight I5	ECP5 LFE5U-25F-6BG381C	OK	OK
crosslinknx_evn	Lattice CrossLink-NX Evaluation Board	Nexus LIFCL-40	OK	OK
cyc1000	Trenz cyc1000	Cyclone 10 LP 10CL025YU256C8G	OK	OK
de0	Terasic DE0	Cyclone III EP3C16F484C6	OK	NT
de0nano	Terasic de0nano	Cyclone IV E EP4CE22F17C6	OK	OK
de0nanoSoc	Terasic de0nanoSoc	Cyclone V SoC 5CSEMA4U23C6	OK
de10nano	Terasic de10Nano	Cyclone V SoC 5CSEBA6U23I7	OK
ecp5_evn	Lattice ECP5 5G Evaluation Board	ECP5G LFE5UM5G-85F	OK	OK
ecpix5	LambdaConcept ECPIX-5	ECP5 LFE5UM5G-85F	OK	OK
fireant	Fireant Trion T8	Trion T8F81	NA	AS
fomu	Fomu PVT	iCE40UltraPlus UP5K	NA	OK
honeycomb	honeycomb	littleBee GW1NS-2C	OK	IF
ice40_generic	iCEBreaker	iCE40UltraPlus UP5K	NA	AS
ice40_generic	icestick	iCE40 HX1k	NA	AS
ice40_generic	iCE40-HX8K	iCE40 HX8k	NT	AS
ice40_generic	Olimex iCE40HX1K-EVB	iCE40 HX1k	NT	AS
ice40_generic	Olimex iCE40HX8K-EVB	iCE40 HX8k	NT	AS
kc705	Xilinx KC705	Kintex7 xc7k325t	OK	NT
licheeTang	Sipeed Lichee Tang	eagle s20 EG4S20BG256	OK	OK
machXO2EVN	Lattice MachXO2 Breakout Board Evaluation Kit	MachXO2 LCMXO2-7000HE	OK	OK
machXO3EVN	Lattice MachXO3D Development Board	MachXO3D LCMXO3D-9400HC	OK	NT
machXO3SK	Lattice MachXO3LF Starter Kit	MachXO3 LCMX03LF-6900C	OK	OK
nexysVideo	Digilent Nexys Video	Artix xc7a200tsbg484	OK	OK
orangeCrab	Orange Crab	ECP5 LFE5U-25F-8MG285C	OK (JTAG)	OK (DFU)
pipistrello	Saanlima Pipistrello LX45	Spartan6 xc6slx45-csg324	OK	OK
qmtechCycloneV	QMTech CycloneV Core Board	Cyclone V 5CEFA2F23I7	OK	OK
runber	SeeedStudio Gowin RUNBER	littleBee GW1N-4	OK	IF
	Scarab Hardware MiniSpartan6+	Spartan6 xc6slx25-3-ftg256	OK	NT
spartanEdgeAccelBoard	SeeedStudio Spartan Edge Accelerator Board	Spartan7 xc7s15ftgb196	OK	NA
tangnano	Sipeed Tang Nano	littleBee GW1N-1	OK
tec0117	Trenz Gowin LittleBee (TEC0117)	littleBee GW1NR-9	OK	IF
xtrx	FairWaves XTRXPro	Artix xc7a50tcpg236	OK	OK
xyloni_spi	Efinix Xyloni	Trion T8F81	NA	AS
zedboard	Avnet ZedBoard	zynq7000 xc7z020clg484	OK	NA

• IF Internal Flash
• AS Active Serial flash mode
• NA Not Available
• NT Not Tested

Supported (tested) FPGA:

vendor	model	memory	flash
Anlogic	EG4S20	OK	AS
Efinix	Trion T8	NA	OK
Gowin	GW1N (GW1N-1, GW1N-4, GW1NR-9, GW1NS-2C)	OK	IF
Intel	Cyclone III EP3C16	OK	OK
	Cyclone IV CE EP4CE22	OK	OK
	Cyclone V E 5CEA2, 5CEBA4	OK	OK
	Cyclone 10 LP 10CL025	OK	OK
Lattice	CrossLink-NX (LIFCL-40)	OK	OK
	ECP5 (25F, 5G 85F	OK	OK
	iCE40 (HX1K,HX8K, UP5K)	OK	NT
	MachXO2	OK	OK
	MachXO3D	OK	OK
	MachXO3LF	OK	OK
Xilinx	Artix 7 xc7a35ti, xc7a50t, xc7a75t, xc7a100t, xc7a200t	OK	OK
	Kintex 7 xc7k325t	OK	NT
	Spartan 6 xc6slx9, xc6slx16, xc6slx25, xc6slx45	OK	OK
	Spartan 7 xc7s15, xc7s25, xc7s50	OK	OK

• IF Internal Flash
• AS Active Serial flash mode
• NA Not Available
• NT Not Tested

Supported cables:

• anlogic JTAG adapter
• digilent_hs2: jtag programmer cable from digilent
• cmsisdap: ARM CMSIS DAP protocol interface (hid only)
• Orbtrace: Open source FPGA-based debug and trace interface
• DFU (Device Firmware Upgrade): USB device compatible with DFU protocol
• DirtyJTAG: JTAG probe firmware for STM32F1 (Best to use release (1.4 or newer) or limit the --freq to 600000 with older releases. New version https://github.com/jeanthom/DirtyJTAG/tree/dirtyjtag2 is also supported)
• Intel USB Blaster I & II : jtag programmer cable from intel/altera
• JTAG-HS3: jtag programmer cable from digilent
• FT2232: generic programmer cable based on Ftdi FT2232
• FT232RL and FT231X: generic USB<->UART converters in bitbang mode
• Tang Nano USB-JTAG interface: FT2232C clone based on CH552 microcontroler (with some limitations and workaround)
• Tigard: SWD/JTAG/UART/SPI programmer based on Ftdi FT2232HQ
• honeycomb USB-JTAG interface: FT2232C clone based on STM32F042 microcontroler

Contents

• Compile and install
• Access Right
• Usage
  • Generic usage
  • display FPGA
  • Reset device
  • Load bistream
  • Bypass file type detection
  • Bitbang mode and pins configuration
• Altera
• Xilinx
• Lattice machXO
• Lattice ECP5 and Nexus
• Gowin
• Anlogic
• Efinix
• ice40

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 libhidapi-libusb0 libhidapi-dev libudev-dev cmake pkg-config make g++

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

By default, cmsisdap support is enabled (used for colorlight I5). 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

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

access right

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 YourUserName -G plugdev # add user to plugdev group

After that you need to unplug and replug your device.

Usage

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

      --bitstream arg       bitstream
  -b, --board arg           board name, may be used instead of cable
  -c, --cable arg           jtag interface
      --ftdi-serial arg     FTDI chip serial number
      --ftdi-channel arg    FTDI chip channel number (channels 0-3 map to
                            A-D)
  -d, --device arg          device to use (/dev/ttyUSBx)
      --detect              detect FPGA
      --dfu                 DFU mode
      --dump-flash          Dump flash mode
      --file-size arg       provides size in Byte to dump, must be used with
                            dump-flash
      --file-type arg       provides file type instead of let's deduced by
                            using extension
      --fpga-part arg       fpga model flavor + package
      --freq arg            jtag frequency (Hz)
  -f, --write-flash         write bitstream in flash (default: false, only
                            for Gowin and ECP5 devices)
      --index-chain arg     device index in JTAG-chain
      --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 and ECP5 devices)
  -o, --offset arg          start offset in EEPROM
      --pins arg            pin config (only for ft232R) TDI:TDO:TCK:TMS
      --probe-firmware arg  firmware for JTAG probe (usbBlasterII)
      --quiet               Produce quiet output (no progress bar)
  -r, --reset               reset FPGA after operations
      --spi                 SPI mode (only for FTDI in serial mode)
  -v, --verbose             Produce verbose output
  -h, --help                Give this help list
      --verify              Verify write operation (SPI Flash only)
  -V, --Version             Print program version

Mandatory or optional arguments to long options are also mandatory or optional
for any corresponding short options.

Report bugs to <[email protected]>.

To have complete help

Generic usage

• when a bitstream file is compatible with both memory load and FLASH write, the default behavior is to load bitstream in 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.

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

Using pipe

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

--file-type is required to detect file type

Note: It's possible to load a bitstream through network:

# FPGA side
nc -lp port | openFPGALoader --filetype 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 mecanism --file-type type must be used.

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:

• ft23XXX may be ft232RL or ft231X
• TDI:TDO:TCK:TMS may be the pin ID (0 <= id <= 7) or string value

allowed values are:

value	ID
TXD	0
RXD	1
RTS	2
CTS	3
DTR	4
DSR	5
DCD	6
RI	7

Intel/Altera: CYC1000, DE0, de0nano

loading in memory:

SVF and RBF files are supported:

sof to svf generation:

quartus_cpf -c -q -g 3.3 -n 12.0MHz 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: as mentionned in cyclone handbooks, real-time decompression is not supported by FPGA in JTAG mode. Keep in mind to disable this option.

file load:

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

with boardname = de0, cyc1000, de0nano, de0nanoSoc or qmtechCycloneV

SPI flash:

RPD and RBF are supported

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
# or
openFPGALoader -b cyc1000 -r project_name.rbf

Xilinx based boards

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

Note:

1. Spartan Edge Accelerator Board has only pinheader, so the cable must be provided
2. a JTAG <-> SPI bridge (used to write bitstream in FLASH) is available for some device, see spiOverJtag to check if your model is supported
3. board provides the device/package model, but if the targeted board is not officially supported but the FPGA yes, you can use --fpga-part to provides model

Warning .bin may be loaded in memory or in flash, but this extension is a classic extension for CPU firmware and, by default, openFPGALoader load file in memory, double check -m / -f when you want to use a firmware for a softcore (or anything, other than a bitstream) to write somewhere in the FLASH device).

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

.bin is not, by default, produces. To have access to this file you need to configure the tool:

• GUI: Tools -> Settings -> Bitstreams -> check -bin_file
• TCL: append your TCL file with set_property STEPS.WRITE_BITSTREAM.ARGS.BIN_FILE true [get_runs impl_1]

Warning: for alchitry board the bitstream must be configured with a buswidth of 1 or 2. Quad mode can't be used with alchitry's FLASH

loading in memory:

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

.bit, .bin, and .mcs are supported for FLASH.

.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 [--fpga-part xxxx] -f -b arty *.runs/impl_1/*.mcs (or .bit / .bin)

Note: -f is required to write bitstream (without them .bit and .bin are loaded in memory)

Note: "--fpga-part" is only required if this information is not provided at board.hpp level or if the board is not officially supported. device/packagee format is something like xc7a35tcsg324 (arty model). See src/board.hpp, or spiOverJtag directory for examples.

MachXO2/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 yourboard] impl1/*.jed

where yourboard may be:

• machX02EVN
• machXO3SK

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:

• machX02EVN
• machXO3SK

Lattice ECP5 (Colorlight 5A-75b, Lattice ECP5 5G Evaluation board, ULX3S) CrossLink-NX

SRAM:

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

By default, openFPGALoader load bitstream in memory, so the '-m' argument is optional

SPI Flash:

bit

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

mcs

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

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

GOWIN GW1N (Trenz TEC0117, Sipeed Tang Nano, Honeycomb and RUNBER)

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

• tec0117
• tangnano
• runber

Flash (only with Trenz TEC0117 and runber):

with -f

file load:

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

where BOARD_NAME is:

• tec0117
• runber

Sipeed Lichee Tang

For this target, openFPGALoader support 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:

• Tools->Device Chain
• Add your bit file
• Option : Create svf

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

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

openFPGALoader -b licheeTang /somewhere/*.svf

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 support 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)

ice40 boards (icestick, iCE40-HX8K, iCEBreaker, iCE40HX1K-EVB, iCE40HX8K-EVB)

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

FTDI	iCE40HXXK-EVB
SCK (ADBUS0)	Pin 9
SI (ADBUS1)	Pin 8
SO (ADBUS2)	Pin 7
CS (ABDUS4)	Pin 10
RST (ADBUS6	Pin 6
DONE (ADBUS7)	Pin 5

bin file load

openFPGALoader -b ice40_generic /somewhere/*.bin

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