Important

Since May 2022, packages providing Architecture Definition assets do not include CLI utilities/wrappers to interact with Yosys, Verilog-to-Routing, etc. For backwards compatibility, end-users can install Python package f4pga from gh:chipsalliance/f4pga. For instance: pip install https://github.com/chipsalliance/f4pga/archive/main.zip#subdirectory=f4pga.

Getting Started with F4PGA Toolchain development

Important

This documentation explains the first steps in the development of the toolchain itself: generating definitions about the primitives and routing infrastructure of the architectures. If you are looking for the user documentation, i.e. how to generate bitstreams from HDL designs, please look at FOSS Flows For FPGA and Welcome to F4PGA examples! instead.

Warning

Generating Architecture Definition files is expected to take a long time to build, even on fast machines. To run the tests in this repository, please make sure these resources are available:

  • Memory: 5.5G

  • Disk space: 20G

This section provides an introduction on how to get started with the development of the F4PGA toolchain. Each FPGA architecture has its own toolchain backend that will be called during build. The aim of this repository is to gather the knowledge from those backends and generate useful human and machine readable documentation to be used by tools such as yosys, vpr and/or vpr. See Project X-Ray and Project Trellis for more information.

In order to generate architecture definitions, any intermediate file format or bitstreams, you can use one of the toolchain tests in this repository. The following steps describe the whole process:

Prepare the environment

Clone the repository:

git clone https://github.com/f4pga/f4pga-arch-defs.git

Bootstrap an isolated Conda environment with all the necessary dependencies:

cd f4pga-arch-defs
make env

Hint

This also checks out all the submodules and generates the build system (Make or Ninja) from the CMake configuration. If you want to use the Ninja build tool add this line before calling make env:

export CMAKE_FLAGS="-GNinja"

Build the tests

While different architectures provide different build targets, there are some targets that should exist for all architectures.

For development purposes a set of test designs are included for each supported architecture. In order to perform a build of a test design with the Make build system, enter the appropriate test build directory specific to your target architecture and invoke the desired target.

Assuming that you would like to generate the bitstream .bit file with the counter example for the Arty board, which uses Xilinx Artix-7 FPGA, you will execute the following:

cd build/xilinx/xc7/tests/counter
make counter_arty_bit

If you use Ninja, the target is accessible from the root of the build directory:

cd build
ninja counter_arty_bit

Note

Test design target names are based on the following naming convention: <design>_<platform>_<target_step>, where <target_step> is the actual step to be done, e.g.: bit, place, route, prog.

There are targets to run multiple tests at once:

# Build all demo bitstreams, targetting all architectures
make all_demos

# Build all Xilinx 7-series demo bitstreams
make all_xc7

# Build all Lattice ICE40 demo bitstreams
make all_ice40

# Build all QuickLogic demo bitstreams
make all_quicklogic

Specific bitstreams can be built by specifying their target name, followed by a suffix specifying the desired output. For example, the LUT-RAM test for the RAM64X1D primative is called dram_test_64x1d. Example targets are:

# Just run synthesis on the input Verilog
make dram_test_64x1d_eblif

# Complete synthesis and place and route the circuit
make dram_test_64x1d_route

# Create the output bitstream (including synthesis and place and route)
make dram_test_64x1d_bin

# Run bitstream back into Vivado for timing checks, etc.
make dram_test_64x1d_vivado

Load the bitstreams

The last step to test the whole flow is to load the bitstream to your platform. The final output file can be found in the appropriate test directory, i.e: build/xilinx/xc7/tests/counter/counter_arty/artix7-xc7a50t-arty-swbut-roi-virt-xc7a50t-arty-swbut-test/top.bit

Programming tools used in F4PGA are either provided as a conda package during the environment setup, or are automatically downloaded and referenced by CMake.

For convenience, the prog targets are provided for loading the bitstream, e.g.:

make counter_arty_prog

or for Ninja:

ninja counter_arty_prog

Find further details about loading bitstreams in Loading bitstreams.