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