DOCSEARCHbyAlgolia
Submit Docs

openFPGALoader Documentation

repository·master·Indexed 23 days ago

https://github.com/trabucayre/openfpgaloader

A universal utility for programming FPGAs supporting manufacturers including Xilinx, Altera/Intel, Lattice, Gowin, Efinix, Anlogic, and Cologne Chip. It works across Linux, Windows, macOS, and OpenBSD, providing capabilities to load bitstreams into SRAM or write to non-volatile flash memory using board configurations or JTAG cables. The tool includes spiOverJtag for accessing external SPI flash over JTAG on specific FPGA families.

Tokens
16K
Snippets
41
Records
93
Agent score
81%

What's inside openFPGALoader

  1. What is spiOverJtag and when to use it

    master

    spiOverJtag provides bridge bitstreams used by openFPGALoader to access external SPI flash over JTAG on specific FPGA families.

    While some FPGAs (Lattice ECP3/ECP5, Gowin GW2/GW5, and Cologne Chip GateMate) have internal interfaces for this, others require these dedicated bridge bitstreams:

    • Xilinx
    • Altera Cyclone
    • Efinix

    Key constraints:

    • It supports Single-Wire mode only (MOSI/MISO) to ensure maximum board compatibility.
    • Rebuilding is typically only necessary when adding support for a new FPGA model or package.

  3. Load bitstreams to ECP5/ECP3/Certus/Crosslink-NX SRAM

    master

    To load a bitstream into the SRAM of ECP5, ECP3, Certus-NX, CertusPro-NX, or Crosslink-NX devices, use the -m flag. Note that -m is optional as openFPGALoader loads bitstreams in memory by default.

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

  4. Build spiOverJtag bitstreams

    master

    To build bridge bitstreams, you must be in the spiOverJtag sub-directory. The build process uses make to invoke vendor-specific scripts (build.py for Xilinx/Altera and efinix_build.py for Efinix).

    Build Commands

    Xilinx Artix7 35t

    make spiOverJtag_xc7a35t.bit.gz

    Altera Cyclone10CL 016

    make spiOverJtag_10cl016484.rbf.gz

    Efinix Trion T13 F256

    make spiOverJtag_efinix_t13f256.bit.gz

    Package-Specific Bitstreams

    If a board uses different SPI flash pin mappings based on the device package, you must pass the full device name (device + package) to make.

    Example for QMTech XC7A100T (FGG676):

    make spiOverJtag_xc7a100tfgg676.bit.gz

    Cleanup

    To remove temporary build files:

    make clean

    Generated Outputs

    • Xilinx: spiOverJtag_<part>.bit.gz
    • Efinix: spiOverJtag_efinix_<part>.bit.gz
    • Altera: spiOverJtag_<part>.rbf.gz
    # Xilinx Artix7 35t
make spiOverJtag_xc7a35t.bit.gz

# Altera Cyclone10CL 016
make spiOverJtag_10cl016484.rbf.gz

# Efinix Trion T13 F256
make spiOverJtag_efinix_t13f256.bit.gz

# Package-specific (e.g., QMTech XC7A100T FGG676)
make spiOverJtag_xc7a100tfgg676.bit.gz

  6. Install openFPGALoader on Linux

    master

    Depending on your distribution, you can install openFPGALoader using the package manager:

    • Debian/Ubuntu: sudo apt install openfpgaloader
    • Guix: guix install openfpgaloader
    • Arch Linux: sudo pacman -S openfpgaloader
    • Fedora: Use the mobicarte/openFPGALoader Copr repository.

    Guix System Note: To use openFPGALoader without root privileges on GuixSystem, you must install udev rules by extending udev-service-type in your operating-system configuration and adding the plugdev group to your user-account declaration.

    # Debian/Ubuntu
sudo apt install openfpgaloader

# Guix
guix install openfpgaloader

# Arch Linux
sudo pacman -S openfpgaloader

# Fedora
sudo dnf copr enable mobicarte/openFPGALoader
sudo dnf install openFPGALoader

  7. Configure FT231/FT232 bitbang mode and pins

    master

    FT232R and ft231X devices can be used as JTAG programmers by emulating JTAG communications in bitbang mode. When using these devices, you must provide both the cable type and the pin mapping using the --pins flag.

    Cable types:

    • ft232RL
    • ft231X

    Pin Mapping Format: --pins=TDI:TDO:TCK:TMS

    Each pin can be specified by its ID (0-7) or its string name. The available pin names and IDs are:

    ValueID
    TXD0
    RXD1
    RTS2
    CTS3
    DTR4
    DSR5
    DCD6
    RI7
    openFPGALoader [options] -cft23XXX --pins=TDI:TDO:TCK:TMS /path/to/bitstream.ext

  8. Program Cologne Chip GateMate via JTAG

    master

    To program a GateMate FPGA using JTAG, ensure the configuration mode pins CFG_MD[3:0] are set to 0xC (JTAG). This method performs an active hardware reset and writes the configuration directly into the FPGA latches.

    Supported file formats are bitfiles (*.bit) and their ASCII equivalents (*.cfg).

    Using the GateMate Evaluation Board: Use the board parameter -b gatemate_evb_jtag.

    Using the GateMate Programmer Cable: Use the cable parameter -c gatemate_pgm.

  9. Load bitstreams for Intel/Altera boards (CYC1000, DE0, etc.)

    master

    For Intel/Altera boards like cyc1000, c10lp-refkit, de0, de0nano, de0nanoSoc, or qmtechCycloneV, you can load bitstreams using .svf or .rbf files.

    Important: Real-time decompression is not supported by FPGAs in JTAG mode. Ensure you disable bitstream decompression in your Quartus settings or .qsf file to avoid issues.

    To generate these files from a .sof file using Quartus quartus_cpf:

    • SVF: quartus_cpf -c -q 12.0MHz -g 3.3 -n p project_name.sof project_name.svf
    • RBF: quartus_cpf --option=bitstream_compression=off -c project_name.sof project_name.rbf

    To load the files with openFPGALoader:

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

  10. Add support for a new FPGA device to spiOverJtag

    master

    To add a new device to the spiOverJtag build system, follow these four steps:

    1. Register the part in Makefile

    Add the short part name to the appropriate list in the Makefile:

    • XILINX_PARTS
    • ALTERA_PARTS
    • EFINIX_PARTS

    2. Update build script mappings

    • Xilinx (build.py):
      • For Artix, Kintex 7, and Spartan 7: Update the packages dictionary with size and package info.
      • For other devices: Update pkg_name (for Vivado) or tool_options (for ISE) to map the FPGA model/size/package to the device/package.
    • Altera (build.py):
      • Update the full_part dictionary to include the short format and a Quartus-compatible device name.
    • Efinix (efinix_build.py):
      • Update efinix_pinout with a new sub-dictionary providing pin names for each SPI IO.
      • Update the timing_models dictionary with an entry for the new FPGA. (For Titanium devices, ensure the package mapping exists in efinix_pinout["Titanium"]).

    3. Add constraints (if required)

    If the package is not yet available for a given FPGA family, add a constraint file:

    • Xilinx Vivado: constr_<name>.xdc
    • Xilinx ISE: constr_<name>.ucf
    • Altera: Handled by Quartus/script flow (no explicit file needed here).
    • Efinix: Handled by efinix_build.py (update script data for new package pinouts).

    4. Build the bitstream

    Run the make command for your new part:

    # Xilinx/Efinix
make spiOverJtag_<new-part>.bit.gz
# Altera
make spiOverJtag_<new-part>.rbf.gz

  11. Program bitstream to SPI flash

    master

    To write a bitstream to the non-volatile SPI flash, use the -f flag. Supported formats for flash programming are .bit, .bin, and .mcs.

    Important Constraints:

    • For Zynq (7000 and MPSoC) devices, SPI flash is not accessible through the PL (Programmable Logic).
    • For Alchitry boards, the bitstream must be configured with a buswidth of 1 or 2; Quad mode is not supported.
    • For Spartan 3, the flash is an independent JTAG device. Use --index-chain to switch between the FPGA (RAM only) and the flash (write/read only).

    If the board is not officially supported, use --fpga-part to specify the device/package model (e.g., xc7a35tcsg324).

  12. Read the bitstream from STDIN

    master

    You can pipe a bitstream into openFPGALoader via STDIN. When using STDIN, the --file-type option is required so the tool can identify the correct parser.

    To load a bitstream over a network, you can use nc (netcat) to bridge the connection between the FPGA side and the bitstream side.