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