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/System/DataTypes.h"
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.
36 typedef int (*EDByteReaderCallback)(uint8_t *byte, uint64_t address, void *arg);
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
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.
47 typedef int (*EDRegisterReaderCallback)(uint64_t *value, unsigned regID,
51 @typedef EDAssemblySyntax_t
52 An assembly syntax for use in tokenizing instructions.
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
62 @typedef EDDisassemblerRef
63 Encapsulates a disassembler for a single CPU architecture.
65 struct EDDisassembler;
66 typedef struct EDDisassembler *EDDisassemblerRef;
70 Encapsulates a single disassembled instruction in one assembly syntax.
73 typedef struct EDInst *EDInstRef;
77 Encapsulates a token from the disassembly of an instruction.
80 typedef struct EDToken *EDTokenRef;
84 Encapsulates an operand of an instruction.
87 typedef struct EDOperand *EDOperandRef;
90 @functiongroup Getting a disassembler
94 @function EDGetDisassembler
95 Gets the disassembler for a given target.
96 @param disassembler A pointer whose target will be filled in with the
98 @param triple Identifies the target. Example: "x86_64-apple-darwin10"
99 @param syntax The assembly syntax to use when decoding instructions.
100 @result 0 on success; -1 otherwise.
102 int EDGetDisassembler(EDDisassemblerRef *disassembler,
104 EDAssemblySyntax_t syntax);
107 @functiongroup Generic architectural queries
111 @function EDGetRegisterName
112 Gets the human-readable name for a given register.
113 @param regName A pointer whose target will be pointed at the name of the
114 register. The name does not need to be deallocated and will be
115 @param disassembler The disassembler to query for the name.
116 @param regID The register identifier, as returned by EDRegisterTokenValue.
117 @result 0 on success; -1 otherwise.
119 int EDGetRegisterName(const char** regName,
120 EDDisassemblerRef disassembler,
124 @function EDRegisterIsStackPointer
125 Determines if a register is one of the platform's stack-pointer registers.
126 @param disassembler The disassembler to query.
127 @param regID The register identifier, as returned by EDRegisterTokenValue.
128 @result 1 if true; 0 otherwise.
130 int EDRegisterIsStackPointer(EDDisassemblerRef disassembler,
134 @function EDRegisterIsProgramCounter
135 Determines if a register is one of the platform's stack-pointer registers.
136 @param disassembler The disassembler to query.
137 @param regID The register identifier, as returned by EDRegisterTokenValue.
138 @result 1 if true; 0 otherwise.
140 int EDRegisterIsProgramCounter(EDDisassemblerRef disassembler,
144 @functiongroup Creating and querying instructions
148 @function EDCreateInst
149 Gets a set of contiguous instructions from a disassembler.
150 @param insts A pointer to an array that will be filled in with the
151 instructions. Must have at least count entries. Entries not filled in will
153 @param count The maximum number of instructions to fill in.
154 @param disassembler The disassembler to use when decoding the instructions.
155 @param byteReader The function to use when reading the instruction's machine
157 @param address The address of the first byte of the instruction.
158 @param arg An anonymous argument to be passed to byteReader.
159 @result The number of instructions read on success; 0 otherwise.
161 unsigned int EDCreateInsts(EDInstRef *insts,
163 EDDisassemblerRef disassembler,
164 EDByteReaderCallback byteReader,
169 @function EDReleaseInst
170 Frees the memory for an instruction. The instruction can no longer be accessed
172 @param inst The instruction to be freed.
174 void EDReleaseInst(EDInstRef inst);
177 @function EDInstByteSize
178 @param inst The instruction to be queried.
179 @result The number of bytes consumed by the instruction.
181 int EDInstByteSize(EDInstRef inst);
184 @function EDGetInstString
185 Gets the disassembled text equivalent of the instruction.
186 @param buf A pointer whose target will be filled in with a pointer to the
187 string. (The string becomes invalid when the instruction is released.)
188 @param inst The instruction to be queried.
189 @result 0 on success; -1 otherwise.
191 int EDGetInstString(const char **buf,
196 @param instID A pointer whose target will be filled in with the LLVM identifier
198 @param inst The instruction to be queried.
199 @result 0 on success; -1 otherwise.
201 int EDInstID(unsigned *instID, EDInstRef inst);
204 @function EDInstIsBranch
205 @param inst The instruction to be queried.
206 @result 1 if the instruction is a branch instruction; 0 if it is some other
207 type of instruction; -1 if there was an error.
209 int EDInstIsBranch(EDInstRef inst);
212 @function EDInstIsMove
213 @param inst The instruction to be queried.
214 @result 1 if the instruction is a move instruction; 0 if it is some other
215 type of instruction; -1 if there was an error.
217 int EDInstIsMove(EDInstRef inst);
220 @function EDBranchTargetID
221 @param inst The instruction to be queried.
222 @result The ID of the branch target operand, suitable for use with
223 EDCopyOperand. -1 if no such operand exists.
225 int EDBranchTargetID(EDInstRef inst);
228 @function EDMoveSourceID
229 @param inst The instruction to be queried.
230 @result The ID of the move source operand, suitable for use with
231 EDCopyOperand. -1 if no such operand exists.
233 int EDMoveSourceID(EDInstRef inst);
236 @function EDMoveTargetID
237 @param inst The instruction to be queried.
238 @result The ID of the move source operand, suitable for use with
239 EDCopyOperand. -1 if no such operand exists.
241 int EDMoveTargetID(EDInstRef inst);
244 @functiongroup Creating and querying tokens
248 @function EDNumTokens
249 @param inst The instruction to be queried.
250 @result The number of tokens in the instruction, or -1 on error.
252 int EDNumTokens(EDInstRef inst);
256 Retrieves a token from an instruction. The token is valid until the
257 instruction is released.
258 @param token A pointer to be filled in with the token.
259 @param inst The instruction to be queried.
260 @param index The index of the token in the instruction.
261 @result 0 on success; -1 otherwise.
263 int EDGetToken(EDTokenRef *token,
268 @function EDGetTokenString
269 Gets the disassembled text for a token.
270 @param buf A pointer whose target will be filled in with a pointer to the
271 string. (The string becomes invalid when the token is released.)
272 @param token The token to be queried.
273 @result 0 on success; -1 otherwise.
275 int EDGetTokenString(const char **buf,
279 @function EDOperandIndexForToken
280 Returns the index of the operand to which a token belongs.
281 @param token The token to be queried.
282 @result The operand index on success; -1 otherwise
284 int EDOperandIndexForToken(EDTokenRef token);
287 @function EDTokenIsWhitespace
288 @param token The token to be queried.
289 @result 1 if the token is whitespace; 0 if not; -1 on error.
291 int EDTokenIsWhitespace(EDTokenRef token);
294 @function EDTokenIsPunctuation
295 @param token The token to be queried.
296 @result 1 if the token is punctuation; 0 if not; -1 on error.
298 int EDTokenIsPunctuation(EDTokenRef token);
301 @function EDTokenIsOpcode
302 @param token The token to be queried.
303 @result 1 if the token is opcode; 0 if not; -1 on error.
305 int EDTokenIsOpcode(EDTokenRef token);
308 @function EDTokenIsLiteral
309 @param token The token to be queried.
310 @result 1 if the token is a numeric literal; 0 if not; -1 on error.
312 int EDTokenIsLiteral(EDTokenRef token);
315 @function EDTokenIsRegister
316 @param token The token to be queried.
317 @result 1 if the token identifies a register; 0 if not; -1 on error.
319 int EDTokenIsRegister(EDTokenRef token);
322 @function EDTokenIsNegativeLiteral
323 @param token The token to be queried.
324 @result 1 if the token is a negative signed literal; 0 if not; -1 on error.
326 int EDTokenIsNegativeLiteral(EDTokenRef token);
329 @function EDLiteralTokenAbsoluteValue
330 @param value A pointer whose target will be filled in with the absolute value
332 @param token The token to be queried.
333 @result 0 on success; -1 otherwise.
335 int EDLiteralTokenAbsoluteValue(uint64_t *value,
339 @function EDRegisterTokenValue
340 @param registerID A pointer whose target will be filled in with the LLVM
341 register identifier for the token.
342 @param token The token to be queried.
343 @result 0 on success; -1 otherwise.
345 int EDRegisterTokenValue(unsigned *registerID,
349 @functiongroup Creating and querying operands
353 @function EDNumOperands
354 @param inst The instruction to be queried.
355 @result The number of operands in the instruction, or -1 on error.
357 int EDNumOperands(EDInstRef inst);
360 @function EDGetOperand
361 Retrieves an operand from an instruction. The operand is valid until the
362 instruction is released.
363 @param operand A pointer to be filled in with the operand.
364 @param inst The instruction to be queried.
365 @param index The index of the operand in the instruction.
366 @result 0 on success; -1 otherwise.
368 int EDGetOperand(EDOperandRef *operand,
373 @function EDEvaluateOperand
374 Evaluates an operand using a client-supplied register state accessor.
375 @param result A pointer whose target is to be filled with the result of
376 evaluating the operand.
377 @param operand The operand to be evaluated.
378 @param regReader The function to use when reading registers from the register
380 @param arg An anonymous argument for client use.
381 @result 0 if the operand could be evaluated; -1 otherwise.
383 int EDEvaluateOperand(uint64_t *result,
384 EDOperandRef operand,
385 EDRegisterReaderCallback regReader,
391 @typedef EDByteBlock_t
392 Block-based interface to memory from which instructions may be read.
393 @param byte A pointer whose target should be filled in with the data returned.
394 @param address The address of the byte to be read.
395 @result 0 on success; -1 otherwise.
397 typedef int (^EDByteBlock_t)(uint8_t *byte, uint64_t address);
400 @typedef EDRegisterBlock_t
401 Block-based interface to registers from which registers may be read.
402 @param value A pointer whose target should be filled in with the value of the
404 @param regID The LLVM register identifier for the register to read.
405 @result 0 if the register could be read; -1 otherwise.
407 typedef int (^EDRegisterBlock_t)(uint64_t *value, unsigned regID);
410 @typedef EDTokenVisitor_t
411 Block-based handler for individual tokens.
412 @param token The current token being read.
413 @result 0 to continue; 1 to stop normally; -1 on error.
415 typedef int (^EDTokenVisitor_t)(EDTokenRef token);
417 /*! @functiongroup Block-based interfaces */
420 @function EDBlockCreateInsts
421 Gets a set of contiguous instructions from a disassembler, using a block to
423 @param insts A pointer to an array that will be filled in with the
424 instructions. Must have at least count entries. Entries not filled in will
426 @param count The maximum number of instructions to fill in.
427 @param disassembler The disassembler to use when decoding the instructions.
428 @param byteBlock The block to use when reading the instruction's machine
430 @param address The address of the first byte of the instruction.
431 @result The number of instructions read on success; 0 otherwise.
433 unsigned int EDBlockCreateInsts(EDInstRef *insts,
435 EDDisassemblerRef disassembler,
436 EDByteBlock_t byteBlock,
440 @function EDBlockEvaluateOperand
441 Evaluates an operand using a block to read registers.
442 @param result A pointer whose target is to be filled with the result of
443 evaluating the operand.
444 @param operand The operand to be evaluated.
445 @param regBlock The block to use when reading registers from the register
447 @result 0 if the operand could be evaluated; -1 otherwise.
449 int EDBlockEvaluateOperand(uint64_t *result,
450 EDOperandRef operand,
451 EDRegisterBlock_t regBlock);
454 @function EDBlockVisitTokens
455 Visits every token with a visitor.
456 @param inst The instruction with the tokens to be visited.
457 @param visitor The visitor.
458 @result 0 if the visit ended normally; -1 if the visitor encountered an error
459 or there was some other error.
461 int EDBlockVisitTokens(EDInstRef inst,
462 EDTokenVisitor_t visitor);