DOCSEARCHbyAlgolia
Submit Docs

Zydis Documentation

repository·master·Indexed 26 days ago

https://github.com/zyantific/zydis

A fast, lightweight, and high-performance x86/x86-64 (AMD64) disassembler and code generation (encoder) library. Zydis is thread-safe, requires no dynamic memory allocation, and has no third-party dependencies. It includes features for custom symbol resolution, instruction tokenization, and support for Windows kernel-mode drivers. The library provides official bindings for Rust and Python 3, and can be built via CMake or MSVC.

Tokens
2.3K
Snippets
2
Records
22
Agent score
77%

What's inside Zydis

  3. Use the Amalgamated Distribution

    master
    For projects that want to avoid complex build systems, Zydis provides an auto-generated single header and single source file variant. To use it, simply copy these two files into your project. You can find these on the release page as zydis-amalgamated.tar.gz.

  4. Port Zydis Decoder usage from v4 to v5

    master

    When upgrading the Decoder from v4 to v5, the following struct changes must be addressed:

    ZydisDecodedOperandImm struct

    • New field offset: Contains the offset of the immediate data, relative to the beginning of the instruction, in bytes.
    • New field size: Contains the physical immediate size, in bits.

    ZydisDecodedOperandMemDisp_ struct

    • New field offset: Contains the offset of the immediate data, relative to the beginning of the instruction, in bytes.
    • New field size: Contains the physical displacement size, in bits.
    • Removed field has_displacement: This field has been removed. To check if a displacement exists, check if size is non-zero. A size of 0 indicates there is no displacement.

  5. Port Zydis Encoder usage from v4 to v5

    master

    When upgrading the Encoder from v4 to v5, note the following changes to function behavior and requirements:

    1. ZydisRegisterGetLargestEnclosing: For registers that do not have an enclosing register, this function now returns the register itself. In v4, it returned ZYDIS_REGISTER_NONE for these cases.
    2. ZydisEncoderDecodedInstructionToEncoderRequest: This function now requires that the operand count passed is exactly equal to instruction->operand_count_visible. In v4, passing a value lower than the maximum visible operand count was permitted, but this is no longer allowed in v5.

  6. Build Zydis using MSVC project files

    master

    You can build Zydis and its included tools/examples using the MSVC project files located in the msvc/ directory. The build system provides five distinct configurations, each supporting both 32/64-bit and Debug/Release modes:

    • Static with dynamic run-time library (MD)
    • Static with static run-time library (MT)
    • Dynamic (DLL) with dynamic run-time library (MD)
    • Dynamic (DLL) with static run-time library (MT)
    • Kernel mode

    Note that the Kernel mode configuration only builds the Zydis project and the ZydisWinKernel driver sample. All other configurations build all projects except for ZydisWinKernel.

  7. Install Zydis via Package Managers

    master

    Pre-built headers, shared libraries, and executables are available through several package managers depending on your operating system.

    # Arch Linux
pacman -S zydis

# Debian / Ubuntu
apt-get install libzydis-dev zydis-tools

# Homebrew (macOS)
brew install zydis

# NixOS
nix-shell -p zydis

# vcpkg
vcpkg install zydis

  8. Migrate from Zydis v3 to v4

    master

    When upgrading from version 3 to version 4, note the following general breaking changes:

    • Compiler Requirement: Zydis now requires a C11 capable compiler.
    • Type Renaming: ZydisAddressWidth has been renamed to ZydisStackWidth.
    • Constant Renaming:
      • ZYDIS_STATIC_DEFINE $\rightarrow$ ZYDIS_STATIC_BUILD
      • Zydis_EXPORTS $\rightarrow$ ZYDIS_SHOULD_EXPORT
      • ZYDIS_ADDRESS_WIDTH_XXX $\rightarrow$ ZYDIS_STACK_WIDTH_XXX
    • Enum Changes: ZydisMemoryOperandType now includes ZYDIS_MEMOP_TYPE_VSIB.
    • Flag API Changes:
      • ZydisCPUFlagAction is replaced by ZydisAccessedFlagsMask.
      • ZydisAccessedFlags is the new replacement for CPU flag arrays.
      • ZYDIS_CPUFLAG_C[0-3] are replaced with ZYDIS_FPUFLAG_C[0-3].
    • Segment API: ZydisGetInstructionSegments and its related types have been moved to a separate header file.

  9. Use Zydis in a CMake Project

    master
    If you are managing your own project with CMake, you can integrate Zydis as a submodule or external dependency. A complete example of how to set this up is available in the zyantific/zydis-submodule-example repository.

  10. Build Zydis using CMake

    master

    You can use CMake to build Zydis on Windows, macOS, Linux, and BSDs. This is the recommended method for most platforms.

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

  11. Disable specific Zydis features via preprocessor directives

    master

    All Zydis features are enabled by default. To reduce the footprint or disable specific functionality, you can define preprocessor directives. For example, to disable the formatter, define ZYDIS_DISABLE_FORMATTER.

    For a complete list of available feature switches, refer to the CMakeLists.txt file in the repository.

  12. Troubleshoot shared library relocation errors

    master

    If you encounter relocation errors like /usr/bin/ld: ... relocation R_X86_64_PC32 ... can not be used when making a shared object; recompile with -fPIC when building Zydis as a static library to be linked into a shared library, force position-independent code by passing the following flag to your CMake invocation:

    -DCMAKE_POSITION_INDEPENDENT_CODE=ON