1/*===----------- llvm-c/LLJIT.h - OrcV2 LLJIT C bindings ----------*- 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 the LLJIT class in *|
11|* libLLVMOrcJIT.a, which provides a simple MCJIT-like ORC JIT. *|
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. Only C API usage documentation is *|
19|* provided. See the C++ documentation for all higher level ORC API *|
20|* details. *|
21|* *|
22\*===----------------------------------------------------------------------===*/
23
24#ifndef LLVM_C_LLJIT_H
25#define LLVM_C_LLJIT_H
26
27#include "llvm-c/Error.h"
28#include "llvm-c/Orc.h"
29#include "llvm-c/TargetMachine.h"
30#include "llvm-c/Types.h"
31#include "llvm-c/Visibility.h"
32
33LLVM_C_EXTERN_C_BEGIN
34
35/**
36 * @defgroup LLVMCExecutionEngineLLJIT LLJIT
37 * @ingroup LLVMCExecutionEngine
38 *
39 * @{
40 */
41
42/**
43 * A function for constructing an ObjectLinkingLayer instance to be used
44 * by an LLJIT instance.
45 *
46 * Clients can call LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator to
47 * set the creator function to use when constructing an LLJIT instance.
48 * This can be used to override the default linking layer implementation
49 * that would otherwise be chosen by LLJITBuilder.
50 *
51 * Object linking layers returned by this function will become owned by the
52 * LLJIT instance. The client is not responsible for managing their lifetimes
53 * after the function returns.
54 */
55typedef LLVMOrcObjectLayerRef (
56 *LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction)(
57 void *Ctx, LLVMOrcExecutionSessionRef ES, const char *Triple);
58
59/**
60 * A reference to an orc::LLJITBuilder instance.
61 */
62typedef struct LLVMOrcOpaqueLLJITBuilder *LLVMOrcLLJITBuilderRef;
63
64/**
65 * A reference to an orc::LLJIT instance.
66 */
67typedef struct LLVMOrcOpaqueLLJIT *LLVMOrcLLJITRef;
68
69/**
70 * Create an LLVMOrcLLJITBuilder.
71 *
72 * The client owns the resulting LLJITBuilder and should dispose of it using
73 * LLVMOrcDisposeLLJITBuilder once they are done with it.
74 */
75LLVM_C_ABI LLVMOrcLLJITBuilderRef LLVMOrcCreateLLJITBuilder(void);
76
77/**
78 * Dispose of an LLVMOrcLLJITBuilderRef. This should only be called if ownership
79 * has not been passed to LLVMOrcCreateLLJIT (e.g. because some error prevented
80 * that function from being called).
81 */
82LLVM_C_ABI void LLVMOrcDisposeLLJITBuilder(LLVMOrcLLJITBuilderRef Builder);
83
84/**
85 * Set the JITTargetMachineBuilder to be used when constructing the LLJIT
86 * instance. Calling this function is optional: if it is not called then the
87 * LLJITBuilder will use JITTargeTMachineBuilder::detectHost to construct a
88 * JITTargetMachineBuilder.
89 *
90 * This function takes ownership of the JTMB argument: clients should not
91 * dispose of the JITTargetMachineBuilder after calling this function.
92 */
93LLVM_C_ABI void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder(
94 LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB);
95
96/**
97 * Set an ObjectLinkingLayer creator function for this LLJIT instance.
98 */
99LLVM_C_ABI void LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator(
100 LLVMOrcLLJITBuilderRef Builder,
101 LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction F, void *Ctx);
102
103/**
104 * Create an LLJIT instance from an LLJITBuilder.
105 *
106 * This operation takes ownership of the Builder argument: clients should not
107 * dispose of the builder after calling this function (even if the function
108 * returns an error). If a null Builder argument is provided then a
109 * default-constructed LLJITBuilder will be used.
110 *
111 * On success the resulting LLJIT instance is uniquely owned by the client and
112 * automatically manages the memory of all JIT'd code and all modules that are
113 * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the
114 * LLJIT instance will free all memory managed by the JIT, including JIT'd code
115 * and not-yet compiled modules.
116 */
117LLVM_C_ABI LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result,
118 LLVMOrcLLJITBuilderRef Builder);
119
120/**
121 * Dispose of an LLJIT instance.
122 */
123LLVM_C_ABI LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J);
124
125/**
126 * Get a reference to the ExecutionSession for this LLJIT instance.
127 *
128 * The ExecutionSession is owned by the LLJIT instance. The client is not
129 * responsible for managing its memory.
130 */
131LLVM_C_ABI LLVMOrcExecutionSessionRef
132LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J);
133
134/**
135 * Return a reference to the Main JITDylib.
136 *
137 * The JITDylib is owned by the LLJIT instance. The client is not responsible
138 * for managing its memory.
139 */
140LLVM_C_ABI LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J);
141
142/**
143 * Return the target triple for this LLJIT instance. This string is owned by
144 * the LLJIT instance and should not be freed by the client.
145 */
146LLVM_C_ABI const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J);
147
148/**
149 * Returns the global prefix character according to the LLJIT's DataLayout.
150 */
151LLVM_C_ABI char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J);
152
153/**
154 * Mangles the given string according to the LLJIT instance's DataLayout, then
155 * interns the result in the SymbolStringPool and returns a reference to the
156 * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to
157 * decrement the ref-count on the pool entry once they are finished with this
158 * value.
159 */
160LLVM_C_ABI LLVMOrcSymbolStringPoolEntryRef
161LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName);
162
163/**
164 * Add a buffer representing an object file to the given JITDylib in the given
165 * LLJIT instance. This operation transfers ownership of the buffer to the
166 * LLJIT instance. The buffer should not be disposed of or referenced once this
167 * function returns.
168 *
169 * Resources associated with the given object will be tracked by the given
170 * JITDylib's default resource tracker.
171 */
172LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITAddObjectFile(
173 LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD, LLVMMemoryBufferRef ObjBuffer);
174
175/**
176 * Add a buffer representing an object file to the given ResourceTracker's
177 * JITDylib in the given LLJIT instance. This operation transfers ownership of
178 * the buffer to the LLJIT instance. The buffer should not be disposed of or
179 * referenced once this function returns.
180 *
181 * Resources associated with the given object will be tracked by ResourceTracker
182 * RT.
183 */
184LLVM_C_ABI LLVMErrorRef
185LLVMOrcLLJITAddObjectFileWithRT(LLVMOrcLLJITRef J, LLVMOrcResourceTrackerRef RT,
186 LLVMMemoryBufferRef ObjBuffer);
187
188/**
189 * Add an IR module to the given JITDylib in the given LLJIT instance. This
190 * operation transfers ownership of the TSM argument to the LLJIT instance.
191 * The TSM argument should not be disposed of or referenced once this
192 * function returns.
193 *
194 * Resources associated with the given Module will be tracked by the given
195 * JITDylib's default resource tracker.
196 */
197LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule(
198 LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD, LLVMOrcThreadSafeModuleRef TSM);
199
200/**
201 * Add an IR module to the given ResourceTracker's JITDylib in the given LLJIT
202 * instance. This operation transfers ownership of the TSM argument to the LLJIT
203 * instance. The TSM argument should not be disposed of or referenced once this
204 * function returns.
205 *
206 * Resources associated with the given Module will be tracked by ResourceTracker
207 * RT.
208 */
209LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITAddLLVMIRModuleWithRT(
210 LLVMOrcLLJITRef J, LLVMOrcResourceTrackerRef JD,
211 LLVMOrcThreadSafeModuleRef TSM);
212
213/**
214 * Look up the given symbol in the main JITDylib of the given LLJIT instance.
215 *
216 * This operation does not take ownership of the Name argument.
217 */
218LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J,
219 LLVMOrcExecutorAddress *Result,
220 const char *Name);
221
222/**
223 * Returns a non-owning reference to the LLJIT instance's object linking layer.
224 */
225LLVM_C_ABI LLVMOrcObjectLayerRef
226LLVMOrcLLJITGetObjLinkingLayer(LLVMOrcLLJITRef J);
227
228/**
229 * Returns a non-owning reference to the LLJIT instance's object linking layer.
230 */
231LLVM_C_ABI LLVMOrcObjectTransformLayerRef
232LLVMOrcLLJITGetObjTransformLayer(LLVMOrcLLJITRef J);
233
234/**
235 * Returns a non-owning reference to the LLJIT instance's IR transform layer.
236 */
237LLVM_C_ABI LLVMOrcIRTransformLayerRef
238LLVMOrcLLJITGetIRTransformLayer(LLVMOrcLLJITRef J);
239
240/**
241 * Get the LLJIT instance's default data layout string.
242 *
243 * This string is owned by the LLJIT instance and does not need to be freed
244 * by the caller.
245 */
246LLVM_C_ABI const char *LLVMOrcLLJITGetDataLayoutStr(LLVMOrcLLJITRef J);
247
248/**
249 * @}
250 */
251
252LLVM_C_EXTERN_C_END
253
254#endif /* LLVM_C_LLJIT_H */
255