FPGA Arch Explorer

FPGA Arch Explorer is an integrated FPGA architecture exploration framework based on COFFE, VTR and SHAP-guided design-space exploration. It supports three parts of the workflow:

• generating FPGA architecture XMLs with COFFE;
• evaluating FPGA architectures with VTR and Koios benchmarks;
• running DSE with two SHAP-guided methods.

The COFFE source tree is maintained in the repository. VTR is pinned as a Git submodule, while the project Koios workloads and VTR task helper are maintained under vtr/.

Repository contents

Component	Purpose	Main location
COFFE	Architecture characterization and architecture XML generation	COFFE/
VTR	Architecture evaluation through synthesis, packing, placement and routing	vtr-verilog-to-routing/
Koios benchmark	Verilog HDL benchmarks for architecture evaluation	vtr/vtr_flow/benchmarks/verilog/koios/
DSE	FPGA architecture exploration with two SHAP-guided methods	dse/

The pinned upstream revisions and VTR nested submodules are recorded in deps.lock.json. Detailed build and dependency notes are in dependencies.md.

End-to-end workflow

COFFE flow
        |
        v
Architecture XMLs + manifest.csv
        |
        v
VTR flow with Koios benchmarks
        |
        v
Area and delay results
        |
        v
SHAP-guided DSE

1. Generate architecture XMLs with COFFE

The COFFE flow characterizes FPGA components and generates an architecture XML from architecture parameters and an architecture template. The extensions cover FPGA component and routing characterization, architecture XML generation for configurable blocks, layout and interconnect structures, hard-block modeling, layout analysis and architecture collection.

Generate an architecture collection from the included 22 nm architecture template and the routing, PE-array, BRAM and DSP characterization data:

python COFFE/scripts/arch_collect.py \
  --output-root /path/to/architecture-collection \
  --run-name example \
  --mode random \
  --count 10 \
  --dry-run

--dry-run validates the parameter expansion and command construction. Remove it to run COFFE. A completed collection contains per-architecture YAML inputs, generated architecture XMLs and manifest.csv; the manifest is the handoff to the VTR flow.

The PE-array characterization flow is separate. Its .yaml.in templates use the Nangate 45 nm standard-cell flow and scale the resulting area and frequency metrics to the 22 nm architecture model. To rerun this characterization, obtain the Nangate PDK, accept its license and point the renderer to the directory containing Front_End/ and Back_End/:

export NANGATE_PDK_ROOT=/licensed/path/NangateOpenCellLibrary_PDK

python COFFE/scripts/pe_array_modeling/render_pe_configs.py \
  --output-root /path/to/pe-modeling-run

The repository does not provide Nangate PDK files. The rendered YAMLs are inputs to COFFE/scripts/pe_array_modeling/run_pe_modeling.py. To use a customized PE array in generated architecture XMLs, record its scaled area and delay in a characterization file following the included COFFE/input_files/tensor_slice/pe_array_sweep/pe_array_arch_characterization.json schema, then pass that file to the architecture collection flow:

python COFFE/scripts/arch_collect.py \
  --pe-array-char-file /path/to/pe_array_arch_characterization.json \
  --output-root /path/to/custom-architecture-collection \
  --run-name example \
  --mode random --count 10 --dry-run

The architecture XML generator reads PE-array dimensions, area and delay from this characterization file; the included characterization supplies the default values.

Routing, BRAM and DSP characterization have corresponding inputs and scripts:

• COFFE/scripts/characterize_routing_segments.py produces routing switch and wire characterization for the architecture XML generator;
• COFFE/scripts/bram_modeling/ renders and runs the 16, 32 and 64 Kb BRAM characterization inputs; 20 and 40 Kb values are interpolated by the loader;
• COFFE/scripts/dsp_modeling/ renders and runs the floating-point and fixed-point DSP hard-block inputs and converts their reports into a DSP characterization file.

Use arch_collect.py --routing-char-file, --pe-array-char-file, --bram-char-file and --dsp-char-file to generate architecture XMLs with custom characterization. The detailed commands and tool requirements are in dependencies.md.

2. Evaluate FPGA architectures with VTR

Initialize the official VTR submodule and its nested dependencies:

git submodule update --init --recursive

Then build VTR from the repository root:

cmake -S vtr-verilog-to-routing -B vtr-verilog-to-routing/build \
  -DVPR_USE_EZGL=off -DVPR_USE_SERVER=OFF
cmake --build vtr-verilog-to-routing/build -j
vtr-verilog-to-routing/build/vpr/vpr --version

The project VTR tree contains the selected no-PE Koios benchmarks and PE-array benchmark variants for the 4x4, 8x4 and 8x8 PE arrays. Matching SDC files are under vtr/vtr_flow/sdc/koios. The VTR submodule supplies Parmys, VPR and the supporting flow tools. Verify reproducible variant generation with:

python vtr/vtr_flow/benchmarks/verilog/koios/tensor_slice_variants/verify_tensor_slice_variants.py

Use the COFFE manifest to prepare and run a VTR task across the generated architecture XMLs. Repeat --circuit to include more benchmarks:

python vtr/vtr_flow/scripts/run_arch_sweep.py \
  --manifest /path/to/architecture-collection/manifest.csv \
  --task-name tensor_slice_sweep \
  --circuit attention_layer.pe4x4.int16.tensor_slice.v \
  --jobs 4

The helper creates a VTR task, evaluates the selected architecture and benchmark combinations, and invokes VTR's result parsers. Use --prepare-only to inspect the generated task configuration, or --parse-only to parse an existing run. The benchmark's PE-array size must be compatible with the hard block described by the selected architecture XML.

3. Prepare the DSE input

The COFFE manifest identifies each architecture and its twelve design parameters. VTR produces the corresponding area and delay results. Before using the current DSE implementation, join those records and apply one consistent aggregation and area/delay definition across every architecture design.

The resulting CSV must contain one unique row for each architecture design with these columns:

arch_name,n,k,fclocal,sarray,sram,layout,fill,asp,lmix,fcin,fcout,sb,area,delay

area and delay must be finite and strictly positive. Store generated input data in the working directory selected for the experiment.

4. Run DSE

Install the Python package:

python -m pip install -e .

Then run one method and initialization strategy per invocation:

fpga-arch-explore \
  --method shap-domain \
  --init sobol \
  --seed 101 \
  --dataset /path/to/candidates.csv \
  --result-root /path/to/results/shap-domain-sobol

The two supported SHAP-guided methods are:

• shap-domain, which applies domain contraction;
• shap-density, which applies density shaping.

Both methods use the same hypervolume-aware TPE backbone and support random and sobol initialization. Each run writes evaluations.csv, metrics.csv, pareto.csv, summary.json, metadata.json and Pareto-front plots directly under --result-root. Use a different result directory for every method and initialization combination.

The CLI is also available as python -m dse. Run fpga-arch-explore --help for the complete parameter list.

Reproducibility and generated data

• VTR is pinned to v9.0.0 commit 8cb20aa5293b5ce5f6a05c88b37b38e1305d9b07.
• COFFE is based on commit 098710234df938655ff3e9261434c46d4f5b3990 plus the architecture and characterization changes maintained here.
• COFFE provenance is documented in COFFE/VENDORED_PROVENANCE.md.

License and third-party content

Original FPGA Arch Explorer code is licensed under the MIT License. VTR, Koios, COFFE and other derived or third-party content retain their respective terms. See THIRD_PARTY_NOTICES.md before redistributing or publishing derived artifacts.