Formatter.h

Go to the documentation of this file.

/***************************************************************************************************

  Zyan Disassembler Library (Zydis)

  Original Author : Florian Bernd

 * 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.

***************************************************************************************************/

#ifndef ZYDIS_FORMATTER_H
#define ZYDIS_FORMATTER_H

#include <Zycore/Defines.h>
#include <Zycore/String.h>
#include <Zycore/Types.h>
#include <Zydis/DecoderTypes.h>
#include <Zydis/FormatterBuffer.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================================================== */
/* Constants                                                                                      */
/* ============================================================================================== */

#define ZYDIS_RUNTIME_ADDRESS_NONE (ZyanU64)(-1)

/* ============================================================================================== */
/* Enums and types                                                                                */
/* ============================================================================================== */

/* ---------------------------------------------------------------------------------------------- */
/* Formatter style                                                                                */
/* ---------------------------------------------------------------------------------------------- */

typedef enum ZydisFormatterStyle_
{
    ZYDIS_FORMATTER_STYLE_ATT,
    ZYDIS_FORMATTER_STYLE_INTEL,
    ZYDIS_FORMATTER_STYLE_INTEL_MASM,

    ZYDIS_FORMATTER_STYLE_MAX_VALUE = ZYDIS_FORMATTER_STYLE_INTEL_MASM,
    ZYDIS_FORMATTER_STYLE_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_FORMATTER_STYLE_MAX_VALUE)
} ZydisFormatterStyle;

/* ---------------------------------------------------------------------------------------------- */
/* Properties                                                                                     */
/* ---------------------------------------------------------------------------------------------- */

typedef enum ZydisFormatterProperty_
{
    /* ---------------------------------------------------------------------------------------- */
    /* General                                                                                  */
    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_PROP_FORCE_SIZE,
    ZYDIS_FORMATTER_PROP_FORCE_SEGMENT,
    ZYDIS_FORMATTER_PROP_FORCE_RELATIVE_BRANCHES,
    ZYDIS_FORMATTER_PROP_FORCE_RELATIVE_RIPREL,
    ZYDIS_FORMATTER_PROP_PRINT_BRANCH_SIZE,

    ZYDIS_FORMATTER_PROP_DETAILED_PREFIXES,

    /* ---------------------------------------------------------------------------------------- */
    /* Numeric values                                                                           */
    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_PROP_ADDR_BASE,
    ZYDIS_FORMATTER_PROP_ADDR_SIGNEDNESS,
    ZYDIS_FORMATTER_PROP_ADDR_PADDING_ABSOLUTE,
    ZYDIS_FORMATTER_PROP_ADDR_PADDING_RELATIVE,

    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_PROP_DISP_BASE,
    ZYDIS_FORMATTER_PROP_DISP_SIGNEDNESS,
    ZYDIS_FORMATTER_PROP_DISP_PADDING,

    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_PROP_IMM_BASE,
    ZYDIS_FORMATTER_PROP_IMM_SIGNEDNESS,
    ZYDIS_FORMATTER_PROP_IMM_PADDING,

    /* ---------------------------------------------------------------------------------------- */
    /* Text formatting                                                                          */
    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_PROP_UPPERCASE_PREFIXES,
    ZYDIS_FORMATTER_PROP_UPPERCASE_MNEMONIC,
    ZYDIS_FORMATTER_PROP_UPPERCASE_REGISTERS,
    ZYDIS_FORMATTER_PROP_UPPERCASE_TYPECASTS,
    ZYDIS_FORMATTER_PROP_UPPERCASE_DECORATORS,

    /* ---------------------------------------------------------------------------------------- */
    /* Number formatting                                                                        */
    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_PROP_DEC_PREFIX,
    ZYDIS_FORMATTER_PROP_DEC_SUFFIX,

    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_PROP_HEX_UPPERCASE,
    ZYDIS_FORMATTER_PROP_HEX_PREFIX,
    ZYDIS_FORMATTER_PROP_HEX_SUFFIX,

    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_PROP_MAX_VALUE = ZYDIS_FORMATTER_PROP_HEX_SUFFIX,
    ZYDIS_FORMATTER_PROP_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_FORMATTER_PROP_MAX_VALUE)
} ZydisFormatterProperty;

/* ---------------------------------------------------------------------------------------------- */

typedef enum ZydisNumericBase_
{
    ZYDIS_NUMERIC_BASE_DEC,
    ZYDIS_NUMERIC_BASE_HEX,

    ZYDIS_NUMERIC_BASE_MAX_VALUE = ZYDIS_NUMERIC_BASE_HEX,
    ZYDIS_NUMERIC_BASE_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_NUMERIC_BASE_MAX_VALUE)
} ZydisNumericBase;

/* ---------------------------------------------------------------------------------------------- */

typedef enum ZydisSignedness_
{
    ZYDIS_SIGNEDNESS_AUTO,
    ZYDIS_SIGNEDNESS_SIGNED,
    ZYDIS_SIGNEDNESS_UNSIGNED,

    ZYDIS_SIGNEDNESS_MAX_VALUE = ZYDIS_SIGNEDNESS_UNSIGNED,
    ZYDIS_SIGNEDNESS_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_SIGNEDNESS_MAX_VALUE)
} ZydisSignedness;

/* ---------------------------------------------------------------------------------------------- */

typedef enum ZydisPadding_
{
    ZYDIS_PADDING_DISABLED = 0,
    ZYDIS_PADDING_AUTO     = (-1),

    ZYDIS_PADDING_MAX_VALUE = ZYDIS_PADDING_AUTO,
    ZYDIS_PADDING_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_PADDING_MAX_VALUE)
} ZydisPadding;

/* ---------------------------------------------------------------------------------------------- */
/* Function types                                                                                 */
/* ---------------------------------------------------------------------------------------------- */

typedef enum ZydisFormatterFunction_
{
    /* ---------------------------------------------------------------------------------------- */
    /* Instruction                                                                              */
    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_FUNC_PRE_INSTRUCTION,
    ZYDIS_FORMATTER_FUNC_POST_INSTRUCTION,

    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_FUNC_FORMAT_INSTRUCTION,

    /* ---------------------------------------------------------------------------------------- */
    /* Operands                                                                                 */
    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_FUNC_PRE_OPERAND,
    ZYDIS_FORMATTER_FUNC_POST_OPERAND,

    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_FUNC_FORMAT_OPERAND_REG,
    ZYDIS_FORMATTER_FUNC_FORMAT_OPERAND_MEM,
    ZYDIS_FORMATTER_FUNC_FORMAT_OPERAND_PTR,
    ZYDIS_FORMATTER_FUNC_FORMAT_OPERAND_IMM,

    /* ---------------------------------------------------------------------------------------- */
    /* Elemental tokens                                                                         */
    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_FUNC_PRINT_MNEMONIC,

    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_FUNC_PRINT_REGISTER,
    ZYDIS_FORMATTER_FUNC_PRINT_ADDRESS_ABS,
    ZYDIS_FORMATTER_FUNC_PRINT_ADDRESS_REL,
    ZYDIS_FORMATTER_FUNC_PRINT_DISP,
    ZYDIS_FORMATTER_FUNC_PRINT_IMM,

    /* ---------------------------------------------------------------------------------------- */
    /* Optional tokens                                                                          */
    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_FUNC_PRINT_TYPECAST,
    ZYDIS_FORMATTER_FUNC_PRINT_SEGMENT,
    ZYDIS_FORMATTER_FUNC_PRINT_PREFIXES,
    ZYDIS_FORMATTER_FUNC_PRINT_DECORATOR,

    /* ---------------------------------------------------------------------------------------- */

    ZYDIS_FORMATTER_FUNC_MAX_VALUE = ZYDIS_FORMATTER_FUNC_PRINT_DECORATOR,
    ZYDIS_FORMATTER_FUNC_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_FORMATTER_FUNC_MAX_VALUE)
} ZydisFormatterFunction;

/* ---------------------------------------------------------------------------------------------- */
/* Decorator types                                                                                */
/* ---------------------------------------------------------------------------------------------- */

typedef enum ZydisDecorator_
{
    ZYDIS_DECORATOR_INVALID,
    ZYDIS_DECORATOR_MASK,
    ZYDIS_DECORATOR_BC,
    ZYDIS_DECORATOR_RC,
    ZYDIS_DECORATOR_SAE,
    ZYDIS_DECORATOR_SWIZZLE,
    ZYDIS_DECORATOR_CONVERSION,
    ZYDIS_DECORATOR_EH,

    ZYDIS_DECORATOR_MAX_VALUE = ZYDIS_DECORATOR_EH,
    ZYDIS_DECORATOR_REQUIRED_BITS = ZYAN_BITS_TO_REPRESENT(ZYDIS_DECORATOR_MAX_VALUE)
} ZydisDecorator;

/* ---------------------------------------------------------------------------------------------- */
/* Formatter context                                                                              */
/* ---------------------------------------------------------------------------------------------- */

typedef struct ZydisFormatter_ ZydisFormatter;

typedef struct ZydisFormatterContext_
{
    const ZydisDecodedInstruction* instruction;
    const ZydisDecodedOperand* operand;
    ZyanU64 runtime_address;
    void* user_data;
} ZydisFormatterContext;

/* ---------------------------------------------------------------------------------------------- */
/* Function prototypes                                                                            */
/* ---------------------------------------------------------------------------------------------- */

typedef ZyanStatus (*ZydisFormatterFunc)(const ZydisFormatter* formatter,
    ZydisFormatterBuffer* buffer, ZydisFormatterContext* context);

typedef ZyanStatus (*ZydisFormatterRegisterFunc)(const ZydisFormatter* formatter,
    ZydisFormatterBuffer* buffer, ZydisFormatterContext* context, ZydisRegister reg);

typedef ZyanStatus (*ZydisFormatterDecoratorFunc)(const ZydisFormatter* formatter,
    ZydisFormatterBuffer* buffer, ZydisFormatterContext* context, ZydisDecorator decorator);

/* ---------------------------------------------------------------------------------------------- */
/* Formatter struct                                                                               */
/* ---------------------------------------------------------------------------------------------- */

struct ZydisFormatter_
{
    ZydisFormatterStyle style;
    ZyanBool force_memory_size;
    ZyanBool force_memory_segment;
    ZyanBool force_relative_branches;
    ZyanBool force_relative_riprel;
    ZyanBool print_branch_size;
    ZyanBool detailed_prefixes;
    ZydisNumericBase addr_base;
    ZydisSignedness addr_signedness;
    ZydisPadding addr_padding_absolute;
    ZydisPadding addr_padding_relative;
    ZydisNumericBase disp_base;
    ZydisSignedness disp_signedness;
    ZydisPadding disp_padding;
    ZydisNumericBase imm_base;
    ZydisSignedness imm_signedness;
    ZydisPadding imm_padding;
    ZyanI32 case_prefixes;
    ZyanI32 case_mnemonic;
    ZyanI32 case_registers;
    ZyanI32 case_typecasts;
    ZyanI32 case_decorators;
    ZyanBool hex_uppercase;
    struct
    {
        const ZyanStringView* string;
        ZyanStringView string_data;
        char buffer[11];
    } number_format[ZYDIS_NUMERIC_BASE_MAX_VALUE + 1][2];
    ZydisFormatterFunc func_pre_instruction;
    ZydisFormatterFunc func_post_instruction;
    ZydisFormatterFunc func_format_instruction;
    ZydisFormatterFunc func_pre_operand;
    ZydisFormatterFunc func_post_operand;
    ZydisFormatterFunc func_format_operand_reg;
    ZydisFormatterFunc func_format_operand_mem;
    ZydisFormatterFunc func_format_operand_ptr;
    ZydisFormatterFunc func_format_operand_imm;
    ZydisFormatterFunc func_print_mnemonic;
    ZydisFormatterRegisterFunc func_print_register;
    ZydisFormatterFunc func_print_address_abs;
    ZydisFormatterFunc func_print_address_rel;
    ZydisFormatterFunc func_print_disp;
    ZydisFormatterFunc func_print_imm;
    ZydisFormatterFunc func_print_typecast;
    ZydisFormatterFunc func_print_segment;
    ZydisFormatterFunc func_print_prefixes;
    ZydisFormatterDecoratorFunc func_print_decorator;
};

/* ---------------------------------------------------------------------------------------------- */

/* ============================================================================================== */
/* Exported functions                                                                             */
/* ============================================================================================== */

/* ---------------------------------------------------------------------------------------------- */
/* Initialization                                                                                 */
/* ---------------------------------------------------------------------------------------------- */

ZYDIS_EXPORT ZyanStatus ZydisFormatterInit(ZydisFormatter* formatter, ZydisFormatterStyle style);

/* ---------------------------------------------------------------------------------------------- */
/* Setter                                                                                         */
/* ---------------------------------------------------------------------------------------------- */

ZYDIS_EXPORT ZyanStatus ZydisFormatterSetProperty(ZydisFormatter* formatter,
    ZydisFormatterProperty property, ZyanUPointer value);

ZYDIS_EXPORT ZyanStatus ZydisFormatterSetHook(ZydisFormatter* formatter,
    ZydisFormatterFunction type, const void** callback);

/* ---------------------------------------------------------------------------------------------- */
/* Formatting                                                                                     */
/* ---------------------------------------------------------------------------------------------- */

ZYDIS_EXPORT ZyanStatus ZydisFormatterFormatInstruction(const ZydisFormatter* formatter,
    const ZydisDecodedInstruction* instruction, char* buffer, ZyanUSize length,
    ZyanU64 runtime_address);

ZYDIS_EXPORT ZyanStatus ZydisFormatterFormatInstructionEx(const ZydisFormatter* formatter,
    const ZydisDecodedInstruction* instruction, char* buffer, ZyanUSize length,
    ZyanU64 runtime_address, void* user_data);

ZYDIS_EXPORT ZyanStatus ZydisFormatterFormatOperand(const ZydisFormatter* formatter,
    const ZydisDecodedInstruction* instruction, ZyanU8 index, char* buffer, ZyanUSize length,
    ZyanU64 runtime_address);

ZYDIS_EXPORT ZyanStatus ZydisFormatterFormatOperandEx(const ZydisFormatter* formatter,
    const ZydisDecodedInstruction* instruction, ZyanU8 index, char* buffer, ZyanUSize length,
    ZyanU64 runtime_address, void* user_data);

/* ---------------------------------------------------------------------------------------------- */
/* Tokenizing                                                                                     */
/* ---------------------------------------------------------------------------------------------- */

ZYDIS_EXPORT ZyanStatus ZydisFormatterTokenizeInstruction(const ZydisFormatter* formatter,
    const ZydisDecodedInstruction* instruction, void* buffer, ZyanUSize length,
    ZyanU64 runtime_address, ZydisFormatterTokenConst** token);

ZYDIS_EXPORT ZyanStatus ZydisFormatterTokenizeInstructionEx(const ZydisFormatter* formatter,
    const ZydisDecodedInstruction* instruction, void* buffer, ZyanUSize length,
    ZyanU64 runtime_address, ZydisFormatterTokenConst** token, void* user_data);

ZYDIS_EXPORT ZyanStatus ZydisFormatterTokenizeOperand(const ZydisFormatter* formatter,
    const ZydisDecodedInstruction* instruction, ZyanU8 index, void* buffer, ZyanUSize length,
    ZyanU64 runtime_address, ZydisFormatterTokenConst** token);

ZYDIS_EXPORT ZyanStatus ZydisFormatterTokenizeOperandEx(const ZydisFormatter* formatter,
    const ZydisDecodedInstruction* instruction, ZyanU8 index, void* buffer, ZyanUSize length,
    ZyanU64 runtime_address, ZydisFormatterTokenConst** token, void* user_data);

/* ---------------------------------------------------------------------------------------------- */

/* ============================================================================================== */

#ifdef __cplusplus
}
#endif

#endif /* ZYDIS_FORMATTER_H */