This tool statically (AOT) translates (or raises) binaries to LLVM IR.
Llvm-mctoll
is capable of raising X86-64 and Arm32 Linux/ELF libraries and executables to LLVM IR.
Raising Windows, OS X and C++ binaries needs to be added. At this time X86-64 support is more mature than Arm32.
Development and testing are done on Ubuntu 18.04. Other platforms that are expected to work are Ubuntu 16.04, Ubuntu 17.04, Ubuntu 17.10, CentOS 7.5, Debian 10, Windows 10, and OS X.
Triple | VarArgs | FuncProto | StackFrame | JumpTables | SharedLibs | C++ |
---|---|---|---|---|---|---|
x86_64-linux | X | X | X | X | X | |
arm-linux | X | X | X | X | X |
- VarArgs: function calls with variable arguments (such as printf)
- FuncProto: function prototype discovery
- StackFrame: stack frame abstraction
- JumpTables: switch statements with jump tables
- SharedLibs: shared libraries
- C++: vtables, name mangling and exception handling
SIMD instructions such as SSE, AVX, and Neon cannot be raised at this time. For X86-64 you can sometimes work around this issue by compiling the binary to raise with SSE disabled (clang -mno-sse
).
Most testing is done using binaries compiled for Linux using LLVM. We have done only limited testing with GCC compiled code.
There are no dependencies outside of LLVM to build llvm-mctoll
. The following instructions assume you will build LLVM with Ninja.
Support for raising X86-64 and Arm32 binaries is enabled by building LLVM's X86 and ARM targets. The tool is not built unless one of the X86 or ARM LLVM targets are built.
-
On Linux and OS X build from a command prompt such as a bash shell. On Windows build from an
x64 Native Tools Command Prompt
. See LLVM's Visual Studio guide. -
Clone the LLVM and mctoll git repositories
git clone -b master https://github.com/llvm/llvm-project.git
cd llvm-project && git clone -b master https://github.com/microsoft/llvm-mctoll.git llvm/tools/llvm-mctoll
- The commit recorded in
LLVMVersion.txt
is the tested version of LLVM to build against. If you use a different version LLVM you might encounter build errors.
git checkout <hash from LLVMVersion.txt>
- Run cmake to create a ninja project then build the
llvm-mctoll
target. See LLVM CMake Variables for more information on LLVM's cmake options.
mkdir build && cd build
cmake -G "Ninja" -DLLVM_TARGETS_TO_BUILD="X86;ARM" -DLLVM_ENABLE_PROJECTS="clang;lld" -DLLVM_ENABLE_ASSERTIONS=true -DCMAKE_BUILD_TYPE=Release ../llvm
ninja llvm-mctoll && ninja lld
- Run the unit tests (Linux only)
ninja check-mctoll
Command | Description |
---|---|
-d <binary> |
Generate LLVM IR for a binary and place the result in <binary>-dis.ll |
--filter-functions-file=<file> |
Text file with C functions to exclude or include during raising |
-print-after-all |
Print the LLVM IR after each pass of the raiser |
This is what you came here for :-). Please file an issue if you find a problem.
llvm-mctoll -d a.out
You can specify the C functions to include or exclude during raising with the --filter-functions-file
option.
llvm-mctoll -d --filter-functions-file=restrict.txt a.out
Provide a plain text file with exclude-functions
and include-functions
sections. Inside each section list the file and function prototype seperated by a colon. Use LLVM IR function types when defining the return and argument types for a function prototype. Here is a simple example.
; exclude `int bar(int)` defined in a.out
exclude-functions {
a.out:i32 bar(i32)
}
; include `int foo(void)` defined in a.out
include-functions {
a.out:i32 foo(void)
}
If you build llvm-mctoll
with assertions enabled you can print the LLVM IR after each pass of the raiser to assist with debugging.
llvm-mctoll -d -print-after-all a.out
The easiest way to check the raised LLVM IR <binary>-dis.ll
is correct is to compile the IR to an executable using clang
and run the resulting executable. The tests in the repository follow this methodology.
Please use the following reference when citing this work Raising Binaries to LLVM IR with MCTOLL (WIP)
@inproceedings{10.1145/3316482.3326354,
author = {Yadavalli, S. Bharadwaj and Smith, Aaron},
title = {Raising Binaries to LLVM IR with MCTOLL (WIP Paper)},
year = {2019},
isbn = {9781450367240},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3316482.3326354},
doi = {10.1145/3316482.3326354},
booktitle = {Proceedings of the 20th ACM SIGPLAN/SIGBED International Conference on Languages, Compilers, and Tools for Embedded Systems},
pages = {213โ218},
numpages = {6},
keywords = {Code Generation, LLVM IR, Binary Translation},
location = {Phoenix, AZ, USA},
series = {LCTES 2019}
}
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.