diff --git a/README.md b/README.md index c302c867..6a1ca7db 100644 --- a/README.md +++ b/README.md @@ -9,98 +9,17 @@ ![GitHub](https://img.shields.io/github/license/cornell-zhang/allo) [![CircleCI](https://circleci.com/gh/cornell-zhang/allo.svg?style=shield)](https://circleci.com/gh/cornell-zhang/allo.svg?style=shield) -Allo is an Accelerator Design Language (ADL) and compiler that facilitates the construction of large-scale, high-performance hardware accelerators in a modular and composable manner. Allo has several key features: -* **Progressive hardware customizations**: Allo decouples hardware customizations from algorithm specifications and treats each hardware customization as a primitive that performs a rewrite on the program. Allo not only decouples the loop-based transformations, but also extends the decoupling to memory, communication, and data types. +Allo is a Python-embedded Accelerator Design Language (ADL) and compiler that facilitates the construction of large-scale, high-performance hardware accelerators in a modular and composable manner. Allo has several key features: +* **Progressive hardware customizations**: Allo decouples hardware customizations from algorithm specifications and treats each hardware customization as a primitive that performs a rewrite on the program. Allo not only decouples the loop-based transformations, but also extends the decoupling to memory, communication, and data types. All the transformations are built on top of [MLIR](https://mlir.llvm.org/) that is easier to target different backends. * **Reusable parameterized kernel templates**: Allo supports declaring type variables during kernel creation and instantiating the kernel when building the hardware executable, which is an important feature for building reusable hardware kernel libraries. Allo introduces a concise grammar for creating kernel templates, eliminating the need for users to possess complicated metaprogramming expertise. * **Composable schedules**: Allo empowers users to construct kernels incrementally from the bottom up, adding customizations one at a time while validating the correctness of each submodule. Ultimately, multiple schedules are progressively integrated into a complete design using the `.compose()` primitive. This approach, unachievable by prior top-down methods, significantly enhances productivity and debuggability. -## Installation - -Please clone the Allo repository to your local machine. - -```bash -git clone https://github.com/cornell-zhang/allo.git -cd allo -``` - -We recommend creating a new conda environment for Allo. Since we are using the latest Python features, the minimum Python version is **3.12**. - -```bash -conda create -n allo python=3.12 -conda activate allo -``` - - -### Prerequisites - -We need to first install the [LLVM project](https://github.com/llvm/llvm-project/tree/llvmorg-18-init) and the [hcl-mlir dialect](https://github.com/cornell-zhang/hcl-dialect). Users can choose to use our provided docker or build from source. - -#### Docker - -To simplify the installation process, we provide a docker image that has already installed the LLVM-18.x project. -Please pull the image from Docker Hub, **patch LLVM, and install the hcl dialect** as described above. - -```bash -# * The LLVM is installed in /root/llvm-project in the docker image, which has already been patched -# * A prebuilt hcl-dialect is installed in /root/hcl-dialect, but please note that it is not up-to-date -# You can pull the latest hcl-dialect using `git pull` and rebuild it if needed -docker pull chhzh123/hcl-dialect:llvm-18.x-py3.12 -docker run --rm -it chhzh123/hcl-dialect:llvm-18.x-py3.12 -``` - -#### Build from source - -Users can also choose to build LLVM and the hcl dialect from source. Please follow the instructions below. - -```bash -# Make sure you are under the correct Python environment -bash build.sh -``` - - -### Install Allo - -After installing LLVM and the hcl dialect, we can directly `pip install` Allo: - -```bash -# Under the root directory of Allo -python3 -m pip install -e . -``` - ## Getting Started -Below is a minimal example of leveraging Allo to customize a GEMM kernel: -```python -import allo -from allo.ir.types import int32 - -# Allo kernel definition -def gemm(A: int32[32, 32], B: int32[32, 32]) -> int32[32, 32]: - C: int32[32, 32] = 0 - for i, j, k in allo.grid(32, 32, 32): - C[i, j] += A[i, k] * B[k, j] - return C - -# Schedule construction -s = allo.customize(gemm) -# Real-time transformation -s.split("i", factor=8) -print(s.module) +Please check out the [Allo documentation](https://cornell-zhang.github.io/allo) for installation instructions and tutorials. +If you encounter any problems, please feel free to open an [issue](https://github.com/cornell-zhang/allo/issues). -# Compilation -mod = s.build(target="llvm") - -# Execution -import numpy as np -np_A = np.random.randint(0, 100, (32, 32)).astype(np.int32) -np_B = np.random.randint(0, 100, (32, 32)).astype(np.int32) -np_C = mod(np_A, np_B) - -# Testing -golden_C = np.matmul(np_A, np_B) -np.testing.assert_allclose(np_C, golden_C, rtol=1e-5, atol=1e-5) -``` ## Publications Please refer to our [PLDI'24 paper](https://arxiv.org/abs/2404.04815) for more details. If you use Allo in your research, please use the following bibtex entry to cite us: diff --git a/build.sh b/build.sh index d2a8cbd1..fe030b79 100644 --- a/build.sh +++ b/build.sh @@ -2,10 +2,19 @@ # Copyright Allo authors. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 +export ALLO_HOME=$(pwd) + # Pull the LLVM project and hcl-mlir dialect git submodule update --init --recursive +# Check the Python version +if ! python3 -c 'import sys; assert sys.version_info >= (3,12)' > /dev/null; then + echo "Error: Python 3.12 or later is required" + exit 1 +fi + # Install the required Python packages +echo "Installing the required Python packages ..." python3 -m pip install -r requirements.txt # Note: we need to patch the LLVM project to add additional @@ -32,6 +41,7 @@ make -j8 # Export the LLVM build directory export LLVM_BUILD_DIR=$(pwd) +export PATH=$LLVM_BUILD_DIR/bin:$PATH echo "LLVM build directory: $LLVM_BUILD_DIR" # Build the hcl dialect @@ -48,6 +58,12 @@ cmake -G "Unix Makefiles" .. \ make -j8 # Install hcl dialect +echo "Installing hcl dialect ..." cd tools/hcl/python_packages/hcl_core python3 -m pip install -e . + +# Install allo +echo "Installing allo ..." +cd $ALLO_HOME +python3 -m pip install -e . echo "Installation completed!" diff --git a/docs/source/conf.py b/docs/source/conf.py index ada927e1..08590bdf 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,7 +39,7 @@ project = "Allo" author = "Allo Authors" -copyright = "2023, Allo Authors" +copyright = "2024, Allo Authors" # The full version, including alpha/beta/rc tags release = "0.5" diff --git a/docs/source/developer/index.rst b/docs/source/developer/index.rst index 9f988dc1..be39a6b0 100644 --- a/docs/source/developer/index.rst +++ b/docs/source/developer/index.rst @@ -24,12 +24,68 @@ Developer Setup ############### +Depending on which part of Allo you want to contribute to, you may set up the environment differently. + +Developer Installation +---------------------- + +If you only want to change the frontend part of Allo, you can install the Allo package following the `general guide <../setup/index.html>`_. + +If you need to change the backend part of Allo, you need to install the LLVM-18 project and make sure your LLVM commit is the same as `the one we referred to `_. + +.. code-block:: bash + + mkdir -p build && cd build + # Python 3.12 is required + 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 + +.. note:: + + For Zhang Group students, you can ``export LLVM_HOME=/work/shared/users/common/llvm-project-18.x`` and ``export PATH=$LLVM_HOME/build-patch/bin:$PATH`` to use the pre-installed LLVM-18 project. + +After installing the LLVM-18 project, you can build the hcl-mlir dialect from source: + +.. code-block:: bash + + git clone https://github.com/cornell-zhang/hcl-dialect.git + cd hcl-dialect + mkdir -p build && cd build + 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 + cd tools/hcl/python_packages/hcl_core + python3 -m pip install -e . + +Every time you change the hcl-mlir dialect, you need to run ``make`` again to make the changes effective. Finally, you can install the Allo package: + +.. code-block:: bash + + python3 -m pip install -e . + +It will connect the frontend with the backend. + +Upstream Changes +---------------- + It would be good to maintain your own `fork `_ of the Allo repository, which helps create a `PR (pull request) `_ and upstream changes easier. To create your own fork, click on the "Fork" button on the top right of the `Allo repository `_. -This will create a copy of the repository under your own GitHub account. Please do *NOT* make it public -at this time. (By default, fork from a private repository should be private.) +This will create a copy of the repository under your own GitHub account. Next, you can clone your fork to your local machine OR if you have already cloned the Allo repository, you can add your fork as a remote: @@ -63,7 +119,6 @@ Basically, the development workflow is as follows: Most of the ``git`` features are integrated in VSCode, please refer to the `document `_ if you want to use the GUI. - Integration Tests ----------------- We have configured `GitHub Actions `_ to run the tests on every PR, so please diff --git a/docs/source/setup/index.rst b/docs/source/setup/index.rst index 54434647..250c3653 100644 --- a/docs/source/setup/index.rst +++ b/docs/source/setup/index.rst @@ -24,19 +24,71 @@ Installation ############ -To install and use Allo, we need to have the LLVM compiler infrastructure installed on our system. -We have already prepared a prebuilt version of LLVM on our server, so you can directly export it to your system path. -Please follow the instruction below to set up the environment. -If you want to install Allo on your local machine, you can refer to the `README `_ guideline in the Allo repository. - -Make sure you have the access to the :code:`brg-zhang` or other Zhang group server. You can log into the server by -SSH or use VSCode Remote SSH extension. Please refer to `this website `_ -for more details on configuring VSCode. Those servers are only accessible from the campus network. - -After logging into the server, the first step is to install an Anaconda environment. We recommend you to install your own -`Miniconda `_, which is a lightweight version of Anaconda and contains -only the necessary packages. You can download the installer from the link above and install it on your system. -After the installation, you can create a new environment for Allo by running the following commands: +To install and use Allo, we need to first install the `LLVM-18 project `_ and the `hcl-mlir dialect `_. You can choose to use our provided docker or build from source. + +Install from Docker +------------------- + +To simplify the installation process, we provide a docker image that has already installed the LLVM-18 project. Please pull the image from Docker Hub as described below. The LLVM is installed under the :code:`/root/llvm-project` folder in the docker image, and a prebuilt hcl-mlir dialect is installed in :code:`/root/hcl-dialect`. + +.. code-block:: console + + $ docker pull chhzh123/hcl-dialect:llvm-18.x-py3.12 + $ docker run --rm -it chhzh123/hcl-dialect:llvm-18.x-py3.12 + (docker) $ git clone https://github.com/cornell-zhang/allo.git && cd allo + (docker) $ python3 -m pip install -e . + +Please note that the hcl-mlir dialect is not up-to-date. You can pull the latest hcl-mlir dialect and rebuild it if needed. + +.. code-block:: console + + (docker) $ cd /root/hcl-dialect + (docker) $ git remote update && git fetch + (docker) $ cd build && make -j8 + (docker) $ cd tools/hcl/python_packages/hcl_core + (docker) $ python3 -m pip install -e . + +Install from Source +------------------- + +Please clone the Allo repository to your local machine. + +.. code-block:: console + + $ git clone https://github.com/cornell-zhang/allo.git + $ cd allo + +We recommend creating a new conda environment for Allo. Since we are using the latest Python features, the minimum Python version is **3.12**. + +.. code-block:: console + + $ conda create -n allo python=3.12 + $ conda activate allo + +After creating the Python environment, you can install the required packages by running the following command. + +.. code-block:: console + + $ bash build.sh + +You should see "Installation completed!" if the installation is finished. + +Testing +------- + +To make sure the installation is successful, you can run the following command to test the Allo package. + +.. code-block:: console + + $ python3 -m pytest tests/ + +Internal Installation +--------------------- +For Zhang Group students, we have already prepared a prebuilt version of LLVM on our server, so you do not need to build everything from source. Please follow the instruction below to set up the environment. + +Make sure you have the access to the :code:`brg-zhang` or other Zhang group server. You can log into the server by SSH or use VSCode Remote SSH extension. Please refer to `this website `_ for more details on configuring VSCode. Those servers are only accessible from the campus network. Please use the VPN if you are off-campus. + +After logging into the server, the first step is to install an Anaconda environment. We recommend you to install your own `Miniconda `_, which is a lightweight version of Anaconda and contains only the necessary packages. You can download the installer from the link above and install it on your system. After the installation, you can create a new environment for Allo by running the following commands: .. code-block:: console