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