Add readme.
This commit is contained in:
cfreksen
parent
fed8e65afc
commit
457559458e
|
|
@ -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, <<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
|
||||
|
||||
Loading…
Reference in New Issue