1 /*===-- llvm-c/EnhancedDisassembly.h - Disassembler C Interface ---*- C -*-===*\
3 |* The LLVM Compiler Infrastructure *|
5 |* This file is distributed under the University of Illinois Open Source *|
6 |* License. See LICENSE.TXT for details. *|
8 |*===----------------------------------------------------------------------===*|
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. *|
14 |* The header declares additional interfaces if the host compiler supports *|
17 \*===----------------------------------------------------------------------===*/
19 #ifndef LLVM_C_ENHANCEDDISASSEMBLY_H
20 #define LLVM_C_ENHANCEDDISASSEMBLY_H
22 #include "llvm/Support/DataTypes.h"
29 * @defgroup LLVMCEnhancedDisassembly Enhanced Disassembly
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
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.
49 typedef int (*EDByteReaderCallback)(uint8_t *byte, uint64_t address, void *arg);
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
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.
60 typedef int (*EDRegisterReaderCallback)(uint64_t *value, unsigned regID,
64 @typedef EDAssemblySyntax_t
65 An assembly syntax for use in tokenizing instructions.
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
74 typedef unsigned EDAssemblySyntax_t;
77 @typedef EDDisassemblerRef
78 Encapsulates a disassembler for a single CPU architecture.
80 typedef void *EDDisassemblerRef;
84 Encapsulates a single disassembled instruction in one assembly syntax.
86 typedef void *EDInstRef;
90 Encapsulates a token from the disassembly of an instruction.
92 typedef void *EDTokenRef;
96 Encapsulates an operand of an instruction.
98 typedef void *EDOperandRef;
101 @functiongroup Getting a disassembler
105 @function EDGetDisassembler
106 Gets the disassembler for a given target.
107 @param disassembler A pointer whose target will be filled in with the
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.
113 int EDGetDisassembler(EDDisassemblerRef *disassembler,
115 EDAssemblySyntax_t syntax);
118 @functiongroup Generic architectural queries
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.
130 int EDGetRegisterName(const char** regName,
131 EDDisassemblerRef disassembler,
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.
141 int EDRegisterIsStackPointer(EDDisassemblerRef disassembler,
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.
151 int EDRegisterIsProgramCounter(EDDisassemblerRef disassembler,
155 @functiongroup Creating and querying instructions
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
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
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.
172 unsigned int EDCreateInsts(EDInstRef *insts,
174 EDDisassemblerRef disassembler,
175 EDByteReaderCallback byteReader,
180 @function EDReleaseInst
181 Frees the memory for an instruction. The instruction can no longer be accessed
183 @param inst The instruction to be freed.
185 void EDReleaseInst(EDInstRef inst);
188 @function EDInstByteSize
189 @param inst The instruction to be queried.
190 @result The number of bytes in the instruction's machine-code representation.
192 int EDInstByteSize(EDInstRef inst);
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.
202 int EDGetInstString(const char **buf,
207 @param instID A pointer whose target will be filled in with the LLVM identifier
209 @param inst The instruction to be queried.
210 @result 0 on success; -1 otherwise.
212 int EDInstID(unsigned *instID, EDInstRef inst);
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.
220 int EDInstIsBranch(EDInstRef inst);
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.
228 int EDInstIsMove(EDInstRef inst);
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.
236 int EDBranchTargetID(EDInstRef inst);
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.
244 int EDMoveSourceID(EDInstRef inst);
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.
252 int EDMoveTargetID(EDInstRef inst);
255 @functiongroup Creating and querying tokens
259 @function EDNumTokens
260 @param inst The instruction to be queried.
261 @result The number of tokens in the instruction, or -1 on error.
263 int EDNumTokens(EDInstRef inst);
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.
274 int EDGetToken(EDTokenRef *token,
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.
286 int EDGetTokenString(const char **buf,
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
295 int EDOperandIndexForToken(EDTokenRef token);
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.
302 int EDTokenIsWhitespace(EDTokenRef token);
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.
309 int EDTokenIsPunctuation(EDTokenRef token);
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.
316 int EDTokenIsOpcode(EDTokenRef token);
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.
323 int EDTokenIsLiteral(EDTokenRef token);
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.
330 int EDTokenIsRegister(EDTokenRef token);
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.
337 int EDTokenIsNegativeLiteral(EDTokenRef token);
340 @function EDLiteralTokenAbsoluteValue
341 @param value A pointer whose target will be filled in with the absolute value
343 @param token The token to be queried.
344 @result 0 on success; -1 otherwise.
346 int EDLiteralTokenAbsoluteValue(uint64_t *value,
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.
356 int EDRegisterTokenValue(unsigned *registerID,
360 @functiongroup Creating and querying operands
364 @function EDNumOperands
365 @param inst The instruction to be queried.
366 @result The number of operands in the instruction, or -1 on error.
368 int EDNumOperands(EDInstRef inst);
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.
379 int EDGetOperand(EDOperandRef *operand,
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.
388 int EDOperandIsRegister(EDOperandRef operand);
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.
395 int EDOperandIsImmediate(EDOperandRef operand);
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.
402 int EDOperandIsMemory(EDOperandRef operand);
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.
411 int EDRegisterOperandValue(unsigned *value,
412 EDOperandRef operand);
415 @function EDImmediateOperandValue
416 @param value A pointer whose target will be filled in with the value of the
418 @param operand The operand to be queried.
419 @result 0 on success; -1 otherwise.
421 int EDImmediateOperandValue(uint64_t *value,
422 EDOperandRef operand);
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
436 @param arg An anonymous argument for client use.
437 @result 0 if the operand could be evaluated; -1 otherwise.
439 int EDEvaluateOperand(uint64_t *result,
440 EDOperandRef operand,
441 EDRegisterReaderCallback regReader,
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.
453 typedef int (^EDByteBlock_t)(uint8_t *byte, uint64_t address);
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
460 @param regID The LLVM register identifier for the register to read.
461 @result 0 if the register could be read; -1 otherwise.
463 typedef int (^EDRegisterBlock_t)(uint64_t *value, unsigned regID);
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.
471 typedef int (^EDTokenVisitor_t)(EDTokenRef token);
473 /*! @functiongroup Block-based interfaces */
476 @function EDBlockCreateInsts
477 Gets a set of contiguous instructions from a disassembler, using a block to
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
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
486 @param address The address of the first byte of the instruction.
487 @result The number of instructions read on success; 0 otherwise.
489 unsigned int EDBlockCreateInsts(EDInstRef *insts,
491 EDDisassemblerRef disassembler,
492 EDByteBlock_t byteBlock,
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
503 @result 0 if the operand could be evaluated; -1 otherwise.
505 int EDBlockEvaluateOperand(uint64_t *result,
506 EDOperandRef operand,
507 EDRegisterBlock_t regBlock);
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.
517 int EDBlockVisitTokens(EDInstRef inst,
518 EDTokenVisitor_t visitor);