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