README.md

# The HPVM Compiler Infrastructure

[![Documentation Status](https://readthedocs.org/projects/hpvm/badge/?version=latest)](https://hpvm.readthedocs.io/en/latest/?badge=latest)
[![pipeline status](https://gitlab.engr.illinois.edu/llvm/hpvm/badges/hpvm-release-exp/pipeline.svg)](https://gitlab.engr.illinois.edu/llvm/hpvm/-/commits/hpvm-release-exp)

This repository contains the source code and documentation for the HPVM Compiler Infrastructure.

HPVM is a compiler for heterogeneous parallel system.
For more about what HPVM is, see [our website](https://publish.illinois.edu/hpvm-project/)
and publications:
[PPoPP'18 paper](https://dl.acm.org/doi/pdf/10.1145/3200691.3178493),
[OOPSLA'19 paper](https://dl.acm.org/doi/10.1145/3360612),
[PPoPP'21 paper](https://dl.acm.org/doi/10.1145/3437801.3446108).

Read our [online documentation](https://hpvm.readthedocs.io/en/latest/)
for how to build, install, and use HPVM.

HPVM is currently at **version 1.0**.

## Getting Started

### Dependencies

The following components are mandatory for building HPVM:
- GCC (>=5.1)
- CMake (>=3.17)
- GNU Make (>=3.79) or Ninja (>=1.10)

### Building HPVM

1. Install [Anaconda](https://www.anaconda.com/), a Python package manager. This provides the command `conda`.

1. Clone this branch (`hpvm-release-epochs0`) of this repository:

    ```bash
    git clone -b hpvm-release-epochs0 --single-branch https://gitlab.engr.illinois.edu/llvm/hpvm.git
    ```

1. Find `env.yaml` in the repo's root, and use conda to create a virtual environment with Python 3.7 and all required packages installed:

    ```bash
    cd hpvm/
    conda env create -n hpvm -f ./env.yaml
    conda activate hpvm
    ```

1. Change directory to `./hpvm` in the repo and run the installer:

    ```bash
    cd hpvm/; ./install.sh
    ```

    This will download additional dependencies, configure HPVM and build HPVM.

    - If you have `ninja` installed (in the place of `make`),
      you may use `./install.sh --ninja` to build HPVM with ninja.

### Generating NVDLA Buffer from PyTorch DNN

Run `test/epoch_dnn/main.py` to generate the PyTorch DNN defined at `test/epoch_dnn/torch_dnn/miniera.py` into NVDLA,
and evaluate it on real hardware:

```bash
cd test/epoch_dnn; python main.py
```

This script will run through the whole code generation (putting everything under `/tmp/miniera`) and evaluation, including
1. Generate quantization scale `calib.txt` for INT8 quantization;
1. Export DNN to NVDLA buffer `hpvm-mod.nvdla`;
1. Select a sample of images from the dataset and put them as JPG files (`images/$idx_$label.jpg`);
   for example, the 0th image which has label 1 will be `images/0000_1.jpg`;
1. Copy NVDLA model and images to an NVDLA device via SCP;
1. Run the NVDLA model on every image we sampled;
1. Display the accuracy of this model.

## HPVM Scheduler Backend

We provide the HPVM Backend pass `DFG2LLVM_EPOCHS` which converts those Dataflow Graph (DFG) nodes which represent specific
tasks from the scheduler's task library (e.g FFT, Viterbi). To specify that a particular node corresponds to a scheduler
task, users must specify the target hint to node be `EPOCHS_TARGET`.

`__hpvm__hint(EPOCHS_TARGET)`

If a particular node in the DFG is marked as above, the `DFG2LLVM_EPOCHS` backend pass would then identify which task from
the scheduler's task library that node corresponds by using the user specified call to `__hpvm__task`. For example, 
to specify that a node represents a Vitterbi Task in the accelerator, the following call will be used:

`__hpvm__task(VIT_TASK)`

Using this information, alongside a task library configuration file (which describes the specific scheduler api to set-up 
and execute each task), the `DFG2LLVM_EPOCHS` pass generates the appropriate task specific api calls while respecting
the task inter-dependency constraints (as denoted by the structure of the HPVM Dataflow Graph).

To add a new task type to this pass, users must simply add a new task type entry to `__hpvm__task` and create the
entry for the name of the specific scheduler api calls to the task library configuration file.

Additionally we provide the notion of node criticality which enable optionally distinguishing which nodes should be prioritised
by the scheduler. Users can provide this optional criticality argument to the `__hpvm__createNodeND` call. The supported criticalities
, in increasing criticality, are:
1. `HPVM_BASE` (Default)
2. `HPVM_ELEVATED`
3. `HPVM_CRITICAL`


## Support

All questions can be directed to [hpvm-dev@lists.cs.illinois.edu](mailto:hpvm-dev@lists.cs.illinois.edu).