README.md 3.79 KB
Newer Older
Akash Kothari's avatar
Akash Kothari committed
1
# The HPVM Compiler Infrastructure
Prakalp Srivastava's avatar
Prakalp Srivastava committed
2

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

The README briefly describes how to get started with building and installing HPVM. It also provides a
Akash Kothari's avatar
Akash Kothari committed
6
benchmark suite to test the compiler infrastructure.
Prakalp Srivastava's avatar
Prakalp Srivastava committed
7

Akash Kothari's avatar
Akash Kothari committed
8
9
HPVM is currently at version 0.5. For more about what HPVM is, see [our website](https://publish.illinois.edu/hpvm-project/).

Prakalp Srivastava's avatar
Prakalp Srivastava committed
10
11
## Paper

Adel Ejjeh's avatar
Adel Ejjeh committed
12
[PPoPP'18 paper](https://dl.acm.org/doi/pdf/10.1145/3200691.3178493)
13

bjschre2's avatar
bjschre2 committed
14
## Docs
Adel Ejjeh's avatar
Adel Ejjeh committed
15
[HPVM IR Specification](/hpvm/docs/hpvm-specification.md)
bjschre2's avatar
bjschre2 committed
16
17
18

[HPVM-C Language Specification](/hpvm/docs/hpvm-c.md)

Adel Ejjeh's avatar
Adel Ejjeh committed
19
20
[HPVM Compilation Process](/hpvm/docs/compilation.md)

Prakalp Srivastava's avatar
Prakalp Srivastava committed
21
## Dependencies
Adel Ejjeh's avatar
Adel Ejjeh committed
22
The following components are required to be installed on your machine to build HPVM.
Prakalp Srivastava's avatar
Prakalp Srivastava committed
23

24
25
26
27
* GCC (>=5.1.0)
* CMake (>=3.4.3)
* Python (>=2.7)
* GNU Make (>=3.79.1)
28
* OpenCL (>=1.0.0) or CUDA (>=9.1, only required for GPU support)
Prakalp Srivastava's avatar
Prakalp Srivastava committed
29

Akash Kothari's avatar
Akash Kothari committed
30
## Getting source code and building HPVM
31

Akash Kothari's avatar
Akash Kothari committed
32
Checkout HPVM:
33
```shell
Yifan Zhao's avatar
Yifan Zhao committed
34
git clone https://gitlab.engr.illinois.edu/llvm/hpvm-release.git/
Akash Kothari's avatar
Akash Kothari committed
35
cd hpvm-release/hpvm
Prakalp Srivastava's avatar
Prakalp Srivastava committed
36
```
Prakalp Srivastava's avatar
Prakalp Srivastava committed
37

Akash Kothari's avatar
Akash Kothari committed
38
HPVM installer script can be used to download, configure and build HPVM along with LLVM and Clang. 
Prakalp Srivastava's avatar
Prakalp Srivastava committed
39
```shell
Akash Kothari's avatar
Akash Kothari committed
40
bash install.sh
Prakalp Srivastava's avatar
Prakalp Srivastava committed
41
```
Akash Kothari's avatar
Akash Kothari committed
42
Specifically, the HPVM installer downloads LLVM, and Clang, copies HPVM source into 
Adel Ejjeh's avatar
Adel Ejjeh committed
43
llvm/tools and builds the entire tree. It also builds a modified LLVM C-Backend, based on the one maintained by [Julia Computing](https://github.com/JuliaComputing/llvm-cbe), as a part of HPVM and is currently used 
44
45
46
to generate OpenCL kernels for GPUs.

In the beginning of the building process, the installer provides users the choice of automatically or manually building HPVM. 
47
48
If HPVM is selected to be built automatically, the installer allows users to type in the number of threads they want to use. 
The default number of threads used to build HPVM is two.
49

Akash Kothari's avatar
Akash Kothari committed
50
Alternatively, CMake can be run manually using the following steps in ./hpvm-release/hpvm directory.
51
```shell
Akash Kothari's avatar
Akash Kothari committed
52
53
mkdir build
cd build
54
55
56
57
58
59
60
cmake ../llvm [options]
```
Some common options that can be used with CMake are:

* -DCMAKE_INSTALL_PREFIX=directory --- Specify for directory the full pathname of where you want the HPVM tools and libraries to be installed.

* -DCMAKE_BUILD_TYPE=type --- Valid options for type are Debug, Release, RelWithDebInfo, and MinSizeRel. Default is Debug.
Prakalp Srivastava's avatar
Prakalp Srivastava committed
61

62
* -DLLVM_ENABLE_ASSERTIONS=On --- Compile with assertion checks enabled (default is Yes for Debug builds, No for all other build types).
Akash Kothari's avatar
Akash Kothari committed
63

Akash Kothari's avatar
Akash Kothari committed
64
In order to manually build and install HPVM, GNU Make can be run using the following in the build directory.
Prakalp Srivastava's avatar
Prakalp Srivastava committed
65
```shell
Akash Kothari's avatar
Akash Kothari committed
66
67
make -j<number of threads>
make install
Prakalp Srivastava's avatar
Prakalp Srivastava committed
68
```
69
70

In the end of the installation process, the installer automatically runs all the regression tests to ensure that the installation is
Akash Kothari's avatar
Akash Kothari committed
71
successful. If HPVM is built and installed manually, the tests can be automatically run by executing the following step from the ./hpvm-release/hpvm directory.
72
73
74
75
```shell
bash scripts/automate_tests.sh
```

Akash Kothari's avatar
Akash Kothari committed
76
With all the aforementioned steps, HPVM should be built, installed, tested and ready to use.
Prakalp Srivastava's avatar
Prakalp Srivastava committed
77

Adel Ejjeh's avatar
Adel Ejjeh committed
78
## Benchmarks and Tests
Adel Ejjeh's avatar
Adel Ejjeh committed
79
80
81
82
83
84
We are providing the following [HPVM benchmarks](/hpvm/test/benchmarks):
* Select benchmarks from the [Parboil](http://impact.crhc.illinois.edu/parboil/parboil.aspx) benchmark suite, located under [test/benchmarks/parboil](/hpvm/test/benchmarks/parboil).
* An edge detection pipeline benchmark, located under [test/benchmarks/pipeline](/hpvm/test/benchmarks/pipeline).
* A Camera ISP pipeline, located under [test/benchmarks/hpvm-cava](/hpvm/test/benchmarks/hpvm-cava), adapted from C code provided from our collaborators at [Harvard](http://vlsiarch.eecs.harvard.edu).

Benchmark descriptions and instructions on how to compile and run them are [here](/hpvm/test/benchmarks).
Prakalp Srivastava's avatar
Prakalp Srivastava committed
85

Yifan Zhao's avatar
Yifan Zhao committed
86
We are also providing [unit tests](/hpvm/test/unitTests) and [regression tests](/hpvm/test/regressionTests).
Adel Ejjeh's avatar
Adel Ejjeh committed
87

Adel Ejjeh's avatar
Adel Ejjeh committed
88