/*************************************************************************************************** Zyan Disassembler Library (Zydis) Original Author : Mappa * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in all * copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. ***************************************************************************************************/ /** * @file * Functions for encoding instructions. */ #ifndef ZYDIS_ENCODER_H #define ZYDIS_ENCODER_H #include "zydis/Zycore/Types.h" #include "zydis/Zydis/MetaInfo.h" #include "zydis/Zydis/Register.h" #include "zydis/Zydis/DecoderTypes.h" #include "zydis/Zydis/Mnemonic.h" #include "zydis/Zydis/Status.h" #ifdef __cplusplus extern "C" { #endif /* ============================================================================================== */ /* Macros */ /* ============================================================================================== */ /* ---------------------------------------------------------------------------------------------- */ /* Constants */ /* ---------------------------------------------------------------------------------------------- */ /** * Maximum number of encodable (explicit and implicit) operands */ #define ZYDIS_ENCODER_MAX_OPERANDS 5 // If asserts are failing here remember to update encoder table generator before fixing asserts ZYAN_STATIC_ASSERT(ZYAN_BITS_TO_REPRESENT(ZYDIS_ENCODER_MAX_OPERANDS) == 3); /** * Combination of all user-encodable prefixes */ #define ZYDIS_ENCODABLE_PREFIXES (ZYDIS_ATTRIB_HAS_LOCK | \ ZYDIS_ATTRIB_HAS_REP | \ ZYDIS_ATTRIB_HAS_REPE | \ ZYDIS_ATTRIB_HAS_REPNE | \ ZYDIS_ATTRIB_HAS_BND | \ ZYDIS_ATTRIB_HAS_XACQUIRE | \ ZYDIS_ATTRIB_HAS_XRELEASE | \ ZYDIS_ATTRIB_HAS_BRANCH_NOT_TAKEN | \ ZYDIS_ATTRIB_HAS_BRANCH_TAKEN | \ ZYDIS_ATTRIB_HAS_NOTRACK | \ ZYDIS_ATTRIB_HAS_SEGMENT_CS | \ ZYDIS_ATTRIB_HAS_SEGMENT_SS | \ ZYDIS_ATTRIB_HAS_SEGMENT_DS | \ ZYDIS_ATTRIB_HAS_SEGMENT_ES | \ ZYDIS_ATTRIB_HAS_SEGMENT_FS | \ ZYDIS_ATTRIB_HAS_SEGMENT_GS) /* ---------------------------------------------------------------------------------------------- */ /* ============================================================================================== */ /* Enums and types */ /* ============================================================================================== */ /** * Defines possible physical instruction encodings as bit flags, so multiple acceptable encodings * can be specified simultaneously. */ typedef enum ZydisEncodableEncoding_ { ZYDIS_ENCODABLE_ENCODING_DEFAULT = 0x00000000, ZYDIS_ENCODABLE_ENCODING_LEGACY = 0x00000001, ZYDIS_ENCODABLE_ENCODING_3DNOW = 0x00000002, ZYDIS_ENCODABLE_ENCODING_XOP = 0x00000004, ZYDIS_ENCODABLE_ENCODING_VEX = 0x00000008, ZYDIS_ENCODABLE_ENCODING_EVEX = 0x00000010, ZYDIS_ENCODABLE_ENCODING_MVEX = 0x00000020, /** * Maximum value of this enum. */ ZYDIS_ENCODABLE_ENCODING_MAX_VALUE = (ZYDIS_ENCODABLE_ENCODING_MVEX | (ZYDIS_ENCODABLE_ENCODING_MVEX - 1)), /** * The minimum number of bits required to represent all values of this enum. */ ZYDIS_ENCODABLE_ENCODING_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_ENCODABLE_ENCODING_MAX_VALUE) } ZydisEncodableEncoding; /** * Defines encodable physical/effective sizes of relative immediate operands. See * `ZydisEncoderRequest.branch_width` for more details. */ typedef enum ZydisBranchWidth_ { ZYDIS_BRANCH_WIDTH_NONE, ZYDIS_BRANCH_WIDTH_8, ZYDIS_BRANCH_WIDTH_16, ZYDIS_BRANCH_WIDTH_32, ZYDIS_BRANCH_WIDTH_64, /** * Maximum value of this enum. */ ZYDIS_BRANCH_WIDTH_MAX_VALUE = ZYDIS_BRANCH_WIDTH_64, /** * The minimum number of bits required to represent all values of this enum. */ ZYDIS_BRANCH_WIDTH_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_BRANCH_WIDTH_MAX_VALUE) } ZydisBranchWidth; /** * Defines possible values for address size hints. See `ZydisEncoderRequest` for more information * about address size hints. */ typedef enum ZydisAddressSizeHint_ { ZYDIS_ADDRESS_SIZE_HINT_NONE, ZYDIS_ADDRESS_SIZE_HINT_16, ZYDIS_ADDRESS_SIZE_HINT_32, ZYDIS_ADDRESS_SIZE_HINT_64, /** * Maximum value of this enum. */ ZYDIS_ADDRESS_SIZE_HINT_MAX_VALUE = ZYDIS_ADDRESS_SIZE_HINT_64, /** * The minimum number of bits required to represent all values of this enum. */ ZYDIS_ADDRESS_SIZE_HINT_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_ADDRESS_SIZE_HINT_MAX_VALUE) } ZydisAddressSizeHint; /** * Defines possible values for operand size hints. See `ZydisEncoderRequest` for more information * about operand size hints. */ typedef enum ZydisOperandSizeHint_ { ZYDIS_OPERAND_SIZE_HINT_NONE, ZYDIS_OPERAND_SIZE_HINT_8, ZYDIS_OPERAND_SIZE_HINT_16, ZYDIS_OPERAND_SIZE_HINT_32, ZYDIS_OPERAND_SIZE_HINT_64, /** * Maximum value of this enum. */ ZYDIS_OPERAND_SIZE_HINT_MAX_VALUE = ZYDIS_OPERAND_SIZE_HINT_64, /** * The minimum number of bits required to represent all values of this enum. */ ZYDIS_OPERAND_SIZE_HINT_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_OPERAND_SIZE_HINT_MAX_VALUE) } ZydisOperandSizeHint; /** * Describes explicit or implicit instruction operand. */ typedef struct ZydisEncoderOperand_ { /** * The type of the operand. */ ZydisOperandType type; /** * Extended info for register-operands. */ struct ZydisEncoderOperandReg_ { /** * The register value. */ ZydisRegister value; /** * Is this 4th operand (`VEX`/`XOP`). Despite its name, `is4` encoding can sometimes be * applied to 3rd operand instead of 4th. This field is used to resolve such ambiguities. * For all other operands it should be set to `ZYAN_FALSE`. */ ZyanBool is4; } reg; /** * Extended info for memory-operands. */ struct ZydisEncoderOperandMem_ { /** * The base register. */ ZydisRegister base; /** * The index register. */ ZydisRegister index; /** * The scale factor. */ ZyanU8 scale; /** * The displacement value. This value is always treated as 64-bit signed integer, so it's * important to take this into account when specifying absolute addresses. For example * to specify a 16-bit address 0x8000 in 16-bit mode it should be sign extended to * `0xFFFFFFFFFFFF8000`. See `address_size_hint` for more information about absolute * addresses. */ ZyanI64 displacement; /** * Size of this operand in bytes. */ ZyanU16 size; } mem; /** * Extended info for pointer-operands. */ struct ZydisEncoderOperandPtr_ { /** * The segment value. */ ZyanU16 segment; /** * The offset value. */ ZyanU32 offset; } ptr; /** * Extended info for immediate-operands. */ union ZydisEncoderOperandImm_ { /** * The unsigned immediate value. */ ZyanU64 u; /** * The signed immediate value. */ ZyanI64 s; } imm; } ZydisEncoderOperand; /** * Main structure consumed by the encoder. It represents full semantics of an instruction. */ typedef struct ZydisEncoderRequest_ { /** * The machine mode used to encode this instruction. */ ZydisMachineMode machine_mode; /** * This optional field can be used to restrict allowed physical encodings for desired * instruction. Some mnemonics can be supported by more than one encoding, so this field can * resolve ambiguities e.g. you can disable `AVX-512` extensions by prohibiting usage of `EVEX` * prefix and allow only `VEX` variants. */ ZydisEncodableEncoding allowed_encodings; /** * The instruction-mnemonic. */ ZydisMnemonic mnemonic; /** * A combination of requested encodable prefixes (`ZYDIS_ATTRIB_HAS_*` flags) for desired * instruction. See `ZYDIS_ENCODABLE_PREFIXES` for list of available prefixes. */ ZydisInstructionAttributes prefixes; /** * Branch type (required for branching instructions only). Use `ZYDIS_BRANCH_TYPE_NONE` to let * encoder pick size-optimal branch type automatically (`short` and `near` are prioritized over * `far`). */ ZydisBranchType branch_type; /** * Specifies physical size for relative immediate operands. Use `ZYDIS_BRANCH_WIDTH_NONE` to * let encoder pick size-optimal branch width automatically. For segment:offset `far` branches * this field applies to physical size of the offset part. For branching instructions without * relative operands this field affects effective operand size attribute. */ ZydisBranchWidth branch_width; /** * Optional address size hint used to resolve ambiguities for some instructions. Generally * encoder deduces address size from `ZydisEncoderOperand` structures that represent * explicit and implicit operands. This hint resolves conflicts when instruction's hidden * operands scale with address size attribute. * * This hint is also used for instructions with absolute memory addresses (memory operands with * displacement and no registers). Since displacement field is a 64-bit signed integer it's not * possible to determine actual size of the address value in all situations. This hint * specifies size of the address value provided inside encoder request rather than desired * address size attribute of encoded instruction. Use `ZYDIS_ADDRESS_SIZE_HINT_NONE` to assume * address size default for specified machine mode. */ ZydisAddressSizeHint address_size_hint; /** * Optional operand size hint used to resolve ambiguities for some instructions. Generally * encoder deduces operand size from `ZydisEncoderOperand` structures that represent * explicit and implicit operands. This hint resolves conflicts when instruction's hidden * operands scale with operand size attribute. */ ZydisOperandSizeHint operand_size_hint; /** * The number of instruction-operands. */ ZyanU8 operand_count; /** * Detailed info for all explicit and implicit instruction operands. */ ZydisEncoderOperand operands[ZYDIS_ENCODER_MAX_OPERANDS]; /** * Extended info for `EVEX` instructions. */ struct ZydisEncoderRequestEvexFeatures_ { /** * The broadcast-mode. Specify `ZYDIS_BROADCAST_MODE_INVALID` for instructions with * static broadcast functionality. */ ZydisBroadcastMode broadcast; /** * The rounding-mode. */ ZydisRoundingMode rounding; /** * Signals, if the `SAE` (suppress-all-exceptions) functionality should be enabled for * the instruction. */ ZyanBool sae; /** * Signals, if the zeroing-mask functionality should be enabled for the instruction. * Specify `ZYAN_TRUE` for instructions with forced zeroing mask. */ ZyanBool zeroing_mask; } evex; /** * Extended info for `MVEX` instructions. */ struct ZydisEncoderRequestMvexFeatures_ { /** * The broadcast-mode. */ ZydisBroadcastMode broadcast; /** * The data-conversion mode. */ ZydisConversionMode conversion; /** * The rounding-mode. */ ZydisRoundingMode rounding; /** * The `AVX` register-swizzle mode. */ ZydisSwizzleMode swizzle; /** * Signals, if the `SAE` (suppress-all-exceptions) functionality is enabled for * the instruction. */ ZyanBool sae; /** * Signals, if the instruction has a memory-eviction-hint (`KNC` only). */ ZyanBool eviction_hint; } mvex; } ZydisEncoderRequest; /* ============================================================================================== */ /* Exported functions */ /* ============================================================================================== */ /** * @addtogroup encoder Encoder * Functions allowing encoding of instruction bytes from a machine interpretable struct. * @{ */ /** * Encodes instruction with semantics specified in encoder request structure. * * @param request A pointer to the `ZydisEncoderRequest` struct. * @param buffer A pointer to the output buffer receiving encoded instruction. * @param length A pointer to the variable containing length of the output buffer. Upon * successful return this variable receives length of the encoded instruction. * * @return A zyan status code. */ ZYDIS_EXPORT ZyanStatus ZydisEncoderEncodeInstruction(const ZydisEncoderRequest *request, void *buffer, ZyanUSize *length); /** * Encodes instruction with semantics specified in encoder request structure. This function expects * absolute addresses inside encoder request instead of `EIP`/`RIP`-relative values. Function * predicts final instruction length prior to encoding and writes back calculated relative operands * to provided encoder request. * * @param request A pointer to the `ZydisEncoderRequest` struct. * @param buffer A pointer to the output buffer receiving encoded instruction. * @param length A pointer to the variable containing length of the output buffer. Upon * successful return this variable receives length of the encoded * instruction. * @param runtime_address The runtime address of the instruction. * * @return A zyan status code. */ ZYDIS_EXPORT ZyanStatus ZydisEncoderEncodeInstructionAbsolute(ZydisEncoderRequest *request, void *buffer, ZyanUSize *length, ZyanU64 runtime_address); /** * Converts decoded instruction to encoder request that can be passed to * `ZydisEncoderEncodeInstruction`. * * @param instruction A pointer to the `ZydisDecodedInstruction` struct. * @param operands A pointer to the decoded operands. * @param operand_count The operand count. * @param request A pointer to the `ZydisEncoderRequest` struct, that receives * information necessary for encoder to re-encode the instruction. * * This function performs simple structure conversion and does minimal sanity checks on the * input. There's no guarantee that produced request will be accepted by * `ZydisEncoderEncodeInstruction` if malformed `ZydisDecodedInstruction` or malformed * `ZydisDecodedOperands` is passed to this function. * * @return A zyan status code. */ ZYDIS_EXPORT ZyanStatus ZydisEncoderDecodedInstructionToEncoderRequest( const ZydisDecodedInstruction* instruction, const ZydisDecodedOperand* operands, ZyanU8 operand_count, ZydisEncoderRequest* request); /** * Fills provided buffer with `NOP` instructions using longest possible multi-byte instructions. * * @param buffer A pointer to the output buffer receiving encoded instructions. * @param length Size of the output buffer. * * @return A zyan status code. */ ZYDIS_EXPORT ZyanStatus ZydisEncoderNopFill(void *buffer, ZyanUSize length); /** @} */ /* ============================================================================================== */ #ifdef __cplusplus } #endif #endif /* ZYDIS_ENCODER_H */