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