Quick start#

Prerequisites#

The following packages need to be installed for generating fabric HDLs

Python:

Version >= 3.12

Dependencies:

sudo apt-get install python3-virtualenv

Note

If you get the warning ModuleNotFoundError: No module named 'virtualenv' or errors when installing the requirements, you have to install the dependencies for your specific python version. For Python 3.12 use

sudo apt-get install python3.12-virtualenv

Note

If you are using an older version than Ubuntu 24.04, you may need to install tkinter. Otherwise, you might get the warning ModuleNotFoundError: No module named 'tkinter'.

sudo apt-get install python3-tk
FABulous repository:

git clone https://github.com/FPGA-Research-Manchester/FABulous
Virtual environment:

We recommend using python virtual environments for the usage of FABulous. If you are not sure what this is and why you should use it, please read the virtualenv documentation.

cd FABulous
virtualenv venv
source venv/bin/activate

Now there is a (venv) at the beginning of your command prompt. You can deactivate the virtual environment with the deactivate command. Please note, that you always have to enable the virtual environment with source venv/bin/activate to use FABulous.

Python dependencies:

pip install -r requirements.txt

The following packages need to be installed for the CAD toolchain:

If you are using yosys oss-cad-suite, no need to install the following packages.

Yosys:

version > 0.26+0

Nextpnr-generic:

version > 0.4-28-gac17c36b

Yosys ghdl plugin:

Only needed for VHDL synthesis

Note

We recommend using the OSS CAD Suite to install the packages.

If you just want to install Yosys using apt, make sure you have at least Ubuntu 23.10 (24.04 for the LTS versions) installed to meet the above requirement.

Development workflow (uv)#

For development and contribution workflows, see the dedicated Development page which covers:

  • Setting up uv development environment

  • Pre-commit hooks and code standards

  • Git workflow and contribution guidelines

  • Testing and CI requirements

Building Fabric and Bitstream#

We offer two ways to run the FABulous flow, either via the FABulous Shell or directly supplying the commands via the command line (similar to Vivado Batch mode).

To use the FABulous Shell, you can run the following command:

FABulous -c <name_of_project>
FABulous <name_of_project>

Inside the FABulous shell, run:

run_FABulous_fabric
run_FABulous_bitstream user_design/sequential_16bit_en.v

To run the FABulous flow directly from the command line, you can use the following commands:

FABulous -c <name_of_project>
FABulous <name_of_project> -p "run_FABulous_fabric; run_FABulous_bitstream user_design/sequential_16bit_en.v"

Note

You will probably receive a warning for the FASM package like the following:
RuntimeWarning: Unable to import fast Antlr4 parser implementation.
ImportError: cannot import name 'antlr_to_tuple' from partially initialized module 'fasm.parser' (most likely due to a circular import)

Falling back to the much slower pure Python textX based parser
implementation.

Getting the faster antlr parser can normally be done by installing the
required dependencies and then reinstalling the fasm package with:
  pip uninstall
  pip install -v fasm

This usually happens when FASM can’t find the Antlr4 package, but this is not mandatory for us. If you still want to fix this issue, you have to install FASM in your virtual environment from source. Please have a look at the FASM documentation for more information.

After a successful call with the command run_FABulous_fabric the RTL file of each of the tiles can be found in the Tile folder and the fabric RTL file can be found in the Fabric folder.

After a successful call with the command run_FABulous_bitstream user_design/sequential_16bit_en.v. The bitstream and all the log files generated during synthesis and place and route can be found under the user_design folder. The bitstream will be named as sequential_16bit_en.bin.

Running in a Docker container#

Within the FABulous repo we provide a Dockerfile that allows users to run the FABulous flow within a Docker container, installing all requirements automatically.

Setting up the Docker environment

To set up the Docker environment, navigate to the FABulous root directory and run:

$ docker build -t fabulous .

Running the Docker environment

To run the Docker environment, stay in the FABulous root directory (this is vital as the command mounts the current directory as the container’s filesystem) and run:

$ docker run -it -v $PWD:/workspace fabulous

This will bring up an interactive bash environment within the Docker container, within which you can use FABulous as if hosted natively on your machine. When you are finished using FABulous, simply type exit, and all changes made will have been made to your copy of the FABulous repository.

FABulous Environment Variables#

FABulous can use environment variables to configure options, paths and projects. We distinguish between two types of environment variables: global and project specific environment variables. Global environment variables are used to configure FABulous itself, while project specific environment variables are used to configure a specific FABulous project. All environment variables can be set in the shell before running FABulous or can be set via .env files.

Note

Environment variables can be set in the shell before running FABulous. Shell environment variables always have the highest priority.

Global Environment Variables#

Global environment variables always start with FAB_` and are used to configure FABulous itself. To add a global .env file, create a file named .env in the root directory of the FABulous repository or use the --globalDotEnv command line argument when running FABulous. The following global environment variables are available:

Variable Name

Description

Default Value

FAB_ROOT

The root directory of the FABulous repository

The directory where the FABulous repository is located

FAB_FABULATOR_ROOT

The root directory of the FABulator repository

<None>

FAB_YOSYS_PATH

Path to Yosys binary

yosys (Uses global Yosys installation)

FAB_NEXTPNR_PATH

Path to Nextpnr binary

nextpnr-generic (Uses global Nextpnr installation)

FAB_IVERILOG_PATH

Path to Icarus Verilog binary

iverilog (Uses global Icarus Verilog installation)

FAB_VVP_PATH

Path to Verilog VVP binary

vvp (Uses global Verilog VVP installation)

FAB_GHDL_PATH

Path to GHDL binary

ghdl (Uses global GHDL installation)

FAB_PROJ_DIR

The root directory of the FABulous project

The directory where the FABulous project is located, given by command line

FAB_MODEL_PACK

The model pack for the project

Pointing to <project_dir>/Fabric/model_pack.<project_lang>

FAB_OSS_CAD_SUITE

Path to the oss-cad-suite installation

<None>

FAB_DEBUG

Enable debug mode

False

FAB_PROJ_VERSION_CREATED

The version of FABulous used to create the project

Same as the version of FABulous-FPGA package installed

FAB_PROJ_VERSION

The current project version

Same as the version of FABulous-FPGA package installed

Project Specific Environment Variables#

Project specific environment variables always start with FAB_PROJ_ and are used to configure a specific FABulous project. To add a project specific .env file, create a file named .env in the .FABulous directory of the FABulous project or use the --projectDotEnv command line argument when running FABulous. The following project specific environment variables are available:

Note

The project specific environment variables overwrite the global environment variables.

Variable Name

Description

Default Value

FAB_PROJ_LANG

RTL language used in FABulous project [verilog/vhdl]

verilog (default) or language specified by -w command line argument

FAB_SWITCH_MATRIX_DEBUG_SIGNAL

Generate debug signals in switch matrix RTL implementation [True/False]

True