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.

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

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.

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

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

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

target_link_libraries(project-that-needs-capstone2llvmir capstone2llvmir)

Not supported at the moment.

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

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.

See RetDec contribution guidelines.