RPCS3/llvm-mirror
1
0
Fork 0
mirror of https://github.com/RPCS3/llvm-mirror.git synced 2024-11-01 00:12:50 +01:00
Code Issues Projects Releases Wiki Activity
46244975ff
llvm-mirror/include/llvm-c/EnhancedDisassembly.h
Gregory Szorc 43c1c2e000 Organize LLVM C API docs into doxygen modules; add docs 
This gives a lot of love to the docs for the C API. Like Clang's
documentation, the C API is now organized into a Doxygen "module"
(LLVMC). Each C header file is a child of the main module. Some modules
(like Core) have a hierarchy of there own. The produced documentation is
thus better organized (before everything was in one monolithic list).

This patch also includes a lot of new documentation for APIs in Core.h.
It doesn't document them all, but is better than none. Function docs are
missing @param and @return annotation, but the documentation body now
commonly provides help details (like the expected llvm::Value sub-type
to expect).

llvm-svn: 153157
2012-03-21 03:54:29 +00:00

531 lines
17 KiB
C
Raw Blame History

/*===-- 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/Support/DataTypes.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup LLVMCEnhancedDisassembly Enhanced Disassembly
* @ingroup LLVMC
* @deprecated
*
* This module contains an interface to the Enhanced Disassembly (edis)
* library. The edis library is deprecated and will likely disappear in
* the near future. You should use the @ref LLVMCDisassembler interface
* instead.
*
* @{
*/
/*!
@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.
*/
enum {
/*! @constant kEDAssemblySyntaxX86Intel Intel syntax for i386 and x86_64. */
kEDAssemblySyntaxX86Intel = 0,
/*! @constant kEDAssemblySyntaxX86ATT AT&T syntax for i386 and x86_64. */
kEDAssemblySyntaxX86ATT = 1,
kEDAssemblySyntaxARMUAL = 2
};
typedef unsigned EDAssemblySyntax_t;
/*!
@typedef EDDisassemblerRef
Encapsulates a disassembler for a single CPU architecture.
*/
typedef void *EDDisassemblerRef;
/*!
@typedef EDInstRef
Encapsulates a single disassembled instruction in one assembly syntax.
*/
typedef void *EDInstRef;
/*!
@typedef EDTokenRef
Encapsulates a token from the disassembly of an instruction.
*/
typedef void *EDTokenRef;
/*!
@typedef EDOperandRef
Encapsulates an operand of an instruction.
*/
typedef void *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
Reference in New Issue View Git Blame Copy Permalink