Zydis  v2.0.0-alpha1
Formatter.h File Reference
#include <Zydis/DecoderTypes.h>
#include <Zydis/Defines.h>
#include <Zydis/Status.h>
Include dependency graph for Formatter.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ZydisFormatter_
 Defines the ZydisFormatter struct. More...
 

Macros

#define ZYDIS_FMTFLAG_UPPERCASE   0x00000001
 Formats the instruction in uppercase instead of lowercase. More...
 
#define ZYDIS_FMTFLAG_FORCE_SEGMENTS   0x00000002
 Forces the formatter to always print the segment register of memory-operands, instead of ommiting implicit DS/SS segments. More...
 
#define ZYDIS_FMTFLAG_FORCE_OPERANDSIZE   0x00000004
 Forces the formatter to always print the size of memory-operands. More...
 

Typedefs

typedef uint8_t ZydisFormatterStyle
 Defines the ZydisFormatterStyle datatype. More...
 
typedef uint32_t ZydisFormatterFlags
 Defines the ZydisFormatFlags datatype. More...
 
typedef uint8_t ZydisFormatterAddressFormat
 Defines the ZydisFormatterAddressFormat datatype. More...
 
typedef uint8_t ZydisFormatterDisplacementFormat
 Defines the ZydisFormatterDisplacementFormat datatype. More...
 
typedef uint8_t ZydisFormatterImmediateFormat
 Defines the ZydisFormatterImmediateFormat datatype. More...
 
typedef uint8_t ZydisFormatterHookType
 Defines the ZydisFormatterHookType datatype. More...
 
typedef uint8_t ZydisDecoratorType
 Defines the ZydisDecoratorType datatype. More...
 
typedef struct ZydisFormatter_ ZydisFormatter
 
typedef ZydisStatus(* ZydisFormatterNotifyFunc) (const ZydisFormatter *formatter, ZydisDecodedInstruction *instruction)
 Defines the ZydisFormatterNotifyFunc function pointer. More...
 
typedef ZydisStatus(* ZydisFormatterFormatFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, ZydisDecodedInstruction *instruction)
 Defines the ZydisFormatterFormatFunc function pointer. More...
 
typedef ZydisStatus(* ZydisFormatterFormatOperandFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, ZydisDecodedInstruction *instruction, ZydisDecodedOperand *operand)
 Defines the ZydisFormatterFormatOperandFunc function pointer. More...
 
typedef ZydisStatus(* ZydisFormatterFormatAddressFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, ZydisDecodedInstruction *instruction, ZydisDecodedOperand *operand, uint64_t address)
 Defines the ZydisFormatterFormatAddressFunc function pointer. More...
 
typedef ZydisStatus(* ZydisFormatterFormatDecoratorFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, ZydisDecodedInstruction *instruction, ZydisDecodedOperand *operand, ZydisDecoratorType type)
 Defines the ZydisFormatterFormatDecoratorFunc function pointer. More...
 

Enumerations

enum  ZydisFormatterStyles { ZYDIS_FORMATTER_STYLE_INTEL }
 Values that represent formatter-styles. More...
 
enum  ZydisFormatterAddressFormats { ZYDIS_FORMATTER_ADDR_DEFAULT , ZYDIS_FORMATTER_ADDR_ABSOLUTE , ZYDIS_FORMATTER_ADDR_RELATIVE_SIGNED , ZYDIS_FORMATTER_ADDR_RELATIVE_UNSIGNED }
 Values that represent address-formats. More...
 
enum  ZydisFormatterDisplacementFormats { ZYDIS_FORMATTER_DISP_DEFAULT , ZYDIS_FORMATTER_DISP_HEX_SIGNED , ZYDIS_FORMATTER_DISP_HEX_UNSIGNED }
 Values that represent displacement-formats. More...
 
enum  ZydisFormatterImmediateFormats { ZYDIS_FORMATTER_IMM_DEFAULT , ZYDIS_FORMATTER_IMM_HEX_AUTO , ZYDIS_FORMATTER_IMM_HEX_SIGNED , ZYDIS_FORMATTER_IMM_HEX_UNSIGNED }
 Values that represent formatter immediate-formats. More...
 
enum  ZydisFormatterHookTypes {
  ZYDIS_FORMATTER_HOOK_PRE , ZYDIS_FORMATTER_HOOK_POST , ZYDIS_FORMATTER_HOOK_FORMAT_INSTRUCTION , ZYDIS_FORMATTER_HOOK_PRINT_PREFIXES ,
  ZYDIS_FORMATTER_HOOK_PRINT_MNEMONIC , ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_REG , ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_MEM , ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_PTR ,
  ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_IMM , ZYDIS_FORMATTER_HOOK_PRINT_OPERANDSIZE , ZYDIS_FORMATTER_HOOK_PRINT_SEGMENT , ZYDIS_FORMATTER_HOOK_PRINT_DECORATOR ,
  ZYDIS_FORMATTER_HOOK_PRINT_ADDRESS , ZYDIS_FORMATTER_HOOK_PRINT_DISPLACEMENT , ZYDIS_FORMATTER_HOOK_PRINT_IMMEDIATE
}
 Values that represent formatter hook-types. More...
 
enum  ZydisDecoratorTypes {
  ZYDIS_DECORATOR_TYPE_INVALID , ZYDIS_DECORATOR_TYPE_MASK , ZYDIS_DECORATOR_TYPE_BROADCAST , ZYDIS_DECORATOR_TYPE_ROUNDING_CONTROL ,
  ZYDIS_DECORATOR_TYPE_SAE , ZYDIS_DECORATOR_TYPE_SWIZZLE , ZYDIS_DECORATOR_TYPE_CONVERSION , ZYDIS_DECORATOR_TYPE_EVICTION_HINT
}
 Values that represent decorator-types. More...
 

Functions

ZYDIS_EXPORT ZydisStatus ZydisFormatterInit (ZydisFormatter *formatter, ZydisFormatterStyle style)
 Initializes the given ZydisFormatter instance. More...
 
ZYDIS_EXPORT ZydisStatus ZydisFormatterInitEx (ZydisFormatter *formatter, ZydisFormatterStyle style, ZydisFormatterFlags flags, ZydisFormatterAddressFormat addressFormat, ZydisFormatterDisplacementFormat displacementFormat, ZydisFormatterImmediateFormat immmediateFormat)
 Initializes the given ZydisFormatter instance. More...
 
ZYDIS_EXPORT ZydisStatus ZydisFormatterSetHook (ZydisFormatter *formatter, ZydisFormatterHookType hook, const void **callback)
 Replaces a formatter function with a custom callback and/or retrieves the currently used function. More...
 
ZYDIS_EXPORT ZydisStatus ZydisFormatterFormatInstruction (const ZydisFormatter *formatter, ZydisDecodedInstruction *instruction, char *buffer, size_t bufferLen)
 Formats the given instruction and writes it into the output buffer. More...
 

Macro Definition Documentation

◆ ZYDIS_FMTFLAG_FORCE_OPERANDSIZE

#define ZYDIS_FMTFLAG_FORCE_OPERANDSIZE   0x00000004

Forces the formatter to always print the size of memory-operands.

◆ ZYDIS_FMTFLAG_FORCE_SEGMENTS

#define ZYDIS_FMTFLAG_FORCE_SEGMENTS   0x00000002

Forces the formatter to always print the segment register of memory-operands, instead of ommiting implicit DS/SS segments.

◆ ZYDIS_FMTFLAG_UPPERCASE

#define ZYDIS_FMTFLAG_UPPERCASE   0x00000001

Formats the instruction in uppercase instead of lowercase.

Typedef Documentation

◆ ZydisDecoratorType

typedef uint8_t ZydisDecoratorType

Defines the ZydisDecoratorType datatype.

◆ ZydisFormatter

◆ ZydisFormatterAddressFormat

typedef uint8_t ZydisFormatterAddressFormat

Defines the ZydisFormatterAddressFormat datatype.

◆ ZydisFormatterDisplacementFormat

Defines the ZydisFormatterDisplacementFormat datatype.

◆ ZydisFormatterFlags

typedef uint32_t ZydisFormatterFlags

Defines the ZydisFormatFlags datatype.

◆ ZydisFormatterFormatAddressFunc

typedef ZydisStatus(* ZydisFormatterFormatAddressFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, ZydisDecodedInstruction *instruction, ZydisDecodedOperand *operand, uint64_t address)

Defines the ZydisFormatterFormatAddressFunc function pointer.

Parameters
formatterA pointer to the ZydisFormatter instance.
bufferA pointer to the string-buffer.
bufferLenThe length of the string-buffer.
instructionA pointer to the ZydisDecodedInstruction struct.
operandA pointer to the ZydisDecodedOperand struct.
Returns
Returning a status code other than ZYDIS_STATUS_SUCCESS will immediately cause the formatting process to fail.

After appending text to the buffer you MUST increase the buffer-pointer by the size of the number of chars written. Not increasing the buffer-pointer will cause unexpected behavior.

This function type is used for the ZYDIS_FORMATTER_HOOK_PRINT_ADDRESS hook-type.

◆ ZydisFormatterFormatDecoratorFunc

typedef ZydisStatus(* ZydisFormatterFormatDecoratorFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, ZydisDecodedInstruction *instruction, ZydisDecodedOperand *operand, ZydisDecoratorType type)

Defines the ZydisFormatterFormatDecoratorFunc function pointer.

Parameters
formatterA pointer to the ZydisFormatter instance.
bufferA pointer to the string-buffer.
bufferLenThe length of the string-buffer.
instructionA pointer to the ZydisDecodedInstruction struct.
operandA pointer to the ZydisDecodedOperand struct.
typeThe decorator type.
Returns
Returning a status code other than ZYDIS_STATUS_SUCCESS will immediately cause the formatting process to fail.

After appending text to the buffer you MUST increase the buffer-pointer by the size of the number of chars written.

Returning ZYDIS_STATUS_SUCCESS without increasing the buffer-pointer is valid and will cause the formatter to omit the current decorator.

This function type is used for the ZYDIS_FORMATTER_HOOK_PRINT_DECORATOR hook-type.

◆ ZydisFormatterFormatFunc

typedef ZydisStatus(* ZydisFormatterFormatFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, ZydisDecodedInstruction *instruction)

Defines the ZydisFormatterFormatFunc function pointer.

Parameters
formatterA pointer to the ZydisFormatter instance.
bufferA pointer to the string-buffer.
bufferLenThe length of the string-buffer.
instructionA pointer to the ZydisDecodedInstruction struct.
Returns
Returning a status code other than ZYDIS_STATUS_SUCCESS will immediately cause the formatting process to fail.

After appending text to the buffer you MUST increase the buffer-pointer by the size of the number of chars written. Not increasing the buffer-pointer will cause unexpected behavior.

This function type is used for the ZYDIS_FORMATTER_HOOK_FORMAT_INSTRUCTION, ZYDIS_FORMATTER_HOOK_PRINT_PREFIXES and ZYDIS_FORMATTER_HOOK_PRINT_MNEMONIC hook-types.

◆ ZydisFormatterFormatOperandFunc

typedef ZydisStatus(* ZydisFormatterFormatOperandFunc) (const ZydisFormatter *formatter, char **buffer, size_t bufferLen, ZydisDecodedInstruction *instruction, ZydisDecodedOperand *operand)

Defines the ZydisFormatterFormatOperandFunc function pointer.

Parameters
formatterA pointer to the ZydisFormatter instance.
bufferA pointer to the string-buffer.
bufferLenThe length of the string-buffer.
instructionA pointer to the ZydisDecodedInstruction struct.
operandA pointer to the ZydisDecodedOperand struct.
Returns
Returning a status code other than ZYDIS_STATUS_SUCCESS will immediately cause the formatting process to fail.

After appending text to the buffer you MUST increase the buffer-pointer by the size of the number of chars written.

Returning ZYDIS_STATUS_SUCCESS in one of the ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_X hooks without increasing the buffer-pointer is valid and will cause the formatter to omit the current operand.

Returning ZYDIS_STATUS_SUCCESS in ZYDIS_FORMATTER_HOOK_PRINT_OPERANDSIZE, ZYDIS_FORMATTER_HOOK_PRINT_SEGMENT or ZYDIS_FORMATTER_HOOK_PRINT_DECORATOR without increasing the buffer-pointer is valid and signals that the corresponding element should not be printed for the current operand.

Not increasing the buffer-pointer for any other hook-type will cause unexpected behavior.

This function type is used for the ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_REG, ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_MEM, ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_PTR, ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_IMM, ZYDIS_FORMATTER_HOOK_PRINT_OPERANDSIZE, ZYDIS_FORMATTER_HOOK_PRINT_SEGMENT, ZYDIS_FORMATTER_HOOK_PRINT_DECORATOR, ZYDIS_FORMATTER_HOOK_PRINT_DISPLACEMENT and ZYDIS_FORMATTER_HOOK_PRINT_IMMEDIATE hook-types.

◆ ZydisFormatterHookType

typedef uint8_t ZydisFormatterHookType

Defines the ZydisFormatterHookType datatype.

◆ ZydisFormatterImmediateFormat

Defines the ZydisFormatterImmediateFormat datatype.

◆ ZydisFormatterNotifyFunc

typedef ZydisStatus(* ZydisFormatterNotifyFunc) (const ZydisFormatter *formatter, ZydisDecodedInstruction *instruction)

Defines the ZydisFormatterNotifyFunc function pointer.

Parameters
formatterA pointer to the ZydisFormatter instance.
instructionA pointer to the ZydisDecodedInstruction struct.
Returns
Returning a status code other than ZYDIS_STATUS_SUCCESS will immediately cause the formatting process to fail.

This function type is used for the ZYDIS_FORMATTER_HOOK_PRE and ZYDIS_FORMATTER_HOOK_POST hook-types.

◆ ZydisFormatterStyle

typedef uint8_t ZydisFormatterStyle

Defines the ZydisFormatterStyle datatype.

Enumeration Type Documentation

◆ ZydisDecoratorTypes

Values that represent decorator-types.

Enumerator
ZYDIS_DECORATOR_TYPE_INVALID 
ZYDIS_DECORATOR_TYPE_MASK 
ZYDIS_DECORATOR_TYPE_BROADCAST 
ZYDIS_DECORATOR_TYPE_ROUNDING_CONTROL 
ZYDIS_DECORATOR_TYPE_SAE 
ZYDIS_DECORATOR_TYPE_SWIZZLE 
ZYDIS_DECORATOR_TYPE_CONVERSION 
ZYDIS_DECORATOR_TYPE_EVICTION_HINT 

◆ ZydisFormatterAddressFormats

Values that represent address-formats.

Enumerator
ZYDIS_FORMATTER_ADDR_DEFAULT 

Currently defaults to ZYDIS_FORMATTER_ADDR_ABSOLUTE.

ZYDIS_FORMATTER_ADDR_ABSOLUTE 

Displays absolute addresses instead of relative ones.

ZYDIS_FORMATTER_ADDR_RELATIVE_SIGNED 

Uses signed hexadecimal values to display relative addresses.

Examples: "JMP 0x20" "JMP -0x20"

ZYDIS_FORMATTER_ADDR_RELATIVE_UNSIGNED 

Uses unsigned hexadecimal values to display relative addresses.

Examples: "JMP 0x20" "JMP 0xE0"

◆ ZydisFormatterDisplacementFormats

Values that represent displacement-formats.

Enumerator
ZYDIS_FORMATTER_DISP_DEFAULT 

Currently defaults to ZYDIS_FORMATTER_DISP_HEX_SIGNED.

ZYDIS_FORMATTER_DISP_HEX_SIGNED 

Formats displacements as signed hexadecimal values.

Examples: "MOV EAX, DWORD PTR SS:[ESP+0x400]" "MOV EAX, DWORD PTR SS:[ESP-0x400]"

ZYDIS_FORMATTER_DISP_HEX_UNSIGNED 

Formats displacements as unsigned hexadecimal values.

Examples: "MOV EAX, DWORD PTR SS:[ESP+0x400]" "MOV EAX, DWORD PTR SS:[ESP+0xFFFFFC00]"

◆ ZydisFormatterHookTypes

Values that represent formatter hook-types.

Enumerator
ZYDIS_FORMATTER_HOOK_PRE 

This function is called before the formatter starts formatting an instruction.

ZYDIS_FORMATTER_HOOK_POST 

This function is called before the formatter finished formatting an instruction.

ZYDIS_FORMATTER_HOOK_FORMAT_INSTRUCTION 

This function refers to the main formatting function, that internally calls all
other function except the ones that are hooked by ZYDIS_FORMATTER_HOOK_PRE and ZYDIS_FORMATTER_HOOK_POST.

Replacing this function allows for complete custom formatting, but indirectly disables all other hooks except for ZYDIS_FORMATTER_HOOK_PRE and ZYDIS_FORMATTER_HOOK_POST.

ZYDIS_FORMATTER_HOOK_PRINT_PREFIXES 

This function is called to print the instruction prefixes.

ZYDIS_FORMATTER_HOOK_PRINT_MNEMONIC 

This function is called to print the instruction mnemonic.

ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_REG 

This function is called to format an register operand.

ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_MEM 

This function is called to format an memory operand.

Replacing this function might indirectly disable some specific calls to the ZYDIS_FORMATTER_PRINT_ADDRESS and ZYDIS_FORMATTER_HOOK_PRINT_DISPLACEMENT functions.

ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_PTR 

This function is called to format an pointer operand.

ZYDIS_FORMATTER_HOOK_FORMAT_OPERAND_IMM 

This function is called to format an immediate operand.

Replacing this function might indirectly disable some specific calls to the ZYDIS_FORMATTER_PRINT_ADDRESS and ZYDIS_FORMATTER_HOOK_PRINT_IMMEDIATE functions.

ZYDIS_FORMATTER_HOOK_PRINT_OPERANDSIZE 

This function is called right before formatting an memory operand to print the optional size-specifier.

ZYDIS_FORMATTER_HOOK_PRINT_SEGMENT 

This function is called right before formatting an memory operand to print the optional segment-register.

ZYDIS_FORMATTER_HOOK_PRINT_DECORATOR 

This function is called right after formatting an operand to print the optional EVEX/MVEX operand-decorator.

ZYDIS_FORMATTER_HOOK_PRINT_ADDRESS 

This function is called to print an absolute address.

ZYDIS_FORMATTER_HOOK_PRINT_DISPLACEMENT 

This function is called to print a memory displacement value.

ZYDIS_FORMATTER_HOOK_PRINT_IMMEDIATE 

This function is called to print an immediate value.

◆ ZydisFormatterImmediateFormats

Values that represent formatter immediate-formats.

Enumerator
ZYDIS_FORMATTER_IMM_DEFAULT 

Currently defaults to ZYDIS_FORMATTER_IMM_HEX_UNSIGNED.

ZYDIS_FORMATTER_IMM_HEX_AUTO 

Automatically chooses the most suitable formatting-mode based on the operands ZydisOperandInfo.imm.isSigned attribute.

ZYDIS_FORMATTER_IMM_HEX_SIGNED 

Formats immediates as signed hexadecimal values.

Examples: "MOV EAX, 0x400" "MOV EAX, -0x400"

ZYDIS_FORMATTER_IMM_HEX_UNSIGNED 

Formats immediates as unsigned hexadecimal values.

Examples: "MOV EAX, 0x400" "MOV EAX, 0xFFFFFC00"

◆ ZydisFormatterStyles

Values that represent formatter-styles.

Enumerator
ZYDIS_FORMATTER_STYLE_INTEL 

Generates intel-style disassembly.

Function Documentation

◆ ZydisFormatterFormatInstruction()

ZYDIS_EXPORT ZydisStatus ZydisFormatterFormatInstruction ( const ZydisFormatter formatter,
ZydisDecodedInstruction instruction,
char *  buffer,
size_t  bufferLen 
)

Formats the given instruction and writes it into the output buffer.

Parameters
formatterA pointer to the ZydisFormatter instance.
instructionA pointer to the ZydisDecodedInstruction struct.
bufferA pointer to the output buffer.
bufferLenThe length of the output buffer.
Returns
A zydis status code.

◆ ZydisFormatterInit()

ZYDIS_EXPORT ZydisStatus ZydisFormatterInit ( ZydisFormatter formatter,
ZydisFormatterStyle  style 
)

Initializes the given ZydisFormatter instance.

Parameters
formatterA pointer to the ZydisFormatter instance.
styleThe formatter style.
Returns
A zydis status code.

◆ ZydisFormatterInitEx()

ZYDIS_EXPORT ZydisStatus ZydisFormatterInitEx ( ZydisFormatter formatter,
ZydisFormatterStyle  style,
ZydisFormatterFlags  flags,
ZydisFormatterAddressFormat  addressFormat,
ZydisFormatterDisplacementFormat  displacementFormat,
ZydisFormatterImmediateFormat  immmediateFormat 
)

Initializes the given ZydisFormatter instance.

Parameters
formatterA pointer to the ZydisFormatter instance.
styleThe formatter style.
addressFormatThe address format.
displacementFormatThe displacement format.
immmediateFormatThe immediate format.
Returns
A zydis status code.

◆ ZydisFormatterSetHook()

ZYDIS_EXPORT ZydisStatus ZydisFormatterSetHook ( ZydisFormatter formatter,
ZydisFormatterHookType  hook,
const void **  callback 
)

Replaces a formatter function with a custom callback and/or retrieves the currently used function.

Parameters
formatterA pointer to the ZydisFormatter instance.
hookThe formatter hook-type.
callbackA pointer to a variable that contains the pointer of the callback function and receives the pointer of the currently used function.
Returns
A zydis status code.

Call this function with callback pointing to a NULL value to retrieve the currently used function without replacing it.