[Backend][BLIF] Automatic generation of blif files

.github/workflows/unittests.yml

@@ -51,13 +51,14 @@ jobs:
             gzip libreadline-dev \
             libboost-all-dev pkg-config python3.12 \
             python3.12-venv python3.12-dev \
-            ghdl verilator
+            ghdl verilator \
+            flex bison tcl-dev
 
       - name: Verify Python 3.12
         run: python3.12 --version
 
       - name: build
-        run: ./build.sh --release --use-prebuilt-llvm --enable-abc --enable-cbc --force
+        run: ./build.sh --release --use-prebuilt-llvm --enable-abc --enable-cbc --enable-yosys --force
 
       - name: check-dynamatic
         if: steps.build.outputs.exit_code == 0

CMakeLists.txt

@@ -268,11 +268,46 @@ if(DYNAMATIC_ENABLE_ABC)
 
     FetchContent_MakeAvailable(abc)
     add_compile_definitions(DYNAMATIC_ENABLE_ABC)
+    add_compile_definitions("DYNAMATIC_ABC_EXECUTABLE=\"${CMAKE_BINARY_DIR}/_deps/abc-build/abc\"")
   else()
     message(FATAL_ERROR "ABC integration is not tested on the OS you use!")
   endif()
 endif()
 
+#-------------------------------------------------------------------------------
+# Yosys setup
+#-------------------------------------------------------------------------------
+
+if(DYNAMATIC_ENABLE_YOSYS)
+  if (UNIX)
+
+    FetchContent_Declare(
+      yosys
+      GIT_REPOSITORY https://github.com/ETHZ-DYNAMO/yosys.git
+      GIT_TAG v1.0.0
+      GIT_SUBMODULES ""
+    )
+    add_custom_target(yosys-submodules
+      COMMAND git submodule update --init --recursive
+      WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/_deps/yosys-src
+    )
+
+    add_custom_target(build-yosys ALL
+      COMMAND make -j
+      WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/_deps/yosys-src
+    )
+
+    add_dependencies(build-yosys yosys-submodules)
+
+    FetchContent_MakeAvailable(yosys)
+    add_compile_definitions(DYNAMATIC_ENABLE_YOSYS)
+    add_compile_definitions("DYNAMATIC_YOSYS_EXECUTABLE=\"${CMAKE_BINARY_DIR}/_deps/yosys-src/yosys\"")
+  else()
+    message(FATAL_ERROR "Yosys integration is not tested on the OS you use!")
+  endif()
+endif()
+
+
 #-------------------------------------------------------------------------------
 # Python (Virtual Environment)
 #-------------------------------------------------------------------------------

build.sh

@@ -31,6 +31,7 @@ List of options:
   --use-prebuilt-llvm                  : download and use the prebuilt LLVM
   --enable-cbc                         : enable the CBC milp solver
   --enable-abc                         : enable the ABC logic synthesis tool
+  --enable-yosys                       : enable the Yosys logic synthesis tool
   --build-legacy-lsq                   : build the legacy chisel-based lsq
   --check | -c                         : run tests during build
   --help | -h                          : display this help message
@@ -145,6 +146,7 @@ BUILD_CHIESEL_LSQ=0
 ENABLE_CBC=0
 CMAKE_DYNAMATIC_ENABLE_CBC=""
 CMAKE_DYNAMATIC_ENABLE_ABC=""
+CMAKE_DYNAMATIC_ENABLE_YOSYS=""
 LLVM_DIR="$PWD/llvm-project/build"
 
 # Loop over command line arguments and update script variables
@@ -211,6 +213,9 @@ do
           "--enable-abc")
               CMAKE_DYNAMATIC_ENABLE_ABC="-DDYNAMATIC_ENABLE_ABC=ON"
               ;;
+          "--enable-yosys")
+              CMAKE_DYNAMATIC_ENABLE_YOSYS="-DDYNAMATIC_ENABLE_YOSYS=ON"
+              ;;
           "--build-legacy-lsq")
               BUILD_CHIESEL_LSQ=1
               ;;
@@ -365,6 +370,7 @@ if should_run_cmake ; then
             $CMAKE_DYNAMATIC_ENABLE_XLS \
             $CMAKE_DYNAMATIC_ENABLE_CBC \
             $CMAKE_DYNAMATIC_ENABLE_ABC \
+            $CMAKE_DYNAMATIC_ENABLE_YOSYS \
             $CMAKE_DYNAMATIC_ENABLE_LEQ_BINARIES
 
     LLVM_DIR="../build/llvm-project"
@@ -382,6 +388,7 @@ if should_run_cmake ; then
         $CMAKE_DYNAMATIC_ENABLE_XLS \
         $CMAKE_DYNAMATIC_ENABLE_CBC \
         $CMAKE_DYNAMATIC_ENABLE_ABC \
+        $CMAKE_DYNAMATIC_ENABLE_YOSYS \
         $CMAKE_DYNAMATIC_ENABLE_LEQ_BINARIES
   fi
   exit_on_fail "Failed to cmake dynamatic"

docs/DeveloperGuide/DynamaticFeaturesAndOptimizations/Synth/BLIFGenerator.md

@@ -0,0 +1,99 @@
+# BLIFGenerator
+
+## Overview
+
+`BLIFGenerator` is a C++ class that synthesises a BLIF file on demand for a given Handshake component by invoking **Yosys** (synthesis) followed by **ABC** (logic optimisation). It replicates the logic of `tools/blif-generator/blif_generator.py` and is called automatically by `BLIFFileManager` when a required BLIF file is not yet present on disk.
+
+The generator requires `DYNAMATIC_ENABLE_ABC` and `DYNAMATIC_ENABLE_YOSYS` to be enabled at build time (see [CMake configuration](#cmake-configuration)).
+
+---
+
+## Synthesis Pipeline
+
+For each component, generation proceeds in the following steps:
+
+1. **JSON config lookup**: The component name is looked up in `data/rtl-config-verilog.json` to obtain the Verilog source file(s) and the names of the parameterisable generics.
+2. **Verilog generation**: If the JSON entry has a `generator` command instead of a static `generic` file, the generator is executed first to produce the Verilog.
+3. **Dependency collection**: All Verilog files listed under `dependencies` are collected recursively.
+4. **Yosys synthesis**: A `run_yosys.sh` script is written to the output directory and executed. It uses `chparam` to set the generic values, then synthesises to BLIF.
+5. **ABC optimisation**: A `run_abc.sh` script applies a multi-iteration rewrite/refactor sequence (`strash` + 6x (`rewrite`; `balance`; `refactor`; `balance`)) and writes the optimised BLIF.
+6. **Blackbox post-processing**: For components whose internal logic should remain abstract, `.names` / `.latch` lines are stripped from the output BLIF.
+
+---
+
+## Output Directory Layout
+
+Generated files are placed under `<blifDirPath>/<component>/<param1>/<param2>/`:
+
+```
+<blifDirPath>/
+  <component>/
+    <param1>/
+      <param2>/
+        <component>_<param1>_<param2>_yosys.blif   <- raw Yosys output
+        <component>.blif                            <- final ABC-optimised output
+        run_yosys.sh                                <- synthesis script
+        run_abc.sh                                  <- optimisation script
+```
+
+The path follows the same convention used by `BLIFFileManager::combineBlifFilePath`.
+
+---
+
+## JSON Config Lookup
+
+The generator reads `data/rtl-config-verilog.json` (located two levels above `blifDirPath`) to find the entry for the requested component. The lookup priority for matching an entry is:
+
+1. `module-name` field (exact match)
+2. `name` field with the `"handshake."` prefix stripped
+3. Basename of the `generic` file path (for support modules without a `name`)
+
+---
+
+## Parameter Mapping
+
+The JSON `parameters` array may contain a mix of fixed and range (generic) parameters. Only **range parameters** contribute to the Yosys `chparam` command and to the BLIF path. A parameter is a range parameter when:
+- Its `type` is `"unsigned"` or `"dataflow"`, **and**
+- It has no `eq` or `data-eq` fixed-value constraint, **and**
+- Its `generic` field is not explicitly `false`.
+
+The `paramValues` passed to `generate()` are **right-aligned** against the ordered list of range parameter names. This means a single value always maps to the innermost (last) range parameter, which is correct for components like `tfifo` where the BLIF path encodes only `DATA_TYPE` but the JSON also declares `NUM_SLOTS` as a range parameter.
+
+---
+
+## Key Functions
+
+### Constructor
+```cpp
+BLIFGenerator(const std::string &blifDirPath,
+              const std::string &yosysExecutable,
+              const std::string &abcExecutable);
+```
+- `blifDirPath`: absolute path to the BLIF file tree (e.g. `<repo>/data/blif`). The Dynamatic root and the JSON config path are derived from this.
+- `yosysExecutable` / `abcExecutable`: paths to the Yosys and ABC binaries.
+
+---
+
+### `generate`
+```cpp
+bool generate(const std::string &component,
+              const std::vector<std::string> &paramValues);
+```
+Runs the full synthesis pipeline for the given component and parameter values. Returns `true` if `<component>.blif` exists in the output directory after generation.
+
+`component` must match the JSON `module-name` (or the stripped `name`) of the target entry, e.g. `"addi"`, `"fork_dataless"`, `"oehb"`.
+
+---
+
+## CMake Configuration
+
+`BLIFGenerator` is only active when both `DYNAMATIC_ENABLE_ABC=ON` and `DYNAMATIC_ENABLE_YOSYS=ON` are passed to CMake (e.g. via `./build.sh --enable-abc --enable-yosys`). These options:
+
+1. Build ABC and Yosys as CMake `FetchContent` dependencies.
+2. Set `DYNAMATIC_ABC_EXECUTABLE` and `DYNAMATIC_YOSYS_EXECUTABLE` CMake variables to the built binary paths.
+
+In `BLIFFileManager`, the call to `BLIFGenerator` is guarded by:
+```cpp
+#if defined(DYNAMATIC_YOSYS_EXECUTABLE) && defined(DYNAMATIC_ABC_EXECUTABLE)
+```
+If neither macro is defined, a missing BLIF file causes an assertion failure with a message directing the user to enable those options.

docs/SUMMARY.md

@@ -80,6 +80,7 @@
   - [Synth]()
     - [Blif Exporter](DeveloperGuide/DynamaticFeaturesAndOptimizations/Synth/BlifExporter.md)
     - [Blif File Manager](DeveloperGuide/DynamaticFeaturesAndOptimizations/Synth/BLIFFileManager.md)
+    - [Blif Generator](DeveloperGuide/DynamaticFeaturesAndOptimizations/Synth/BLIFGenerator.md)
     - [Blif Importer](DeveloperGuide/DynamaticFeaturesAndOptimizations/Synth/BlifImporter.md)
     - [Handshake To Synth Conversion](DeveloperGuide/DynamaticFeaturesAndOptimizations/Synth/HandshakeToSynthConversion.md)
     - [Mark Blif File](DeveloperGuide/DynamaticFeaturesAndOptimizations/Synth/MarkBlifFile.md)

include/dynamatic/Support/BLIFFileManager.h

@@ -28,7 +28,10 @@ namespace dynamatic {
 class BLIFFileManager {
 public:
   // Constructor for the BLIFFileManager class
-  BLIFFileManager(std::string blifDirPath) : blifDirPath(blifDirPath) {}
+  BLIFFileManager(std::string blifDirPath, std::string dynamaticRootPath,
+                  std::string RTLJSONFile)
+      : blifDirPath(blifDirPath), dynamaticRootPath(dynamaticRootPath),
+        RTLJSONFile(RTLJSONFile) {}
 
   // Function to combine parameter values, module type and blif directory path
   // to create the blif file path
@@ -43,6 +46,10 @@ class BLIFFileManager {
 private:
   // String containing the base path of the blif files
   std::string blifDirPath;
+  // String containing the path to the Dynamatic root directory
+  std::string dynamaticRootPath;
+  // String containing the path to the RTL JSON file
+  std::string RTLJSONFile;
 };
 
 // Formats a bit-indexed port name: "sig[bit]".

include/dynamatic/Support/BLIFGenerator.h

@@ -0,0 +1,62 @@
+//===- BLIFGenerator.h - On-demand BLIF file generator ----------*- C++ -*-===//
+//
+// Dynamatic is under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// Generates a BLIF file for a given Handshake operation by running Yosys
+// (synthesis) followed by ABC (optimization).
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef DYNAMATIC_SUPPORT_BLIFGENERATOR_H
+#define DYNAMATIC_SUPPORT_BLIFGENERATOR_H
+
+#include "mlir/IR/Operation.h"
+#include <string>
+#include <vector>
+
+namespace dynamatic {
+
+class BLIFGenerator {
+public:
+  BLIFGenerator(const std::string &blifDirPath,
+                const std::string &dynamaticRootPath,
+                const std::string &RTLJSONFile,
+                const std::string &yosysExecutable,
+                const std::string &abcExecutable, mlir::Operation *op,
+                const std::string &expectedBlifPath);
+
+  /// Generate the BLIF file for the operation supplied at construction.
+  ///
+  /// If the expected BLIF file already exists, this function does nothing and
+  /// returns true. Otherwise, it runs the RTL generator, Yosys, and ABC in
+  /// sequence to produce the BLIF file.
+  ///
+  /// Returns true when the BLIF file was successfully created.
+  bool generate();
+
+private:
+  std::string blifDirPath;      /// Absolute path to the BLIF directory.
+  std::string RTLJSONFile;      /// Path to the RTL JSON configuration file.
+  std::string dynamaticRoot;    /// Dynamatic root, derived from blifDirPath.
+  std::string yosysExecutable;  /// Path to the Yosys binary.
+  std::string abcExecutable;    /// Path to the ABC binary.
+  mlir::Operation *op;          /// The operation to synthesize.
+  std::string expectedBlifPath; /// Expected output path of the final BLIF.
+
+  /// Write run_yosys.sh inside outputDir and execute it.
+  bool runYosys(const std::string &topModule, const std::string &outputDir,
+                const std::vector<std::string> &verilogFiles,
+                const std::string &outputName) const;
+
+  /// Write run_abc.sh inside outputDir and execute it.
+  bool runAbc(const std::string &inputFile, const std::string &outputDir,
+              const std::string &outputName) const;
+};
+
+} // namespace dynamatic
+
+#endif // DYNAMATIC_SUPPORT_BLIFGENERATOR_H

include/dynamatic/Support/RTLGenerator.h

@@ -0,0 +1,74 @@
+//===- RTLGenerator.h - RTL code generator from JSON config -----*- C++ -*-===//
+//
+// Dynamatic is under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// Generates a Verilog file for a given Handshake operation by looking up its
+// entry in a JSON RTL config, substituting RTL parameters, and running the
+// configured generator command.
+//
+// Parameters are extracted from the operation via RTLAttrInterface
+// (getRTLParameters()). Results (module name, output directory, Verilog file
+// list) are available via getters after a successful generate() call.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef DYNAMATIC_SUPPORT_RTLGENERATOR_H
+#define DYNAMATIC_SUPPORT_RTLGENERATOR_H
+
+#include <string>
+#include <vector>
+
+namespace mlir {
+class Operation;
+} // namespace mlir
+
+namespace dynamatic {
+
+class RTLGenerator {
+public:
+  RTLGenerator(const std::string &rtlConfigPath,
+               const std::string &dynamaticRoot,
+               const std::string &outputBaseDir, mlir::Operation *op);
+
+  /// Runs the RTL generator command found in the JSON config.
+  ///
+  /// Extracts parameters from the operation via RTLAttrInterface, locates the
+  /// matching config entry, substitutes all variables into the generator
+  /// command, and executes it. On success the generated and support Verilog
+  /// files are collected and made available via getters.
+  ///
+  /// Returns true when RTL generation succeeded.
+  bool generate();
+
+  const std::string &getModuleName() const { return moduleName; }
+  const std::string &getOutputDir() const { return outputDir; }
+  const std::vector<std::string> &getVerilogFiles() const {
+    return verilogFiles;
+  }
+
+private:
+  std::string rtlConfigPath; /// Absolute path to the JSON RTL config file.
+  std::string dynamaticRoot; /// Project root used to resolve $DYNAMATIC paths
+                             /// in the config.
+  std::string outputBaseDir; /// Base directory under which the per-module
+                             /// output subdirectory will be created.
+  mlir::Operation *op;       /// The Handshake operation to generate RTL for.
+
+  std::string moduleName; /// The generated module name, derived from the
+                          /// operation name and parameters.
+  std::string outputDir;  /// The output directory for generated files, derived
+                         /// from outputBaseDir, operation name, and parameters.
+  std::vector<std::string>
+      verilogFiles; /// List of generated and support Verilog files to be
+                    /// synthesized, including the main generated file
+                    /// (outputDir/moduleName.v) and any additional files
+                    /// specified in the config with "generic" paths.
+};
+
+} // namespace dynamatic
+
+#endif // DYNAMATIC_SUPPORT_RTLGENERATOR_H