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