Getting started

To begin using F4PGA, you might want to take a look at the Guidelines below, which make for a good starting point. They will guide you through the process of installing and using the flows, explaining how to generate and load a bitstream into your FPGA.

F4PGA flows are composed of multiple tools, scripts and CLI utilities. Fortunately, various alternatives exist for setting up the whole ecosystem without going through the daunting task of installing pieces one-by-one. See Toolchain installation below.

Guidelines

This is the main documentation, which gathers info about the Python CLI tools and APIs and the Design Flows supported by F4PGA, along with a Glossary, references to specifications, plugins and publications.

Since F4PGA is meant for users with varying backgrounds and expertise, three paths are provided to walk into the ecosystem.

Newcomers are invited to go through Examples ➚, which provides step-by-step guidelines to install the tools through Conda ➚, generate a bitstream from one of the provided designs and load the bitstream into a development board. See Customizing the Makefiles for adapting the build plumbing to your own desings.

For Intermediate users and contributors, who are already familiar with installing the tools and building bitstreams, it is recommended to read the shell scripts in subdir scripts, as well as the Continuous Integration Pipeline. Moreover, workflow containers-conda-f4pga.yml in gh:hdl/packages shows how to use the */conda/f4pga/* containers from gh:hdl/containers (see workflow runs and Containers).

Advanced users and developers willing to support new devices and/or enhance the features of the supported families (see F4PGA Architectures Visualizer ➚) should head to Architecture Definitions ➚. The effort to document the details of each device/family are distributed on multiple projects:

Toolchain installation

F4PGA flows require multiple radpidly moving tools, assets and scripts, which makes it difficult for system packagers to catch up. Although some of the tools used in F4PGA (such as yosys, nextpnr or vpr) are available already through apt, dnf, pacman, etc. they typically use pinned versions which are not the latest. Therefore, the recommended installation procedure to follow the guidelines in F4PGA is repositories is using Conda ➚, or some other pre-packaged solution combining latest releases.

Other

Apart from Conda, multiple other solutions exist for setting up all the tools required in F4PGA. gh:hdl/packages is an index for several projects providing great prepackaged/prebuilt and easy-to-set-up bleeding-edge packages/environments of electronic design automation (EDA) tools/projects.

Containers

Ready-to-use docker/podman containers are maintained in gh:hdl/containers and made available through gcr.io/hdl-containers or ghcr.io/hdl/containers. Some of those include Conda, the Architecture Definitions and the f4pga Python package, so they are ready to use along with the examples in gh:chipsalliance/f4pga-examples. See F4PGA (Conda).

Hint

#574 is work in progress to provide an F4PGA Action (see Understanding GitHub Actions) based on */conda/f4pga/* containers.

Loading bitstreams

For every board, the loading process may vary and different tools may be required. Typically, each tool supports a specific target family or the lines of products of a vendor. Some of the most known are listed in hdl/constraints: Programming and debugging. The tools used in the F4PGA Toolchain are e.g. OpenOCD, tinyfpgab or tinyprog. Moreover, OpenFPGALoader is a universal utility for programming FPGA devices, which is becoming an alternative to the fragmentation in bitstream loading tools. OpenFPGALoader supports many different boards with FPGAs based on the architectures including xc7, ECP5, iCE40 and many more. It can utilize a variety of the programming adapters based on JTAG, DAP interface, ORBTrace, DFU and FTDI chips.

Installing OpenFPGALoader

OpenFPGALoader is available in several packaging solutions. It can be installed with distribution specific package managers on Arch Linux and Fedora. There are also prebuilt packages available in conda or packages in tool repository. OpenFPGALoader can also be built from sources. For installation guidelines using both prebuilt packages and building from source, please refer to instructions in readme.

Usage

For programming the FPGA, use one of these commands:

openFPGALoader -b <board> <bitstream>           # (e.g. arty)
openFPGALoader -c <cable> <bitstream>           # (e.g. digilent)
openFPGALoader -d <device> <bitstream>          # (e.g. /dev/ttyUSB0)

You can also list the supported boards, cables and FPGAs:

openFPGALoader --list-boards
openFPGALoader --list-cables
openFPGALoader --list-fpga

If you encounter any issues, please refer to openFPGALoader: universal utility for programming FPGA.