diff --git a/README.md b/README.md index 09f09f973b4c1223184b24898a19023dfb394389..acd94086990ccc9e85d2dc63fa8d5a81ae1b08cc 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,8 @@ HPVM is currently at **version 1.0**. For more about what HPVM is, see [our webs [PPoPP'21 paper](https://dl.acm.org/doi/10.1145/3437801.3446108) +## Resources -## Docs [HPVM IR Specification](/hpvm/docs/hpvm-specification.md) [HPVM-C Language Specification](/hpvm/docs/hpvm-c.md) @@ -24,6 +24,7 @@ HPVM is currently at **version 1.0**. For more about what HPVM is, see [our webs [HPVM Compilation Process](/hpvm/docs/compilation.md) ## Dependencies + The following components are required to be installed on your machine to build HPVM. * GCC (>=5.1) @@ -36,25 +37,38 @@ The following components are required to be installed on your machine to build H * CUDA (>=9.1) ## Supported Targets + Supported/tested CPU architectures: + * Intel Xeon E5-2640 * Intel Xeon W-2135 * ARM Cortex A-57 -Supported/tested GPU architectures: +Supported/tested GPU architectures for OpenCL backend: + * Nvidia Quadro P1000 * Nvidia GeForce GTX 1080 +Supported/tested GPU architectures for Tensor Backend: + +* Nvidia Jetson TX2 +* Nvidia GeForce GTX 1080 + HPVM has not been tested but might work on other CPUs supported by LLVM Backend, and GPUs supported by OpenCL such as Intel, AMD, etc. +**NOTE**: Approximations are tuned for Jetson TX2 and same speedups may not exist for other architectures. + +## Getting Started -## Getting source code and building HPVM +### Getting source code and setting up environment + +Checkout HPVM and go to directory `./hpvm` under project root: -Checkout HPVM: ```shell git clone --recursive https://gitlab.engr.illinois.edu/llvm/hpvm.git +cd hpvm/ git checkout approx_hpvm_reorg -cd hpvm/hpvm +cd hpvm/ ``` HPVM needs to be able to find CUDA. @@ -64,64 +78,77 @@ Otherwise, some environment variables are required: * `CUDA_TOOLKIT_PATH` --- Path to the CUDA toolkit * `CUDA_INCLUDE_PATH` --- Path to the CUDA headers -* `CUDA_LIB_PATH` --- Path to CUDA libraries +* `CUDA_LIB_PATH` --- Path to CUDA libraries + +`set_paths.sh` can be used for this. +Modify the values of these variables in `set_paths.sh` according to your system, and source the script: -`hpvm/set_paths.sh` can be used for this. Modify the values of these variables in set_paths.sh and source the script: ```shell source set_paths.sh ``` -HPVM installer script can be used to download, configure and build HPVM along with LLVM and Clang. +HPVM installer script can be used to download, configure and build HPVM along with LLVM and Clang. + ```shell bash install.sh ``` -Post Installation Build the HPVM Compilation Tool `approxhpvm.py` using: -``` -make approxhpvm.py -``` +On launch, the installer asks whether it should also build HPVM. +If HPVM is to be built, the installer asks the number of threads to be used. +The default number of threads used to build HPVM is two (2). + +If you use this automatic build, skip the next section. + +* Specifically, the HPVM installer downloads LLVM, and Clang, copies HPVM source into + 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 to generate OpenCL kernels for GPUs. + +### Manually Build HPVM -Specifically, the HPVM installer downloads LLVM, and Clang, copies HPVM source into -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 -to generate OpenCL kernels for GPUs. +Alternatively, you can manually build HPVM with CMake. +Please note that in this case, +the installer script still *must* be executed to obtain some required components, +but without the build step. -In the beginning of the building process, the installer provides users the choice of automatically or manually building HPVM. -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. +In current directory (`hpvm/`), do -Alternatively, CMake can be run manually using the following steps in ./hpvm-release/hpvm directory. ```shell mkdir build cd build cmake ../llvm [options] +export PATH=$(realpath ./bin):$PATH ``` -**Note** that if the installer script was not used, -you must _manually add `build/bin` directory to your $PATH variable_ (as absolute path). 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. - * -DLLVM_ENABLE_ASSERTIONS=On --- Compile with assertion checks enabled (default is Yes for Debug builds, No for all other build types). -In order to manually build and install HPVM, GNU Make can be run using the following in the build directory. +**Note** that if the installer script was not used, +you must _manually add `build/bin` directory to your $PATH variable_ as absolute path (as shown above). + +Now, compile the HPVM Compilation Tool `approxhpvm.py` using: + ```shell -make -j<number of threads> -make install +make -j<number of threads> approxhpvm.py ``` -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 ./hpvm-release/hpvm directory. +With all the aforementioned steps, HPVM should be built, installed, tested and ready to use. +In particular, `approxhpvm.py` should be an executable command from your command line. + +When not using the installer, you may want to run the regression tests using this script (outside of build directory): + ```shell +cd .. bash scripts/automate_tests.sh ``` -With all the aforementioned steps, HPVM should be built, installed, tested and ready to use. - ## Benchmarks and Tests + 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). @@ -131,4 +158,5 @@ Benchmark descriptions and instructions on how to compile and run them are [here We are also providing [unit tests](/hpvm/test/unitTests) and [regression tests](/hpvm/test/regressionTests). ## Support + All questions can be directed to [hpvm-dev@lists.cs.illinois.edu](mailto:hpvm-dev@lists.cs.illinois.edu). diff --git a/hpvm/scripts/llvm_installer.sh b/hpvm/scripts/llvm_installer.sh index 3ed7fd3a951d27dedc9b84adf82835a0eedbd1e2..b6b71383d56d4d3bb95c829ef7628f422b3b0f27 100755 --- a/hpvm/scripts/llvm_installer.sh +++ b/hpvm/scripts/llvm_installer.sh @@ -208,7 +208,7 @@ if ! $AUTOMATE ; then echo "To complete installation, follow these instructions:" echo " - Create and navigate to a folder \"./build\" " echo " - Run \"cmake ../llvm [options]\". Find potential options in README.md." - echo " - Run \"make -j<number of threads>\" and then \"make install\"" + echo " - Run \"make -j<number of threads> approxhpvm.py\" and then \"make install\"" echo "For more details refer to README.md." echo echo "Exiting." @@ -237,8 +237,8 @@ cd $BUILD_DIR echo cmake ../$LLVM_SRC -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLLVM_TARGETS_TO_BUILD=$TARGET -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR cmake ../$LLVM_SRC -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DLLVM_TARGETS_TO_BUILD=$TARGET -DCMAKE_INSTALL_PREFIX=$INSTALL_DIR -echo make -j$NUM_THREADS -make -j$NUM_THREADS +echo make -j$NUM_THREADS approxhpvm.py +make -j$NUM_THREADS approxhpvm.py #make install if [ -f $BUILD_DIR/tools/hpvm/projects/$HPVM_RT ]; then