README.md 4.24 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
31

## Supported Targets
Akash Kothari's avatar
Akash Kothari committed
32
33
34
35
36
37
38
39
40
41
Supported/tested CPU architectures:
* Intel Xeon E5-2640
* Intel Xeon W-2135
* ARM Cortex A-57

Supported/tested GPU architectures:
* Nvidia Quadro P1000
* Nvidia GeForce GTX 1080

It has not been tested on but is likely to support other CPU targets, and other GPUs supported by OpenCL such those by Intel, AMD, etc.
Akash Kothari's avatar
Akash Kothari committed
42
43


Akash Kothari's avatar
Akash Kothari committed
44
## Getting source code and building HPVM
45

Akash Kothari's avatar
Akash Kothari committed
46
Checkout HPVM:
47
```shell
Yifan Zhao's avatar
Yifan Zhao committed
48
git clone https://gitlab.engr.illinois.edu/llvm/hpvm-release.git/
Akash Kothari's avatar
Akash Kothari committed
49
cd hpvm-release/hpvm
Prakalp Srivastava's avatar
Prakalp Srivastava committed
50
```
Prakalp Srivastava's avatar
Prakalp Srivastava committed
51

Akash Kothari's avatar
Akash Kothari committed
52
HPVM installer script can be used to download, configure and build HPVM along with LLVM and Clang. 
Prakalp Srivastava's avatar
Prakalp Srivastava committed
53
```shell
Akash Kothari's avatar
Akash Kothari committed
54
bash install.sh
Prakalp Srivastava's avatar
Prakalp Srivastava committed
55
```
Akash Kothari's avatar
Akash Kothari committed
56
Specifically, the HPVM installer downloads LLVM, and Clang, copies HPVM source into 
Adel Ejjeh's avatar
Adel Ejjeh committed
57
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 
58
59
60
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. 
61
62
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.
63

Akash Kothari's avatar
Akash Kothari committed
64
Alternatively, CMake can be run manually using the following steps in ./hpvm-release/hpvm directory.
65
```shell
Akash Kothari's avatar
Akash Kothari committed
66
67
mkdir build
cd build
68
69
70
71
72
73
74
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
75

76
* -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
77

Akash Kothari's avatar
Akash Kothari committed
78
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
79
```shell
Akash Kothari's avatar
Akash Kothari committed
80
81
make -j<number of threads>
make install
Prakalp Srivastava's avatar
Prakalp Srivastava committed
82
```
83
84

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
85
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.
86
87
88
89
```shell
bash scripts/automate_tests.sh
```

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

Adel Ejjeh's avatar
Adel Ejjeh committed
92
## Benchmarks and Tests
Adel Ejjeh's avatar
Adel Ejjeh committed
93
94
95
96
97
98
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
99

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

102
## Support
Akash Kothari's avatar
Akash Kothari committed
103
All questions can be directed to [hpvm-dev@lists.cs.illinois.edu](mailto:hpvm-dev@lists.cs.illinois.edu).
104

Adel Ejjeh's avatar
Adel Ejjeh committed
105