Home | History | Annotate | Download | only in llvm-c
      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 LLVMCreateDisasmCPU()
    178  * with an empty CPU name.
    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.
    190  */
    191 LLVMDisasmContextRef LLVMCreateDisasmCPU(const char *Triple, const char *CPU,
    192                                          void *DisInfo, int TagType,
    193                                          LLVMOpInfoCallback GetOpInfo,
    194                                          LLVMSymbolLookupCallback SymbolLookUp);
    195 
    196 /**
    197  * Set the disassembler's options.  Returns 1 if it can set the Options and 0
    198  * otherwise.
    199  */
    200 int LLVMSetDisasmOptions(LLVMDisasmContextRef DC, uint64_t Options);
    201 
    202 /* The option to produce marked up assembly. */
    203 #define LLVMDisassembler_Option_UseMarkup 1
    204 /* The option to print immediates as hex. */
    205 #define LLVMDisassembler_Option_PrintImmHex 2
    206 /* The option use the other assembler printer variant */
    207 #define LLVMDisassembler_Option_AsmPrinterVariant 4
    208 /* The option to set comment on instructions */
    209 #define LLVMDisassembler_Option_SetInstrComments 8
    210   /* The option to print latency information alongside instructions */
    211 #define LLVMDisassembler_Option_PrintLatency 16
    212 
    213 /**
    214  * Dispose of a disassembler context.
    215  */
    216 void LLVMDisasmDispose(LLVMDisasmContextRef DC);
    217 
    218 /**
    219  * Disassemble a single instruction using the disassembler context specified in
    220  * the parameter DC.  The bytes of the instruction are specified in the
    221  * parameter Bytes, and contains at least BytesSize number of bytes.  The
    222  * instruction is at the address specified by the PC parameter.  If a valid
    223  * instruction can be disassembled, its string is returned indirectly in
    224  * OutString whose size is specified in the parameter OutStringSize.  This
    225  * function returns the number of bytes in the instruction or zero if there was
    226  * no valid instruction.
    227  */
    228 size_t LLVMDisasmInstruction(LLVMDisasmContextRef DC, uint8_t *Bytes,
    229                              uint64_t BytesSize, uint64_t PC,
    230                              char *OutString, size_t OutStringSize);
    231 
    232 /**
    233  * @}
    234  */
    235 
    236 #ifdef __cplusplus
    237 }
    238 #endif /* !defined(__cplusplus) */
    239 
    240 #endif /* !defined(LLVM_C_DISASSEMBLER_H) */
    241