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
25extern "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 */
49typedef 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 */
60typedef 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 */
67enum {
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};
74typedef unsigned EDAssemblySyntax_t;
75
76/*!
77 @typedef EDDisassemblerRef
78 Encapsulates a disassembler for a single CPU architecture.
79 */
80typedef void *EDDisassemblerRef;
81
82/*!
83 @typedef EDInstRef
84 Encapsulates a single disassembled instruction in one assembly syntax.
85 */
86typedef void *EDInstRef;
87
88/*!
89 @typedef EDTokenRef
90 Encapsulates a token from the disassembly of an instruction.
91 */
92typedef void *EDTokenRef;
93
94/*!
95 @typedef EDOperandRef
96 Encapsulates an operand of an instruction.
97 */
98typedef 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 */
113int 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 */
130int 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 */
141int 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 */
151int 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 */
172unsigned 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 */
185void 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 */
192int 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 */
202int 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 */
212int 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 */
220int 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 */
228int 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 */
236int 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 */
244int 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 */
252int 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 */
263int 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 */
274int 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 */
286int 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 */
295int 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 */
302int 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 */
309int 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 */
316int 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 */
323int 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 */
330int 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 */
337int 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 */
346int 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 */
356int 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 */
368int 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 */
379int 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 */
388int 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 */
395int 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 */
402int 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 */
411int 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 */
421int 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 */
439int 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 */
453typedef 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 */
463typedef 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 */
471typedef 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 */
489unsigned 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 */
505int 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 */
517int 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