Adding provenance instrumentation during compilation

Spade's LLVM tracer module provides support for adding provenance instrumentation at function entry and function exit. Finally, the instrumented LLVM bitcode is compiled to native code and linked to into an executable for the target platform.

NOTE: Currently the tool is limited; values of function call arguments are only reported for primitive types.

Setup

1. Install LLVM-3.6 and Clang-3.6. See http://llvm.org/releases/ for installation from sources. On Ubuntu this can be installed using apt-get. It must be noted that the llvm -dev packages are also required. Make sure that the PATH variable is set to the bin directory of the llvm installation. In case of conflicting llvm installations make sure to set the preference in the PATH variable.

2. Install and setup wllvm. See https://github.com/travitch/whole-program-llvm/blob/master/wllvm. The application bitcode to be instrumented can be generated using the 'wllvm' tool.

3. The LLVM_INCLUDE_PATH must be set to the include directory of the llvm headers. The Tracer Module can be built through the SPADE make file using (This should be done after the SPADE kernel is built):

        make build-${OS}-llvm;
   

whereas OS can take on the values from the set {linux, mac, freebsd}

---

How to provenance-enable an application

1. Use the bin/llvm/llvmTrace.sh script to instrument the application bitcode and generate a modified executable with the command:

         ./llvmTrace.sh <inputFile>.bc  <FunctionNamesFile> <outputFile.bc>  ["-instrument-libc"]
   

Parameters:

• inputFile*: Name of the input bitcode module (excluding the .bc extension)
• FunctionNamesFile*: Name of the file with the function names to monitor. A reverse reach-ability analysis is performed on the function list to extract all functions that need to be instrumented. If no specific function monitoring is required. The flag "-no-monitor" can be supplied instead; this would instrument all functions in the input bitcode module.
• outputFile*: Name of the output bitcode module (excluding the .bc extension)
• -instrument-libc (optional): If the flag "-instrument-libc" is specified as the last argument, wrapper functions are created for libc calls. Further Provenance instrumentation is added to these wrapper routines hence logging all libc call arguments across the application.

1. Add the LLVM reporter to the SPADE kernel. (Use add reporter LLVM in the SPADE control client).
2. Run the target application. Function call level provenance will silenty be reported to the SPADE kernel.