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