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 531
