[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/DesignDecisionProposals/BackendGenerator.md

@@ -0,0 +1,147 @@
+# BackendGenerator
+
+## Overview
+
+`BackendGenerator` is a C++ class responsible for generating backend representations of Handshake operations. It currently supports two output formats:
+
+- **Verilog**
+- **BLIF**
+
+The high-level overview of the code is the following:
+1. It queryies operation parameters through the Handshake RTL interface.
+2. It selects the output directory depending on the operation.
+3. It calls the generator for each backend.
+4. It records the produced outputs.
+
+---
+
+## Supported Backends
+
+### Verilog Backend
+
+- Generates RTL using a generator command defined in the JSON config.
+- Produces one or more `.v` files.
+- No synthesis or optimization is performed.
+
+### BLIF Backend
+
+- Calls on the Verilog backend.
+- Synthesizes the generated Verilog using **Yosys**.
+- Optimizes the result using **ABC**.
+- Produces a final `.blif` file.
+
+---
+
+## Inputs
+
+`BackendGenerator` requires the following inputs:
+
+### Operation
+
+- An `mlir::Operation*` implementing `handshake::RTLAttrInterface`
+- The operation must provide its parameters via `getRTLParameters()`
+
+### Backend Selection
+
+- A `Backend` enum specifying the target format:
+  - `Backend::Verilog`
+  - `Backend::BLIF`
+
+### Backend Parameters
+
+- `rtlConfigPath`: Path to the JSON RTL configuration file
+- `dynamaticRoot`: Root path of the Dynamatic repository (used in substitutions)
+- `outputBaseDir`: Base directory for generated files
+
+
+---
+
+## Generation Flow
+
+### Preparation Steps
+
+For all backends:
+
+1. **Parameter Extraction**  
+   Parameters are retrieved from the operation via  
+   `handshake::RTLAttrInterface::getRTLParameters()`.
+
+2. **Output Directory Construction**  
+   The output directory structure is the following:
+   `<baseDir>/<operation>/<param1>/<param2>/...` where `baseDir` is the base directory specified as input to the backend generator, `operation` is the name of the operation, `param1`,`param2` and so on are the values of the parameter for the operation.
+
+3. **JSON Config Lookup**  
+The file specified by `rtlConfigPath` is parsed to locate a matching entry:
+- Match is based on `"name"` == operation name
+- Optional `"parameters"` constraints must also match
+
+4. **Generator Command Execution**  
+The `"generator"` field is expanded using parameter substitution:
+- `$PARAM_NAME` -> actual value
+- Special variables that are set by the backend generator code are the following:
+  - `MODULE_NAME`
+  - `OUTPUT_DIR`
+  - `DYNAMATIC`
+  - `BITWIDTH`
+  - `EXTRA_SIGNALS`
+
+---
+
+### Verilog Backend Pipeline
+
+1. Execute the generator command.
+2. Expect output:
+  `<outputDir>/<moduleName>.v`
+3. Collect:
+- Generated Verilog file
+- Additional dependency files from JSON (`generic` entries)
+
+---
+
+### BLIF Backend Pipeline
+
+The BLIF backend reuses the Verilog backend, then applies synthesis:
+
+1. **Verilog Generation**  
+Internally invokes the Verilog backend.
+
+2. **Yosys Synthesis**  
+A script `run_yosys.sh` is generated and executed. It performs:
+- Verilog parsing
+- Hierarchy resolution
+- Lowering and optimization
+- BLIF emission
+
+3. **ABC Optimization**  
+A script `run_abc.sh` is generated and executed. It applies:
+```
+strash
+6x (rewrite -> balance -> refactor -> balance)
+```
+
+For the BLIF backend, the directory additionally contains:
+- Intermediate BLIF file from Yosys
+- Final optimized BLIF file
+- Generated Yosys and ABC scripts
+
+---
+
+## Parameter Handling
+
+Parameters are extracted from the operation using the MLIR function `handshake::RTLAttrInterface::getRTLParameters()`. and stored in a map:
+`std::map<std::string, std::string>`
+
+---
+
+## External Dependencies
+
+### Verilog Backend
+- No external tools required beyond the generator command.
+
+### BLIF Backend
+- **Yosys**
+- **ABC**
+
+Both these tools are automatically installed when using the flags `--enable-abc` and `--enable-yosys` when building Dynamatic with the `build.sh` script. If there is a specific choice of the versions of both tools, please include the binaries of both tools in the `PATH` variable.
+
+Paths to these tools must be provided through the backend parameters.

docs/SUMMARY.md

@@ -52,6 +52,7 @@
 
 - [Design Decision Proposals]()
   - [Add/Remove/Promote Extra Signals](DeveloperGuide/DesignDecisionProposals/AddRemovePromoteExtraSignals.md)
+  - [Backend Generator](DeveloperGuide/DesignDecisionProposals/BackendGenerator.md)
   - [Circuit Interface](DeveloperGuide/DesignDecisionProposals/CircuitInterface.md)
   - [Type System](DeveloperGuide/DesignDecisionProposals/TypeSystem.md)
   - [Wait Synchronization](DeveloperGuide/DesignDecisionProposals/WaitSynchronization.md)

include/dynamatic/Support/BLIFFileManager.h

@@ -1,48 +1,50 @@
-//===- BLIFFileManager.h - Support functions for BLIF importer -*- C++
-//-*-===//
+//===- BLIFFileManager.h - Support functions for BLIF importer -*- 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
 //
 //===----------------------------------------------------------------------===//
 //
-// This file contains the function to retrieve the path of the blif file for a
-// given handshake operation. The path is created by combining the base path
-// contining all the blif files and the operation name and parameters. The file
-// is expected to be named in the format <op_name>_<param1>_<param2>_..._.blif.
-// If the file does not exist, an error is emitted.
+// Retrieves the BLIF file path for a given Handshake operation by combining
+// the base BLIF directory, the operation name, and its RTL parameter values.
+// If the file does not exist and Yosys+ABC are configured, it is generated
+// on demand via BackendGenerator.
 //
 //===----------------------------------------------------------------------===//
 
-#include "dynamatic/Analysis/NameAnalysis.h"
-#include "dynamatic/Dialect/Handshake/HandshakeInterfaces.h"
-#include "dynamatic/Dialect/Handshake/HandshakeOps.h"
+#ifndef DYNAMATIC_SUPPORT_BLIFFILEMANAGER_H
+#define DYNAMATIC_SUPPORT_BLIFFILEMANAGER_H
+
 #include "dynamatic/Support/LLVM.h"
-#include "llvm/ADT/TypeSwitch.h"
-#include <filesystem>
-#include <regex>
+#include "llvm/ADT/SmallVector.h"
+#include <string>
+#include <vector>
+
+namespace mlir {
+class Operation;
+} // namespace mlir
 
 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(std::move(blifDirPath)),
+        dynamaticRootPath(std::move(dynamaticRootPath)),
+        rtlJsonFile(std::move(rtlJsonFile)) {}
 
-  // Function to combine parameter values, module type and blif directory path
-  // to create the blif file path
-  std::string combineBlifFilePath(std::string moduleType,
-                                  std::vector<std::string> paramValues,
-                                  std::string extraSuffix = "");
+  std::string combineBlifFilePath(const std::string &moduleType,
+                                  const std::vector<std::string> &paramValues,
+                                  const std::string &extraSuffix = "");
 
-  // Function to retrieve the path of the blif file for a given handshake
-  // operation
   std::string getBlifFilePathForHandshakeOp(mlir::Operation *op);
 
 private:
-  // String containing the base path of the blif files
   std::string blifDirPath;
+  std::string dynamaticRootPath;
+  std::string rtlJsonFile;
 };
 
 // Formats a bit-indexed port name: "sig[bit]".
@@ -59,15 +61,17 @@ std::string legalizeControlPortName(const std::string &name,
 
 // Converts a (root, index) pair into the canonical "root[index]" form.
 // If root already contains "[N]", the old index is linearised with
-//  arrayWidth before adding index.
+// arrayWidth before adding index.
 // Example: formatArrayName("data[2]", 3, 4) becomes "data[11]"  (2*4 + 3)
 std::string formatArrayName(const std::string &root, unsigned index,
                             unsigned arrayWidth = 0);
 
 // Legalizes a list of handshake port names by converting the "root_N" index
 // pattern (used internally by NamedIOInterface) into the "root[N]" array
-// notation expected by the BLIF importer
+// notation expected by the BLIF importer.
 // Example: ["data_0", "data_1", "valid"] -> ["data[0]", "data[1]", "valid"]
-void legalizeBlifPortNames(mlir::SmallVector<std::string> &names);
+void legalizeBlifPortNames(llvm::SmallVector<std::string> &names);
+
+} // namespace dynamatic
 
-} // namespace dynamatic
+#endif // DYNAMATIC_SUPPORT_BLIFFILEMANAGER_H