README.md 3.6 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
8
9

## Paper

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

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

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

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

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

22
23
24
25
* GCC (>=5.1.0)
* CMake (>=3.4.3)
* Python (>=2.7)
* GNU Make (>=3.79.1)
Adel Ejjeh's avatar
Adel Ejjeh committed
26
* CUDA (>= 9.1) (only required for GPU support)
Prakalp Srivastava's avatar
Prakalp Srivastava committed
27

Akash Kothari's avatar
Akash Kothari committed
28
## Getting source code and building HPVM
29

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

36
HPVM installer script can be used to download, configure and build HPVM along with LLVM and other subprojects including Clang. 
Prakalp Srivastava's avatar
Prakalp Srivastava committed
37
```shell
Akash Kothari's avatar
Akash Kothari committed
38
cd hpvm
Akash Kothari's avatar
Akash Kothari committed
39
bash install.sh
Prakalp Srivastava's avatar
Prakalp Srivastava committed
40
```
Akash Kothari's avatar
Akash Kothari committed
41
Specifically, the HPVM installer downloads LLVM, Clang, libcxx and libcxxabi, copies HPVM source into 
Adel Ejjeh's avatar
Adel Ejjeh committed
42
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 
43
44
45
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. 
Akash Kothari's avatar
Akash Kothari committed
46
47
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.
48
49
50

Alternatively, CMake can be run manually.
```shell
Akash Kothari's avatar
Akash Kothari committed
51
52
mkdir build
cd build
53
54
55
56
57
58
59
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
60

61
* -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
62

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

In the end of the installation process, the installer automatically runs all the regression tests to ensure that the installation is
successful. If HPVM is built and installed manually, the tests can be automatically run by executing the following step from the 
current directory.
```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