Capstone2LlvmIR

A C++ library and tool for translating binary instructions to LLVM IR using Capstone disassembler.

At the moment, the library can translate the following instruction sets:

• ARM (32-bit + Thumb extension) -- core instruction set.
• Mips (32/64-bit) -- core instruction set.
• PowerPC (32/64-bit) -- core instruction set.
• x86 (16/32/64-bit) -- core instruction set.

This repository contains the following libraries:

• capstone2llvmir -- binary instructions to LLVM IR translation library.
• llvmir-emul -- LLVM IR emulation library used for unit testing. Currently undocumented.

This repository contains the following tools:

• capstone2llvmirtool -- frontend for the capstone2llvmir library.

Usage Example

Capstone2LlvmIR Library

For usage examples of Capstone2LlvmIR library, see implementation of capstone2llvmirtool (in src/capstone2llvmirtool) and capstone2llvmir unit tests (in tests/capstone2llvmir).

Capstone2LlvmIR Tool

To translate two x86 instructions add eax, eax; mov ebx, eax in 32-bit mode located at address 0x1234 into LLVM IR code in file out.ll run:

./capstone2llvmir -a x86 -m 32 -b 0x1234 -t "add eax, eax; mov ebx, eax" -o out.ll

To translate an ARM instruction, in ARM mode, encoded as 04 10 81 e2 located at the default address into LLVM IR code in file out.ll run:

./capstone2llvmir -a arm -m arm -c "04 10 81 e2" -o out.ll

Run ./capstone2llvmir --help to list all the available options.

Requirements

• A compiler supporting C++14
  • On Windows, only Microsoft Visual C++ is supported (version >= Visual Studio 2015).
• CMake (version >= 3.6)

Build and Installation

• Recursively clone the repository (it contains submodules):
  • git clone --recursive https://github.com/avast-tl/capstone2llvmir.git
• Linux:
  • cd capstone2llvmir
  • mkdir build && cd build
  • cmake .. -DCMAKE_INSTALL_PREFIX=<path>
  • make && make install
• Windows:
  • Open MSBuild command prompt, or any terminal that is configured to run the msbuild command.
  • cd capstone2llvmir
  • mkdir build && cd build
  • cmake .. -DCMAKE_INSTALL_PREFIX=<path> -G<generator>
  • msbuild /m /p:Configuration=Release capstone2llvmir.sln
  • msbuild /m /p:Configuration=Release INSTALL.vcxproj
  • Alternatively, you can open capstone2llvmir.sln generated by cmake in Visual Studio IDE.

You must pass the following parameters to cmake:

• -DCMAKE_INSTALL_PREFIX=<path> to set the installation path to <path>.
• (Windows only) -G<generator> is -G"Visual Studio 14 2015" for 32-bit build using Visual Studio 2015, or -G"Visual Studio 14 2015 Win64" for 64-bit build using Visual Studio 2015. Later versions of Visual Studio may be used.

You can pass the following additional parameters to cmake:

• -DCAPSTONE2LLVMIR_DOC=ON to build with API documentation (requires Doxygen and Graphviz, disabled by default).
• -DCAPSTONE2LLVMIR_TOOLS=ON to build with tools (disabled by default).
• -DCAPSTONE2LLVMIR_TESTS=ON to build with tests (disabled by default).
• -DCMAKE_BUILD_TYPE=Debug to build with debugging information, which is useful during development. By default, the project is built in the Release mode. This has no effect on Windows, but the same thing can be achieved by running msbuild with the /p:Configuration=Debug parameter.

Library Use

Adding Capstone2LlvmIR to your project via git submodule

A single target named capstone2llvmir is exposed. It can be used as follows:

target_link_libraries(project-that-needs-capstone2llvmir capstone2llvmir)

Using Capstone2LlvmIR via CMake find_package command

Not supported at the moment.

API Documentation

You can generate the API documentation by yourself. Pass -DCAPSTONE2LLVMIR_DOC=ON to cmake and run make doc.

License

Copyright (c) 2017 Avast Software, licensed under the MIT license. See the LICENSE file for more details.

Capstone2LlvmIR uses third-party libraries or other resources listed, along with their licenses, in the LICENSE-THIRD-PARTY file.

Contributing

See RetDec contribution guidelines.