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 const 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 the ReferenceValue to look up as a symbol. If no symbol is found 97 * for the ReferenceValue NULL is returned. The ReferenceType of the 98 * instruction is passed indirectly as is the PC of the instruction in 99 * ReferencePC. If the output reference can be determined its type is returned 100 * indirectly in ReferenceType along with ReferenceName if any, or that is set 101 * to NULL. 102 */ 103 typedef const char *(*LLVMSymbolLookupCallback)(void *DisInfo, 104 uint64_t ReferenceValue, 105 uint64_t *ReferenceType, 106 uint64_t ReferencePC, 107 const char **ReferenceName); 108 /** 109 * The reference types on input and output. 110 */ 111 /* No input reference type or no output reference type. */ 112 #define LLVMDisassembler_ReferenceType_InOut_None 0 113 114 /* The input reference is from a branch instruction. */ 115 #define LLVMDisassembler_ReferenceType_In_Branch 1 116 /* The input reference is from a PC relative load instruction. */ 117 #define LLVMDisassembler_ReferenceType_In_PCrel_Load 2 118 119 /* The output reference is to as symbol stub. */ 120 #define LLVMDisassembler_ReferenceType_Out_SymbolStub 1 121 /* The output reference is to a symbol address in a literal pool. */ 122 #define LLVMDisassembler_ReferenceType_Out_LitPool_SymAddr 2 123 /* The output reference is to a cstring address in a literal pool. */ 124 #define LLVMDisassembler_ReferenceType_Out_LitPool_CstrAddr 3 125 126 #ifdef __cplusplus 127 extern "C" { 128 #endif /* !defined(__cplusplus) */ 129 130 /** 131 * Create a disassembler for the TripleName. Symbolic disassembly is supported 132 * by passing a block of information in the DisInfo parameter and specifying the 133 * TagType and callback functions as described above. These can all be passed 134 * as NULL. If successful, this returns a disassembler context. If not, it 135 * returns NULL. 136 */ 137 LLVMDisasmContextRef LLVMCreateDisasm(const char *TripleName, void *DisInfo, 138 int TagType, LLVMOpInfoCallback GetOpInfo, 139 LLVMSymbolLookupCallback SymbolLookUp); 140 141 /** 142 * Dispose of a disassembler context. 143 */ 144 void LLVMDisasmDispose(LLVMDisasmContextRef DC); 145 146 /** 147 * Disassemble a single instruction using the disassembler context specified in 148 * the parameter DC. The bytes of the instruction are specified in the 149 * parameter Bytes, and contains at least BytesSize number of bytes. The 150 * instruction is at the address specified by the PC parameter. If a valid 151 * instruction can be disassembled, its string is returned indirectly in 152 * OutString whose size is specified in the parameter OutStringSize. This 153 * function returns the number of bytes in the instruction or zero if there was 154 * no valid instruction. 155 */ 156 size_t LLVMDisasmInstruction(LLVMDisasmContextRef DC, uint8_t *Bytes, 157 uint64_t BytesSize, uint64_t PC, 158 char *OutString, size_t OutStringSize); 159 160 #ifdef __cplusplus 161 } 162 #endif /* !defined(__cplusplus) */ 163 164 #endif /* !defined(LLVM_C_DISASSEMBLER_H) */ 165
