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 * @defgroup LLVMCDisassembler Disassembler 23 * @ingroup LLVMC 24 * 25 * @{ 26 */ 27 28 /** 29 * An opaque reference to a disassembler context. 30 */ 31 typedef void *LLVMDisasmContextRef; 32 33 /** 34 * The type for the operand information call back function. This is called to 35 * get the symbolic information for an operand of an instruction. Typically 36 * this is from the relocation information, symbol table, etc. That block of 37 * information is saved when the disassembler context is created and passed to 38 * the call back in the DisInfo parameter. The instruction containing operand 39 * is at the PC parameter. For some instruction sets, there can be more than 40 * one operand with symbolic information. To determine the symbolic operand 41 * information for each operand, the bytes for the specific operand in the 42 * instruction are specified by the Offset parameter and its byte widith is the 43 * size parameter. For instructions sets with fixed widths and one symbolic 44 * operand per instruction, the Offset parameter will be zero and Size parameter 45 * will be the instruction width. The information is returned in TagBuf and is 46 * Triple specific with its specific information defined by the value of 47 * TagType for that Triple. If symbolic information is returned the function 48 * returns 1, otherwise it returns 0. 49 */ 50 typedef int (*LLVMOpInfoCallback)(void *DisInfo, uint64_t PC, 51 uint64_t Offset, uint64_t Size, 52 int TagType, void *TagBuf); 53 54 /** 55 * The initial support in LLVM MC for the most general form of a relocatable 56 * expression is "AddSymbol - SubtractSymbol + Offset". For some Darwin targets 57 * this full form is encoded in the relocation information so that AddSymbol and 58 * SubtractSymbol can be link edited independent of each other. Many other 59 * platforms only allow a relocatable expression of the form AddSymbol + Offset 60 * to be encoded. 61 * 62 * The LLVMOpInfoCallback() for the TagType value of 1 uses the struct 63 * LLVMOpInfo1. The value of the relocatable expression for the operand, 64 * including any PC adjustment, is passed in to the call back in the Value 65 * field. The symbolic information about the operand is returned using all 66 * the fields of the structure with the Offset of the relocatable expression 67 * returned in the Value field. It is possible that some symbols in the 68 * relocatable expression were assembly temporary symbols, for example 69 * "Ldata - LpicBase + constant", and only the Values of the symbols without 70 * symbol names are present in the relocation information. The VariantKind 71 * type is one of the Target specific #defines below and is used to print 72 * operands like "_foo@GOT", ":lower16:_foo", etc. 73 */ 74 struct LLVMOpInfoSymbol1 { 75 uint64_t Present; /* 1 if this symbol is present */ 76 const char *Name; /* symbol name if not NULL */ 77 uint64_t Value; /* symbol value if name is NULL */ 78 }; 79 80 struct LLVMOpInfo1 { 81 struct LLVMOpInfoSymbol1 AddSymbol; 82 struct LLVMOpInfoSymbol1 SubtractSymbol; 83 uint64_t Value; 84 uint64_t VariantKind; 85 }; 86 87 /** 88 * The operand VariantKinds for symbolic disassembly. 89 */ 90 #define LLVMDisassembler_VariantKind_None 0 /* all targets */ 91 92 /** 93 * The ARM target VariantKinds. 94 */ 95 #define LLVMDisassembler_VariantKind_ARM_HI16 1 /* :upper16: */ 96 #define LLVMDisassembler_VariantKind_ARM_LO16 2 /* :lower16: */ 97 98 /** 99 * The ARM64 target VariantKinds. 100 */ 101 #define LLVMDisassembler_VariantKind_ARM64_PAGE 1 /* @page */ 102 #define LLVMDisassembler_VariantKind_ARM64_PAGEOFF 2 /* @pageoff */ 103 #define LLVMDisassembler_VariantKind_ARM64_GOTPAGE 3 /* @gotpage */ 104 #define LLVMDisassembler_VariantKind_ARM64_GOTPAGEOFF 4 /* @gotpageoff */ 105 #define LLVMDisassembler_VariantKind_ARM64_TLVP 5 /* @tvlppage */ 106 #define LLVMDisassembler_VariantKind_ARM64_TLVOFF 6 /* @tvlppageoff */ 107 108 /** 109 * The type for the symbol lookup function. This may be called by the 110 * disassembler for things like adding a comment for a PC plus a constant 111 * offset load instruction to use a symbol name instead of a load address value. 112 * It is passed the block information is saved when the disassembler context is 113 * created and the ReferenceValue to look up as a symbol. If no symbol is found 114 * for the ReferenceValue NULL is returned. The ReferenceType of the 115 * instruction is passed indirectly as is the PC of the instruction in 116 * ReferencePC. If the output reference can be determined its type is returned 117 * indirectly in ReferenceType along with ReferenceName if any, or that is set 118 * to NULL. 119 */ 120 typedef const char *(*LLVMSymbolLookupCallback)(void *DisInfo, 121 uint64_t ReferenceValue, 122 uint64_t *ReferenceType, 123 uint64_t ReferencePC, 124 const char **ReferenceName); 125 /** 126 * The reference types on input and output. 127 */ 128 /* No input reference type or no output reference type. */ 129 #define LLVMDisassembler_ReferenceType_InOut_None 0 130 131 /* The input reference is from a branch instruction. */ 132 #define LLVMDisassembler_ReferenceType_In_Branch 1 133 /* The input reference is from a PC relative load instruction. */ 134 #define LLVMDisassembler_ReferenceType_In_PCrel_Load 2 135 136 /* The input reference is from an ARM64::ADRP instruction. */ 137 #define LLVMDisassembler_ReferenceType_In_ARM64_ADRP 0x100000001 138 /* The input reference is from an ARM64::ADDXri instruction. */ 139 #define LLVMDisassembler_ReferenceType_In_ARM64_ADDXri 0x100000002 140 /* The input reference is from an ARM64::LDRXui instruction. */ 141 #define LLVMDisassembler_ReferenceType_In_ARM64_LDRXui 0x100000003 142 /* The input reference is from an ARM64::LDRXl instruction. */ 143 #define LLVMDisassembler_ReferenceType_In_ARM64_LDRXl 0x100000004 144 /* The input reference is from an ARM64::ADR instruction. */ 145 #define LLVMDisassembler_ReferenceType_In_ARM64_ADR 0x100000005 146 147 /* The output reference is to as symbol stub. */ 148 #define LLVMDisassembler_ReferenceType_Out_SymbolStub 1 149 /* The output reference is to a symbol address in a literal pool. */ 150 #define LLVMDisassembler_ReferenceType_Out_LitPool_SymAddr 2 151 /* The output reference is to a cstring address in a literal pool. */ 152 #define LLVMDisassembler_ReferenceType_Out_LitPool_CstrAddr 3 153 154 /* The output reference is to a Objective-C CoreFoundation string. */ 155 #define LLVMDisassembler_ReferenceType_Out_Objc_CFString_Ref 4 156 /* The output reference is to a Objective-C message. */ 157 #define LLVMDisassembler_ReferenceType_Out_Objc_Message 5 158 /* The output reference is to a Objective-C message ref. */ 159 #define LLVMDisassembler_ReferenceType_Out_Objc_Message_Ref 6 160 /* The output reference is to a Objective-C selector ref. */ 161 #define LLVMDisassembler_ReferenceType_Out_Objc_Selector_Ref 7 162 /* The output reference is to a Objective-C class ref. */ 163 #define LLVMDisassembler_ReferenceType_Out_Objc_Class_Ref 8 164 165 /* The output reference is to a C++ symbol name. */ 166 #define LLVMDisassembler_ReferenceType_DeMangled_Name 9 167 168 #ifdef __cplusplus 169 extern "C" { 170 #endif /* !defined(__cplusplus) */ 171 172 /** 173 * Create a disassembler for the TripleName. Symbolic disassembly is supported 174 * by passing a block of information in the DisInfo parameter and specifying the 175 * TagType and callback functions as described above. These can all be passed 176 * as NULL. If successful, this returns a disassembler context. If not, it 177 * returns NULL. This function is equivalent to calling 178 * LLVMCreateDisasmCPUFeatures() with an empty CPU name and feature set. 179 */ 180 LLVMDisasmContextRef LLVMCreateDisasm(const char *TripleName, void *DisInfo, 181 int TagType, LLVMOpInfoCallback GetOpInfo, 182 LLVMSymbolLookupCallback SymbolLookUp); 183 184 /** 185 * Create a disassembler for the TripleName and a specific CPU. Symbolic 186 * disassembly is supported by passing a block of information in the DisInfo 187 * parameter and specifying the TagType and callback functions as described 188 * above. These can all be passed * as NULL. If successful, this returns a 189 * disassembler context. If not, it returns NULL. This function is equivalent 190 * to calling LLVMCreateDisasmCPUFeatures() with an empty feature set. 191 */ 192 LLVMDisasmContextRef LLVMCreateDisasmCPU(const char *Triple, const char *CPU, 193 void *DisInfo, int TagType, 194 LLVMOpInfoCallback GetOpInfo, 195 LLVMSymbolLookupCallback SymbolLookUp); 196 197 /** 198 * Create a disassembler for the TripleName, a specific CPU and specific feature 199 * string. Symbolic disassembly is supported by passing a block of information 200 * in the DisInfo parameter and specifying the TagType and callback functions as 201 * described above. These can all be passed * as NULL. If successful, this 202 * returns a disassembler context. If not, it returns NULL. 203 */ 204 LLVMDisasmContextRef 205 LLVMCreateDisasmCPUFeatures(const char *Triple, const char *CPU, 206 const char *Features, void *DisInfo, int TagType, 207 LLVMOpInfoCallback GetOpInfo, 208 LLVMSymbolLookupCallback SymbolLookUp); 209 210 /** 211 * Set the disassembler's options. Returns 1 if it can set the Options and 0 212 * otherwise. 213 */ 214 int LLVMSetDisasmOptions(LLVMDisasmContextRef DC, uint64_t Options); 215 216 /* The option to produce marked up assembly. */ 217 #define LLVMDisassembler_Option_UseMarkup 1 218 /* The option to print immediates as hex. */ 219 #define LLVMDisassembler_Option_PrintImmHex 2 220 /* The option use the other assembler printer variant */ 221 #define LLVMDisassembler_Option_AsmPrinterVariant 4 222 /* The option to set comment on instructions */ 223 #define LLVMDisassembler_Option_SetInstrComments 8 224 /* The option to print latency information alongside instructions */ 225 #define LLVMDisassembler_Option_PrintLatency 16 226 227 /** 228 * Dispose of a disassembler context. 229 */ 230 void LLVMDisasmDispose(LLVMDisasmContextRef DC); 231 232 /** 233 * Disassemble a single instruction using the disassembler context specified in 234 * the parameter DC. The bytes of the instruction are specified in the 235 * parameter Bytes, and contains at least BytesSize number of bytes. The 236 * instruction is at the address specified by the PC parameter. If a valid 237 * instruction can be disassembled, its string is returned indirectly in 238 * OutString whose size is specified in the parameter OutStringSize. This 239 * function returns the number of bytes in the instruction or zero if there was 240 * no valid instruction. 241 */ 242 size_t LLVMDisasmInstruction(LLVMDisasmContextRef DC, uint8_t *Bytes, 243 uint64_t BytesSize, uint64_t PC, 244 char *OutString, size_t OutStringSize); 245 246 /** 247 * @} 248 */ 249 250 #ifdef __cplusplus 251 } 252 #endif /* !defined(__cplusplus) */ 253 254 #endif /* !defined(LLVM_C_DISASSEMBLER_H) */ 255