FABulous: an Embedded FPGA Framework

Warning

Active Development - Use Tagged Releases for Production

The main branch is under active development and may contain errors, incomplete features, and breaking changes. We are not responsible for any issues caused by using the development branch.

For production use, please use tagged releases or reach out to us for further advice.

Documentation: Our documentation defaults to the latest development version. You can switch between versions (including the latest development version or specific tagged releases) using the version selector at documentation page. Please ensure you consult the documentation version that matches your installation to avoid compatibility issues.

• FABulous: an Embedded FPGA Framework
  • Introduction
  • Prerequisites
    • Optional: uv for faster dependency management
  • Getting started
    • Using uv (optional)
  • Contribution Guidelines
  • How to cite
  • Disclaimer and Limitation of Liability

Introduction

FABulous is designed to fulfill the objectives of ease of use, maximum portability to different process nodes, good control for customization, and delivering good area, power, and performance characteristics of the generated FPGA fabrics. The framework provides templates for logic, arithmetic, memory, and I/O blocks that can be easily stitched together, whilst enabling users to add their own fully customized blocks and primitives.

The FABulous ecosystem generates the embedded FPGA fabric for chip fabrication, integrates YosysHQ toolchain release packages, deals with the bitstream generation and provides after-fabrication tests. Additionally, we plan to provide an emulation path for system development.

This guide describes everything you need to set up your system to use the FABulous ecosystem, and the full project documentation can be found here.

Silicon Proven

FABulous is silicon proven technology with multiple successful tapeouts. The framework has been used to fabricate real chips, demonstrating its capability to generate production-ready FPGA fabrics. These tapeouts validate the correctness and reliability of the generated IP across different process nodes and design configurations.

See our Chip Gallery for a few examples of fabricated chips using FABulous fabrics.

Prerequisites

Warning

Windows Support

FABulous is not officially supported on native Windows. While the tool may work, you may encounter errors and unexpected behavior. For the best experience on Windows-based systems, we strongly recommend using Windows Subsystem for Linux (WSL).

To set up WSL, visit: https://docs.microsoft.com/en-us/windows/wsl/install

The following packages need to be installed for generating fabric HDL models and using the FABulous front end:

• Python 3.12 or later

Install python 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 make python3-tk

The following packages need to be installed for the CAD toolchain

• Yosys
• nextpnr-generic

Optional: uv for faster dependency management

uv is a high-performance Python package manager that provides faster dependency resolution and installation. While not required for end users, it offers significant speed improvements and reproducible environments.

Benefits of using uv:

• 10-100x faster than pip for dependency resolution
• Automatic virtual environment management
• Deterministic dependency locking
• Cross-platform compatibility

Installation:

Linux/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

macOS with Homebrew:

brew install uv

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Or from PyPI:

pip install uv

To build the docs locally, some further Python dependencies are required - to install these, run

pip3 install -r docs/requirements.txt

from the top directory of the repository.

Getting started

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.

$ git clone https://github.com/FPGA-Research/FABulous
$ cd FABulous
$ virtualenv venv
$ source venv/bin/activate
(venv)$ pip install -e .

You can deactivate the virtual environment with the deactivate command. Please note, that you always have to enable the virtual environment to use FABulous:

cd <path to FABulous>
source venv/bin/activate

We have provided a Python Command Line Interface (CLI) as well as a project structure for easy access of the FABulous toolchain.

The Tile folder contains all the definitions of the fabric primitive as well as the fabric matrix configuration. fabric.csv is what defining the architecture of the fabric. The FABulous project folder also contains a .FABulous folder which contains all the metadata during the generation of the fabric.

We can initiate the FABulous shell with FABulous <project_dir>. After that you will see a shell interface which allow for interactive fabric generation. To generate a fabric we first need to run load_fabric [fabric_CSV] to load in the fabric definition. Then we can call run_FABulous_fabric to generate a fabric.

To generate a model and bitstream for a specific design call run_FABulous_bitstream <dir_to_top> which will generate a bitstream for the provided design in the same folder as the design.

To exit the shell simply type exit and this will terminate the shell.

A demo of the whole flow:

(venv)$ FABulous create-project demo # Create a demo project
(venv)$ cd demo
(venv)$ FABulous start # Run Fabulous interactive shell for demo project

# In the FABulous shell
FABulous> load_fabric
FABulous> run_FABulous_fabric
FABulous> run_FABulous_bitstream ./user_design/sequential_16bit_en.v
FABulous> exit

To run a simulation of a test bitstream on the design with Icarus Verilog:

(venv)$ cd demo/Test
(venv)$ make sim

The tool also supports using TCL script to drive the build process. Assuming you have created a demo project using (venv)$ FABulous c demo, you can call (venv)$ FABulous -p ./demo script ./demo/FABulous.tcl to run the demo flow with the TCL interface.

Using uv (optional)

If you have uv installed (see Prerequisites section), you can use it for faster dependency management and automatic virtual environment handling:

git clone https://github.com/FPGA-Research/FABulous
cd FABulous
uv sync                    # Install dependencies and create virtual environment
uv pip install -e .       # Install FABulous in editable mode

Running FABulous with uv:

uv run FABulous c demo    # Create a demo project
cd demo
uv run FABulous start       # Run FABulous interactive shell

# Or activate the environment and run directly:
source .venv/bin/activate
(venv)$ FABulous c demo
(venv)$ cd demo
(venv)$ FABulous start

Benefits of using uv:

• No need to manually create/manage virtual environments
• Faster dependency installation
• Automatic dependency resolution and locking
• Consistent environments across different machines

More details on bitstream generation can be found here.

Detailed documentation for the project can be found here

GUI Setup

FABulator supports exploration of fabrics generated by FABulous, as well as displaying user designs.

to import a fabric into FABulator, a geometry file for the fabric is needed. This can be generated by running

FABulous> load_fabric
FABulous> gen_fabric      # only needed once to generate matrix.csv files
FABulous> gen_geometry

in the FABulous shell. This file can then be imported into FABulator. More information can be found here.

Contribution Guidelines

For comprehensive development information including environment setup, coding standards, and contribution workflows, please see our Development Guide.

Quick Reference for Contributors:

• Use uv for development environment setup
• Follow Ruff formatting and linting standards
• Use conventional commits for commit messages
• Ensure all tests pass and CI checks succeed

Quick Setup:

curl -LsSf https://astral.sh/uv/install.sh | sh  # Install uv
git clone https://github.com/FPGA-Research/FABulous
cd FABulous
uv sync --dev
uv pip install -e .
uv run pre-commit install

By contributing to this project, you agree that your contributions will be licensed under the project's License.

How to cite

The following paper can be used to cite FABulous:

Dirk Koch, Nguyen Dao, Bea Healy, Jing Yu, and Andrew Attwood. 2021. FABulous: An Embedded FPGA Framework. In The 2021 ACM/SIGDA International Symposium on Field-Programmable Gate Arrays (FPGA '21). Association for Computing Machinery, New York, NY, USA, 45–56. DOI: https://doi.org/10.1145/3431920.3439302

Link to Paper

@inproceedings{koch2021fabulous,
  title={FABulous: An embedded FPGA framework},
  author={Koch, Dirk and Dao, Nguyen and Healy, Bea and Yu, Jing and Attwood, Andrew},
  booktitle={The 2021 ACM/SIGDA International Symposium on Field-Programmable Gate Arrays},
  pages={45--56},
  year={2021}
}

Disclaimer and Limitation of Liability

IMPORTANT: READ CAREFULLY BEFORE USING THIS SOFTWARE

This software is provided AS IS” without any express or implied warranty. In no event shall the authors, contributors, copyright holders, or affiliated institutions be liable for any claims, damages, or other liabilities.

IP Generation and ASIC/FPGA Fabrication

FABulous is an IP generator framework that produces HDL designs for embedded FPGA fabrics intended for ASIC fabrication. Users of this software acknowledge and agree that:

1. No Liability for Generated IP: The developers and contributors assume no responsibility or liability for any intellectual property (IP) generated using this framework, including but not limited to HDL code, netlists, GDSII files, or any other design artifacts.

2. No Liability for Fabricated Products: We are not responsible for any chips, ASICs, FPGAs, or any physical devices fabricated using IP generated by this framework. This includes but is not limited to:

   • Design errors, bugs, or defects in generated IP
   • Manufacturing defects or yield issues
   • Functional failures or performance issues
   • Timing violations or signal integrity problems
   • Power consumption or thermal issues
   • Any damages or losses resulting from the use of fabricated devices

3. No Warranty of Correctness: While constant efforts are being made to create reliable tools, we make no guarantees regarding the correctness, reliability, or suitability of generated IP for any specific purpose, including but not limited to:

   • Functional correctness of generated HDL
   • Timing closure or synthesis results
   • Physical design or layout quality
   • Compliance with any manufacturing process or design rules

   IMPORTANT: Silicon proven status does NOT imply that FABulous-generated designs can be used without thorough verification. Users MUST perform comprehensive whole-system verification, including timing-annotated simulation and formal verification, to ensure the generated fabric works correctly for their specific circuit and application requirements. Previous successful tapeouts do not guarantee functionality for new designs or configurations.

4. User Responsibility: Users are solely responsible for:

   • Verification and validation of all generated IP
   • Testing and qualification of designs before fabrication
   • Ensuring compliance with applicable standards and regulations
   • Any consequences of using designs generated by this framework

Use at Your Own Risk

By using this software, you acknowledge that you have read this disclaimer, understand it, and agree to be bound by its terms. You accept full responsibility for any use of this software and any IP or products derived from it.

For the complete license terms, see the Apache 2.0 License.