Installing openFPGALoader¶

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

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, 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

usermod is used to add $USER as a member of plugdev group. However this update is not taken into account immediately: it’s required to logout from current session and login again. Check, by using id $USER, if plugdev is mentioned after groups=. An alternate (and temporary) solution is to use sudo - $USER to have your user seen as a member of plugdev group (works only for the current terminal).

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¶

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. The build system will automatically download and build the required dependencies (libusb, libftdi).

Prerequisites (Debian/Ubuntu):

sudo apt install \
  mingw-w64 \
  cmake \
  pkg-config \
  p7zip-full

Prerequisites (Fedora/RHEL/Rocky):

sudo dnf install \
  mingw64-gcc \
  mingw64-gcc-c++ \
  mingw64-zlib \
  mingw64-zlib-static \
  cmake \
  p7zip \
  p7zip-plugins

Build:

git clone https://github.com/trabucayre/openFPGALoader
cd openFPGALoader
mkdir build-win64
cd build-win64
cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-x86_64-w64-mingw32.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).

Optional: Strip debug symbols to reduce size:

x86_64-w64-mingw32-strip openFPGALoader.exe

Cross-compilation options:

-DCROSS_COMPILE_DEPS=OFF - Disable automatic dependency download (use system libraries)
-DENABLE_CMSISDAP=ON - Enable CMSIS-DAP support (requires manually providing hidapi)

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

The default value for each option is provided by ENABLE_CABLE_ALL and ENABLE_VENDORS_ALL.

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

ENABLE_USB_SCAN: Enable USB cable discovery/scanning support.
ENABLE_ANLOGIC_CABLE: Enable Anlogic cable support (requires libUSB).
ENABLE_CH347: Enable CH347 cable support (requires libUSB).
ENABLE_CMSISDAP: Enable CMSIS-DAP interface support (requires hidapi).
ENABLE_DIRTYJTAG: Enable DirtyJTAG cable support (requires libUSB).
ENABLE_ESP_USB: Enable ESP32-S3 USB-JTAG cable support (requires libUSB).
ENABLE_JLINK: Enable J-Link cable support (requires libUSB).
ENABLE_DFU: Enable DFU-based cable support (requires libUSB).
ENABLE_FTDI_BASED_CABLE: Enable FTDI-based cable drivers (requires libftdi).
ENABLE_GOWIN_GWU2X: Enable Gowin GWU2X interface support.
ENABLE_SVF_JTAG: Enable SVF JTAG playback support.
ENABLE_USB_BLASTERI: Enable Altera USB-Blaster I support.
ENABLE_USB_BLASTERII: Enable Altera USB-Blaster II support.
ENABLE_LIBGPIOD: Enable libgpiod bitbang driver support (Linux only).
ENABLE_REMOTEBITBANG: Enable remote-bitbang driver support.
ENABLE_XILINX_VIRTUAL_CABLE: Enable Xilinx Virtual Cable (XVC) support.

Vendor options

ENABLE_ALTERA_SUPPORT: Enable Altera/Intel device family support.
ENABLE_ANLOGIC_SUPPORT: Enable Anlogic device family support.
ENABLE_COLOGNECHIP_SUPPORT: Enable Cologne Chip device family support (requires libftdi).
ENABLE_EFINIX_SUPPORT: Enable Efinix device family support (requires libftdi).
ENABLE_GOWIN_SUPPORT: Enable Gowin device family support.
ENABLE_ICE40_SUPPORT: Enable Lattice iCE40 device family support (requires libftdi).
ENABLE_LATTICE_SUPPORT: Enable Lattice device family support.
ENABLE_LATTICESSPI_SUPPORT: Enable Lattice SSPI support (requires libftdi).
ENABLE_XILINX_SUPPORT: Enable Xilinx device family support.

Note

SPI support is hardcoded to FTDI. When FTDI support is disabled, some vendor drivers are also disabled (iCE40, Cologne Chip, Efinix, and Lattice SSPI).

Installing openFPGALoader¶

Linux¶

Debian/Ubuntu¶

Guix¶

Arch Linux¶

Fedora¶

From source¶

Udev rules¶

macOS¶

Windows¶

MSYS2 (Native Build)¶

Cross-compilation from Linux¶

Common¶

Disabling/Enabling Cable or Vendor Drivers¶

openFPGALoader: universal utility for programming FPGA

Navigation

Related Topics