README

--------------------------------------------------------------
                  AST - Extractor for LLVM
                          (axtor)
--------------------------------------------------------------
date    : 15.03.17
author  : Simon Moll


##### Introduction #####
This is the source-code of the AST-extractor (axtor) for the Low-Level Virtual
Machine (LLVM). Axtor takes a generic LLVM-Bitcode module and generates
high-level control-flow structures for its functions.
For detailed information on the algorithm refer to the author's Bachelor thesis [1].
Information about the LLVM can be found on http://llvm.org/ .


##### Remarks #####
Has only been tested on Arch Linux. Although,
the OpenCL backend and core library should work out of the box on other OSes
as well.

##### Build Prerequisites #####
LLVM 4.0 (release)


##### Build Instructions #####
This project is realised as a LLVM subproject and can be build
according to the generic build instructions found on the LLVM website.
Follow the instructions below to run OpenCL applications with
the "loop" driver (found in tools/axtorOCLDriver).

##### Loop Driver Build Instructions (Linux only) #####
To get it all working, proceed as follows:
1.) Checkout the project (e.g. into LLVM's projects/ folder)
2.) Patch your Clang installation using the patches provided (folder patches/)
3.) Rebuild Clang
4.) Configure & build Axtor

To run an executable with the loop driver, do as follows:
1.) Make LLVM_PATH point to the LLVM binary directory
2.) Run the OpenCL application with
	LD_PRELOAD=<Path/To/libaxtorOpenCLDriver.so> <OpenCLApplication>


##### Project structure #####

lib/axtor/ - AST-Extractor

	The core library of Axtor. This contains all facilites for buildling
	high-level control-flow structures from LLVM-bitcode. Along with it, come
	header files for writing serialization backends.


lib/axtor_ocl/ -  OpenCL backend for Axtor

	The OpenCL backend based on the AST-extractor serialization interface. Also
	includes a custom header for the Clang OpenCL Frontend. 
	
	
lib/axtor_glsl/ - (unreleased) GLSL backend for Axtor 

	The GLSL backend based on Axtor. Not yet ported to LLVM-svn, but will
	follow.


tools/extractor/

	Tool for running axtor from the shell.


tools/oclang/ - OpenCL LLVM frontend

	Passes command line arguments to clang with the OpenCL frontend enabled.
	
	
tools/axtorOCLDriver/ - driver for OpenCL kernel manipulation

	OpenCL driver wrapper for source-to-source kernel transformations.
	Loads OpenCL source-code into LLVM bitcode and serializes it back
	for execution.
	To be preloaded before an actual OpenCL implementation. This requires
	both the extractor and oclang. 
	(read tools/axtorOCLDriver/README for details).
	
tools/axtorIntrinsicHeaders

	Installs headers for using OCL/GLSL builtin functions with C++/C through Clang. After installations,
	these headers can be found in the llvm/include directory "axtor_glsl/GLSL_Intrinsics.h"
	"axtor_ocl/OpenCL_Intrinsics.h", respectively.
	
	
##### References #####
[1] Simon Moll, "Decompilation of LLVM IR", Bachelor Thesis
	(http://www.cdl.uni-saarland.de/publications/theses/moll_bsc.pdf)