Disassembler.h (6145B)
1 /*************************************************************************************************** 2 3 Zyan Disassembler Library (Zydis) 4 5 Original Author : Joel Hoener 6 7 * Permission is hereby granted, free of charge, to any person obtaining a copy 8 * of this software and associated documentation files (the "Software"), to deal 9 * in the Software without restriction, including without limitation the rights 10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 * copies of the Software, and to permit persons to whom the Software is 12 * furnished to do so, subject to the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be included in all 15 * copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 23 * SOFTWARE. 24 25 ***************************************************************************************************/ 26 27 /** 28 * @file 29 * All-in-one convenience function providing the simplest possible way to use Zydis. 30 */ 31 32 #ifndef ZYDIS_DISASSEMBLER_H 33 #define ZYDIS_DISASSEMBLER_H 34 35 #include <Zydis/Decoder.h> 36 #include <Zydis/Formatter.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /* ============================================================================================== */ 43 /* Types */ 44 /* ============================================================================================== */ 45 46 /** 47 * All commonly used information about a decoded instruction that Zydis can provide. 48 * 49 * This structure is filled in by calling `ZydisDisassembleIntel` or `ZydisDisassembleATT`. 50 */ 51 typedef struct ZydisDisassembledInstruction_ 52 { 53 /** 54 * The runtime address that was passed when disassembling the instruction. 55 */ 56 ZyanU64 runtime_address; 57 /** 58 * General information about the decoded instruction in machine-readable format. 59 */ 60 ZydisDecodedInstruction info; 61 /** 62 * The operands of the decoded instruction in a machine-readable format. 63 * 64 * The amount of actual operands can be determined by inspecting the corresponding fields 65 * in the `info` member of this struct. Inspect `operand_count_visible` if you care about 66 * visible operands (those that are printed by the formatter) or `operand_count` if you're 67 * also interested in implicit operands (for example the registers implicitly accessed by 68 * `pushad`). Unused entries are zeroed. 69 */ 70 ZydisDecodedOperand operands[ZYDIS_MAX_OPERAND_COUNT]; 71 /** 72 * The textual, human-readable representation of the instruction. 73 * 74 * Guaranteed to be zero-terminated. 75 */ 76 char text[96]; 77 } ZydisDisassembledInstruction; 78 79 /* ============================================================================================== */ 80 /* Exported functions */ 81 /* ============================================================================================== */ 82 83 /** 84 * Disassemble an instruction and format it to human-readable text in a single step (Intel syntax). 85 * 86 * @param machine_mode The machine mode to assume when disassembling. When in doubt, pass 87 * `ZYDIS_MACHINE_MODE_LONG_64` for what is typically referred to as 88 * "64-bit mode" or `ZYDIS_MACHINE_MODE_LEGACY_32` for "32-bit mode". 89 * @param runtime_address The program counter (`eip` / `rip`) to assume when formatting the 90 * instruction. Many instructions behave differently depending on the 91 * address they are located at. 92 * @param buffer A pointer to the raw instruction bytes that you wish to decode. 93 * @param length The length of the input buffer. Note that this can be bigger than the 94 * actual size of the instruction -- you don't have to know the size up 95 * front. This length is merely used to prevent Zydis from doing 96 * out-of-bounds reads on your buffer. 97 * @param instruction A pointer to receive the decoded instruction information. Can be 98 * uninitialized and reused on later calls. 99 * 100 * This is a convenience function intended as a quick path for getting started with using Zydis. 101 * It internally calls a range of other more advanced functions to obtain all commonly needed 102 * information about the instruction. It is likely that you won't need most of this information in 103 * practice, so it is advisable to instead call these more advanced functions directly if you're 104 * concerned about performance. 105 * 106 * This function essentially combines the following more advanced functions into a single call: 107 * 108 * - `ZydisDecoderInit` 109 * - `ZydisDecoderDecodeInstruction` 110 * - `ZydisDecoderDecodeOperands` 111 * - `ZydisFormatterInit` 112 * - `ZydisFormatterFormatInstruction` 113 * 114 * @return A zyan status code. 115 */ 116 ZYDIS_EXPORT ZyanStatus ZydisDisassembleIntel(ZydisMachineMode machine_mode, 117 ZyanU64 runtime_address, const void* buffer, ZyanUSize length, 118 ZydisDisassembledInstruction *instruction); 119 120 /** 121 * Disassemble an instruction and format it to human-readable text in a single step (AT&T syntax). 122 * 123 * @copydetails ZydisDisassembleIntel 124 */ 125 ZYDIS_EXPORT ZyanStatus ZydisDisassembleATT(ZydisMachineMode machine_mode, 126 ZyanU64 runtime_address, const void* buffer, ZyanUSize length, 127 ZydisDisassembledInstruction *instruction); 128 129 /* ============================================================================================== */ 130 131 #ifdef __cplusplus 132 } 133 #endif 134 135 #endif /* ZYDIS_DISASSEMBLER_H */