/*===-- llvm-c/EnhancedDisassembly.h - Disassembler C Interface ---*- C -*-===*\

|*                                                                            *|

|*                     The LLVM Compiler Infrastructure                       *|

|*                                                                            *|

|* This file is distributed under the University of Illinois Open Source      *|

|* License. See LICENSE.TXT for details.                                      *|

|*                                                                            *|

|*===----------------------------------------------------------------------===*|

|*                                                                            *|

|* This header declares the C interface to EnhancedDisassembly.so, which      *|

|* implements a disassembler with the ability to extract operand values and   *|

|* individual tokens from assembly instructions.                              *|

|*                                                                            *|

|* The header declares additional interfaces if the host compiler supports    *|

|* the blocks API.                                                            *|

|*                                                                            *|

\*===----------------------------------------------------------------------===*/

#ifndef LLVM_C_ENHANCEDDISASSEMBLY_H

#define LLVM_C_ENHANCEDDISASSEMBLY_H

#include "llvm/System/DataTypes.h"

#ifdef __cplusplus

extern "C" {

#endif

/*!

 @typedef EDByteReaderCallback

 Interface to memory from which instructions may be read.

 @param byte A pointer whose target should be filled in with the data returned.

 @param address The address of the byte to be read.

 @param arg An anonymous argument for client use.

 @result 0 on success; -1 otherwise.

 */

typedef int (*EDByteReaderCallback)(uint8_t *byte, uint64_t address, void *arg);

/*!

 @typedef EDRegisterReaderCallback

 Interface to registers from which registers may be read.

 @param value A pointer whose target should be filled in with the value of the

   register.

 @param regID The LLVM register identifier for the register to read.

 @param arg An anonymous argument for client use.

 @result 0 if the register could be read; -1 otherwise.

 */

typedef int (*EDRegisterReaderCallback)(uint64_t *value, unsigned regID, 

                                        void* arg);

/*!

 @typedef EDAssemblySyntax_t

 An assembly syntax for use in tokenizing instructions.

 */

typedef enum {

/*! @constant kEDAssemblySyntaxX86Intel Intel syntax for i386 and x86_64. */

  kEDAssemblySyntaxX86Intel  = 0,

/*! @constant kEDAssemblySyntaxX86ATT AT&T syntax for i386 and x86_64. */

  kEDAssemblySyntaxX86ATT    = 1

} EDAssemblySyntax_t;

/*!

 @typedef EDDisassemblerRef

 Encapsulates a disassembler for a single CPU architecture.

 */

struct EDDisassembler;

typedef struct EDDisassembler *EDDisassemblerRef;

/*!

 @typedef EDInstRef

 Encapsulates a single disassembled instruction in one assembly syntax.

 */

struct EDInst;

typedef struct EDInst *EDInstRef;

/*!

 @typedef EDTokenRef

 Encapsulates a token from the disassembly of an instruction.

 */

struct EDToken;

typedef struct EDToken *EDTokenRef;

/*!

 @typedef EDOperandRef

 Encapsulates an operand of an instruction.

 */

struct EDOperand;

typedef struct EDOperand *EDOperandRef;

/*!

 @functiongroup Getting a disassembler

 */

/*!

 @function EDGetDisassembler

 Gets the disassembler for a given target.

 @param disassembler A pointer whose target will be filled in with the 

   disassembler.

 @param triple Identifies the target.  Example: "x86_64-apple-darwin10"

 @param syntax The assembly syntax to use when decoding instructions.

 @result 0 on success; -1 otherwise.

 */

int EDGetDisassembler(EDDisassemblerRef *disassembler,

                      const char *triple,

                      EDAssemblySyntax_t syntax);

/*!

 @functiongroup Generic architectural queries

 */

/*!

 @function EDGetRegisterName

 Gets the human-readable name for a given register.

 @param regName A pointer whose target will be pointed at the name of the

   register.  The name does not need to be deallocated and will be 

 @param disassembler The disassembler to query for the name.

 @param regID The register identifier, as returned by EDRegisterTokenValue.

 @result 0 on success; -1 otherwise.

 */

int EDGetRegisterName(const char** regName,

                      EDDisassemblerRef disassembler,

                      unsigned regID);

/*!

 @function EDRegisterIsStackPointer

 Determines if a register is one of the platform's stack-pointer registers.

 @param disassembler The disassembler to query.

 @param regID The register identifier, as returned by EDRegisterTokenValue.

 @result 1 if true; 0 otherwise.

 */

int EDRegisterIsStackPointer(EDDisassemblerRef disassembler,

                             unsigned regID);

/*!

 @function EDRegisterIsProgramCounter

 Determines if a register is one of the platform's stack-pointer registers.

 @param disassembler The disassembler to query.

 @param regID The register identifier, as returned by EDRegisterTokenValue.

 @result 1 if true; 0 otherwise.

 */

int EDRegisterIsProgramCounter(EDDisassemblerRef disassembler,

                               unsigned regID);

/*!

 @functiongroup Creating and querying instructions

 */

/*!

 @function EDCreateInst

 Gets a set of contiguous instructions from a disassembler.

 @param insts A pointer to an array that will be filled in with the

   instructions.  Must have at least count entries.  Entries not filled in will 

   be set to NULL.

 @param count The maximum number of instructions to fill in.

 @param disassembler The disassembler to use when decoding the instructions.

 @param byteReader The function to use when reading the instruction's machine

   code.

 @param address The address of the first byte of the instruction.

 @param arg An anonymous argument to be passed to byteReader.

 @result The number of instructions read on success; 0 otherwise.

 */

unsigned int EDCreateInsts(EDInstRef *insts,

                           unsigned int count,

                           EDDisassemblerRef disassembler,

                           EDByteReaderCallback byteReader,

                           uint64_t address,

                           void *arg);

/*!

 @function EDReleaseInst

 Frees the memory for an instruction.  The instruction can no longer be accessed

 after this call.

 @param inst The instruction to be freed.

 */

void EDReleaseInst(EDInstRef inst);

/*!

 @function EDInstByteSize

 @param inst The instruction to be queried.

 @result The number of bytes in the instruction's machine-code representation.

 */

int EDInstByteSize(EDInstRef inst);

/*!

 @function EDGetInstString

 Gets the disassembled text equivalent of the instruction.

 @param buf A pointer whose target will be filled in with a pointer to the

   string.  (The string becomes invalid when the instruction is released.)

 @param inst The instruction to be queried.

 @result 0 on success; -1 otherwise.

 */

int EDGetInstString(const char **buf,

                    EDInstRef inst);

/*!

 @function EDInstID

 @param instID A pointer whose target will be filled in with the LLVM identifier

   for the instruction.

 @param inst The instruction to be queried.

 @result 0 on success; -1 otherwise.

 */

int EDInstID(unsigned *instID, EDInstRef inst);

/*!

 @function EDInstIsBranch

 @param inst The instruction to be queried.

 @result 1 if the instruction is a branch instruction; 0 if it is some other

   type of instruction; -1 if there was an error.

 */

int EDInstIsBranch(EDInstRef inst);

/*!

 @function EDInstIsMove

 @param inst The instruction to be queried.

 @result 1 if the instruction is a move instruction; 0 if it is some other

   type of instruction; -1 if there was an error.

 */

int EDInstIsMove(EDInstRef inst);

/*!

 @function EDBranchTargetID

 @param inst The instruction to be queried.

 @result The ID of the branch target operand, suitable for use with 

   EDCopyOperand.  -1 if no such operand exists.

 */

int EDBranchTargetID(EDInstRef inst);

/*!

 @function EDMoveSourceID

 @param inst The instruction to be queried.

 @result The ID of the move source operand, suitable for use with 

   EDCopyOperand.  -1 if no such operand exists.

 */

int EDMoveSourceID(EDInstRef inst);

/*!

 @function EDMoveTargetID

 @param inst The instruction to be queried.

 @result The ID of the move source operand, suitable for use with 

   EDCopyOperand.  -1 if no such operand exists.

 */

int EDMoveTargetID(EDInstRef inst);

/*!

 @functiongroup Creating and querying tokens

 */

/*!

 @function EDNumTokens

 @param inst The instruction to be queried.

 @result The number of tokens in the instruction, or -1 on error.

 */

int EDNumTokens(EDInstRef inst);

/*!

 @function EDGetToken

 Retrieves a token from an instruction.  The token is valid until the

 instruction is released.

 @param token A pointer to be filled in with the token.

 @param inst The instruction to be queried.

 @param index The index of the token in the instruction.

 @result 0 on success; -1 otherwise.

 */

int EDGetToken(EDTokenRef *token,

               EDInstRef inst,

               int index);

/*!

 @function EDGetTokenString

 Gets the disassembled text for a token.

 @param buf A pointer whose target will be filled in with a pointer to the

   string.  (The string becomes invalid when the token is released.)

 @param token The token to be queried.

 @result 0 on success; -1 otherwise.

 */

int EDGetTokenString(const char **buf,

                     EDTokenRef token);

/*!

 @function EDOperandIndexForToken

 Returns the index of the operand to which a token belongs.

 @param token The token to be queried.

 @result The operand index on success; -1 otherwise

 */

int EDOperandIndexForToken(EDTokenRef token);

/*!

 @function EDTokenIsWhitespace

 @param token The token to be queried.

 @result 1 if the token is whitespace; 0 if not; -1 on error.

 */

int EDTokenIsWhitespace(EDTokenRef token);

/*!

 @function EDTokenIsPunctuation

 @param token The token to be queried.

 @result 1 if the token is punctuation; 0 if not; -1 on error.

 */

int EDTokenIsPunctuation(EDTokenRef token);

/*!

 @function EDTokenIsOpcode

 @param token The token to be queried.

 @result 1 if the token is opcode; 0 if not; -1 on error.

 */

int EDTokenIsOpcode(EDTokenRef token);

/*!

 @function EDTokenIsLiteral

 @param token The token to be queried.

 @result 1 if the token is a numeric literal; 0 if not; -1 on error.

 */

int EDTokenIsLiteral(EDTokenRef token);

/*!

 @function EDTokenIsRegister

 @param token The token to be queried.

 @result 1 if the token identifies a register; 0 if not; -1 on error.

 */

int EDTokenIsRegister(EDTokenRef token);

/*!

 @function EDTokenIsNegativeLiteral

 @param token The token to be queried.

 @result 1 if the token is a negative signed literal; 0 if not; -1 on error.

 */

int EDTokenIsNegativeLiteral(EDTokenRef token);

/*!

 @function EDLiteralTokenAbsoluteValue

 @param value A pointer whose target will be filled in with the absolute value

   of the literal.

 @param token The token to be queried.

 @result 0 on success; -1 otherwise.

 */

int EDLiteralTokenAbsoluteValue(uint64_t *value,

                                EDTokenRef token);

/*!

 @function EDRegisterTokenValue

 @param registerID A pointer whose target will be filled in with the LLVM 

   register identifier for the token.

 @param token The token to be queried.

 @result 0 on success; -1 otherwise.

 */

int EDRegisterTokenValue(unsigned *registerID,

                         EDTokenRef token);

/*!

 @functiongroup Creating and querying operands

 */

/*!

 @function EDNumOperands

 @param inst The instruction to be queried.

 @result The number of operands in the instruction, or -1 on error.

 */

int EDNumOperands(EDInstRef inst);

/*!

 @function EDGetOperand

 Retrieves an operand from an instruction.  The operand is valid until the

 instruction is released.

 @param operand A pointer to be filled in with the operand.

 @param inst The instruction to be queried.

 @param index The index of the operand in the instruction.

 @result 0 on success; -1 otherwise.

 */

int EDGetOperand(EDOperandRef *operand,

                 EDInstRef inst,

                 int index);

/*!

 @function EDOperandIsRegister

 @param operand The operand to be queried.

 @result 1 if the operand names a register; 0 if not; -1 on error.

 */

int EDOperandIsRegister(EDOperandRef operand);

/*!

 @function EDOperandIsImmediate

 @param operand The operand to be queried.

 @result 1 if the operand specifies an immediate value; 0 if not; -1 on error.

 */

int EDOperandIsImmediate(EDOperandRef operand);

/*!

 @function EDOperandIsMemory

 @param operand The operand to be queried.

 @result 1 if the operand specifies a location in memory; 0 if not; -1 on error.

 */

int EDOperandIsMemory(EDOperandRef operand);

/*!

 @function EDRegisterOperandValue

 @param value A pointer whose target will be filled in with the LLVM register ID

   of the register named by the operand.  

 @param operand The operand to be queried.

 @result 0 on success; -1 otherwise.

 */

int EDRegisterOperandValue(unsigned *value,

                           EDOperandRef operand);

/*!

 @function EDImmediateOperandValue

 @param value A pointer whose target will be filled in with the value of the

   immediate.

 @param operand The operand to be queried.

 @result 0 on success; -1 otherwise.

 */

int EDImmediateOperandValue(uint64_t *value,

                            EDOperandRef operand);

/*!

 @function EDEvaluateOperand

 Evaluates an operand using a client-supplied register state accessor.  Register

 operands are evaluated by reading the value of the register; immediate operands

 are evaluated by reporting the immediate value; memory operands are evaluated

 by computing the target address (with only those relocations applied that were

 already applied to the original bytes).

 @param result A pointer whose target is to be filled with the result of

   evaluating the operand.

 @param operand The operand to be evaluated.

 @param regReader The function to use when reading registers from the register

   state.

 @param arg An anonymous argument for client use.

 @result 0 if the operand could be evaluated; -1 otherwise.

 */

int EDEvaluateOperand(uint64_t *result,

                      EDOperandRef operand,

                      EDRegisterReaderCallback regReader,

                      void *arg);

#ifdef __BLOCKS__

/*!

 @typedef EDByteBlock_t

 Block-based interface to memory from which instructions may be read.

 @param byte A pointer whose target should be filled in with the data returned.

 @param address The address of the byte to be read.

 @result 0 on success; -1 otherwise.

 */

typedef int (^EDByteBlock_t)(uint8_t *byte, uint64_t address);

/*!

 @typedef EDRegisterBlock_t

 Block-based interface to registers from which registers may be read.

 @param value A pointer whose target should be filled in with the value of the

   register.

 @param regID The LLVM register identifier for the register to read.

 @result 0 if the register could be read; -1 otherwise.

 */

typedef int (^EDRegisterBlock_t)(uint64_t *value, unsigned regID);

/*!

 @typedef EDTokenVisitor_t

 Block-based handler for individual tokens.

 @param token The current token being read.

 @result 0 to continue; 1 to stop normally; -1 on error.

 */

typedef int (^EDTokenVisitor_t)(EDTokenRef token);

/*! @functiongroup Block-based interfaces */

/*!

 @function EDBlockCreateInsts

 Gets a set of contiguous instructions from a disassembler, using a block to

 read memory.

 @param insts A pointer to an array that will be filled in with the

   instructions.  Must have at least count entries.  Entries not filled in will 

   be set to NULL.

 @param count The maximum number of instructions to fill in.

 @param disassembler The disassembler to use when decoding the instructions.

 @param byteBlock The block to use when reading the instruction's machine

   code.

 @param address The address of the first byte of the instruction.

 @result The number of instructions read on success; 0 otherwise.

 */

unsigned int EDBlockCreateInsts(EDInstRef *insts,

                                int count,

                                EDDisassemblerRef disassembler,

                                EDByteBlock_t byteBlock,

                                uint64_t address);

/*!

 @function EDBlockEvaluateOperand

 Evaluates an operand using a block to read registers.

 @param result A pointer whose target is to be filled with the result of

   evaluating the operand.

 @param operand The operand to be evaluated.

 @param regBlock The block to use when reading registers from the register

   state.

 @result 0 if the operand could be evaluated; -1 otherwise.

 */

int EDBlockEvaluateOperand(uint64_t *result,

                           EDOperandRef operand,

                           EDRegisterBlock_t regBlock);

/*!

 @function EDBlockVisitTokens

 Visits every token with a visitor.

 @param inst The instruction with the tokens to be visited.

 @param visitor The visitor.

 @result 0 if the visit ended normally; -1 if the visitor encountered an error

   or there was some other error.

 */

int EDBlockVisitTokens(EDInstRef inst,

                       EDTokenVisitor_t visitor);

#endif

#ifdef __cplusplus

}

#endif

#endif