#+TITLE: LLVM--emulator README
#+AUTHOR: Casper Freksen
#+OPTIONS: ^:nil

* Overview
  This application is an emulator/debugger for LLVM-- as defined in
  the Compiler course (dOvs) at Aarhus University.

  While I hope that you will find it useful, the tool is being
  provided AS IS, this means
  1) There is no guarantee that emulator emulates LLVM--
     correctly. Various liberties has been taken to simplify the
     emulations, e.g. values of type ~i64~ can be arbitrarily
     large. And there can, of course, be bugs in the application.
  2) Not all parts of LLVM-- has been implemented. While the main set
     of instructions and types has been implemented at this point, you
     might hit a "TODO: Not implemented yet" message.
  3) Many type annotations are being ignored. This means that
     ill-typed LLVM-- programs might be emulated without a
     problem. This can give a false sense of security, so always use a
     tool like ~clang~, if you want to check types of your generated code
  4) We, as TAs, do not give support for this emulator.
  5) *If your generated code works in this emulator, but not in clang,
     your generated code is incorrect!* We, as TAs, will *not* accept
     it.

* Requirements
  This application is written in Python. It was developed in Python
  3.6, but I expected to work for Python 3.5 and above. Note that
  Python 2 is not supported.

  Several Linux distributions have Python 2 as the default. You can
  usually use the commands ~python3~, ~pip3~, etc. to use Python 3 on
  such systems (assuming you have installed Python 3).

  The application uses some third party libraries as indicated in
  =requirements.txt=.

  This project is designed for Linux, though I do not expect there to
  be any issues on other platforms. As a consequence the commands
  given below are designed for a Linux shell.

* Installation
  If you have not already, download the code.
  #+BEGIN_SRC sh
    $ cd path/to/folder/where/you/want/to/store/the/emulator
    $ git clone git@gitlab.com:cfreksen/llvm--emulator.git
  #+END_SRC

  Currently, to install the software you have to install the
  dependencies via ~pip~, e.g.
  #+BEGIN_SRC sh
    $ pip install -r requirements.txt
  #+END_SRC

  You should now be ready to use the software.

  There is currently work being done to use ~setuptools~ to handle
  installing and setting up the application. Once that is done,
  installation and usage will hopefully be more streamlined.

* Usage
  You use the application by entering its directory and envoking the
  emulator script:
  #+BEGIN_SRC sh
    $ cd path/to/the/repository/llvm_emulator/
    $ ./emulator.py
  #+END_SRC

  Use the ~-h~ (~--help~) flag for information on more options:
  #+BEGIN_SRC sh
    $ ./emulator.py -h
  #+END_SRC

  To automatically step through a LLVM file (and be quite verbose
  about it), you can use the ~-a~ (~--auto~) flag:
  #+BEGIN_SRC sh
    $ ./emulator.py -a path/to/your/file.ll
  #+END_SRC

  As mentioned above, there is work being done on using
  ~setuptools~. This will affect how the emulator can be invoked. The
  hope is that it will be installed into your =bin= folder, so that
  you can use the emulator without having to navigate to it.

** Example
   Let us say, that we have the following LLVM-- code in =some_file.ll=
   #+BEGIN_SRC llvm
     %Ttigermain = type { i64, i64, i64 }

     define i64 @tigermain (i64 %U_mainSL_8, i64 %U_mainDummy_9) {
         %t = alloca %Ttigermain
         %a = getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 1
         store i64 9, i64* %a
         %r = load i64, i64* %a
         %s = add i64 100, %r
         %b = getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 0
         store i64 %s, i64* %b
         ret i64 %s
     }
   #+END_SRC

   Then we run the emulator:
   #+BEGIN_SRC sh
     $ ./emulator.py -a ../some_file.ll
     Parsing ../some_file.ll
     Beginning execution of ../some_file.ll
     Heap after globals are allocated:
     [None]

     Evaluating alloca %Ttigermain
     alloca {i64, i64, i64}  -->  allocating 3 cells
     %t <- 1

     Evaluating getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 1
     Gep formula: 1 + 0 * 3 + (1)
     %a <- 2

     Evaluating store i64 9, i64* %a
     heap[2] <- 9

     Evaluating load i64, i64* %a
     load heap[2]
     %r <- 9

     Evaluating add i64 100, %r
     add 100, 9
     %s <- 109

     Evaluating getelementptr %Ttigermain, %Ttigermain* %t, i32 0, i32 0
     Gep formula: 1 + 0 * 3 + 0
     %b <- 1

     Evaluating store i64 %s, i64* %b
     heap[1] <- 109

     Evaluating ret i64 %s
     Returning 109

     Stepping done!
     Final ssa_env: {'U_mainSL_8': 1234, 'U_mainDummy_9': 5678, 't': 1, 'a': 2, 'r': 9, 's': 109, 'b': 1}
     Final heap: [None, 109, 9, <<Garbage>>]
     Program resulted in 109 after 8 steps
   #+END_SRC

   This shows which values variables have as they are encountered as
   well as the order the instructions are evaluated.

* License
  The code in this project is licensed under GPLv3+. The full
  licensing text can be found in the ~LICENSE~ file, while a small but
  descriptive header is:
  #+BEGIN_QUOTE
  LLVM-- Emulator -- A simple hacky emulator and debugger for LLVM--
  Copyright © 2017  Casper Freksen

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  #+END_QUOTE