# fpga-research/fabulous architecture

> Architecture diagram of the GitHub repository fpga-research/fabulous, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fpga-research/fabulous
- Repository: https://github.com/fpga-research/fabulous

## Overview

##### Project type and purpose
- FABulous is an open-source Python-based FPGA fabric generation framework and toolchain.
- It provides a CLI for orchestrating a modular pipeline that:
- parses a CSV fabric definition and tile templates
- generates HDL/VHDL fabric models and project metadata
- invokes external CAD tools (Yosys, nextpnr or VPR) to produce bitstreams
- produces simulation test benches and a geometry file for FABulator.

##### File structure
- Top level:
- FABulous.py – CLI entry point
- fabric_generator/ – core code-generation modules (file_parser, code_generator, model_generation)
- geometry_generator/ – modules to extract fabric geometry
- fabric_cad/ – TCL and Python scripts for mapping primitives and driving synthesis flows
- fabric_files/ – HDL/VHDL templates & project skeletons for Verilog and VHDL
- docs/ – Sphinx documentation, figures, usage guides, build scripts
- Dockerfile & .github/workflows – CI for docs and automation
- Patterns:
- Orchestration layer (CLI) controls a sequence of pure-Python stages.
- Separation of “templates” vs “generator logic” vs “external tool adapters.”

##### Insights from the README
- Workflow steps in the shell:
1) load_fabric [fabric.csv]
2) run_FABulous_fabric → generates HDL, .FABulous metadata
3) run_FABulous_bitstream npnr/VPR → calls CAD toolchain to produce a bitstream
4) gen_geometry → emits a CSV/JSON geometry file for FABulator
5) exit
- Supports both interactive shell and TCL‐driven batch mode.
- Emulation path uses Icarus Verilog for test simulation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    CLI[/FABulous CLI/]:::ui
    click CLI "https://github.com/fpga-research/fabulous/blob/master/FABulous.py"

    %% Data Stores
    CSV((fabric.csv)):::data
    META((.FABulous metadata)):::data

    %% Fabric Generator Layer
    subgraph "Fabric Generator (Python Modules)"
        ORC["Orchestration Entry Point<br/>(fabric_gen)"]:::python
        click ORC "https://github.com/fpga-research/fabulous/blob/master/fabric_generator/fabric_gen.py"
        FP["File Parser"]:::python
        click FP "https://github.com/fpga-research/fabulous/blob/master/fabric_generator/file_parser.py"
        FM["Fabric Definition Model"]:::python
        click FM "https://github.com/fpga-research/fabulous/blob/master/fabric_generator/fabric.py"
        UTIL["Utilities"]:::python
        click UTIL "https://github.com/fpga-research/fabulous/blob/master/fabric_generator/utilities.py"
        CGH["Codegen Helpers"]:::python
        click CGH "https://github.com/fpga-research/fabulous/blob/master/fabric_generator/code_generator.py"
        VG["Verilog Code Generator"]:::python
        click VG "https://github.com/fpga-research/fabulous/blob/master/fabric_generator/code_generation_Verilog.py"
        HG["VHDL Code Generator"]:::python
        click HG "https://github.com/fpga-research/fabulous/blob/master/fabric_generator/code_generation_VHDL.py"
        NPnR["NPnR Model Generator"]:::python
        click NPnR "https://github.com/fpga-research/fabulous/blob/master/fabric_generator/model_generation_npnr.py"
        VPR["VPR Model Generator"]:::python
        click VPR "https://github.com/fpga-research/fabulous/blob/master/fabric_generator/model_generation_vpr.py"
    end

    %% Template Storage
    subgraph "HDL/VHDL Templates" 
        TPL1["Verilog Templates"]:::template
        TPL2["VHDL Templates"]:::template
        click TPL1 "https://github.com/fpga-research/fabulous/tree/master/fabric_files/"
        click TPL2 "https://github.com/fpga-research/fabulous/tree/master/fabric_files/"
        TOP["Top-Level Wrapper Templates"]:::template
        click TOP "https://github.com/fpga-research/fabulous/tree/master/fabric_generator/fabulous_top_wrapper_temp/"
    end

    %% Geometry Generator Layer
    subgraph "Geometry Generator"
        GG["Geometry Controller"]:::python
        click GG "https://github.com/fpga-research/fabulous/blob/master/geometry_generator/geometry_gen.py"
    end

    %% CAD Integration Layer
    subgraph "CAD Integration"
        BG["Bitstream Driver"]:::python
        click BG "https://github.com/fpga-research/fabulous/blob/master/fabric_cad/bit_gen.py"
        TCL["Synthesis TCL Scripts"]:::python
        click TCL "https://github.com/fpga-research/fabulous/tree/master/fabric_cad/synth/"
    end

    %% External Tools
    subgraph "External Tools"
        YOS["Yosys"]:::external
        NPN["nextpnr-generic"]:::external
        VPR_EX["VPR"]:::external
        IV["Icarus Verilog"]:::external
    end

    %% Artifacts
    subgraph "Generated Artifacts"
        HDL["Generated HDL/VHDL"]:::artifact
        BIT["Bitstream"]:::artifact
        SIMTB["Simulation Testbenches"]:::artifact
        GEO["Geometry CSV/JSON"]:::artifact
    end

    %% Documentation & CI/CD
    subgraph "Docs & CI/CD"
        DOCS["Sphinx Documentation"]:::docs
        click DOCS "https://github.com/fpga-research/fabulous/tree/master/docs/"
        CI1["Build Docs Workflow"]:::docs
        click CI1 "https://github.com/fpga-research/fabulous/blob/master/.github/workflows/build_docs.yml"
        CI2["Fabric Gen Workflow"]:::docs
        click CI2 "https://github.com/fpga-research/fabulous/blob/master/.github/workflows/fabric_gen.yml"
        DOCK["Dockerfile"]:::docs
        click DOCK "https://github.com/fpga-research/fabulous/tree/master/Dockerfile"
    end

    %% Flows
    CLI -->|"load_fabric"| CSV
    CLI -->|"run_FABulous_fabric"| ORC
    ORC --> FP
    FP --> FM
    FM --> CGH
    CGH --> VG
    CGH --> HG
    VG -->|uses templates| TPL1
    HG -->|uses templates| TPL2
    VG --> HDL
    HG --> HDL
    ORC --> NPnR
    NPnR --> BG
    ORC --> VPR
    VPR --> BG
    BG --> TCL
    TCL --> YOS
    YOS --> NPN
    NPN --> BIT
    VPR_EX --> BIT
    ORC -->|generate TBs| SIMTB
    SIMTB --> IV
    ORC -->|"gen_geometry"| GG
    GG --> FM
    GG --> GEO

    %% Metadata Flow
    VG --> META
    HG --> META
    NPnR --> META
    VPR --> META

    %% Documentation & CI triggers
    DOCS -->|monitors| ORC
    DOCS -->|monitors| GG
    DOCS -->|monitors| FP
    CI1 -->|runs in| DOCK
    CI2 -->|runs in| DOCK

    %% Styles
    classDef python fill:#cce5ff,stroke:#4d9aff,color:#003366;
    classDef template fill:#d4edda,stroke:#28a745,color:#155724;
    classDef external fill:#fff3cd,stroke:#ffc107,color:#856404;
    classDef artifact fill:#e2e3e5,stroke:#6c757d,color:#343a40;
    classDef data fill:#f0f0f0,stroke:#999999,color:#333333;
    classDef ui fill:#e8eaf6,stroke:#3f51b5,color:#1a237e;
    classDef docs fill:#f5f5f5,stroke:#9e9e9e,color:#212121;
```
