Vitis Accelerator IP Flow

hls4ml/backends/__init__.py

@@ -8,12 +8,18 @@
 from hls4ml.backends.vivado_accelerator.vivado_accelerator_config import VivadoAcceleratorConfig  # noqa: F401
 
 from hls4ml.backends.catapult.catapult_backend import CatapultBackend  # isort: skip
-
 from hls4ml.backends.vitis.vitis_backend import VitisBackend  # isort: skip
+from hls4ml.backends.vitis_accelerator_ip_flow.vitis_accelerator_ip_flow_backend import (  # isort: skip
+    VitisAcceleratorIPFlowBackend,
+)
+from hls4ml.backends.vitis_accelerator_ip_flow.vitis_accelerator_ip_flow_config import (  # isort: skip  # noqa: F401
+    VitisAcceleratorIPFlowConfig,
+)
 
 register_backend('Vivado', VivadoBackend)
 register_backend('VivadoAccelerator', VivadoAcceleratorBackend)
 register_backend('Vitis', VitisBackend)
+register_backend('VitisAcceleratorIPFlow', VitisAcceleratorIPFlowBackend)
 register_backend('Quartus', QuartusBackend)
 register_backend('Catapult', CatapultBackend)
 register_backend('SymbolicExpression', SymbolicExpressionBackend)

hls4ml/backends/vitis_accelerator_ip_flow/passes/fifo_depth_optimization.py

@@ -0,0 +1,221 @@
+import json
+import os
+
+from hls4ml.model.optimizer.optimizer import ConfigurableOptimizerPass, ModelOptimizerPass
+
+
+def initialize_large_fifos(model, profiling_fifo_depth):
+    """Set all FIFO depths equal to a large value so that they can be profiled.
+
+    Args:
+        model (ModelGraph): The model to which FIFO depth optimization is applied.
+        profiling_fifo_depth (int): A large non-negative integer, must be larger than the max expected depth of the FIFOs.
+
+    Returns:
+        Dict[str, int]: A dictionary containing FIFO names as keys and their initial depths as values is returned for
+        comparison with the optimized depths.
+    """
+
+    # filter all the output variables and keep only the internal FIFOs, excluding output objects that are not FIFOs and the
+    # input and output FIFOs as they can't be profiled and are implementation dependant i.e AXI Stream, AXI Master or
+    # connected to another IP
+    vars_to_profile = {
+        output_variable_name: output_variable
+        for output_variable_name, output_variable in model.output_vars.items()
+        if ("VivadoStreamVariable" in str(type(output_variable)))
+        and output_variable != model.get_output_variables()[0]
+        and output_variable != model.get_input_variables()[0]
+    }
+
+    # initialize all the fifos to `profiling_fifo_depth` so that they will be automatically implemented in BRAMs and so
+    # they will be profiled. Alternatively, "config_dataflow -override_user_fifo_depth profiling_fifo_depth" can be
+    # used inside build_prj.tcl to override all FIFO depths with the specified value
+    initial_fifo_depths = {}
+    for output_variable in vars_to_profile.values():
+        if output_variable.pragma:
+            initial_fifo_depths[output_variable.name] = int(output_variable.pragma[1])
+            output_variable.pragma = (output_variable.pragma[0], profiling_fifo_depth)
+
+    inp = model.get_input_variables()[0]
+    initial_fifo_depths['in_local'] = int(inp.pragma[1])
+    inp.pragma = (inp.pragma[0], profiling_fifo_depth)
+
+    outp = model.get_output_variables()[0]
+    initial_fifo_depths['out_local'] = int(outp.pragma[1])
+    outp.pragma = (outp.pragma[0], profiling_fifo_depth)
+    return initial_fifo_depths
+
+
+def execute_cosim_to_profile_fifos(model):
+    """Execute a cosimulation with a testh bench that calls the top function - Vitis IP at **least twice**,
+    to properly profile the max FIFO depths. The function will momentarily replace the initial test bench
+    with a suitable one for the optimization, and after the optimizer pass, the original test bench reinitialized.
+
+    Args:
+        model (ModelGraph): The model to which FIFO depth optimization is applied.
+    """
+    model.write()
+
+    model.build(
+        reset=False,
+        csim=False,
+        synth=True,
+        cosim=True,
+        validation=False,
+        export=False,
+        vsynth=False,
+        fifo_opt=True,
+    )
+
+    return
+
+
+def get_vitis_optimized_fifo_depths(model):
+    """Parse the files generated by the cosimulation to retrieve the optimized depths for the FIFOs.
+    Attention, only the FIFOs between the layers are profiled!
+
+    Args:
+        model (ModelGraph): The model to which FIFO depth optimization is applied.
+
+    Returns:
+        Dict[str, int]: A dictionary that contains the FIFO names as keys and the optimized depths as values.
+    """
+    # channel.zip is generated after the cosimulation and contains the chan_status*.csv files
+    # in the chan_status*.csv files the max depth achieved during cosimulation can be found at the last (4th) line
+    path_to_zip_file = (
+        model.config.get_output_dir()
+        + "/"
+        + model.config.get_project_name()
+        + "_prj"
+        + "/solution1/.autopilot/db/channel_depth_info/"
+    )
+
+    os.system(f"unzip -q -o {path_to_zip_file}channel.zip -d {path_to_zip_file}")
+
+    # the channel_info.csv file contains the mapping of each fifo name (i.e layer4_out_U) to the respective
+    # chan_status*.csv file
+    names_file_path = (
+        model.config.get_output_dir()
+        + "/"
+        + model.config.get_project_name()
+        + "_prj"
+        + "/solution1/.autopilot/db/channel_info.csv"
+    )
+
+    csv_fifo_depth_files = {}
+    with open(names_file_path) as names_file:
+        for line in names_file:
+            layer_name = line.split(",")[1]
+            csv_file_name = line.split(",")[3][:-1]
+            csv_fifo_depth_files[layer_name] = csv_file_name
+
+    optmized_fifo_depths = {}
+    for layer_name, file_name in csv_fifo_depth_files.items():
+        with open(path_to_zip_file + file_name) as chan_status_file:
+            lines = chan_status_file.readlines()
+            optmized_fifo_depths[layer_name[:-2]] = int(
+                lines[-1]
+            )  # remove "_U" from the layer name string and keep the last line of the file that contains the max depth
+
+    return optmized_fifo_depths
+
+
+def generate_depths_file(model, initial_fifo_depths, optimized_fifo_depths):
+    """Generate a json file with the names of the FIFOs, the initial depths set by hls4ml and their optimized depths,
+    for post-processing. The json file is not used by the rest of the pipeline, it is only produced for the user.
+
+    Args:
+        model (ModelGraph): The model to which FIFO depth optimization is applied.
+        initial_fifo_depths (Dict[str, int]): A dictionary that contains the FIFO names as keys and the initial
+        depths as values.
+        optmized_fifo_depths (Dict[str, int]): A dictionary that contains the FIFO names as keys and the optimized
+        depths as values.
+    """
+    depths = {}
+    for fifo_name in initial_fifo_depths.keys():
+        depths[fifo_name] = {}
+        depths[fifo_name]['initial'] = initial_fifo_depths[fifo_name]
+        depths[fifo_name]['optimized'] = optimized_fifo_depths[fifo_name]
+
+    with open(model.config.get_output_dir() + "/fifo_depths.json", "w") as f:
+        json.dump(depths, f, indent=4)
+
+
+def set_optimized_fifo_depths(model, optimized_fifo_depths):
+    """Set the new optimized FIFO depths.
+
+    Args:
+        model (ModelGraph): The model to which FIFO depth optimization is applied.
+        optmized_fifo_depths (Dict[str, int]): A dictionary that contains the FIFO names as keys and the optimized
+        depths as values.
+    """
+
+    # iterate through the layer output FIFOs
+    for output_variable in model.output_vars.values():
+        if (
+            ("VivadoStreamVariable" in str(type(output_variable)))
+            or (output_variable.name == 'in_local')
+            or (output_variable.name == 'out_local')
+        ):
+            if output_variable.pragma:
+
+                if output_variable.name not in optimized_fifo_depths.keys():
+                    continue
+
+                filtered_depth = optimized_fifo_depths[output_variable.name]
+                output_variable.pragma = (output_variable.pragma[0], filtered_depth)
+
+    inp = model.get_input_variables()[0]
+    inp.pragma = (inp.pragma[0], optimized_fifo_depths['in_local'])
+
+    outp = model.get_output_variables()[0]
+    outp.pragma = (inp.pragma[0], optimized_fifo_depths['out_local'])
+    return
+
+
+class FifoDepthOptimization(ConfigurableOptimizerPass, ModelOptimizerPass):
+    def __init__(self):
+        pass
+
+    def transform(self, model):
+        """Perform FIFO depth optimization between the FIFOs of all layers to reduce resource utilization as the
+        initial FIFOs set by hls4ml might be larger than required. At the end of the optimization the FIFOs will
+        have the largest depths achieved during cosimulation without causing any deadlocks between the layers
+        (producer-consumer), thus no additional delays between the layers. In some cases, this optimization
+        might lead to bigger FIFOs than initially set by the hls4ml tool in order to prevent deadlocks.
+
+        Args:
+            model (ModelGraph): The model to which FIFO depth optimization is applied.
+
+        Raises:
+            ValueError: If the FIFO depth for profiling provided by the user is not a non-negative integer.
+            RuntimeError: If the IO type is not set to "io_stream".
+
+        Returns:
+            bool: The execution state of the Optimzer Pass
+        """
+
+        # use `large_fifo_depth = 0` to keep the default fifo depth
+        # consider changing 100_000 either with a very very large value > of any total bram storage space
+        # or via vitis 2023.2 c-simulation
+        profiling_fifo_depth = getattr(self, "profiling_fifo_depth", 100_000)
+
+        if not isinstance(profiling_fifo_depth, int) or profiling_fifo_depth <= 0:
+            raise ValueError("The FIFO depth for profiling (profiling_fifo_depth variable) must be a positive integer.")
+
+        # check axi-stream or io-stream
+        if not (model.config.get_config_value("IOType") == "io_stream"):
+            raise RuntimeError("To use this optimization you have to set `IOType` field to `io_stream` in the HLS config.")
+
+        initial_fifo_depths = initialize_large_fifos(model, profiling_fifo_depth)
+
+        execute_cosim_to_profile_fifos(model)
+
+        optimized_fifo_depths = get_vitis_optimized_fifo_depths(model)
+
+        generate_depths_file(model, initial_fifo_depths, optimized_fifo_depths)
+
+        set_optimized_fifo_depths(model, optimized_fifo_depths)
+
+        print("[hls4ml] - FIFO optimization completed")
+        return False

hls4ml/backends/vitis_accelerator_ip_flow/supported_boards.json

@@ -0,0 +1,14 @@
+{
+  "pynq-z2": {
+    "part": "xc7z020clg400-1",
+    "tcl_scripts": {"axi_lite": "axi_lite_design.tcl", "axi_stream":  "axi_stream_design.tcl"},
+    "python_drivers": {"axi_stream":  "axi_stream_driver.py"},
+    "c_drivers": {}
+  },
+  "zcu102": {
+    "part": "xczu9eg-ffvb1156-2-e",
+    "tcl_scripts": { "axi_stream": "axi_stream_design.tcl"},
+    "python_drivers": {"axi_stream":  "axi_stream_driver.py"},
+    "c_drivers": {}
+  }
+}

hls4ml/backends/vitis_accelerator_ip_flow/vitis_accelerator_ip_flow_backend.py

@@ -0,0 +1,117 @@
+import os
+
+from hls4ml.backends import VitisBackend, VivadoBackend
+from hls4ml.model.flow import register_flow
+from hls4ml.report import parse_vivado_report
+
+
+class VitisAcceleratorIPFlowBackend(VitisBackend):
+    def __init__(self):
+        super(VivadoBackend, self).__init__(name='VitisAcceleratorIPFlow')
+        self._register_layer_attributes()
+        self._register_flows()
+
+    def build(
+        self,
+        model,
+        reset=False,
+        csim=True,
+        synth=True,
+        cosim=False,
+        validation=False,
+        export=False,
+        vsynth=False,
+        fifo_opt=False,
+        bitfile=False,
+    ):
+        # run the VitisBackend build
+        super().build(
+            model,
+            reset=reset,
+            csim=csim,
+            synth=synth,
+            cosim=cosim,
+            validation=validation,
+            export=export,
+            vsynth=vsynth,
+            fifo_opt=fifo_opt,
+        )
+
+        # now make a bitfile
+        if bitfile:
+            curr_dir = os.getcwd()
+            os.chdir(model.config.get_output_dir())
+            try:
+                os.system('vivado -mode batch -source design.tcl')  # check if this is accepted as a command
+            except Exception:
+                print("Something went wrong, check the Vivado logs")
+            os.chdir(curr_dir)
+
+        return parse_vivado_report(model.config.get_output_dir())
+
+    def create_initial_config(
+        self,
+        board='pynq-z2',
+        part=None,
+        clock_period=5,
+        clock_uncertainty='12.5%',
+        io_type='io_parallel',
+        interface='axi_stream',
+        driver='python',
+        input_type='float',
+        output_type='float',
+    ):
+        '''
+        Create initial accelerator config with default parameters
+
+        Args:
+            board: one of the keys defined in supported_boards.json
+            clock_period: clock period passed to hls project
+            io_type: io_parallel or io_stream
+            interface: `axi_stream`: generate hardware designs and drivers which exploit axi stream channels.
+                       `axi_master`: generate hardware designs and drivers which exploit axi master channels.
+                       `axi_lite` : generate hardware designs and drivers which exploit axi lite channels. (Don't use it
+                       to exchange large amount of data)
+            driver: `python`: generates the python driver to use the accelerator in the PYNQ stack.
+                    `c`: generates the c driver to use the accelerator bare-metal.
+            input_type: the wrapper input precision. Can be `float` or an `ap_type`. Note: VivadoAcceleratorBackend
+                             will round the number of bits used to the next power-of-2 value.
+            output_type: the wrapper output precision. Can be `float` or an `ap_type`. Note:
+                              VivadoAcceleratorBackend will round the number of bits used to the next power-of-2 value.
+            platform: development target platform
+
+        Returns:
+            populated config
+        '''
+        board = board if board is not None else 'pynq-z2'
+        config = super().create_initial_config(part, clock_period, clock_uncertainty, io_type)
+        config['AcceleratorConfig'] = {}
+        config['AcceleratorConfig']['Board'] = board
+        config['AcceleratorConfig']['Interface'] = interface  # axi_stream, axi_master, axi_lite
+        config['AcceleratorConfig']['Driver'] = driver
+        config['AcceleratorConfig']['Precision'] = {}
+        config['AcceleratorConfig']['Precision']['Input'] = {}
+        config['AcceleratorConfig']['Precision']['Output'] = {}
+        config['AcceleratorConfig']['Precision']['Input'] = input_type  # float, double or ap_fixed<a,b>
+        config['AcceleratorConfig']['Precision']['Output'] = output_type  # float, double or ap_fixed<a,b>
+
+        return config
+
+    def get_default_flow(self):
+        return self._default_flow
+
+    def get_writer_flow(self):
+        return self._writer_flow
+
+    def _register_flows(self):
+        vitis_ip = 'vitis:ip'
+        writer_passes = ['make_stamp', 'vitisacceleratoripflow:write_hls']
+        self._writer_flow = register_flow('write', writer_passes, requires=['vitis:ip'], backend=self.name)
+        self._default_flow = vitis_ip
+
+        # Register the fifo depth optimization flow which is different from the one for vivado
+        fifo_depth_opt_passes = [
+            'vitisacceleratoripflow:fifo_depth_optimization'
+        ] + writer_passes  # After optimization, a new project will be written
+
+        register_flow('fifo_depth_optimization', fifo_depth_opt_passes, requires=['vitis:ip'], backend=self.name)