From 552cbf67b361241f345662b4e4a839d52c8f9f71 Mon Sep 17 00:00:00 2001
From: Ben Schreiber <bjschre2@illinois.edu>
Date: Wed, 22 Jan 2020 21:29:15 -0600
Subject: [PATCH] Document the HPVM compilation process

---
 hpvm/test/template/README.md | 37 ++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 hpvm/test/template/README.md

diff --git a/hpvm/test/template/README.md b/hpvm/test/template/README.md
new file mode 100644
index 0000000000..198604817d
--- /dev/null
+++ b/hpvm/test/template/README.md
@@ -0,0 +1,37 @@
+Compilation of a project with HPVM is a multi-step process.
+Let's look at the compilation of the `pipeline` test for gpu as an example.
+
+`clang` is used to produce an LLVM IR file that contains the HPVM intrinsics in the form of function calls.
+```
+/.../hpvm/build/bin/clang -Isrc/ -I -I/.../hpvm/llvm/include -I../include -I/.../hpvm/build/include -ffast-math -O3 -fno-lax-vector-conversions -fno-vectorize -fno-slp-vectorize -I/.../hpvm/llvm/include -I../include -I/.../hpvm/build/include -DDEVICE=GPU_TARGET -emit-llvm -S -o build/main.ll src/main.cc
+```
+
+`opt` is used to invoke the GenVISC pass, which converts the HPVM function calls to LLVM intrinsics.
+```
+/.../hpvm/build/bin/opt -debug-only=genvisc -load LLVMGenVISC.so -genvisc -globaldce -visc-timers-gen build/main.ll -S -o build/main.visc.ll
+```
+
+`opt` is used again to invoke the BuildDFG pass, which converts the textual representation to the internal HPVM representation.
+```
+/.../hpvm/build/bin/opt -debug -load LLVMBuildDFG.so -load LLVMLocalMem.so -load LLVMDFG2LLVM_NVPTX.so -load LLVMDFG2LLVM_X86.so -load LLVMClearDFG.so -localmem -dfg2llvm-nvptx -dfg2llvm-x86 -clearDFG -visc-timers-x86 -visc-timers-ptx -S build/main.visc.ll -o build/pipeline-gpu.host.ll
+```
+
+`llvm-cbe` is a C backend for LLVM. It is used here to create the OpenCL kernel.
+```
+/.../hpvm/build/bin/llvm-cbe -debug build/gpu/main.visc.ll.kernels.ll -o build/gpu/main.visc.ll.kernels.cl
+```
+
+`clang` is used again to compile a separate source file that contains I/O code.
+```
+/.../hpvm/build/bin/clang -Isrc/ -I -I/.../hpvm/llvm/include -I../include -I/.../hpvm/build/include -ffast-math -O3 -fno-lax-vector-conversions -fno-vectorize -fno-slp-vectorize -I/.../hpvm/llvm/include -I../include -I/.../hpvm/build/include -emit-llvm -S -o build/gpu/io.ll src/io.cc
+```
+
+`llvm-link` is used to link against the VISC runtime.
+```
+/.../hpvm/build/bin/llvm-link build/gpu/pipeline-gpu.host.ll build/gpu/io.ll /.../hpvm/llvm/tools/hpvm/projects/visc-rt/visc-rt.ll -S -o build/gpu/pipeline-gpu.linked.ll
+```
+
+`clang++` is used to do the final linking against OpenCL and emit the binary.
+```
+/.../hpvm/build/bin/clang++ -O3 `pkg-config opencv --libs` -lm -lpthread -lrt -lOpenCL -L/software/cuda-9.1/lib64 build/gpu/pipeline-gpu.linked.ll -o pipeline-gpu
+```
\ No newline at end of file
-- 
GitLab