include/llvm-c/OrcBindings.h

   1 /*===----------- llvm-c/OrcBindings.h - Orc Lib C Iface ---------*- 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 declares the C interface to libLLVMOrcJIT.a, which implements  *|
  11 |* JIT compilation of LLVM IR.                                                *|
  12 |*                                                                            *|
  13 |* Many exotic languages can interoperate with C code but have a harder time  *|
  14 |* with C++ due to name mangling. So in addition to C, this interface enables *|
  15 |* tools written in such languages.                                           *|
  16 |*                                                                            *|
  17 |* Note: This interface is experimental. It is *NOT* stable, and may be       *|
  18 |*       changed without warning.                                             *|
  19 |*                                                                            *|
  20 \*===----------------------------------------------------------------------===*/
  21
  22 #ifndef LLVM_C_ORCBINDINGS_H
  23 #define LLVM_C_ORCBINDINGS_H
  24
  25 #include "llvm-c/Object.h"
  26 #include "llvm-c/TargetMachine.h"
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 typedef struct LLVMOpaqueSharedModule *LLVMSharedModuleRef;
  33 typedef struct LLVMOrcOpaqueJITStack *LLVMOrcJITStackRef;
  34 typedef uint32_t LLVMOrcModuleHandle;
  35 typedef uint64_t LLVMOrcTargetAddress;
  36 typedef uint64_t (*LLVMOrcSymbolResolverFn)(const char *Name, void *LookupCtx);
  37 typedef uint64_t (*LLVMOrcLazyCompileCallbackFn)(LLVMOrcJITStackRef JITStack,
  38                                                  void *CallbackCtx);
  39
  40 typedef enum { LLVMOrcErrSuccess = 0, LLVMOrcErrGeneric } LLVMOrcErrorCode;
  41
  42 /**
  43  * Turn an LLVMModuleRef into an LLVMSharedModuleRef.
  44  *
  45  * The JIT uses shared ownership for LLVM modules, since it is generally
  46  * difficult to know when the JIT will be finished with a module (and the JIT
  47  * has no way of knowing when a user may be finished with one).
  48  *
  49  * Calling this method with an LLVMModuleRef creates a shared-pointer to the
  50  * module, and returns a reference to this shared pointer.
  51  *
  52  * The shared module should be disposed when finished with by calling
  53  * LLVMOrcDisposeSharedModule (not LLVMDisposeModule). The Module will be
  54  * deleted when the last shared pointer owner relinquishes it.
  55  */
  56
  57 LLVMSharedModuleRef LLVMOrcMakeSharedModule(LLVMModuleRef Mod);
  58
  59 /**
  60  * Dispose of a shared module.
  61  *
  62  * The module should not be accessed after this call. The module will be
  63  * deleted once all clients (including the JIT itself) have released their
  64  * shared pointers.
  65  */
  66
  67 void LLVMOrcDisposeSharedModuleRef(LLVMSharedModuleRef SharedMod);
  68
  69 /**
  70  * Create an ORC JIT stack.
  71  *
  72  * The client owns the resulting stack, and must call OrcDisposeInstance(...)
  73  * to destroy it and free its memory. The JIT stack will take ownership of the
  74  * TargetMachine, which will be destroyed when the stack is destroyed. The
  75  * client should not attempt to dispose of the Target Machine, or it will result
  76  * in a double-free.
  77  */
  78 LLVMOrcJITStackRef LLVMOrcCreateInstance(LLVMTargetMachineRef TM);
  79
  80 /**
  81  * Get the error message for the most recent error (if any).
  82  *
  83  * This message is owned by the ORC JIT Stack and will be freed when the stack
  84  * is disposed of by LLVMOrcDisposeInstance.
  85  */
  86 const char *LLVMOrcGetErrorMsg(LLVMOrcJITStackRef JITStack);
  87
  88 /**
  89  * Mangle the given symbol.
  90  * Memory will be allocated for MangledSymbol to hold the result. The client
  91  */
  92 void LLVMOrcGetMangledSymbol(LLVMOrcJITStackRef JITStack, char **MangledSymbol,
  93                              const char *Symbol);
  94
  95 /**
  96  * Dispose of a mangled symbol.
  97  */
  98 void LLVMOrcDisposeMangledSymbol(char *MangledSymbol);
  99
 100 /**
 101  * Create a lazy compile callback.
 102  */
 103 LLVMOrcErrorCode
 104 LLVMOrcCreateLazyCompileCallback(LLVMOrcJITStackRef JITStack,
 105                                  LLVMOrcTargetAddress *RetAddr,
 106                                  LLVMOrcLazyCompileCallbackFn Callback,
 107                                  void *CallbackCtx);
 108
 109 /**
 110  * Create a named indirect call stub.
 111  */
 112 LLVMOrcErrorCode LLVMOrcCreateIndirectStub(LLVMOrcJITStackRef JITStack,
 113                                            const char *StubName,
 114                                            LLVMOrcTargetAddress InitAddr);
 115
 116 /**
 117  * Set the pointer for the given indirect stub.
 118  */
 119 LLVMOrcErrorCode LLVMOrcSetIndirectStubPointer(LLVMOrcJITStackRef JITStack,
 120                                                const char *StubName,
 121                                                LLVMOrcTargetAddress NewAddr);
 122
 123 /**
 124  * Add module to be eagerly compiled.
 125  */
 126 LLVMOrcErrorCode
 127 LLVMOrcAddEagerlyCompiledIR(LLVMOrcJITStackRef JITStack,
 128                             LLVMOrcModuleHandle *RetHandle,
 129                             LLVMSharedModuleRef Mod,
 130                             LLVMOrcSymbolResolverFn SymbolResolver,
 131                             void *SymbolResolverCtx);
 132
 133 /**
 134  * Add module to be lazily compiled one function at a time.
 135  */
 136 LLVMOrcErrorCode
 137 LLVMOrcAddLazilyCompiledIR(LLVMOrcJITStackRef JITStack,
 138                            LLVMOrcModuleHandle *RetHandle,
 139                            LLVMSharedModuleRef Mod,
 140                            LLVMOrcSymbolResolverFn SymbolResolver,
 141                            void *SymbolResolverCtx);
 142
 143 /**
 144  * Add an object file.
 145  *
 146  * This method takes ownership of the given memory buffer and attempts to add
 147  * it to the JIT as an object file.
 148  * Clients should *not* dispose of the 'Obj' argument: the JIT will manage it
 149  * from this call onwards.
 150  */
 151 LLVMOrcErrorCode LLVMOrcAddObjectFile(LLVMOrcJITStackRef JITStack,
 152                                       LLVMOrcModuleHandle *RetHandle,
 153                                       LLVMMemoryBufferRef Obj,
 154                                       LLVMOrcSymbolResolverFn SymbolResolver,
 155                                       void *SymbolResolverCtx);
 156
 157 /**
 158  * Remove a module set from the JIT.
 159  *
 160  * This works for all modules that can be added via OrcAdd*, including object
 161  * files.
 162  */
 163 LLVMOrcErrorCode LLVMOrcRemoveModule(LLVMOrcJITStackRef JITStack,
 164                                      LLVMOrcModuleHandle H);
 165
 166 /**
 167  * Get symbol address from JIT instance.
 168  */
 169 LLVMOrcErrorCode LLVMOrcGetSymbolAddress(LLVMOrcJITStackRef JITStack,
 170                                          LLVMOrcTargetAddress *RetAddr,
 171                                          const char *SymbolName);
 172
 173 /**
 174  * Dispose of an ORC JIT stack.
 175  */
 176 LLVMOrcErrorCode LLVMOrcDisposeInstance(LLVMOrcJITStackRef JITStack);
 177
 178 #ifdef __cplusplus
 179 }
 180 #endif /* extern "C" */
 181
 182 #endif /* LLVM_C_ORCBINDINGS_H */