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