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 LLVMOrcOpaqueJITStack *LLVMOrcJITStackRef;
33 typedef uint64_t LLVMOrcModuleHandle;
34 typedef uint64_t LLVMOrcTargetAddress;
35 typedef uint64_t (*LLVMOrcSymbolResolverFn)(const char *Name, void *LookupCtx);
36 typedef uint64_t (*LLVMOrcLazyCompileCallbackFn)(LLVMOrcJITStackRef JITStack,
37                                                  void *CallbackCtx);
38 
39 typedef enum { LLVMOrcErrSuccess = 0, LLVMOrcErrGeneric } LLVMOrcErrorCode;
40 
41 /**
42  * Create an ORC JIT stack.
43  *
44  * The client owns the resulting stack, and must call OrcDisposeInstance(...)
45  * to destroy it and free its memory. The JIT stack will take ownership of the
46  * TargetMachine, which will be destroyed when the stack is destroyed. The
47  * client should not attempt to dispose of the Target Machine, or it will result
48  * in a double-free.
49  */
50 LLVMOrcJITStackRef LLVMOrcCreateInstance(LLVMTargetMachineRef TM);
51 
52 /**
53  * Get the error message for the most recent error (if any).
54  *
55  * This message is owned by the ORC JIT Stack and will be freed when the stack
56  * is disposed of by LLVMOrcDisposeInstance.
57  */
58 const char *LLVMOrcGetErrorMsg(LLVMOrcJITStackRef JITStack);
59 
60 /**
61  * Mangle the given symbol.
62  * Memory will be allocated for MangledSymbol to hold the result. The client
63  */
64 void LLVMOrcGetMangledSymbol(LLVMOrcJITStackRef JITStack, char **MangledSymbol,
65                              const char *Symbol);
66 
67 /**
68  * Dispose of a mangled symbol.
69  */
70 void LLVMOrcDisposeMangledSymbol(char *MangledSymbol);
71 
72 /**
73  * Create a lazy compile callback.
74  */
75 LLVMOrcErrorCode
76 LLVMOrcCreateLazyCompileCallback(LLVMOrcJITStackRef JITStack,
77                                  LLVMOrcTargetAddress *RetAddr,
78                                  LLVMOrcLazyCompileCallbackFn Callback,
79                                  void *CallbackCtx);
80 
81 /**
82  * Create a named indirect call stub.
83  */
84 LLVMOrcErrorCode LLVMOrcCreateIndirectStub(LLVMOrcJITStackRef JITStack,
85                                            const char *StubName,
86                                            LLVMOrcTargetAddress InitAddr);
87 
88 /**
89  * Set the pointer for the given indirect stub.
90  */
91 LLVMOrcErrorCode LLVMOrcSetIndirectStubPointer(LLVMOrcJITStackRef JITStack,
92                                                const char *StubName,
93                                                LLVMOrcTargetAddress NewAddr);
94 
95 /**
96  * Add module to be eagerly compiled.
97  */
98 LLVMOrcErrorCode
99 LLVMOrcAddEagerlyCompiledIR(LLVMOrcJITStackRef JITStack,
100                             LLVMOrcModuleHandle *RetHandle, LLVMModuleRef Mod,
101                             LLVMOrcSymbolResolverFn SymbolResolver,
102                             void *SymbolResolverCtx);
103 
104 /**
105  * Add module to be lazily compiled one function at a time.
106  */
107 LLVMOrcErrorCode
108 LLVMOrcAddLazilyCompiledIR(LLVMOrcJITStackRef JITStack,
109                            LLVMOrcModuleHandle *RetHandle, LLVMModuleRef Mod,
110                            LLVMOrcSymbolResolverFn SymbolResolver,
111                            void *SymbolResolverCtx);
112 
113 /**
114  * Add an object file.
115  *
116  * This method takes ownership of the given memory buffer and attempts to add
117  * it to the JIT as an object file.
118  * Clients should *not* dispose of the 'Obj' argument: the JIT will manage it
119  * from this call onwards.
120  */
121 LLVMOrcErrorCode LLVMOrcAddObjectFile(LLVMOrcJITStackRef JITStack,
122                                       LLVMOrcModuleHandle *RetHandle,
123                                       LLVMMemoryBufferRef Obj,
124                                       LLVMOrcSymbolResolverFn SymbolResolver,
125                                       void *SymbolResolverCtx);
126 
127 /**
128  * Remove a module set from the JIT.
129  *
130  * This works for all modules that can be added via OrcAdd*, including object
131  * files.
132  */
133 LLVMOrcErrorCode LLVMOrcRemoveModule(LLVMOrcJITStackRef JITStack,
134                                      LLVMOrcModuleHandle H);
135 
136 /**
137  * Get symbol address from JIT instance.
138  */
139 LLVMOrcErrorCode LLVMOrcGetSymbolAddress(LLVMOrcJITStackRef JITStack,
140                                          LLVMOrcTargetAddress *RetAddr,
141                                          const char *SymbolName);
142 
143 /**
144  * Get symbol address from JIT instance, searching only the specified
145  * handle.
146  */
147 LLVMOrcErrorCode LLVMOrcGetSymbolAddressIn(LLVMOrcJITStackRef JITStack,
148                                            LLVMOrcTargetAddress *RetAddr,
149                                            LLVMOrcModuleHandle H,
150                                            const char *SymbolName);
151 
152 /**
153  * Dispose of an ORC JIT stack.
154  */
155 LLVMOrcErrorCode LLVMOrcDisposeInstance(LLVMOrcJITStackRef JITStack);
156 
157 /**
158  * Register a JIT Event Listener.
159  *
160  * A NULL listener is ignored.
161  */
162 void LLVMOrcRegisterJITEventListener(LLVMOrcJITStackRef JITStack, LLVMJITEventListenerRef L);
163 
164 /**
165  * Unegister a JIT Event Listener.
166  *
167  * A NULL listener is ignored.
168  */
169 void LLVMOrcUnregisterJITEventListener(LLVMOrcJITStackRef JITStack, LLVMJITEventListenerRef L);
170 
171 #ifdef __cplusplus
172 }
173 #endif /* extern "C" */
174 
175 #endif /* LLVM_C_ORCBINDINGS_H */
176