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