README.md (6644B)
1 <p align="center"> 2 <img alt="zydis logo" src="https://zydis.re/img/logo.svg" width="400px"> 3 </p> 4 5 <p align="center"> 6 <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"> 7 <a href="https://github.com/zyantific/zydis/actions"><img src="https://github.com/zyantific/zydis/workflows/CI/badge.svg" alt="GitHub Actions"></a> 8 <a href="https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:zydis"><img src="https://oss-fuzz-build-logs.storage.googleapis.com/badges/zydis.svg" alt="Fuzzing Status"></a> 9 <a href="https://gitter.im/zyantific/zydis?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=body_badge"><img src="https://badges.gitter.im/zyantific/zyan-disassembler-engine.svg" alt="Gitter"></a> 10 <a href="https://discord.zyantific.com/"><img src="https://img.shields.io/discord/390136917779415060.svg?logo=discord&label=Discord" alt="Discord"></a> 11 </p> 12 13 <p align="center">Fast and lightweight x86/x86-64 disassembler and code generation library.</p> 14 15 ## Features 16 17 - Supports all x86 and x86-64 (AMD64) instructions and [extensions](./include/Zydis/Generated/EnumISAExt.h) 18 - Optimized for high performance 19 - No dynamic memory allocation ("malloc") 20 - Thread-safe by design 21 - Very small file-size overhead compared to other common disassembler libraries 22 - [Complete doxygen documentation](https://doc.zydis.re/) 23 - Absolutely no third party dependencies — not even libc 24 - Should compile on any platform with a working C11 compiler 25 - Tested on Windows, macOS, FreeBSD, Linux and UEFI, both user and kernel mode 26 27 ## Examples 28 29 ### Disassembler 30 31 The following example program uses Zydis to disassemble a given memory buffer and prints the output to the console. 32 33 https://github.com/zyantific/zydis/blob/214536a814ba20d2e33d2a907198d1a329aac45c/examples/DisassembleSimple.c#L38-L63 34 35 The above example program generates the following output: 36 37 ```asm 38 007FFFFFFF400000 push rcx 39 007FFFFFFF400001 lea eax, [rbp-0x01] 40 007FFFFFFF400004 push rax 41 007FFFFFFF400005 push qword ptr [rbp+0x0C] 42 007FFFFFFF400008 push qword ptr [rbp+0x08] 43 007FFFFFFF40000B call [0x008000007588A5B1] 44 007FFFFFFF400011 test eax, eax 45 007FFFFFFF400013 js 0x007FFFFFFF42DB15 46 ``` 47 48 ### Encoder 49 50 https://github.com/zyantific/zydis/blob/b37076e69f5aa149fde540cae43c50f15a380dfc/examples/EncodeMov.c#L39-L62 51 52 The above example program generates the following output: 53 54 ``` 55 48 C7 C0 37 13 00 00 56 ``` 57 58 ### More Examples 59 60 More examples can be found in the [examples](./examples/) directory of this repository. 61 62 ## Build 63 64 ### Unix 65 66 Zydis builds cleanly on most platforms without any external dependencies. You can use CMake to generate project files for your favorite C11 compiler. 67 68 ```bash 69 git clone --recursive 'https://github.com/zyantific/zydis.git' 70 cd zydis 71 mkdir build && cd build 72 cmake .. 73 make 74 ``` 75 76 ### Windows 77 78 Either use the [Visual Studio 2019 project](./msvc/) or build Zydis using [CMake](https://cmake.org/download/) ([video guide](https://www.youtube.com/watch?v=fywLDK1OAtQ)). 79 80 #### Building Zydis - Using vcpkg 81 82 You can download and install Zydis using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager: 83 84 ```bash 85 git clone https://github.com/Microsoft/vcpkg.git 86 cd vcpkg 87 ./bootstrap-vcpkg.sh 88 ./vcpkg integrate install 89 ./vcpkg install zydis 90 ``` 91 The Zydis port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. 92 93 ## Using Zydis in a CMake project 94 95 An example on how to use Zydis in your own CMake based project [can be found in this repo](https://github.com/zyantific/zydis-submodule-example). 96 97 ## ZydisInfo tool 98 99  100 101 ## Bindings 102 103 Official bindings exist for a selection of languages: 104 105 - [Pascal](https://github.com/zyantific/zydis-pascal) 106 - [Python 3](https://github.com/zyantific/zydis-py) 107 - [Rust](https://github.com/zyantific/zydis-rs) 108 109 Unofficial but actively maintained bindings: 110 111 - [Go](https://github.com/jpap/go-zydis) 112 - [Haskell](https://github.com/nerded1337/zydiskell) 113 114 ## asmjit-style C++ front-end 115 116 If you're looking for an asmjit-style assembler front-end for the encoder, check out [zasm](https://github.com/zyantific/zasm)! 117 118 ## Versions 119 120 ### Scheme 121 122 Versions follow the [semantic versioning scheme](https://semver.org/). All stability guarantees apply to the API only — ABI stability between patches cannot be assumed unless explicitly mentioned in the release notes. 123 124 ### Branches & Tags 125 126 - `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. 127 - Stable and preview versions are annotated with git tags 128 - beta and other preview versions have `-beta`, `-rc`, etc. suffixes 129 - `maintenance/v2` contains the code of the latest legacy release of v2 130 - v2 is now deprecated, but will receive security fixes until 2021 131 132 ## Credits 133 134 - Intel (for open-sourcing [XED](https://github.com/intelxed/xed), allowing for automatic comparison of our tables against theirs, improving both) 135 - [LLVM](https://llvm.org) (for providing pretty solid instruction data as well) 136 - Christian Ludloff (http://sandpile.org, insanely helpful) 137 - [LekoArts](https://www.lekoarts.de/) (for creating the project logo) 138 - Our [contributors on GitHub](https://github.com/zyantific/zydis/graphs/contributors) 139 140 ## Troubleshooting 141 142 ### `-fPIC` for shared library builds 143 144 ``` 145 /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 146 ``` 147 148 Under some circumstances (e.g. when building Zydis as a static library using 149 CMake and then using Makefiles to manually link it into a shared library), CMake 150 might fail to detect that relocation information must be emitted. This can be forced 151 by passing `-DCMAKE_POSITION_INDEPENDENT_CODE=ON` to the CMake invocation. 152 153 ## Consulting and Business Support 154 155 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. 156 157 ## Donations 158 159 Since GitHub Sponsors currently doesn't support sponsoring teams directly, donations are collected and distributed using [flobernd](https://github.com/users/flobernd/sponsorship)s account. 160 161 ## License 162 163 Zydis is licensed under the MIT license.