Zydis  v3.0.0
Zydis Documentation

zydis logo

License: MIT GitHub Actions Gitter Discord

Fast and lightweight x86/x86-64 disassembler 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 (master, stable)
  • Absolutely no third party dependencies — not even libc
    • Should compile on any platform with a working C99 compiler
    • Tested on Windows, macOS, FreeBSD, Linux and UEFI, both user and kernel mode

Quick Example

The following example program uses Zydis to disassemble a given memory buffer and prints the output to the console (more examples here).

#include <stdio.h>
#include <inttypes.h>
#include <Zydis/Zydis.h>
int main()
{
ZyanU8 data[] =
{
0x51, 0x8D, 0x45, 0xFF, 0x50, 0xFF, 0x75, 0x0C, 0xFF, 0x75,
0x08, 0xFF, 0x15, 0xA0, 0xA5, 0x48, 0x76, 0x85, 0xC0, 0x0F,
0x88, 0xFC, 0xDA, 0x02, 0x00
};
// Initialize decoder context
ZydisDecoder decoder;
ZydisDecoderInit(&decoder, ZYDIS_MACHINE_MODE_LONG_64, ZYDIS_ADDRESS_WIDTH_64);
// Initialize formatter. Only required when you actually plan to do instruction
// formatting ("disassembling"), like we do here
ZydisFormatter formatter;
// Loop over the instructions in our buffer.
// The runtime-address (instruction pointer) is chosen arbitrary here in order to better
// visualize relative addressing
ZyanU64 runtime_address = 0x007FFFFFFF400000;
ZyanUSize offset = 0;
const ZyanUSize length = sizeof(data);
while (ZYAN_SUCCESS(ZydisDecoderDecodeBuffer(&decoder, data + offset, length - offset,
&instruction)))
{
// Print current instruction pointer.
printf("%016" PRIX64 " ", runtime_address);
// Format & print the binary instruction structure to human readable format
char buffer[256];
ZydisFormatterFormatInstruction(&formatter, &instruction, buffer, sizeof(buffer),
runtime_address);
puts(buffer);
offset += instruction.length;
runtime_address += instruction.length;
}
}
@ ZYDIS_FORMATTER_STYLE_INTEL
Generates Intel-style disassembly.
Definition: Formatter.h:76
@ ZYDIS_MACHINE_MODE_LONG_64
64 bit mode.
Definition: SharedTypes.h:70
Master include file, including everything else.
ZYDIS_EXPORT ZyanStatus ZydisDecoderDecodeBuffer(const ZydisDecoder *decoder, const void *buffer, ZyanUSize length, ZydisDecodedInstruction *instruction)
Decodes the instruction in the given input buffer.
ZYDIS_EXPORT ZyanStatus ZydisDecoderInit(ZydisDecoder *decoder, ZydisMachineMode machine_mode, ZydisAddressWidth address_width)
Initializes the given ZydisDecoder instance.
ZYDIS_EXPORT ZyanStatus ZydisFormatterInit(ZydisFormatter *formatter, ZydisFormatterStyle style)
Initializes the given ZydisFormatter instance.
ZYDIS_EXPORT ZyanStatus ZydisFormatterFormatInstruction(const ZydisFormatter *formatter, const ZydisDecodedInstruction *instruction, char *buffer, ZyanUSize length, ZyanU64 runtime_address)
Formats the given instruction and writes it into the output buffer.
Defines the ZydisDecodedInstruction struct.
Definition: DecoderTypes.h:892
ZyanU8 length
The length of the decoded instruction.
Definition: DecoderTypes.h:904
Defines the ZydisDecoder struct.
Definition: Decoder.h:161
Defines the ZydisFormatter struct.
Definition: Formatter.h:747

Sample Output

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

Build

Unix

Zydis builds cleanly on most platforms without any external dependencies. You can use CMake to generate project files for your favorite C99 compiler.

git clone --recursive 'https://github.com/zyantific/zydis.git'
cd zydis
mkdir build && cd build
cmake ..
make

Windows

Either use the Visual Studio 2017 project or build Zydis using CMake (video guide).

ZydisInfo tool

ZydisInfo

Bindings

Official bindings exist for a selection of languages:

Unofficial but actively maintained bindings:

Versions

Scheme

Versions follow the semantic versioning scheme. All stability guarantees apply to the API only — ABI stability between patches cannot be assumed unless explicitly mentioned in the release notes.

Branches

  • master holds the bleeding edge code of the next, unreleased Zydis version. Elevated amounts of bugs and issues must be expected, API stability is not guaranteed outside of tagged commits.
  • maintenance/v2 contains the code of the latest stable v2 release.

Credits

  • Intel (for open-sourcing XED, allowing for automatic comparision of our tables against theirs, improving both)
  • LLVM (for providing pretty solid instruction data as well)
  • Christian Ludloff (http://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.

License

Zydis is licensed under the MIT license.