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

git clone https://github.com/llvm/llvm-project.git
cd llvm-project
git checkout tags/llvmorg-18-init

Build

Without Python binding

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.

# 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 \
   -DLLVM_ENABLE_PROJECTS=mlir \
   -DLLVM_BUILD_EXAMPLES=ON \
   -DLLVM_TARGETS_TO_BUILD="host" \
   -DCMAKE_BUILD_TYPE=Release \
   -DLLVM_ENABLE_ASSERTIONS=ON \
   -DLLVM_INSTALL_UTILS=ON \
   -DMLIR_ENABLE_BINDINGS_PYTHON=ON \
   -DPython3_EXECUTABLE=`which python3`
make -j8
# You can either use ninja to build
# cmake -G Ninja
# ninja

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

# To enable better backtracing for debugging,
# we suggest setting the following system path
export LLVM_SYMBOLIZER_PATH=$(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.

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

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

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` \
   -DCMAKE_CXX_FLAGS="-Wfatal-errors -std=c++17"
make -j8

# Export the generated HCL-MLIR Python library
export PYTHONPATH=$(pwd)/tools/hcl/python_packages/hcl_core:${PYTHONPATH}

Build with OpenSCoP extraction enabled: Set -DOPENSCOP=ON and export the library path.

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

# 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.

# 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 python/requirements.txt

# export the library
export HCL_HOME=$(pwd)
export PYTHONPATH=$HCL_HOME/python:${PYTHONPATH}

# run regression tests in the HeteroCL repo
cd tests && python3 -m pytest