Skip to content

finn.builder

Jump to bottom
GitHub Action edited this page May 28, 2026 · 13 revisions

This page contains the complete API reference for all modules in the finn.builder package.

Table of Contents

finn.builder.build_dataflow

FINN dataflow build system.

This module provides the main build infrastructure for converting ONNX models to FINN dataflow accelerators. It handles step resolution, logging, error handling, and the complete build pipeline from ONNX input to hardware accelerator output.

get_logfile_path

def get_logfile_path(cfg: DataflowBuildConfig) -> str

Return the path to the logfile in the build dir.

PrintLogger Objects

class PrintLogger()

Custom stream handler that writes to both console and log file with timestamps.

__init__

def __init__(logger: logging.Logger, level: int,
             originalstream: TextIO | Any) -> None

Initialize the print logger with logger, level, and original stream.

write

def write(buf: str) -> None

Write buffer content to both logger and console with timestamp.

flush

def flush() -> None

Flush the console stream.

resolve_build_steps

def resolve_build_steps(cfg: DataflowBuildConfig,
                        partial: bool = True) -> list[BuildStep]

Resolve build step names to callable functions.

Converts string step names to callable functions by looking up in the step registry, importing from modules, or using direct callable objects. Supports partial execution between start_step and stop_step if specified in config.

Arguments:

  • cfg - Build configuration containing step definitions
  • partial - If True, respect start_step/stop_step boundaries

Returns:

List of callable step functions ready for execution

resolve_step_filename

def resolve_step_filename(step_name: str,
                          cfg: DataflowBuildConfig,
                          step_delta: int = 0) -> Path

Resolve the intermediate model filename for a given build step.

Arguments:

  • step_name - Name of the build step
  • cfg - Build configuration
  • step_delta - Offset from the step (0=current, -1=previous, +1=next)

Returns:

Path to the intermediate model file for the specified step

setup_logging

def setup_logging(cfg: DataflowBuildConfig) -> logging.Logger

Configure logging for the build process.

Sets up file logging, console mirroring, and rich console handlers based on the build configuration settings.

Arguments:

  • cfg - Build configuration with logging settings

Returns:

Configured logger instance

exit_buildflow

def exit_buildflow(cfg: DataflowBuildConfig,
                   time_per_step: dict[str, float] | None = None,
                   exit_code: int = 0) -> int

Create metadata_builder.json and time_per_step.json files with build results.

Arguments:

  • cfg - Build configuration
  • time_per_step - Dictionary of step execution times
  • exit_code - Build exit code (0=success, non-zero=failure)

Returns:

The provided exit code

create_model_wrapper

def create_model_wrapper(model_filename: str,
                         cfg: DataflowBuildConfig) -> ModelWrapper

Create a modelwrapper from the given config and filename. If a start-step is given, the ModelWrapper is constructed from a previous intermediate model.

build_dataflow_cfg

def build_dataflow_cfg(model_filename: str, cfg: DataflowBuildConfig) -> int

Build a dataflow accelerator using the given configuration.

Main entry point for building FINN dataflow accelerators. Handles step execution, logging, error handling, and intermediate model saving.

Arguments:

  • model_filename - ONNX model filename to build
  • cfg - Build configuration specifying steps and options

Returns:

Exit code (0=success, non-zero=failure)

finn.builder.build_dataflow_config

This module contains the DataflowBuildConfig class and related functionality for configuring FINN+ dataflow builds.

📖 For detailed documentation, please visit: DataflowBuildConfig Documentation

finn.builder.build_dataflow_steps

Collection of default build steps for building and verifying a dataflow accelerator from an ONNX model.

verify_step

def verify_step(model: ModelWrapper,
                cfg: DataflowBuildConfig,
                step_name: str,
                need_parent: bool,
                rtlsim_pre_hook=None)

Verify a build step by running simulation and comparing results.

Arguments:

  • model - The ONNX model to verify
  • cfg - Build configuration object
  • step_name - Name of the build step being verified
  • need_parent - Whether parent model execution is needed for comparison
  • rtlsim_pre_hook - Optional pre-hook function for RTL simulation

prepare_for_stitched_ip_rtlsim

def prepare_for_stitched_ip_rtlsim(verify_model, cfg)

Prepare model for stitched IP RTL simulation.

Switches implementation styles from Vivado components to RTL where needed and ensures proper configuration for RTL simulation.

Arguments:

  • verify_model - The model to prepare for RTL simulation
  • cfg - Build configuration object

step_qonnx_to_finn

def step_qonnx_to_finn(model: ModelWrapper, cfg: DataflowBuildConfig)

This step will only execute if QONNX nodes are found. These include the following op_types: "Quant" , "Trunc" and "BinaryQuant". If such nodes are found the step will run the tidy-up step from QONNX and then convert the QONNX model to the FINN-ONNX dialect.

step_tidy_up

def step_tidy_up(model: ModelWrapper, cfg: DataflowBuildConfig)

Run the tidy-up step on given model. This includes shape and datatype inference, constant folding, and giving nodes and tensors better names.

step_streamline

def step_streamline(model: ModelWrapper, cfg: DataflowBuildConfig)

Run streamlining on given model. Streamlining involves moving floating point scale/shift parameters around, collapsing adjacent ones into a single parameter, then absorbing the scale/shift into the following MultiThreshold node. Streamlining requires careful topology design and cannot be applied to all topologies.

step_convert_to_hw

def step_convert_to_hw(model: ModelWrapper, cfg: DataflowBuildConfig)

Convert eligible nodes to HWCustomOp subclasses that represent HW layers. Which nodes and particular configurations can be converted to HW is limited, see the source code of the convert_to_hw module for more. In the end an empty json file is created which can be used to set user specific preferred implementation styles for each node.

step_create_dataflow_partition

def step_create_dataflow_partition(model: ModelWrapper,
                                   cfg: DataflowBuildConfig)

Separate consecutive groups of HWCustomOp nodes into StreamingDataflowPartition nodes, which point to a separate ONNX file. Dataflow accelerator synthesis can only be performed on those HWCustomOp sub-graphs.

step_specialize_layers

def step_specialize_layers(model: ModelWrapper, cfg: DataflowBuildConfig)

Convert HW nodes to either an HLS or RTL variant of the node. HW nodes get converted either based on pre-determined rules (details can be found in specialize_layers source code) or the user provides a configuration file which contains the desired setting. If the user preference cannot be fulfilled, a warning will be printed and the implementation style will be set to a default.

step_transpose_decomposition

def step_transpose_decomposition(model: ModelWrapper,
                                 cfg: DataflowBuildConfig)

Decomposes a Shuffle into a chain of InnerShuffle and OuterShuffles that can be specialised into hardware operators. This should be executed after the folding has been configured.

step_target_fps_parallelization

def step_target_fps_parallelization(model: ModelWrapper,
                                    cfg: DataflowBuildConfig)

If target_fps was specified, use the SetFolding transformation to determine parallelization attributes. The auto-generated config will be saved under auto_folding_config.json under the outputs, which can serve as a basis for customizing the folding factors further.

step_apply_folding_config

def step_apply_folding_config(model: ModelWrapper, cfg: DataflowBuildConfig)

Apply the folding configuration file onto the model to set folding (parallelization) and other attributes, if config file is specified.

step_generate_estimate_reports

def step_generate_estimate_reports(model: ModelWrapper,
                                   cfg: DataflowBuildConfig)

Generate per-layer resource and cycle estimates using analytical models.

step_minimize_bit_width

def step_minimize_bit_width(model: ModelWrapper, cfg: DataflowBuildConfig)

Tighten the weight and accumulator bit widths for each layer.

step_hw_codegen

def step_hw_codegen(model: ModelWrapper, cfg: DataflowBuildConfig)

Generate Vitis HLS code to prepare HLSBackend nodes for IP generation. And fills RTL templates for RTLBackend nodes.

step_hw_ipgen

def step_hw_ipgen(model: ModelWrapper, cfg: DataflowBuildConfig)

Run Vitis HLS synthesis on generated code for HLSBackend nodes, in order to generate IP blocks. For RTL nodes this step does not do anything.

step_insert_dwc

def step_insert_dwc(model: ModelWrapper, cfg: DataflowBuildConfig)

Inserts data width converters between layers where necessary.

step_set_fifo_depths

def step_set_fifo_depths(model: ModelWrapper, cfg: DataflowBuildConfig)

Depending on the auto_fifo_depths setting, do one of the following:

  • if auto_fifo_depths=True: Run the appropriate auto-sizing transformation to attempt to determine the FIFO sizes that provide full throughput. May take a long time.
  • if auto_fifo_depths=False: Assume the folding config file contains FIFO sizes as well. Runs the InsertFIFO transformation, then ApplyConfig(cfg.folding_config_file), and finally RemoveShallowFIFOs. Coherency with config file node naming is ensured by calling GiveUniqueNodeNames.

step_create_stitched_ip

def step_create_stitched_ip(model: ModelWrapper, cfg: DataflowBuildConfig)

Create stitched IP for a graph after all HLS IP blocks have been generated. Depends on the DataflowOutputType.STITCHED_IP output product.

step_measure_rtlsim_performance

def step_measure_rtlsim_performance(model: ModelWrapper,
                                    cfg: DataflowBuildConfig)

Measure performance + latency of stitched-IP model in rtlsim (xsi). Depends on the DataflowOutputType.STITCHED_IP output product.

step_make_driver

def step_make_driver(model: ModelWrapper, cfg: DataflowBuildConfig)

Create a driver that can be used to interface the generated accelerator. Use DataflowBuildConfig to select PYNQ Python or C++ driver.

step_out_of_context_synthesis

def step_out_of_context_synthesis(model: ModelWrapper,
                                  cfg: DataflowBuildConfig)

Run out-of-context synthesis and generate reports. Depends on the DataflowOutputType.STITCHED_IP output product.

step_vivado_power_estimation

def step_vivado_power_estimation(model: ModelWrapper,
                                 cfg: DataflowBuildConfig)

Run Vivado power estimation on the stitched IP after OOC synthesis.

step_synthesize_bitfile

def step_synthesize_bitfile(model: ModelWrapper, cfg: DataflowBuildConfig)

Synthesize a bitfile for the using the specified shell flow, using either Vivado or Vitis, to target the specified board.

step_deployment_package

def step_deployment_package(model: ModelWrapper, cfg: DataflowBuildConfig)

Create a deployment package including the driver and bitfile.

step_loop_rolling

def step_loop_rolling(model, cfg)

Roll a repeating sequence of layers into a loop. PyTorch metadata node hierarchy is used to indicate the loop structure.

build_dataflow_step_lookup

map step name strings to step functions

finn.builder.custom_step_library.resnet

Custom build steps for ResNet model processing.

This module provides specialized transformation steps for converting quantized ResNet models from QONNX format through various stages of optimization and hardware conversion.

step_resnet_tidy

def step_resnet_tidy(model: ModelWrapper,
                     cfg: DataflowBuildConfig) -> ModelWrapper

Tidy up ResNet models.

step_resnet_streamline

def step_resnet_streamline(model: ModelWrapper,
                           cfg: DataflowBuildConfig) -> ModelWrapper

Streamline ResNet models.

step_resnet_convert_to_hw

def step_resnet_convert_to_hw(model: ModelWrapper,
                              cfg: DataflowBuildConfig) -> ModelWrapper

Convert ResNet models to hardware-specific operations.

step_resnet50_tidy

def step_resnet50_tidy(model: ModelWrapper, cfg: DataflowBuildConfig)

Tidy up ResNet-50 models (backwards-compatible legacy step).

Applies shape and datatype inference, constant folding, unique naming, and inserts a TopK layer at the output.

step_resnet50_streamline_linear

def step_resnet50_streamline_linear(model: ModelWrapper,
                                    cfg: DataflowBuildConfig)

Apply linear streamlining transformations to a ResNet-50 model.

Moves and absorbs scalar linear operations (mul, add) past convolutions and matrix multiplications, collapses repeated operations, converts sign nodes to thresholds, and absorbs values into multithreshold nodes.

step_resnet50_streamline_nonlinear

def step_resnet50_streamline_nonlinear(model: ModelWrapper,
                                       cfg: DataflowBuildConfig)

Apply non-linear streamlining transformations to a ResNet-50 model.

Moves linear operations past elementwise-add nodes and fork points to enable further fusion in subsequent linear streamlining passes.

step_resnet50_streamline

def step_resnet50_streamline(model: ModelWrapper, cfg: DataflowBuildConfig)

Streamline a ResNet-50 model (backwards-compatible legacy step).

Iterates linear and non-linear streamlining passes, then lowers convolutions to matrix multiplications and absorbs the resulting transpose operations.

step_resnet50_convert_to_hw

def step_resnet50_convert_to_hw(model: ModelWrapper, cfg: DataflowBuildConfig)

Convert a ResNet-50 model to hardware-specific operations (backwards-compatible legacy step).

Sets the input datatype to UINT8, then sequentially converts channelwise linear layers, pooling, matrix-vector activations, thresholding, convolution input generators, stream duplication/addition, and label selection to their corresponding HLS hardware layer variants.

finn.builder.custom_step_library.transformer_adhoc

Ad-hoc build steps for transformer models, covering hardware conversion and folding configuration for operators not yet handled by the standard FINN pipeline, in particular scaled dot-product attention.

step_convert_to_hw

def step_convert_to_hw(model: ModelWrapper,
                       cfg: DataflowBuildConfig) -> ModelWrapper

Convert a streamlined transformer ONNX model to FINN hardware operators.

Applies the full sequence of hardware-conversion transformations, including split/concat infrastructure, pooling, convolution input generation, fused scaled dot-product attention, MVAUs/VVAUs, thresholding, lookup layers, and elementwise binary operators. A cleanup pass (type/shape inference, unique node naming) is executed at the end.

Arguments:

  • model - QONNX ModelWrapper of the streamlined model to convert.
  • cfg - FINN DataflowBuildConfig controlling optional steps such as standalone_thresholds.

Returns:

The transformed ModelWrapper with all supported operators replaced by FINN HW custom-ops.

step_set_folding

def step_set_folding(model: ModelWrapper,
                     cfg: DataflowBuildConfig) -> ModelWrapper

Configure the folding (parallelism) of all dataflow operators in model.

When cfg specifies a throughput target the function first applies _set_folding_attention for attention operators and then FINN's SetFolding for the remaining operators. An optional two-pass relaxation step re-runs attention folding at the cycle count of the identified bottleneck. When only a folding_config_file is provided (no FPS target), the config is applied directly without any auto-folding.

After auto-folding, the resolved configuration is written to <output_dir>/auto_folding_config.yaml. If cfg.folding_config_file is also set its entries are applied on top to override resource-style defaults (mem_mode, ram_style, etc.).

Arguments:

  • model - ModelWrapper containing the dataflow graph.
  • cfg - FINN DataflowBuildConfig with throughput targets and optional folding overrides.

Returns:

The ModelWrapper with folding attributes fully configured.

Raises:

  • FINNUserError - If neither a throughput target nor a folding config file is provided.

finn.builder.passes

Integrates ONNX Passes and ONNX Script passes into the FINN build steps.

prepare

def prepare(model: ModelWrapper, cfg: DataflowBuildConfig) -> ModelWrapper

Prepares a model to be processed by ONNX Passes.

inline

def inline(model: ModelWrapper, cfg: DataflowBuildConfig) -> ModelWrapper

Applies ONNX Passes inlining transformations.

streamline

def streamline(model: ModelWrapper, cfg: DataflowBuildConfig) -> ModelWrapper

Applies ONNX Passes streamlining transformations.

_ExportThresholdsToFINN Objects

class _ExportThresholdsToFINN(Transformation, RewriteRulePass)

Exports MultiThreshold representation from ONNX Passes to FINN format.

pattern

def pattern(op, x, thresholds, weights)

Target pattern to match.

check

def check(op, x, thresholds, weights)

Match condition.

rewrite

def rewrite(op, x, thresholds, weights)

Replacement pattern.

_ExportIm2ColToFINN Objects

class _ExportIm2ColToFINN(Transformation, RewriteRulePass)

Exports Im2Col representation from ONNX Passes to FINN format.

pattern

def pattern(op, x, indices, dilations, kernel_shape, strides)

Target pattern to match.

check

def check(op, x, indices, dilations, kernel_shape, strides)

Match condition.

rewrite

def rewrite(op, x, indices, dilations, kernel_shape, strides)

Replacement pattern.

export

def export(model: ModelWrapper, cfg: DataflowBuildConfig) -> ModelWrapper

Converts the model back to the FINN compatible format.

step_passes_frontend

def step_passes_frontend(model: ModelWrapper, cfg: DataflowBuildConfig)

Meta build step calling the ONNX Passes steps in the expected order.

📚 Navigation: ← Back to API Documentation

This page was generated automatically from source code documentation.

FINN+ Wiki

🏠 Home

🚀 Getting Started

📖 User Guide

🛠️ Development

📋 Quick Reference

🔗 External Links

Clone this wiki locally