RANGE ANALYSIS OF POINTERS
============================================================
------------------------------------------------------------
Artifact evaluation
------------------------------------------------------------

INTRODUCTION
............

This virtual machine contains the code and execution scripts 
for the work presented in the article Range Analysis of 
Pointers. It sees pointers as base plus integers offsets,
so it's possible to disambiguate pointers by their offsets
also.

In the desktop folder you find ways to run our analysis with
any source code of your choosing and also run the benchmarks
we presented in the paper.

THE CODE
........

The code from this work can be found inside llvm's build and
source at the home directory for the user artifact. In 
~/llvm/lib/Ecosoc/ you can find the three, non-llvm standard,
passes used for the experiments. SSIfy is a pass that 
transforms the program to e-SSA form. llvm-sra is the symbolic
analysis we've used. And, finally, rbaa is the llvm pass that
implements our analysis. You can find llvm-sra in the github
repository:
https://github.com/henry-nazare/llvm-sra
You can find rbaa in the github repository:
https://github.com/Uncannytable/rbaa
We've used llvm's 3.5 version.

GETTING STARTED
...............

The artifcat is provided as a Virtual Machine image. To use the artifact, you
need to dowload and install the VirtualBox VM player at
https://www.virtualbox.org/wiki/Downloads . After downloading and installing
VirtualBox, to run the VM image do the following:
  - download and uncompress the VM image
  - open VirtualBox
  - create a new virtual machine, by clicking in "Machine"->"New..."
  - give a name to the new VM, by filling the "Name" field
  - in "Type", select "Linux"
  - in "Version", select "Ubuntu (64 bit)"
  - click "continue", select the desired amount of RAM memory, then click
    "continue" again
  - in the hard drive selection screen, select the option "Use an existing
    virtual hard drive file", then select the .vdi file containing the VM image
    that you just downloaded
  - your Virtual Machine is ready to use! To start, simply double-click it in
    the VirtualBox VM list

If the VM prompts for a username and password. Use the following
combination:
login: artifact
password: artifact

RUNNING EXAMPLES
................

At the folder ExecuteExample in the Desktop you'll find a script 
that compilesan example program you wish to run. On running 
compile.sh and all scripts in this folder you must pass as first 
parameter the name of the C source file you wish to test without any 
extensions (if alias.c, the first parameter should be alias only). 

After compilation you can run rbaa.sh basicaa.sh and 
basicaa+rbaa.sh which run the analyses specified in their names.
An example source code is provided in the folder and it 
illustrates an advantage of our analysis over llvm's standard
analysis. But you can run any example source code you wish.

Since our analysis, in its implementation, manipulates pointer
dependence graphs, the execution of rbaa in this folder will
present .dot files with these dependence graphs (before and 
after), making it easier to visualize how the analysis 
manipulated them and it's results.

The clean.sh script will remove all files created by the
other scripts.


RUNNING THE BENCHMARKS
......................

In the folder ExecuteBenchmarks you'll find the scripts that
run the benchmarks used in the paper. Upon finishing, each of them
will have copied the results to the folder. It is that straight 
forward. We use llvm's test suite to simplify benchmarking. For
more information about llvm's testing suite acces:
http://llvm.org/docs/TestingGuide.html

Keep in mind that these experiments can take a long time to run, mainly because
they are being executed in a Virtual Machine.

The clean.sh script will remove all files created by the
other scripts, and make clean the benchmarks at llvm's test
suite.

THE OUTPUT
----------

The output for the analysis is very simple. We use the aa-eval
pass to compare, within the samefunction, all possible pairs of pointers
and return how many comparisons issued a NoAlias response, MayAlias
or MustAlias.