LLVM–emulator README

• Overview
• Requirements
• Installation
• Usage
  • Example
• License

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.

  $ pip install -r requirements.txt

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:

  $ cd path/to/the/repository/llvm_emulator/
  $ ./emulator.py

Use the -h (--help) flag for information on more options:

  $ ./emulator.py -h

To automatically step through a LLVM file (and be quite verbose about it), you can use the -a (--auto) flag:

  $ ./emulator.py -a path/to/your/file.ll

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

  %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
  }

Then we run the emulator:

  $ ./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

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:

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/>.