HeteroCL Dialect

Overview

HeteroCL dialect is an out-of-tree MLIR dialect for accelerator design. HeteroCL dialect decouples algorithm from hardware customizations, and classifies them into compute and data customizations. The HeteroCL dialect is part of the HeteroCL compilation flow. HeteroCL provides an end-to-end flow from Python to LLVM backend or C HLS FPGA backends. With HeteroCL, designers can explore tradeoffs with hardware customizations in a systematic manner and quickly obtain high-performance design with little manual effort.

Building

Preliminary tools

• gcc >= 9 (Please make sure you have installed the gcc that supports C++17)
• cmake >= 3.22
• python >= 3.8

Install LLVM 18.x

• Download LLVM from llvm-project or checkout the Github branch sh git clone https://github.com/llvm/llvm-project.git cd llvm-project git checkout tags/llvmorg-18-init

• Build

  • Without Python binding sh mkdir build && cd build cmake -G "Unix Makefiles" ../llvm \ -DLLVM_ENABLE_PROJECTS=mlir \ -DLLVM_BUILD_EXAMPLES=ON \ -DLLVM_TARGETS_TO_BUILD="X86" \ -DCMAKE_BUILD_TYPE=Release \ -DLLVM_ENABLE_ASSERTIONS=ON \ -DLLVM_INSTALL_UTILS=ON make -j8 # You can either use ninja to build # cmake -G Ninja # ninja
  • With Python binding: Please follow the official guide to set up the environment. In the following, we set up a virtual environment called hcl-dev using Python venv, but we prefer you to install Anaconda3 and create an environment there. If you want to use your own Python environment, please specify the path for -DPython3_EXECUTABLE. ```sh # Create a virtual environment. Make sure you have installed Python3. which python3 python3 -m venv ~/.venv/hcl-dev source ~/.venv/hcl-dev/bin/activate

# It is recommended to upgrade pip python3 -m pip install --upgrade pip

# Install required packages. Suppose you are inside the llvm-project folder. python3 -m pip install -r mlir/python/requirements.txt

# Run cmake mkdir build && cd build cmake -G "Unix Makefiles" ../llvm \ -DLLVMENABLEPROJECTS=mlir \ -DLLVMBUILDEXAMPLES=ON \ -DLLVMTARGETSTOBUILD="host" \ -DCMAKEBUILDTYPE=Release \ -DLLVMENABLEASSERTIONS=ON \ -DLLVMINSTALLUTILS=ON \ -DMLIRENABLEBINDINGSPYTHON=ON \ -DPython3_EXECUTABLE=which python3 make -j8 # You can either use ninja to build # cmake -G Ninja # ninja

# Export the LLVM build directory export LLVMBUILDDIR=$(pwd)

# To enable better backtracing for debugging, # we suggest setting the following system path export LLVMSYMBOLIZERPATH=$(pwd)/bin/llvm-symbolizer ```

Build HeteroCL Dialect

This setup assumes that you have built LLVM and MLIR in $LLVM_BUILD_DIR. Please firstly clone our repository. sh git clone --recursive git@github.com:cornell-zhang/hcl-dialect.git cd hcl-dialect mkdir build && cd build

NOTE: The HeteroCL dialect is a standalone system that works without a frontend. If you are using it with the HeteroCL frontend, the minimum requirement is to build with Python binding. Building with OpenSCoP extraction is optional.

• Build without Python binding sh cmake -G "Unix Makefiles" .. \ -DMLIR_DIR=$LLVM_BUILD_DIR/lib/cmake/mlir \ -DLLVM_EXTERNAL_LIT=$LLVM_BUILD_DIR/bin/llvm-lit \ -DPYTHON_BINDING=OFF \ -DOPENSCOP=OFF make -j8

• Build with Python binding ``sh cmake -G "Unix Makefiles" .. \ -DMLIR_DIR=$LLVM_BUILD_DIR/lib/cmake/mlir \ -DLLVM_EXTERNAL_LIT=$LLVM_BUILD_DIR/bin/llvm-lit \ -DPYTHON_BINDING=ON \ -DOPENSCOP=OFF \ -DPython3_EXECUTABLE=which python3` \ -DCMAKECXXFLAGS="-Wfatal-errors -std=c++17" make -j8

Export the generated HCL-MLIR Python library

export PYTHONPATH=$(pwd)/tools/hcl/pythonpackages/hclcore:${PYTHONPATH} ```

• Build with OpenSCoP extraction enabled: Set -DOPENSCOP=ON and export the library path. sh export LD_LIBRARY_PATH=$(pwd)/openscop/lib:$LD_LIBRARY_PATH

Lastly, you can use the following integration test to see whether your built dialect works properly. cmake --build . --target check-hcl

Run HeteroCL Dialect

```sh

perform loop transformation passes

./bin/hcl-opt -opt ../test/Transforms/compute/tiling.mlir

generate C++ HLS code

./bin/hcl-opt -opt ../test/Transforms/compute/tiling.mlir | \ ./bin/hcl-translate -emit-vivado-hls

generate OpenSCoP

An hcl.openscop file will be generated in the build folder

./bin/hcl-opt -opt ../test/Transforms/memory/buffer_add.mlir | \ ./bin/hcl-translate --extract-scop-stmt

run code on CPU

./bin/hcl-opt -opt -jit ../test/Translation/mm.mlir ```

Integrate with upstream HeteroCL frontend

Make sure you have correctly built the above HCL-MLIR dialect, and follow the instruction below.

```sh

clone the HeteroCL repo

git clone https://github.com/cornell-zhang/heterocl.git heterocl-mlir cd heterocl-mlir

install dependencies

python3 -m pip install -r requirements.txt

export the library

export HCLHOME=$(pwd) export PYTHONPATH=$HCLHOME/python:${PYTHONPATH}

run regression tests in the HeteroCL repo

cd tests && python3 -m pytest ```

HeteroCL Dialect Examples

Coding Style

We follow Google Style Guides and use * clang-format for C/C++ * black and pylint for Python

To install clang-format, you can reuse the LLVM project by specifying the following CMake options:

```sh

Inside the llvm-project folder

mkdir build-clang && cd build-clang cmake -G Ninja ../llvm \ -DLLVMENABLEPROJECTS="clang" \ -DLLVMBUILDEXAMPLES=ON \ -DLLVMTARGETSTOBUILD="host" \ -DCMAKEBUILDTYPE=Release \ -DLLVMENABLEASSERTIONS=ON \ -DLLVMINSTALL_UTILS=ON ninja clang-format ```

References

• ScaleHLS
• Torch-MLIR
• Polymer