include/llvm-c/EnhancedDisassembly.h

   1 /*===-- llvm-c/EnhancedDisassembly.h - Disassembler C Interface ---*- C -*-===*\
   2 |*                                                                            *|
   3 |*                     The LLVM Compiler Infrastructure                       *|
   4 |*                                                                            *|
   5 |* This file is distributed under the University of Illinois Open Source      *|
   6 |* License. See LICENSE.TXT for details.                                      *|
   7 |*                                                                            *|
   8 |*===----------------------------------------------------------------------===*|
   9 |*                                                                            *|
  10 |* This header declares the C interface to EnhancedDisassembly.so, which      *|
  11 |* implements a disassembler with the ability to extract operand values and   *|
  12 |* individual tokens from assembly instructions.                              *|
  13 |*                                                                            *|
  14 |* The header declares additional interfaces if the host compiler supports    *|
  15 |* the blocks API.                                                            *|
  16 |*                                                                            *|
  17 \*===----------------------------------------------------------------------===*/
  18
  19 #ifndef LLVM_C_ENHANCEDDISASSEMBLY_H
  20 #define LLVM_C_ENHANCEDDISASSEMBLY_H
  21
  22 #include "llvm/Support/DataTypes.h"
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /*!
  29  @typedef EDByteReaderCallback
  30  Interface to memory from which instructions may be read.
  31  @param byte A pointer whose target should be filled in with the data returned.
  32  @param address The address of the byte to be read.
  33  @param arg An anonymous argument for client use.
  34  @result 0 on success; -1 otherwise.
  35  */
  36 typedef int (*EDByteReaderCallback)(uint8_t *byte, uint64_t address, void *arg);
  37
  38 /*!
  39  @typedef EDRegisterReaderCallback
  40  Interface to registers from which registers may be read.
  41  @param value A pointer whose target should be filled in with the value of the
  42    register.
  43  @param regID The LLVM register identifier for the register to read.
  44  @param arg An anonymous argument for client use.
  45  @result 0 if the register could be read; -1 otherwise.
  46  */
  47 typedef int (*EDRegisterReaderCallback)(uint64_t *value, unsigned regID,
  48                                         void* arg);
  49
  50 /*!
  51  @typedef EDAssemblySyntax_t
  52  An assembly syntax for use in tokenizing instructions.
  53  */
  54 enum {
  55 /*! @constant kEDAssemblySyntaxX86Intel Intel syntax for i386 and x86_64. */
  56   kEDAssemblySyntaxX86Intel  = 0,
  57 /*! @constant kEDAssemblySyntaxX86ATT AT&T syntax for i386 and x86_64. */
  58   kEDAssemblySyntaxX86ATT    = 1,
  59   kEDAssemblySyntaxARMUAL    = 2
  60 };
  61 typedef unsigned EDAssemblySyntax_t;
  62
  63 /*!
  64  @typedef EDDisassemblerRef
  65  Encapsulates a disassembler for a single CPU architecture.
  66  */
  67 typedef void *EDDisassemblerRef;
  68
  69 /*!
  70  @typedef EDInstRef
  71  Encapsulates a single disassembled instruction in one assembly syntax.
  72  */
  73 typedef void *EDInstRef;
  74
  75 /*!
  76  @typedef EDTokenRef
  77  Encapsulates a token from the disassembly of an instruction.
  78  */
  79 typedef void *EDTokenRef;
  80
  81 /*!
  82  @typedef EDOperandRef
  83  Encapsulates an operand of an instruction.
  84  */
  85 typedef void *EDOperandRef;
  86
  87 /*!
  88  @functiongroup Getting a disassembler
  89  */
  90
  91 /*!
  92  @function EDGetDisassembler
  93  Gets the disassembler for a given target.
  94  @param disassembler A pointer whose target will be filled in with the
  95    disassembler.
  96  @param triple Identifies the target.  Example: "x86_64-apple-darwin10"
  97  @param syntax The assembly syntax to use when decoding instructions.
  98  @result 0 on success; -1 otherwise.
  99  */
 100 int EDGetDisassembler(EDDisassemblerRef *disassembler,
 101                       const char *triple,
 102                       EDAssemblySyntax_t syntax);
 103
 104 /*!
 105  @functiongroup Generic architectural queries
 106  */
 107
 108 /*!
 109  @function EDGetRegisterName
 110  Gets the human-readable name for a given register.
 111  @param regName A pointer whose target will be pointed at the name of the
 112    register.  The name does not need to be deallocated and will be
 113  @param disassembler The disassembler to query for the name.
 114  @param regID The register identifier, as returned by EDRegisterTokenValue.
 115  @result 0 on success; -1 otherwise.
 116  */
 117 int EDGetRegisterName(const char** regName,
 118                       EDDisassemblerRef disassembler,
 119                       unsigned regID);
 120
 121 /*!
 122  @function EDRegisterIsStackPointer
 123  Determines if a register is one of the platform's stack-pointer registers.
 124  @param disassembler The disassembler to query.
 125  @param regID The register identifier, as returned by EDRegisterTokenValue.
 126  @result 1 if true; 0 otherwise.
 127  */
 128 int EDRegisterIsStackPointer(EDDisassemblerRef disassembler,
 129                              unsigned regID);
 130
 131 /*!
 132  @function EDRegisterIsProgramCounter
 133  Determines if a register is one of the platform's stack-pointer registers.
 134  @param disassembler The disassembler to query.
 135  @param regID The register identifier, as returned by EDRegisterTokenValue.
 136  @result 1 if true; 0 otherwise.
 137  */
 138 int EDRegisterIsProgramCounter(EDDisassemblerRef disassembler,
 139                                unsigned regID);
 140
 141 /*!
 142  @functiongroup Creating and querying instructions
 143  */
 144
 145 /*!
 146  @function EDCreateInst
 147  Gets a set of contiguous instructions from a disassembler.
 148  @param insts A pointer to an array that will be filled in with the
 149    instructions.  Must have at least count entries.  Entries not filled in will
 150    be set to NULL.
 151  @param count The maximum number of instructions to fill in.
 152  @param disassembler The disassembler to use when decoding the instructions.
 153  @param byteReader The function to use when reading the instruction's machine
 154    code.
 155  @param address The address of the first byte of the instruction.
 156  @param arg An anonymous argument to be passed to byteReader.
 157  @result The number of instructions read on success; 0 otherwise.
 158  */
 159 unsigned int EDCreateInsts(EDInstRef *insts,
 160                            unsigned int count,
 161                            EDDisassemblerRef disassembler,
 162                            EDByteReaderCallback byteReader,
 163                            uint64_t address,
 164                            void *arg);
 165
 166 /*!
 167  @function EDReleaseInst
 168  Frees the memory for an instruction.  The instruction can no longer be accessed
 169  after this call.
 170  @param inst The instruction to be freed.
 171  */
 172 void EDReleaseInst(EDInstRef inst);
 173
 174 /*!
 175  @function EDInstByteSize
 176  @param inst The instruction to be queried.
 177  @result The number of bytes in the instruction's machine-code representation.
 178  */
 179 int EDInstByteSize(EDInstRef inst);
 180
 181 /*!
 182  @function EDGetInstString
 183  Gets the disassembled text equivalent of the instruction.
 184  @param buf A pointer whose target will be filled in with a pointer to the
 185    string.  (The string becomes invalid when the instruction is released.)
 186  @param inst The instruction to be queried.
 187  @result 0 on success; -1 otherwise.
 188  */
 189 int EDGetInstString(const char **buf,
 190                     EDInstRef inst);
 191
 192 /*!
 193  @function EDInstID
 194  @param instID A pointer whose target will be filled in with the LLVM identifier
 195    for the instruction.
 196  @param inst The instruction to be queried.
 197  @result 0 on success; -1 otherwise.
 198  */
 199 int EDInstID(unsigned *instID, EDInstRef inst);
 200
 201 /*!
 202  @function EDInstIsBranch
 203  @param inst The instruction to be queried.
 204  @result 1 if the instruction is a branch instruction; 0 if it is some other
 205    type of instruction; -1 if there was an error.
 206  */
 207 int EDInstIsBranch(EDInstRef inst);
 208
 209 /*!
 210  @function EDInstIsMove
 211  @param inst The instruction to be queried.
 212  @result 1 if the instruction is a move instruction; 0 if it is some other
 213    type of instruction; -1 if there was an error.
 214  */
 215 int EDInstIsMove(EDInstRef inst);
 216
 217 /*!
 218  @function EDBranchTargetID
 219  @param inst The instruction to be queried.
 220  @result The ID of the branch target operand, suitable for use with
 221    EDCopyOperand.  -1 if no such operand exists.
 222  */
 223 int EDBranchTargetID(EDInstRef inst);
 224
 225 /*!
 226  @function EDMoveSourceID
 227  @param inst The instruction to be queried.
 228  @result The ID of the move source operand, suitable for use with
 229    EDCopyOperand.  -1 if no such operand exists.
 230  */
 231 int EDMoveSourceID(EDInstRef inst);
 232
 233 /*!
 234  @function EDMoveTargetID
 235  @param inst The instruction to be queried.
 236  @result The ID of the move source operand, suitable for use with
 237    EDCopyOperand.  -1 if no such operand exists.
 238  */
 239 int EDMoveTargetID(EDInstRef inst);
 240
 241 /*!
 242  @functiongroup Creating and querying tokens
 243  */
 244
 245 /*!
 246  @function EDNumTokens
 247  @param inst The instruction to be queried.
 248  @result The number of tokens in the instruction, or -1 on error.
 249  */
 250 int EDNumTokens(EDInstRef inst);
 251
 252 /*!
 253  @function EDGetToken
 254  Retrieves a token from an instruction.  The token is valid until the
 255  instruction is released.
 256  @param token A pointer to be filled in with the token.
 257  @param inst The instruction to be queried.
 258  @param index The index of the token in the instruction.
 259  @result 0 on success; -1 otherwise.
 260  */
 261 int EDGetToken(EDTokenRef *token,
 262                EDInstRef inst,
 263                int index);
 264
 265 /*!
 266  @function EDGetTokenString
 267  Gets the disassembled text for a token.
 268  @param buf A pointer whose target will be filled in with a pointer to the
 269    string.  (The string becomes invalid when the token is released.)
 270  @param token The token to be queried.
 271  @result 0 on success; -1 otherwise.
 272  */
 273 int EDGetTokenString(const char **buf,
 274                      EDTokenRef token);
 275
 276 /*!
 277  @function EDOperandIndexForToken
 278  Returns the index of the operand to which a token belongs.
 279  @param token The token to be queried.
 280  @result The operand index on success; -1 otherwise
 281  */
 282 int EDOperandIndexForToken(EDTokenRef token);
 283
 284 /*!
 285  @function EDTokenIsWhitespace
 286  @param token The token to be queried.
 287  @result 1 if the token is whitespace; 0 if not; -1 on error.
 288  */
 289 int EDTokenIsWhitespace(EDTokenRef token);
 290
 291 /*!
 292  @function EDTokenIsPunctuation
 293  @param token The token to be queried.
 294  @result 1 if the token is punctuation; 0 if not; -1 on error.
 295  */
 296 int EDTokenIsPunctuation(EDTokenRef token);
 297
 298 /*!
 299  @function EDTokenIsOpcode
 300  @param token The token to be queried.
 301  @result 1 if the token is opcode; 0 if not; -1 on error.
 302  */
 303 int EDTokenIsOpcode(EDTokenRef token);
 304
 305 /*!
 306  @function EDTokenIsLiteral
 307  @param token The token to be queried.
 308  @result 1 if the token is a numeric literal; 0 if not; -1 on error.
 309  */
 310 int EDTokenIsLiteral(EDTokenRef token);
 311
 312 /*!
 313  @function EDTokenIsRegister
 314  @param token The token to be queried.
 315  @result 1 if the token identifies a register; 0 if not; -1 on error.
 316  */
 317 int EDTokenIsRegister(EDTokenRef token);
 318
 319 /*!
 320  @function EDTokenIsNegativeLiteral
 321  @param token The token to be queried.
 322  @result 1 if the token is a negative signed literal; 0 if not; -1 on error.
 323  */
 324 int EDTokenIsNegativeLiteral(EDTokenRef token);
 325
 326 /*!
 327  @function EDLiteralTokenAbsoluteValue
 328  @param value A pointer whose target will be filled in with the absolute value
 329    of the literal.
 330  @param token The token to be queried.
 331  @result 0 on success; -1 otherwise.
 332  */
 333 int EDLiteralTokenAbsoluteValue(uint64_t *value,
 334                                 EDTokenRef token);
 335
 336 /*!
 337  @function EDRegisterTokenValue
 338  @param registerID A pointer whose target will be filled in with the LLVM
 339    register identifier for the token.
 340  @param token The token to be queried.
 341  @result 0 on success; -1 otherwise.
 342  */
 343 int EDRegisterTokenValue(unsigned *registerID,
 344                          EDTokenRef token);
 345
 346 /*!
 347  @functiongroup Creating and querying operands
 348  */
 349
 350 /*!
 351  @function EDNumOperands
 352  @param inst The instruction to be queried.
 353  @result The number of operands in the instruction, or -1 on error.
 354  */
 355 int EDNumOperands(EDInstRef inst);
 356
 357 /*!
 358  @function EDGetOperand
 359  Retrieves an operand from an instruction.  The operand is valid until the
 360  instruction is released.
 361  @param operand A pointer to be filled in with the operand.
 362  @param inst The instruction to be queried.
 363  @param index The index of the operand in the instruction.
 364  @result 0 on success; -1 otherwise.
 365  */
 366 int EDGetOperand(EDOperandRef *operand,
 367                  EDInstRef inst,
 368                  int index);
 369
 370 /*!
 371  @function EDOperandIsRegister
 372  @param operand The operand to be queried.
 373  @result 1 if the operand names a register; 0 if not; -1 on error.
 374  */
 375 int EDOperandIsRegister(EDOperandRef operand);
 376
 377 /*!
 378  @function EDOperandIsImmediate
 379  @param operand The operand to be queried.
 380  @result 1 if the operand specifies an immediate value; 0 if not; -1 on error.
 381  */
 382 int EDOperandIsImmediate(EDOperandRef operand);
 383
 384 /*!
 385  @function EDOperandIsMemory
 386  @param operand The operand to be queried.
 387  @result 1 if the operand specifies a location in memory; 0 if not; -1 on error.
 388  */
 389 int EDOperandIsMemory(EDOperandRef operand);
 390
 391 /*!
 392  @function EDRegisterOperandValue
 393  @param value A pointer whose target will be filled in with the LLVM register ID
 394    of the register named by the operand.
 395  @param operand The operand to be queried.
 396  @result 0 on success; -1 otherwise.
 397  */
 398 int EDRegisterOperandValue(unsigned *value,
 399                            EDOperandRef operand);
 400
 401 /*!
 402  @function EDImmediateOperandValue
 403  @param value A pointer whose target will be filled in with the value of the
 404    immediate.
 405  @param operand The operand to be queried.
 406  @result 0 on success; -1 otherwise.
 407  */
 408 int EDImmediateOperandValue(uint64_t *value,
 409                             EDOperandRef operand);
 410
 411 /*!
 412  @function EDEvaluateOperand
 413  Evaluates an operand using a client-supplied register state accessor.  Register
 414  operands are evaluated by reading the value of the register; immediate operands
 415  are evaluated by reporting the immediate value; memory operands are evaluated
 416  by computing the target address (with only those relocations applied that were
 417  already applied to the original bytes).
 418  @param result A pointer whose target is to be filled with the result of
 419    evaluating the operand.
 420  @param operand The operand to be evaluated.
 421  @param regReader The function to use when reading registers from the register
 422    state.
 423  @param arg An anonymous argument for client use.
 424  @result 0 if the operand could be evaluated; -1 otherwise.
 425  */
 426 int EDEvaluateOperand(uint64_t *result,
 427                       EDOperandRef operand,
 428                       EDRegisterReaderCallback regReader,
 429                       void *arg);
 430
 431 #ifdef __BLOCKS__
 432
 433 /*!
 434  @typedef EDByteBlock_t
 435  Block-based interface to memory from which instructions may be read.
 436  @param byte A pointer whose target should be filled in with the data returned.
 437  @param address The address of the byte to be read.
 438  @result 0 on success; -1 otherwise.
 439  */
 440 typedef int (^EDByteBlock_t)(uint8_t *byte, uint64_t address);
 441
 442 /*!
 443  @typedef EDRegisterBlock_t
 444  Block-based interface to registers from which registers may be read.
 445  @param value A pointer whose target should be filled in with the value of the
 446    register.
 447  @param regID The LLVM register identifier for the register to read.
 448  @result 0 if the register could be read; -1 otherwise.
 449  */
 450 typedef int (^EDRegisterBlock_t)(uint64_t *value, unsigned regID);
 451
 452 /*!
 453  @typedef EDTokenVisitor_t
 454  Block-based handler for individual tokens.
 455  @param token The current token being read.
 456  @result 0 to continue; 1 to stop normally; -1 on error.
 457  */
 458 typedef int (^EDTokenVisitor_t)(EDTokenRef token);
 459
 460 /*! @functiongroup Block-based interfaces */
 461
 462 /*!
 463  @function EDBlockCreateInsts
 464  Gets a set of contiguous instructions from a disassembler, using a block to
 465  read memory.
 466  @param insts A pointer to an array that will be filled in with the
 467    instructions.  Must have at least count entries.  Entries not filled in will
 468    be set to NULL.
 469  @param count The maximum number of instructions to fill in.
 470  @param disassembler The disassembler to use when decoding the instructions.
 471  @param byteBlock The block to use when reading the instruction's machine
 472    code.
 473  @param address The address of the first byte of the instruction.
 474  @result The number of instructions read on success; 0 otherwise.
 475  */
 476 unsigned int EDBlockCreateInsts(EDInstRef *insts,
 477                                 int count,
 478                                 EDDisassemblerRef disassembler,
 479                                 EDByteBlock_t byteBlock,
 480                                 uint64_t address);
 481
 482 /*!
 483  @function EDBlockEvaluateOperand
 484  Evaluates an operand using a block to read registers.
 485  @param result A pointer whose target is to be filled with the result of
 486    evaluating the operand.
 487  @param operand The operand to be evaluated.
 488  @param regBlock The block to use when reading registers from the register
 489    state.
 490  @result 0 if the operand could be evaluated; -1 otherwise.
 491  */
 492 int EDBlockEvaluateOperand(uint64_t *result,
 493                            EDOperandRef operand,
 494                            EDRegisterBlock_t regBlock);
 495
 496 /*!
 497  @function EDBlockVisitTokens
 498  Visits every token with a visitor.
 499  @param inst The instruction with the tokens to be visited.
 500  @param visitor The visitor.
 501  @result 0 if the visit ended normally; -1 if the visitor encountered an error
 502    or there was some other error.
 503  */
 504 int EDBlockVisitTokens(EDInstRef inst,
 505                        EDTokenVisitor_t visitor);
 506
 507 #endif
 508
 509 #ifdef __cplusplus
 510 }
 511 #endif
 512
 513 #endif