Decoder.h (12755B)
1 /*************************************************************************************************** 2 3 Zyan Disassembler Library (Zydis) 4 5 Original Author : Florian Bernd 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 * Functions for decoding instructions. 30 */ 31 32 #ifndef ZYDIS_DECODER_H 33 #define ZYDIS_DECODER_H 34 35 #include "zydis/Zycore/Types.h" 36 #include "zydis/Zycore/Defines.h" 37 #include "zydis/Zydis/DecoderTypes.h" 38 #include "zydis/Zydis/Status.h" 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /* ============================================================================================== */ 45 /* Enums and types */ 46 /* ============================================================================================== */ 47 48 /* ---------------------------------------------------------------------------------------------- */ 49 /* Decoder mode */ 50 /* ---------------------------------------------------------------------------------------------- */ 51 52 /** 53 * Defines the `ZydisDecoderMode` enum. 54 */ 55 typedef enum ZydisDecoderMode_ 56 { 57 /** 58 * Enables minimal instruction decoding without semantic analysis. 59 * 60 * This mode provides access to the mnemonic, the instruction-length, the effective 61 * operand-size, the effective address-width, some attributes (e.g. `ZYDIS_ATTRIB_IS_RELATIVE`) 62 * and all of the information in the `raw` field of the `ZydisDecodedInstruction` struct. 63 * 64 * Operands, most attributes and other specific information (like `AVX` info) are not 65 * accessible in this mode. 66 * 67 * This mode is NOT enabled by default. 68 */ 69 ZYDIS_DECODER_MODE_MINIMAL, 70 /** 71 * Enables the `AMD`-branch mode. 72 * 73 * Intel ignores the operand-size override-prefix (`0x66`) for all branches with 32-bit 74 * immediates and forces the operand-size of the instruction to 64-bit in 64-bit mode. 75 * In `AMD`-branch mode `0x66` is not ignored and changes the operand-size and the size of the 76 * immediate to 16-bit. 77 * 78 * This mode is NOT enabled by default. 79 */ 80 ZYDIS_DECODER_MODE_AMD_BRANCHES, 81 /** 82 * Enables `KNC` compatibility-mode. 83 * 84 * `KNC` and `KNL+` chips are sharing opcodes and encodings for some mask-related instructions. 85 * Enable this mode to use the old `KNC` specifications (different mnemonics, operands, ..). 86 * 87 * This mode is NOT enabled by default. 88 */ 89 ZYDIS_DECODER_MODE_KNC, 90 /** 91 * Enables the `MPX` mode. 92 * 93 * The `MPX` isa-extension reuses (overrides) some of the widenop instruction opcodes. 94 * 95 * This mode is enabled by default. 96 */ 97 ZYDIS_DECODER_MODE_MPX, 98 /** 99 * Enables the `CET` mode. 100 * 101 * The `CET` isa-extension reuses (overrides) some of the widenop instruction opcodes. 102 * 103 * This mode is enabled by default. 104 */ 105 ZYDIS_DECODER_MODE_CET, 106 /** 107 * Enables the `LZCNT` mode. 108 * 109 * The `LZCNT` isa-extension reuses (overrides) some of the widenop instruction opcodes. 110 * 111 * This mode is enabled by default. 112 */ 113 ZYDIS_DECODER_MODE_LZCNT, 114 /** 115 * Enables the `TZCNT` mode. 116 * 117 * The `TZCNT` isa-extension reuses (overrides) some of the widenop instruction opcodes. 118 * 119 * This mode is enabled by default. 120 */ 121 ZYDIS_DECODER_MODE_TZCNT, 122 /** 123 * Enables the `WBNOINVD` mode. 124 * 125 * The `WBINVD` instruction is interpreted as `WBNOINVD` on ICL chips, if a `F3` prefix is 126 * used. 127 * 128 * This mode is disabled by default. 129 */ 130 ZYDIS_DECODER_MODE_WBNOINVD, 131 /** 132 * Enables the `CLDEMOTE` mode. 133 * 134 * The `CLDEMOTE` isa-extension reuses (overrides) some of the widenop instruction opcodes. 135 * 136 * This mode is enabled by default. 137 */ 138 ZYDIS_DECODER_MODE_CLDEMOTE, 139 /** 140 * Enables the `IPREFETCH` mode. 141 * 142 * The `IPREFETCH` isa-extension reuses (overrides) some of the widenop instruction opcodes. 143 * 144 * This mode is enabled by default. 145 */ 146 ZYDIS_DECODER_MODE_IPREFETCH, 147 /** 148 * Enables the `UD0` compatibility mode. 149 * 150 * Some processors decode the `UD0` instruction without a ModR/M byte. Enable this decoder mode 151 * to mimic this behavior. 152 * 153 * This mode is disabled by default. 154 */ 155 ZYDIS_DECODER_MODE_UD0_COMPAT, 156 157 /** 158 * Maximum value of this enum. 159 */ 160 ZYDIS_DECODER_MODE_MAX_VALUE = ZYDIS_DECODER_MODE_UD0_COMPAT, 161 /** 162 * The minimum number of bits required to represent all values of this enum. 163 */ 164 ZYDIS_DECODER_MODE_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_DECODER_MODE_MAX_VALUE) 165 } ZydisDecoderMode; 166 167 /* ---------------------------------------------------------------------------------------------- */ 168 /* Decoder struct */ 169 /* ---------------------------------------------------------------------------------------------- */ 170 171 /** 172 * Defines the `ZydisDecoder` struct. 173 * 174 * All fields in this struct should be considered as "private". Any changes may lead to unexpected 175 * behavior. 176 */ 177 typedef struct ZydisDecoder_ 178 { 179 /** 180 * The machine mode. 181 */ 182 ZydisMachineMode machine_mode; 183 /** 184 * The stack width. 185 */ 186 ZydisStackWidth stack_width; 187 /** 188 * The decoder mode bitmap. 189 */ 190 ZyanU32 decoder_mode; 191 } ZydisDecoder; 192 193 /* ---------------------------------------------------------------------------------------------- */ 194 195 /* ============================================================================================== */ 196 /* Exported functions */ 197 /* ============================================================================================== */ 198 199 /** 200 * @addtogroup decoder Decoder 201 * Functions allowing decoding of instruction bytes to a machine interpretable struct. 202 * @{ 203 */ 204 205 /** 206 * Initializes the given `ZydisDecoder` instance. 207 * 208 * @param decoder A pointer to the `ZydisDecoder` instance. 209 * @param machine_mode The machine mode. 210 * @param stack_width The stack width. 211 * 212 * @return A zyan status code. 213 */ 214 ZYDIS_EXPORT ZyanStatus ZydisDecoderInit(ZydisDecoder* decoder, ZydisMachineMode machine_mode, 215 ZydisStackWidth stack_width); 216 217 /** 218 * Enables or disables the specified decoder-mode. 219 * 220 * @param decoder A pointer to the `ZydisDecoder` instance. 221 * @param mode The decoder mode. 222 * @param enabled `ZYAN_TRUE` to enable, or `ZYAN_FALSE` to disable the specified decoder-mode. 223 * 224 * @return A zyan status code. 225 */ 226 ZYDIS_EXPORT ZyanStatus ZydisDecoderEnableMode(ZydisDecoder* decoder, ZydisDecoderMode mode, 227 ZyanBool enabled); 228 229 /** 230 * Decodes the instruction in the given input `buffer` and returns all details (e.g. operands). 231 * 232 * @param decoder A pointer to the `ZydisDecoder` instance. 233 * @param buffer A pointer to the input buffer. 234 * @param length The length of the input buffer. Note that this can be bigger than the 235 * actual size of the instruction -- you don't have to know the size up 236 * front. This length is merely used to prevent Zydis from doing 237 * out-of-bounds reads on your buffer. 238 * @param instruction A pointer to the `ZydisDecodedInstruction` struct receiving the details 239 * about the decoded instruction. 240 * @param operands A pointer to an array with `ZYDIS_MAX_OPERAND_COUNT` entries that 241 * receives the decoded operands. The number of operands decoded is 242 * determined by the `instruction.operand_count` field. Excess entries are 243 * zeroed. 244 * 245 * This is a convenience function that combines the following functions into one call: 246 * 247 * - `ZydisDecoderDecodeInstruction` 248 * - `ZydisDecoderDecodeOperands` 249 * 250 * Please refer to `ZydisDecoderDecodeInstruction` if operand decoding is not required or should 251 * be done separately (`ZydisDecoderDecodeOperands`). 252 * 253 * This function is not available in MINIMAL_MODE. 254 * 255 * @return A zyan status code. 256 */ 257 ZYDIS_EXPORT ZyanStatus ZydisDecoderDecodeFull(const ZydisDecoder* decoder, 258 const void* buffer, ZyanUSize length, ZydisDecodedInstruction* instruction, 259 ZydisDecodedOperand operands[ZYDIS_MAX_OPERAND_COUNT]); 260 261 /** 262 * Decodes the instruction in the given input `buffer`. 263 * 264 * @param decoder A pointer to the `ZydisDecoder` instance. 265 * @param context A pointer to a decoder context struct which is required for further 266 * decoding (e.g. operand decoding using `ZydisDecoderDecodeOperands`) or 267 * `ZYAN_NULL` if not needed. 268 * @param buffer A pointer to the input buffer. 269 * @param length The length of the input buffer. Note that this can be bigger than the 270 * actual size of the instruction -- you don't have to know the size up 271 * front. This length is merely used to prevent Zydis from doing 272 * out-of-bounds reads on your buffer. 273 * @param instruction A pointer to the `ZydisDecodedInstruction` struct, that receives the 274 * details about the decoded instruction. 275 * 276 * @return A zyan status code. 277 */ 278 ZYDIS_EXPORT ZyanStatus ZydisDecoderDecodeInstruction(const ZydisDecoder* decoder, 279 ZydisDecoderContext* context, const void* buffer, ZyanUSize length, 280 ZydisDecodedInstruction* instruction); 281 282 /** 283 * Decodes the instruction operands. 284 * 285 * @param decoder A pointer to the `ZydisDecoder` instance. 286 * @param context A pointer to the `ZydisDecoderContext` struct. 287 * @param instruction A pointer to the `ZydisDecodedInstruction` struct. 288 * @param operands The array that receives the decoded operands. 289 * Refer to `ZYDIS_MAX_OPERAND_COUNT` or `ZYDIS_MAX_OPERAND_COUNT_VISIBLE` 290 * when allocating space for the array to ensure that the buffer size is 291 * sufficient to always fit all instruction operands. 292 * Refer to `instruction.operand_count` or 293 * `instruction.operand_count_visible' when allocating space for the array 294 * to ensure that the buffer size is sufficient to fit all operands of 295 * the given instruction. 296 * @param operand_count The length of the `operands` array. 297 * This argument as well limits the maximum amount of operands to decode. 298 * If this value is `0`, no operands will be decoded and `ZYAN_NULL` will 299 * be accepted for the `operands` argument. 300 * 301 * This function fails, if `operand_count` is larger than the total number of operands for the 302 * given instruction (`instruction.operand_count`). 303 * 304 * This function is not available in MINIMAL_MODE. 305 * 306 * @return A zyan status code. 307 */ 308 ZYDIS_EXPORT ZyanStatus ZydisDecoderDecodeOperands(const ZydisDecoder* decoder, 309 const ZydisDecoderContext* context, const ZydisDecodedInstruction* instruction, 310 ZydisDecodedOperand* operands, ZyanU8 operand_count); 311 312 /** @} */ 313 314 /* ============================================================================================== */ 315 316 #ifdef __cplusplus 317 } 318 #endif 319 320 #endif /* ZYDIS_DECODER_H */