openFPGALoader

Universal utility for programming FPGA

Current support kits:

Trenz cyc1000 Cyclone 10 LP 10CL025 (memory and spi flash)
Colorlight 5A-75B (version 7) (memory and spi flash)
Digilent Arty A7 xc7a35ti (memory and spi flash)
Digilent Arty S7 xc7s50 (memory and spi flash)
Lattice MachXO2 Breakout Board Evaluation Kit (LCMXO2-7000HE) (memory and flash)
Lattice MachXO3LF Starter Kit LCMX03LF-6900C (memory and flash)
Lattice CrossLink-NX Evaluation Board (LIFCL-40-EVN) (memory and spi flash)
Lattice ECP5 5G Evaluation Board (LFE5UM5G-85F-EVN) (memory and spi flash)
Trenz Gowin LittleBee (TEC0117)
Saanlima Pipistrello LX45 (memory)
SeeedStudio Spartan Edge Accelerator Board (memory)
Sipeed Tang Nano (memory)
Sipeed Lichee Tang (memory and spi flash)
Terasic de0nano (memory)
LambdaConcept ECPIX-5 (memory and flash)

Supported (tested) FPGA:

Anlogic EG4S20 (SRAM and Flash)
Gowin GW1N (GW1N-1, GW1N-4, GW1NR-9) (SRAM and Flash)
Lattice MachXO2 (SRAM and Flash)
Lattice MachXO3LF (SRAM and Flash)
Lattice ECP5 (25F, 5G 85F (SRAM and Flash)
Lattice ECP5 (25F, 5G 85F, CrossLink-NX (LIFCL-40) (SRAM and Flash)
Xilinx Artix 7 xc7a35ti, xc7a100t (memory (all) and spi flash (xc7a35ti)
Xilinx Spartan 6 xc6slx45 (memory)
Xilinx Spartan 7 xc7s15, xc7s50 (memory (all) and spi flash (xc7s50))
Intel Cyclone IV CE EP4CE22 (memory. See note below)
Intel Cyclone 10 LP 10CL025

Note: cyclone IV and cyclone 10 have same idcode. A WA is mandatory to detect correct model for flash programming.

Supported cables:

anlogic JTAG adapter
digilent_hs2: jtag programmer cable from digilent
DirtyJTAG: JTAG probe firmware for STM32F1
Intel USB Blaster: 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)

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

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

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
$ 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 && 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
      --freq arg          jtag frequency (Hz)
  -f, --write-flash       write bitstream in flash (default: false, only for
                          Gowin and ECP5 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 and ECP5 devices)
  -o, --offset arg        start offset in EEPROM
      --pins arg          pin config (only for ft232R) TDI:TDO:TCK:TMS
  -r, --reset             reset FPGA after operations
  -v, --verbose           Produce verbose output
  -h, --help              Give this help list
  -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 <gwenhael.goavec-merou@trabucayre.com>.

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

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

CYC1000 and de0nano

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

openFPGALoader -b de0nano -b 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

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

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

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

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

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

martin2250/openFPGALoader

openFPGALoader

compile and install

access right

Usage

Generic usage

display FPGA

Reset device

load bitstream device (memory or flash)

bitbang mode and pins configuration

CYC1000 and de0nano

loading in memory:

SPI flash:

ARTY and Spartan Edge Accelerator Board

loading in memory:

SPI flash (only for ARTY):

MachXO2/MachXO3 Starter Kit

Flash memory:

SRAM:

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

SRAM:

SPI Flash:

bit

mcs

Trenz GOWIN LittleBee (TEC0117) and Sipeed Tang Nano

Flash SRAM:

Flash (only with Trenz board):

Sipeed Lichee Tang