diff --git a/README b/README new file mode 100644 index 0000000..7d3853f --- /dev/null +++ b/README @@ -0,0 +1,164 @@ +# -*- mode: org; -*- + +#+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 are 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 indicated as 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 + 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 + + 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, <>] + 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 . + #+END_QUOTE +