Multi-FPGA Integration

.gitignore

@@ -107,7 +107,7 @@ MANIFEST
 /notebooks/end2end_example/**/*.onnx
 
 # downloaded dep repos
-/deps/
+deps/
 /finn_deps/
 
 # local test directories for benchmarking infrastructure

pyproject.toml

@@ -55,7 +55,7 @@ onnxruntime = "1.20.1"
 onnxscript = ">=0.6.2"                                # TODO: the onnx-passes installation will overwrite this version
 protobuf = "5.29.6"
 pyyaml = "~6.0.2"
-mip = "~1.13.0"
+mip = "1.17.0"
 cmake = "~4.0.3"
 brevitas = "0.12.1"
 qonnx = "1.0.0"
@@ -111,9 +111,14 @@ markers = [
     "bnn_pynq: mark tests that execute Pynq-Z1 BNN tests",
     "bnn_zcu104: mark tests that execute ZCU104 BNN tests",
     "analysis: mark tests that run analysis tests",
+    "multifpga: mark tests that run multifpga tests"
 ]
 norecursedirs = ["dist", "build", ".tox"]
 testpaths = "tests"
+filterwarnings = [
+    'ignore:Deprecated call to `pkg_resources:DeprecationWarning',
+    'ignore:pkg_resources is deprecated:DeprecationWarning'
+]
 
 [tool.isort]
 line_length = 100

src/finn/analysis/fpgadataflow/hls_synth_res_estimation.py

@@ -28,20 +28,24 @@
 import os
 import qonnx.custom_op.registry as registry
 import xml.etree.ElementTree as ET
+from qonnx.core.modelwrapper import ModelWrapper
 
 from finn.util.fpgadataflow import is_hls_node
 from finn.util.logging import log
 
 
-def hls_synth_res_estimation(model):
-    """Extracts the FPGA resource results from the Vitis HLS synthesis estimates.
+def hls_synth_res_estimation(model: ModelWrapper) -> dict[str, dict[str, int | float]]:
+    """Extract the FPGA resource results from the Vitis HLS synthesis estimates.
     Note that this analysis pass only works on nodes that have an HLS backend.
     Ensure that all nodes have unique names (by calling the GiveUniqueNodeNames
     transformation) prior to calling this analysis pass to ensure all nodes are
     visible in the results.
 
-    Returns {node name : resources_dict}."""
-
+    Returns
+    -------
+        `dict[str, dict[str, int | float]]`: Maps node names to resource dicts.
+            Result example: `res_estimation(...)["MVAU_hls_0"]["LUT"]`
+    """
     res_dict = {}
     for node in model.graph.node:
         if is_hls_node(node):

src/finn/analysis/fpgadataflow/res_estimation.py

@@ -27,23 +27,31 @@
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 import qonnx.custom_op.registry as registry
+from qonnx.core.modelwrapper import ModelWrapper
+from typing import TYPE_CHECKING, cast
 
 from finn.util.fpgadataflow import is_hls_node, is_rtl_node
 
+if TYPE_CHECKING:
+    from finn.custom_op.fpgadataflow.hwcustomop import HWCustomOp
 
-def res_estimation(model, fpgapart):
+
+def res_estimation(model: ModelWrapper, fpgapart: str) -> dict[str, dict[str, int | float]]:
     """Estimates the resources needed for the given model.
     Ensure that all nodes have unique names (by calling the GiveUniqueNodeNames
     transformation) prior to calling this analysis pass to ensure all nodes are
     visible in the results.
 
-    Returns {node name : resource estimation}."""
-
+    Returns
+    -------
+        `dict[str, dict[str, int | float]]`: Maps node names to resource dicts.
+            Result example: `res_estimation(...)["MVAU_hls_0"]["LUT"]`
+    """
     res_dict = {}
     for node in model.graph.node:
         if is_hls_node(node) or is_rtl_node(node):
             inst = registry.getCustomOp(node)
-            res_dict[node.name] = inst.node_res_estimation(fpgapart)
+            res_dict[node.name] = cast("HWCustomOp", inst).node_res_estimation(fpgapart)
 
     return res_dict
 

src/finn/builder/build_dataflow_config.py

@@ -50,6 +50,7 @@
 
 import logging
 import mashumaro.config
+import mip
 import numpy as np
 from dataclasses import dataclass, field
 from enum import Enum
@@ -167,6 +168,150 @@ class VerificationStepType(str, Enum):
     PASSES_FRONTEND = "passes_frontend"
 
 
+class MIPSolver(str, Enum):
+    """Solver type enum. Used for type hinting,
+    since `Literal[mip.CBC]` is currently not allowed.
+    """
+
+    CBC = mip.CBC
+    GUROBI = mip.GUROBI
+    HIGHS = mip.HIGHS
+
+
+class MFVerbosity(Enum):
+    """Verbosity levels for Multi-FPGA."""
+
+    NONE = 0
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    EXTRA_HIGH = 4
+
+
+class PartitioningStrategy(str, Enum):
+    """Multi-FPGA Partitioning strategy for the solver to use."""
+
+    # Strategy to partition based on the estimated resource
+    # utilization of the layers
+    RESOURCE_UTILIZATION = "resource_utilization"
+
+    # Partition based on the number of layers per device
+    # Much simpler but usable in case no estimates
+    # are available
+    LAYER_COUNT = "layer_count"
+
+
+class MFCommunicationKernel(str, Enum):
+    """Communication kernels for Multi-FPGA usage."""
+
+    AURORA = "aurora"
+
+
+class MFTopology(str, Enum):
+    """Topology for Multi-FPGA use."""
+
+    CHAIN = "chain"
+    RETURNCHAIN = "returnchain"
+    CIRCLE = "circle"
+
+
+@dataclass
+class PartitioningConfiguration:
+    """Configuration dataclass for Multi-FPGA. As soon as such a configuration is
+    set in the BuildDataflowConfig, FINN+ automatically switches to Multi-FPGA.
+    """
+
+    # Existing partitionings can either be loaded from a file or
+    # passed directly. If set to None, partitioning is done and the results are
+    # saved in the output dir instead.
+    partitioning: dict[str, int] | Path | None = None
+
+    # Custom partition constraints. This can be used to, for example,
+    # assign a specific layer to a specific device. Maps node names to device IDs.
+    # If `partitioning` is given, this is ignored.
+    # Keep in mind that if the custom constraints contradict implicit other
+    # model constraints, the model may become infeasible.
+    custom_partitioning_constraints: dict[str, int] = field(default_factory=dict)
+
+    # The number of FPGAs to use for Multi-FPGA
+    # TODO: Allow -1, etc.
+    num_fpgas: int = 0
+
+    # The number of ports per device - this might change in meaning,
+    # depending on the communication kernel used
+    # TODO: Should be moved into platforms.py
+    ports_per_device: int = 2
+
+    # What strategy to use to partition the dataflow graph
+    partition_strategy: PartitioningStrategy = PartitioningStrategy.RESOURCE_UTILIZATION
+
+    # Tells the flow what topology to use. This determines the transformation
+    # that creates the network metadata necessary for kernel packing
+    topology: MFTopology = MFTopology.CHAIN
+
+    # What kind of kernel is used to communicate in the network
+    communication_kernel: MFCommunicationKernel = MFCommunicationKernel.AURORA
+
+    # Arguments to pass along to the communication kernel. This can for example
+    # be used to configure specific details, such as a receiver FIFO depth or
+    # data encoding, etc.
+    # It is up to the kernel preparation transformation to interprete this data.
+    communication_kernel_arguments: dict[str, str] = field(default_factory=dict)
+
+    # If set to true, the partitioner considers only cuts in the model where a single concurrent
+    # stream is active. This results in a model that can be distributed across multiple devices,
+    # regardless of the number of network ports available. If set to False, the partitioner can
+    # cut anyhwere - this is more flexible and results in potentially more balanced designs, but
+    # requires that multiple data streams can be
+    # networked (either multiplexed/routed or over multiple ports).
+    single_stream_network: bool = True
+
+    # How much a FPGA can be utilized at max. The solver will fail if it
+    # cannot comply with this limitation. Since platforms.py seems to contain
+    # the numbers for the total resources without shell, the default value is kept
+    # on the lower side on purpose.
+    max_utilization: float = 0.80
+
+    # How much resources of a single FPGA should be used ideally. Used in some objective
+    # functions.
+    ideal_utilization: float = 0.70
+
+    # The list of resource types that the partitioner should consider.
+    # Only relevant if RESOURCE_UTILIZATION is chosen as a strategy
+    # TODO: Add HBM / DDR
+    considered_resources: list[str] = field(
+        default_factory=lambda: ["LUT", "FF", "DSP", "BRAM_18K"]
+    )
+
+    # Number of seconds before the solver doing the partitioning
+    # times out.
+    partition_solver_timeout: int = 100
+
+    # The solver to apply to the partitioning model. If left to None,
+    # the default `mip` solver is used, with CBC as a fallback.
+    partition_solver: Literal[MIPSolver.CBC, MIPSolver.GUROBI, MIPSolver.HIGHS] | None = None
+
+    # Search emphasis. Can be set to default for balanced results, or to OPTIMAL
+    # for optimal solutions or to FEASIBLE for quickly finding feasible solutions.
+    # Details can be found here: https://docs.python-mip.com/en/latest/classes.html
+    partition_solver_emphasis: mip.SearchEmphasis = mip.SearchEmphasis.DEFAULT
+
+    # Determines how many synthesis processes can run in parallel. Keep in mind
+    # that very roughly estimated, one synthesis should be able to use up to 100 GB RAM,
+    # (sometimes more) depending on the model and version of Vivado. For example on a
+    # 512 GB node, you can run roughly 4 Synthesis in parallel.
+    # Defaults to 1, in order not to crash local computers with OOM errors
+    parallel_synthesis_workers: int = 1
+
+    # Whether the IODMA kernels should be separate or part of the compute kernel SDP.
+    # Currently only for Multi-FPGFA!
+    separate_iodmas: bool = True
+
+    # Since the Multi-FPGA flow contains a large number of extra steps (+ information), it benefits
+    # from a verbosity setting that is independent of the general FINN one.
+    verbosity: MFVerbosity = MFVerbosity.MEDIUM
+
+
 #: List of steps that will be run as part of the standard dataflow build, in the
 #: specified order. Use the `steps` as part of build config to restrict which
 #: steps will be run.
@@ -324,7 +469,7 @@ def _fix_path(p: Path | None) -> Path | None:
 
     #: Which output(s) to generate from the build flow.  See documentation of
     #: DataflowOutputType for available options.
-    generate_outputs: Optional[list[DataflowOutputType]] = field(
+    generate_outputs: list[DataflowOutputType] = field(
         default_factory=lambda: [
             DataflowOutputType.STITCHED_IP,
             DataflowOutputType.ESTIMATE_REPORTS,
@@ -516,6 +661,9 @@ def _fix_path(p: Path | None) -> Path | None:
     #: Can be used to use host memory for input/output data instead of DDR or HBM memory
     fpga_memory: FpgaMemoryType = FpgaMemoryType.DEFAULT
 
+    #: Max interface width of the IODMAs for vitis builds.
+    vitis_iodma_intf_max_width: int = 512
+
     #: Whether intermediate ONNX files will be saved during the build process.
     #: These can be useful for debugging if the build fails.
     save_intermediate_models: bool = True
@@ -583,6 +731,10 @@ def _fix_path(p: Path | None) -> Path | None:
     #: rtlsim, otherwise they will be replaced by RTL implementations.
     rtlsim_use_vivado_comps: bool = True
 
+    #: Configuration that provides parameters for Multi-FPGA partitioning.
+    #: If set to something other than None, we assume the Multi-FPGA case
+    partitioning_configuration: Optional[PartitioningConfiguration] = None
+
     #: If set to True, the FINN compiler tries to create an MLO design based on
     #: loop_body_hierarchy and loop_body_range
     mlo: bool = False