zydis

Fast and lightweight x86/x86-64 disassembler and code generation library

3,363

431

3,363

View on GitHub

Top Related Projects

unicorn

7,468

Unicorn CPU emulator framework (ARM, AArch64, M68K, Mips, Sparc, PowerPC, RiscV, S390x, TriCore, X86)

Capstone disassembly/disassembler framework for ARM, ARM64 (ARMv8), Alpha, BPF, Ethereum VM, HPPA, LoongArch, M68K, M680X, Mips, MOS65XX, PPC, RISC-V(rv32G/rv64G), SH, Sparc, SystemZ, TMS320C64X, TriCore, Webassembly, XCore and X86.

udis86

1,012

Disassembler Library for x86 and x86-64

Quick Overview

Zydis is a fast and lightweight x86/x86-64 disassembler library written in C. It provides a user-friendly API for disassembling machine code into human-readable assembly instructions, supporting a wide range of instruction sets including legacy and modern x86 extensions.

Pros

High performance and low memory footprint
Extensive instruction set support, including the latest x86 extensions
Cross-platform compatibility (Windows, macOS, Linux)
Well-documented API with multiple language bindings

Cons

Limited to x86/x86-64 architectures
Requires some knowledge of assembly and machine code concepts
May require manual updates to support new instruction set extensions

Code Examples

Basic disassembly:

#include <Zydis/Zydis.h>

int main()
{
    ZyanU8 machine_code[] = {
        0x48, 0x89, 0x5C, 0x24, 0x10, // mov [rsp+10h], rbx
        0x48, 0x89, 0x74, 0x24, 0x18, // mov [rsp+18h], rsi
        0x55,                         // push rbp
        0x57                          // push rdi
    };

    ZydisDecoder decoder;
    ZydisDecoderInit(&decoder, ZYDIS_MACHINE_MODE_LONG_64, ZYDIS_ADDRESS_WIDTH_64);

    ZydisFormatter formatter;
    ZydisFormatterInit(&formatter, ZYDIS_FORMATTER_STYLE_INTEL);

    ZyanU64 runtime_address = 0x007FFFFFFF400000;
    ZyanUSize offset = 0;
    ZydisDecodedInstruction instruction;

    while (ZYAN_SUCCESS(ZydisDecoderDecodeBuffer(&decoder, machine_code + offset,
        sizeof(machine_code) - offset, &instruction)))
    {
        char buffer[256];
        ZydisFormatterFormatInstruction(&formatter, &instruction, buffer, sizeof(buffer),
            runtime_address);
        printf("%016" PRIX64 " %s\n", runtime_address, buffer);

        offset += instruction.length;
        runtime_address += instruction.length;
    }

    return 0;
}

Instruction encoding:

#include <Zydis/Zydis.h>

int main()
{
    ZydisEncoder encoder;
    ZydisEncoderInit(&encoder);

    ZydisEncoderRequest request;
    ZydisEncoderRequestInit(&request, ZYDIS_MACHINE_MODE_LONG_64);

    request.mnemonic = ZYDIS_MNEMONIC_MOV;
    request.operands[0].type = ZYDIS_OPERAND_TYPE_MEMORY;
    request.operands[0].mem.base = ZYDIS_REGISTER_RSP;
    request.operands[0].mem.displacement = 0x10;
    request.operands[1].type = ZYDIS_OPERAND_TYPE_REGISTER;
    request.operands[1].reg.value = ZYDIS_REGISTER_RBX;
    request.operand_count = 2;

    ZyanU8 buffer[ZYDIS_MAX_INSTRUCTION_LENGTH];
    ZyanUSize encoded_length;
    ZydisEncoderEncodeInstruction(&encoder, &request, buffer, sizeof(buffer), &encoded_length);

    for (ZyanUSize i = 0; i < encoded_length; ++i)
    {
        printf("%02X ", buffer[i]);
    }
    printf("\n");

    return 0;
}

Getting Started

To use Zydis in your project:

Clone the repository: git clone https://github.com/zyantific/zydis.git

Build the library using CMake:

cd zydis
mkdir build && cd build
cmake ..

Competitor Comparisons

unicorn

7,468

Unicorn CPU emulator framework (ARM, AArch64, M68K, Mips, Sparc, PowerPC, RiscV, S390x, TriCore, X86)

Pros of Unicorn

Broader architecture support (x86, ARM, MIPS, SPARC, etc.)
Full system emulation capabilities
Larger community and more extensive documentation

Cons of Unicorn

Higher resource usage and slower performance
More complex setup and integration process
Steeper learning curve for beginners

Code Comparison

Zydis (x86 disassembly):

ZydisDisassembledInstruction instruction;
ZydisDisassembleIntel(ZYDIS_MACHINE_MODE_LONG_64, runtime_address, buffer, length, &instruction);

Unicorn (x86 emulation):

mu = Uc(UC_ARCH_X86, UC_MODE_64)
mu.mem_map(ADDRESS, 2 * 1024 * 1024)
mu.mem_write(ADDRESS, X86_CODE64)
mu.emu_start(ADDRESS, ADDRESS + len(X86_CODE64))

Summary

Zydis is a lightweight, fast x86/x86-64 disassembler library, while Unicorn is a versatile multi-architecture CPU emulator. Zydis excels in performance and ease of use for x86 disassembly tasks, whereas Unicorn offers broader architecture support and full system emulation capabilities at the cost of increased complexity and resource usage.

capstone

7,334

Pros of Capstone

Supports a wider range of architectures (ARM, ARM64, MIPS, PPC, SPARC, SystemZ, XCore, x86)
More mature project with a larger community and ecosystem
Bindings available for multiple programming languages

Cons of Capstone

Generally slower performance compared to Zydis
Larger memory footprint
Less detailed instruction information for x86/x64

Code Comparison

Zydis:

ZydisDecodedInstruction instruction;
ZydisDecoderDecodeBuffer(&decoder, buffer, length, &instruction);

Capstone:

cs_insn *insn;
size_t count = cs_disasm(handle, code, code_size, address, 0, &insn);

Both libraries offer straightforward APIs for disassembling instructions, but Zydis provides more detailed information about x86/x64 instructions in its output structures. Capstone's API is designed to be more generic across multiple architectures, while Zydis focuses specifically on x86/x64 instruction set.

Zydis excels in performance and detailed x86/x64 instruction analysis, making it ideal for projects requiring high-speed disassembly of x86/x64 code. Capstone, on the other hand, offers broader architecture support and language bindings, making it more suitable for multi-architecture projects or those requiring integration with various programming languages.

udis86

1,012

Disassembler Library for x86 and x86-64

Pros of udis86

Simpler and more lightweight implementation
Supports a wider range of x86 and x86-64 instruction sets
Easier to integrate into existing projects due to its simplicity

Cons of udis86

Less actively maintained compared to Zydis
Limited support for newer CPU extensions and instructions
Lacks some advanced features like instruction encoding

Code Comparison

udis86:

ud_t ud_obj;
ud_init(&ud_obj);
ud_set_input_buffer(&ud_obj, buffer, size);
ud_set_mode(&ud_obj, 64);
while (ud_disassemble(&ud_obj)) {
    printf("%s\n", ud_insn_asm(&ud_obj));
}

Zydis:

ZydisDecoder decoder;
ZydisDecoderInit(&decoder, ZYDIS_MACHINE_MODE_LONG_64, ZYDIS_ADDRESS_WIDTH_64);
ZydisFormatter formatter;
ZydisFormatterInit(&formatter, ZYDIS_FORMATTER_STYLE_INTEL);
ZydisDecodedInstruction instruction;
while (ZYDIS_SUCCESS(ZydisDecoderDecodeBuffer(&decoder, buffer, size, &instruction))) {
    char buffer[256];
    ZydisFormatterFormatInstruction(&formatter, &instruction, buffer, sizeof(buffer), 0);
    puts(buffer);
}

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Fast and lightweight x86/x86-64 disassembler and code generation library.

Features

Supports all x86 and x86-64 (AMD64) instructions and extensions
Optimized for high performance
No dynamic memory allocation ("malloc")
Thread-safe by design
Very small file-size overhead compared to other common disassembler libraries
Complete doxygen documentation
Trusted by many major open-source projects
- Examples include x64dbg, Mozilla Firefox and Webkit
Absolutely no third party dependencies â not even libc
- Should compile on any platform with a working C11 compiler
- Tested on Windows, macOS, FreeBSD, Linux and UEFI, both user and kernel mode

Examples

Disassembler

The following example program uses Zydis to disassemble a given memory buffer and prints the output to the console.

https://github.com/zyantific/zydis/blob/214536a814ba20d2e33d2a907198d1a329aac45c/examples/DisassembleSimple.c#L38-L63

The above example program generates the following output:

007FFFFFFF400000   push rcx
007FFFFFFF400001   lea eax, [rbp-0x01]
007FFFFFFF400004   push rax
007FFFFFFF400005   push qword ptr [rbp+0x0C]
007FFFFFFF400008   push qword ptr [rbp+0x08]
007FFFFFFF40000B   call [0x008000007588A5B1]
007FFFFFFF400011   test eax, eax
007FFFFFFF400013   js 0x007FFFFFFF42DB15

Encoder

https://github.com/zyantific/zydis/blob/b37076e69f5aa149fde540cae43c50f15a380dfc/examples/EncodeMov.c#L39-L62

The above example program generates the following output:

48 C7 C0 37 13 00 00

More Examples

More examples can be found in the examples directory of this repository.

Build

There are many ways to make Zydis available on your system. The following sub-sections list commonly used options.

CMake Build

Platforms: Windows, macOS, Linux, BSDs

You can use CMake to build Zydis on all supported platforms. Instructions on how to install CMake can be found here.

git clone --recursive 'https://github.com/zyantific/zydis.git'
cd zydis
cmake -B build
cmake --build build -j4

Visual Studio 2022 project

Platforms: Windows

We manually maintain a Visual Studio 2022 project in addition to the CMake build logic.

CMake generated VS project

Platforms: Windows

CMake can be instructed to generate a Visual Studio project for pretty much any VS version. A video guide describing how to use the CMake GUI to generate such project files is available here. Don't be confused by the apparent use of macOS in the video: Windows is simply running in a virtual machine.

Amalgamated distribution

Platforms: any platform with a working C11 compiler

We provide an auto-generated single header & single source file variant of Zydis. To use this variant of Zydis in your project, all you need to do is to copy these two files into your project. The amalgamated builds can be found on our release page as zydis-amalgamated.tar.gz.

These files are generated with the amalgamate.py script.

Package managers

Platforms: Windows, macOS, Linux, FreeBSD

Pre-built headers, shared libraries and executables are available through a variety of package managers.

Zydis version in various package repositories

Repository	Install command
Arch Linux	`pacman -S zydis`
Debian	`apt-get install libzydis-dev zydis-tools`
Homebrew	`brew install zydis`
NixOS	`nix-shell -p zydis`
Ubuntu	`apt-get install libzydis-dev zydis-tools`
vcpkg	`vcpkg install zydis`

Using Zydis in a CMake project

An example on how to use Zydis in your own CMake based project can be found in this repo.

`ZydisInfo` tool

The ZydisInfo command-line tool can be used to inspect essentially all information that Zydis provides about an instruction.

ZydisInfo

Bindings

Official bindings exist for a selection of languages:

asmjit-style C++ front-end

If you're looking for an asmjit-style assembler front-end for the encoder, check out zasm. zasm also provides an idiomatic C++ wrapper around the decoder and formatter interface.

Versions

Scheme

Versions follow the semantic versioning scheme. All stability guarantees apply to the API only. ABI stability is provided only between patch versions.

Branches & Tags

master holds the bleeding edge code of the next, unreleased Zydis version. Increased amounts of bugs and issues must be expected and API stability is not guaranteed outside of tagged commits.
Stable and preview versions are annotated with git tags
- beta and other preview versions have -beta, -rc, etc. suffixes
maintenance/v4 points to the code of the latest release of v4
- v4 is the latest stable major version and receives feature updates
maintenance/v3 points to the code of the latest release of v3
- v3 won't get any feature updates but will receive security updates until 2025
maintenance/v2 points to the code of the last legacy release of v2
- v2 is has reached end-of-life and won't receive any security updates

Credits

Intel (for open-sourcing XED, allowing for automatic comparison of our tables against theirs, improving both)
LLVM (for providing pretty solid instruction data as well)
Christian Ludloff (https://sandpile.org, insanely helpful)
LekoArts (for creating the project logo)
Our contributors on GitHub

Troubleshooting

`-fPIC` for shared library builds

/usr/bin/ld: ./libfoo.a(foo.c.o): relocation R_X86_64_PC32 against symbol `bar' can not be used when making a shared object; recompile with -fPIC

Under some circumstances (e.g. when building Zydis as a static library using CMake and then using Makefiles to manually link it into a shared library), CMake might fail to detect that relocation information must be emitted. This can be forced by passing -DCMAKE_POSITION_INDEPENDENT_CODE=ON to the CMake invocation.

Consulting and Business Support

We offer consulting services and professional business support for Zydis. If you need a custom extension, require help in integrating Zydis into your product or simply want contractually guaranteed updates and turnaround times, we are happy to assist with that! Please contact us at business@zyantific.com.

Donations

Donations are collected and distributed using flobernd's account.

License

Zydis is licensed under the MIT license.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of Unicorn

Cons of Unicorn

Code Comparison

Summary

Pros of Capstone

Cons of Capstone

Code Comparison

Pros of udis86

Cons of udis86

Code Comparison

Convert designs to code with AI

README

Features

Examples

Disassembler

Encoder

More Examples

Build

CMake Build

Visual Studio 2022 project

CMake generated VS project

Amalgamated distribution

Package managers

Using Zydis in a CMake project

ZydisInfo tool

Bindings

asmjit-style C++ front-end

Versions

Scheme

Branches & Tags

Credits

Troubleshooting

-fPIC for shared library builds

Consulting and Business Support

Donations

License

Top Related Projects

Convert designs to code with AI

`ZydisInfo` tool

`-fPIC` for shared library builds