1 /*===-- llvm-c/Disassembler.h - Disassembler Public 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 provides a public interface to a disassembler library. *| 11 |* LLVM provides an implementation of this interface. *| 12 |* *| 13 \*===----------------------------------------------------------------------===*/ 14 15 #ifndef LLVM_C_DISASSEMBLER_H 16 #define LLVM_C_DISASSEMBLER_H 17 18 #include "llvm/Support/DataTypes.h" 19 #include <stddef.h> 20 21 /** 22 * An opaque reference to a disassembler context. 23 */ 24 typedef void *LLVMDisasmContextRef; 25 26 /** 27 * The type for the operand information call back function. This is called to 28 * get the symbolic information for an operand of an instruction. Typically 29 * this is from the relocation information, symbol table, etc. That block of 30 * information is saved when the disassembler context is created and passed to 31 * the call back in the DisInfo parameter. The instruction containing operand 32 * is at the PC parameter. For some instruction sets, there can be more than 33 * one operand with symbolic information. To determine the symbolic operand 34 * information for each operand, the bytes for the specific operand in the 35 * instruction are specified by the Offset parameter and its byte widith is the 36 * size parameter. For instructions sets with fixed widths and one symbolic 37 * operand per instruction, the Offset parameter will be zero and Size parameter 38 * will be the instruction width. The information is returned in TagBuf and is 39 * Triple specific with its specific information defined by the value of 40 * TagType for that Triple. If symbolic information is returned the function 41 * returns 1, otherwise it returns 0. 42 */ 43 typedef int (*LLVMOpInfoCallback)(void *DisInfo, uint64_t PC, 44 uint64_t Offset, uint64_t Size, 45 int TagType, void *TagBuf); 46 47 /** 48 * The initial support in LLVM MC for the most general form of a relocatable 49 * expression is "AddSymbol - SubtractSymbol + Offset". For some Darwin targets 50 * this full form is encoded in the relocation information so that AddSymbol and 51 * SubtractSymbol can be link edited independent of each other. Many other 52 * platforms only allow a relocatable expression of the form AddSymbol + Offset 53 * to be encoded. 54 * 55 * The LLVMOpInfoCallback() for the TagType value of 1 uses the struct 56 * LLVMOpInfo1. The value of the relocatable expression for the operand, 57 * including any PC adjustment, is passed in to the call back in the Value 58 * field. The symbolic information about the operand is returned using all 59 * the fields of the structure with the Offset of the relocatable expression 60 * returned in the Value field. It is possible that some symbols in the 61 * relocatable expression were assembly temporary symbols, for example 62 * "Ldata - LpicBase + constant", and only the Values of the symbols without 63 * symbol names are present in the relocation information. The VariantKind 64 * type is one of the Target specific #defines below and is used to print 65 * operands like "_foo@GOT", ":lower16:_foo", etc. 66 */ 67 struct LLVMOpInfoSymbol1 { 68 uint64_t Present; /* 1 if this symbol is present */ 69 char *Name; /* symbol name if not NULL */ 70 uint64_t Value; /* symbol value if name is NULL */ 71 }; 72 73 struct LLVMOpInfo1 { 74 struct LLVMOpInfoSymbol1 AddSymbol; 75 struct LLVMOpInfoSymbol1 SubtractSymbol; 76 uint64_t Value; 77 uint64_t VariantKind; 78 }; 79 80 /** 81 * The operand VariantKinds for symbolic disassembly. 82 */ 83 #define LLVMDisassembler_VariantKind_None 0 /* all targets */ 84 85 /** 86 * The ARM target VariantKinds. 87 */ 88 #define LLVMDisassembler_VariantKind_ARM_HI16 1 /* :upper16: */ 89 #define LLVMDisassembler_VariantKind_ARM_LO16 2 /* :lower16: */ 90 91 /** 92 * The type for the symbol lookup function. This may be called by the 93 * disassembler for things like adding a comment for a PC plus a constant 94 * offset load instruction to use a symbol name instead of a load address value. 95 * It is passed the block information is saved when the disassembler context is 96 * created and a value of a symbol to look up. If no symbol is found NULL is 97 * returned. 98 */ 99 typedef const char *(*LLVMSymbolLookupCallback)(void *DisInfo, 100 uint64_t SymbolValue); 101 102 #ifdef __cplusplus 103 extern "C" { 104 #endif /* !defined(__cplusplus) */ 105 106 /** 107 * Create a disassembler for the TripleName. Symbolic disassembly is supported 108 * by passing a block of information in the DisInfo parameter and specifying the 109 * TagType and callback functions as described above. These can all be passed 110 * as NULL. If successful, this returns a disassembler context. If not, it 111 * returns NULL. 112 */ 113 LLVMDisasmContextRef LLVMCreateDisasm(const char *TripleName, void *DisInfo, 114 int TagType, LLVMOpInfoCallback GetOpInfo, 115 LLVMSymbolLookupCallback SymbolLookUp); 116 117 /** 118 * Dispose of a disassembler context. 119 */ 120 void LLVMDisasmDispose(LLVMDisasmContextRef DC); 121 122 /** 123 * Disassemble a single instruction using the disassembler context specified in 124 * the parameter DC. The bytes of the instruction are specified in the 125 * parameter Bytes, and contains at least BytesSize number of bytes. The 126 * instruction is at the address specified by the PC parameter. If a valid 127 * instruction can be disassembled, its string is returned indirectly in 128 * OutString whose size is specified in the parameter OutStringSize. This 129 * function returns the number of bytes in the instruction or zero if there was 130 * no valid instruction. 131 */ 132 size_t LLVMDisasmInstruction(LLVMDisasmContextRef DC, uint8_t *Bytes, 133 uint64_t BytesSize, uint64_t PC, 134 char *OutString, size_t OutStringSize); 135 136 #ifdef __cplusplus 137 } 138 #endif /* !defined(__cplusplus) */ 139 140 #endif /* !defined(LLVM_C_DISASSEMBLER_H) */ 141