Package: llvm-minusminus-emulator
OverviewThis 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 meansThere is no guarantee that emulator emulates LLVM– correctly. Various
liberties has been taken to simplify the emulations, e.g. values of
typei64can be arbitrarily large. And there can, of course, be
bugs in the application.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.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 likeclang, if you
want to check types of your generated codeWe, as TAs, do not give support for this emulator.If your generated code works in this emulator, but not in clang,
your generated code is incorrect!We, as TAs, willnotaccept
it.RequirementsThis 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 commandspython3,pip3, etc. to use Python 3 on
such systems (assuming you have installed Python 3).The application uses some third party libraries as indicated inrequirements.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. Lines beginning with a dollar sign ($)
indicate commands you enter into your terminal, other lines are output
from running those commandsGetting Python 3To see if you already have Python 3 installed, try running (the lines
beginning with $):$python--versionPython2.7.14$python3--versionPython3.6.3If one of these commands gives a version number >= 3, you have Python 3
through that command (without--version, of course). In the example
above, I need to use the commandpython3in order to use the correct
version of Python for this emulator.Otherwise, you could try to install Python 3 via your package manager.
Depending on which Linux distribution you use, you could try something
like$aptinstallpython3or$sudoaptinstallpython3Getting pip for Python 3You need pip to (easily) install Python packages. If your Linux
distribution came with Python 2 and pip, the pip you have might not work
for Python 3. Let us first check that:$pip--versionpip9.0.1from/usr/lib/python2.7/site-packages(python2.7)$pip3--versionpip9.0.1from/usr/lib/python3.6/site-packages(python3.6)As with the Python version commands in the last section, I have to usepip3. If I just usedpippackages would be installed for Python
2, which I do not want.Pip should come with newer versions of Python. If you have a new version
of Python, but no pip, you might need to install it seperately. You
could try (depending on your Linux distribution)$aptinstallpython3-pipor$sudoaptinstallpython3-pipInstallationInstallation includesDownloading and installing dependenciesDownloading the emulatorStoring the emulator libraries where your other Python libraries areAdding a small script to easily start the emulatorPip wayThe recommended way to quickly install and use the emulator, is to
install it via pip. The name on PyPI (where pip gets the software from)
isllvm-minusminus-emulator[1].Make sure that you have Python 3 and pip installed (see above). Then
install the emulator by running$pip3installllvm-minusminus-emulatorIf all goes well, you are now ready to use the emulator.Git wayTo get the very latest version, you can do the followingIf you have not already, download the code.$cdpath/to/folder/where/you/want/to/store/the/emulator$gitclonegit@gitlab.com:cfreksen/llvm--emulator.gitTo install the software, you can usepipon the folder containingsetup.py:$cdpath/to/folder/where/you//stored/the/emulator/llvm--emulator$pip3install.You should now be ready to use the software.UninstallingTo remove the emulator, just uninstall via pip:$pip3uninstallllvm-minusminus-emulatorUsageIf installing the emulator went well, a script (llvm--emulator)
should have been added to yourbinfolder. This means that you can
start the emulator (wherever you are), by running that script:$llvm--emulator--helpusage:llvm--emulator[-h]{auto}...AhackyLLVM--emulator/debuggerpositionalarguments:{auto}autoAutomaticallystepthroughllvminagivenfileoptionalarguments:-h,--helpshowthishelpmessageandexitTo automatically step through a LLVM file (and be quite verbose about
it), you can use theautocommand:$llvm--emulatorautopath/to/your/file.llWhen running the emulator you might get messages like the following:WARNING:Couldn't open 'parser.out'. [Errno 13] Permission denied: '/usr/lib/python3.6/site-packages/llvm_emulator/parser.out'
WARNING: Couldn'tcreate'parsetab'.[Errno13]Permissiondenied:'/usr/lib/python3.6/site-packages/llvm_emulator/parsetab.py'This is because the script does not have permission to write files among
your Python libraries. This is because the parser inside the emulator
tries to cache its parsing table (think oftiger.grm.sml) where the
parsing code is located. If does not have permission to do that, it
still parses your LLVM code; it just needs to rebuild the parsing table
next time you run the emulator. These warnings should be safe to ignore.I have tried to fix this issue without success, so hopefully you can
live with a few warning messages.ExampleLet us say, that we have the following LLVM– code insome_file.ll%Ttigermain=type{i64,i64,i64}definei64@tigermain(i64%U_mainSL_8,i64%U_mainDummy_9){%t=alloca%Ttigermain%a=getelementptr%Ttigermain,%Ttigermain*%t,i320,i321storei649,i64*%a%r=loadi64,i64*%a%s=addi64100,%r%b=getelementptr%Ttigermain,%Ttigermain*%t,i320,i320storei64%s,i64*%breti64%s}Then we run the emulator:$llvm--emulator-asome_file.llParsingsome_file.llBeginningexecutionofsome_file.llHeapafterglobalsareallocated:[None]Evaluatingalloca%Ttigermainalloca{i64,i64,i64}-->allocating3cells%t<-1Evaluatinggetelementptr%Ttigermain,%Ttigermain*%t,i320,i321Gepformula:1+0*3+(1)%a<-2Evaluatingstorei649,i64*%aheap[2]<-9Evaluatingloadi64,i64*%aloadheap[2]%r<-9Evaluatingaddi64100,%radd100,9%s<-109Evaluatinggetelementptr%Ttigermain,%Ttigermain*%t,i320,i320Gepformula:1+0*3+0%b<-1Evaluatingstorei64%s,i64*%bheap[1]<-109Evaluatingreti64%sReturning109Steppingdone!Finalssa_env:{'U_mainSL_8':1234,'U_mainDummy_9':5678,'t':1,'a':2,'r':9,'s':109,'b':1}Finalheap:[None,109,9,<<Garbage>>]Programresultedin109after8stepsThis shows which values variables have as they are encountered as well
as the order the instructions are evaluated.AlternativesIf thellvm--emulatorscript does not work for you, you can inspect
it in thepath/to/emulator/repository/bin/folder (assuming you have
the source code. See the section ‘Installation:Git Way’, or look at the
code online on https://gitlab.com/cfreksen/llvm–emulator). It should be
clear enough what the script does, and if you know a bit of Python, you
should be able to tweak it to your needs.Known Issues/Missing FeaturesHere some of the known major issues/missing features are listed. This
list might be updated, should the issues be fixed/the features
implemented:Interactive modeThere is currently no support for stepping through the code one key
press at a time. Similarly, there is no support for inserting
breakpoints, or looking up the current values in memory/registers via
commands.Builtin functionsWhen generating LLVM code from Tiger code, there can be several calls to
functions defined in a file calledruntime.c. Many of these
functions are not implemented in the emulator. However,allocRecord,initArray, andprintare so that will hopefully be enough for
the majority of your LLVM programs.LicenseThe code in this project is licensed under GPLv3+. The full licensing
text can be found in theLICENSEfile, while a small but descriptive
header is:LLVM– Emulator – A simple hacky emulator and debugger for LLVM–
Copyright © 2017 Casper FreksenThis 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, seehttp://www.gnu.org/licenses/.[1]I know the name is ugly, but Python packaging was not happy about the
double dash inllvm--emulator, andllvm-emulatormakes it
sound like it covers the entire LLVM IR language.