Introduction
SNAX is an open-source platform with a hybrid-coupled heterogeneous accelerator-centric architecture. This system allows users to explore various architectural combinations of accelerators packed in a single shared memory. We provide useful setups, scripts, and supporting modules to make it easy to integrate new accelerators. The figure below shows an overview of the SNAX architecture:
SNAX supports several design-time and run-time configurations to support different accelerators and corresponding data layouts. For example, some design-time configurations include: customizing the memory sizes, the interconnect structure connecting the accelerators to memory, the number of Snitch cores controlling accelerators, and so much more. For run-time configuration, we provide data streamers and reshufflers to aid accelerators in handling data layout in memory and data access pattern management.
Outline
In this tutorial, we will explore how to attach your custom accelerator to the SNAX platform. The outline below guides any new user on a simple ALU accelerator example. Have fun!
- In this section, we will describe the design goals for the example.
- There is also a guide on the configurations to change.
- We also describe the overview of the directory structure.
- This section describes a simple ALU processing element that will serve as the accelerator of interest
- We focus on the data path design and control status registers (CSR) that go with it.
- We emphasize the need to comply with the CSR manager and streamer interfaces.
- This section describes the features of our pre-built CSR manager.
- It helps in hiding set-up delays between accelerator runs by introducing a configuration preloading mechanism.
4 - Streamer Design
- This section talks about our design- and run-time configurable streamer.
- Streamer helps streamline data accesses for an accelerator. It decouples the data access with the acceleration computation datapath and introduces a prefetch mechanism to boost the utilization of the accelerator
- This guide shows how to build the architecture.
- We demonstrate how to program the accelerator of interest.
- We also show how to build the program and run simulations.
7 - Other Tools
- There exists tools that can help profile and analyze your design.
8 - Other Designs
- We've used our SNAX platform for various accelerators already.
- In this section, we demonstrate these accelerators and how we profiled them.
- We also show synthesized results of our work to see how the designs turn out.
9 - Summary and Exercise - We summarize the steps of this tutorial. - We also add an exercise for you to tinker around with.
Getting Started
To follow along with the tutorial, we recommend to create a GitHub Codespace. Alternatively, you can also clone the repository locally and use our prebuilt docker container.
Option 1: Github Codespace
Note
It is recommended you open Codespace in Chrome.
Opening a Github Codespace is the most convenient way to get started quickly. To create a new codespace, go to the main repository, and follow code -> codespace -> create codespace. Or access this at SNAX cluster codespace.
This will launch a new window where the container image for the codespace will be built. This can take a couple of minutes but you only run this once. After this, a Visual Studio Code client will be launched in your browser. This system has all the requirements for developing, building, and simulating a SNAX Cluster preinstalled. If you prefer this, you can launch this codespace in the Visual Studio Code desktop client.
After initializing the Codespace, run the following command in VSCode's shell terminal to fetch all necessary sub modules:
git submodule update --init --recursive
Option 2: Cloning the Repository Locally
First, let's clone the main repository. Do not forget to include the --recurse-submodules.
git clone https://github.com/KULeuven-MICAS/snax_cluster.git --recurse-submodules
If you have already cloned the repository without the --recurse-submodules flag, clone its submodules with:
git submodule update --init --recursive
Docker Container
If you locally cloned the repository, we recommend using our pre-built docker container.
docker pull ghcr.io/kuleuven-micas/snax:main
Go to the root of the snax_cluster repository and mount the directory to the container:
docker run -it -v `pwd`:/repo -w /repo ghcr.io/kuleuven-micas/snax:main
Alternatively, you can use map the real path of your working snax_cluster directory:
podman run -it -v `pwd`:`pwd` -w `pwd` ghcr.io/kuleuven-micas/snax:main
This way the container sees the snax_cluster directory and you can run the pre-built packages and installed software.
Installing Packages and Programs Locally
There are several required packages and programs in the container. If you insist on installing these yourself, then you may refer to the Dockerfile for guidance. You can find this at ./util/container/Dockerfile.
Check if The System Works!
To check if the system is working, let's do a quick run for building the HW and SW, then running the program. Do the following from the root of the git directory.
1 - Generate the RTL:
make -C target/snitch_cluster CFG_OVERRIDE=cfg/snax_alu_cluster.hjson rtl-gen
1 - Build the HW:
make -C target/snitch_cluster CFG_OVERRIDE=cfg/snax_alu_cluster.hjson bin/snitch_cluster.vlt -j
2 - Build the SW:
make -C target/snitch_cluster CFG_OVERRIDE=cfg/snax_alu_cluster.hjson sw -j
3 - Run the program:
./target/snitch_cluster/bin/snitch_cluster.vlt ./target/snitch_cluster/sw/apps/snax-alu/build/snax-alu.elf
You should see a log:
VCD wave generation enabled
[fesvr] Wrote 36 bytes of bootrom to 0x1000
[fesvr] Wrote entry point 0x80000000 to bootloader slot 0x1020
[fesvr] Wrote 72 bytes of bootdata to 0x1024
[Tracer] Logging Hart 0 to logs/trace_chip_00_hart_00000.dasm
[Tracer] Logging Hart 1 to logs/trace_chip_00_hart_00001.dasm
Accelerator Done!
Accelerator Cycles: 25
Number of errors: 0