Capstone Disassembly Framework

Capstone is a high-performance disassembly framework designed for binary analysis and reversing. It provides an architecture-neutral API and detailed instruction decomposition, including semantics like implicit registers read and written.

Key features include:

• Wide Architecture Support: ARM, AArch64, Alpha, ARC, BPF, Ethereum VM, LoongArch, HP PA-RISC (HPPA), M68K, M680X, Mips, MOS65XX, PPC, RISC-V (rv32G/rv64G), SH, Sparc, SystemZ, TMS320C64X, TriCore, Webassembly, XCore, X86 (16, 32, 64), and Xtensa.
• Platform Support: Windows, Mac OSX, iOS, Android, Linux, *BSD, Solaris, etc.
• Design: Thread-safe, implemented in pure C, and suitable for embedding into firmware or OS kernels.
• Bindings: Lightweight bindings available for many languages including Python, C++, Rust, Go, Java, C#, NodeJS, and more.

Capstone is a high-performance disassembly framework designed for binary analysis and reversing.

Key features include:

• Multi-architecture support: ARM, AARCH64 (ARMv8), Mips, PPC, Sparc, SystemZ, XCore, and X86 (including X86_64).
• Detailed instruction analysis: Provides instruction details and semantics, such as lists of implicit registers read and written.
• Cross-platform: Native support for Windows, Mac OSX, iOS, Android, Linux, *BSD, and Solaris.
• Design: Thread-safe, implemented in pure C, and suitable for embedding into firmware or OS kernels.

The bindings/java directory contains test files that demonstrate different ways to use the Capstone API:

• TestBasic.java: Demonstrates the simplest API usage for retrieving basic instruction information, including the address, mnemonic, and operand string.
• Test<arch>.java: Demonstrates how to retrieve architecture-specific information for various supported architectures.

Each Capstone architecture module is divided into two primary functional components:

1. Disassembler logic: Responsible for decoding raw bytes into instructions. This component uses LLVM-based code, including generated state machines, enums, and handwritten logic for operand decoding.
2. Mapping logic: Acts as the interface between the Capstone core and the LLVM code. It performs two main tasks:
   • Mapping LLVM-decoded instructions to the Capstone internal representation.
   • Adding enriched metadata to Capstone instructions, such as operand read/write attributes.

Capstone V6 introduces Auto-Sync, a new update mechanism designed to simplify module updates, facilitate the addition of new architectures, and improve disassembly precision.

Key characteristics of Auto-Sync include:

• LLVM-based updates: Refactored modules are now based on much newer LLVM versions (e.g., LLVM 16 for ARM and PPC, and LLVM 18 for others) compared to the LLVM 7 base used in V5.
• Standardized process: The update process is automated via scripts that allow architecture modules to move closer to the original LLVM code.
• Breaking changes: Because modules are being refactored to fit the Auto-Sync mechanism, users should expect breaking changes when upgrading architectures that have been refactored.
• Long-term goal: The mechanism aims to make Capstone's disassembly quality directly comparable to llvm-objdump.

The vbCapstone.dll provides VB6 access to the Capstone disassembly engine via a stdcall API. This library supports basic disassembly for all processor architectures implemented by Capstone.

Limitations:

• Full instruction details in the VB code are currently only supported for the x86 processor family.
• This implementation was built against Capstone 3.0 rc4. If Capstone structures change in future versions, the VB6 bindings may require adjustments to maintain compatibility.

Updating Capstone via Auto-Sync involves three main stages:

1. Automatic C++ Generation: Changes in auto-generated C++ files (from LLVM TableGen .td files) are handled automatically using a patched LLVM fork that emits C code directly.
2. Semi-automatic Source Translation: Changes in LLVM's handwritten C++ source files are processed through a pipeline:
   • CppTranslator: Replaces C++ syntax with equivalent C syntax to create an intermediate file.
   • Differ: Compares the intermediate file against the existing Capstone C file using Abstract Syntax Tree (AST) parsing. It automatically patches nodes with matching names and presents new differences to the user for decision.
3. Manual Capstone Updates: Any changes specific to Capstone-only files must be performed manually.

To compile the Capstone OCaml bindings on Ubuntu Linux, you must install the ocaml-nox package using apt-get.

$ sudo apt-get install ocaml-nox

Before translating an architecture, you must generate the necessary .inc files from LLVM TableGen.

Prerequisites:

• pip install -e . inside suite/auto-sync/
• A cloned and built llvm-tblgen.
• The architecture must be added to Target.py and handled in llvm-capstone/llvm/utils/TabelGen/PrinterCapstone.cpp::decoderEmitterEmitDecodeInstruction().

Command: Run the following to generate the files:

ASUpdater -s IncGen -a ARCH

Replace ARCH with your architecture name. Check the build directory to verify the generated .inc files.