[COFF] Dump string table size for COFF file headers
[lldb.git] / llvm / include / llvm-c / Orc.h
1 /*===---------------- llvm-c/Orc.h - OrcV2 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 libLLVMOrcJIT.a, which implements  *|
11 |* JIT compilation of LLVM IR. Minimal documentation of C API specific issues *|
12 |* (especially memory ownership rules) is provided. Core Orc concepts are     *|
13 |* documented in llvm/docs/ORCv2.rst and APIs are documented in the C++       *|
14 |* headers                                                                    *|
15 |*                                                                            *|
16 |* Many exotic languages can interoperate with C code but have a harder time  *|
17 |* with C++ due to name mangling. So in addition to C, this interface enables *|
18 |* tools written in such languages.                                           *|
19 |*                                                                            *|
20 |* Note: This interface is experimental. It is *NOT* stable, and may be       *|
21 |*       changed without warning. Only C API usage documentation is           *|
22 |*       provided. See the C++ documentation for all higher level ORC API     *|
23 |*       details.                                                             *|
24 |*                                                                            *|
25 \*===----------------------------------------------------------------------===*/
26
27 #ifndef LLVM_C_ORC_H
28 #define LLVM_C_ORC_H
29
30 #include "llvm-c/Error.h"
31 #include "llvm-c/TargetMachine.h"
32 #include "llvm-c/Types.h"
33
34 LLVM_C_EXTERN_C_BEGIN
35
36 /**
37  * Represents an address in the target process.
38  */
39 typedef uint64_t LLVMOrcJITTargetAddress;
40
41 /**
42  * A reference to an orc::ExecutionSession instance.
43  */
44 typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef;
45
46 /**
47  * A reference to an orc::SymbolStringPool table entry.
48  */
49 typedef struct LLVMOrcQuaqueSymbolStringPoolEntryPtr
50     *LLVMOrcSymbolStringPoolEntryRef;
51
52 /**
53  * A reference to an orc::JITDylib instance.
54  */
55 typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef;
56
57 /**
58  * A reference to an orc::JITDylib::DefinitionGenerator.
59  */
60 typedef struct LLVMOrcOpaqueJITDylibDefinitionGenerator
61     *LLVMOrcJITDylibDefinitionGeneratorRef;
62
63 /**
64  * Predicate function for SymbolStringPoolEntries.
65  */
66 typedef int (*LLVMOrcSymbolPredicate)(LLVMOrcSymbolStringPoolEntryRef Sym,
67                                       void *Ctx);
68
69 /**
70  * A reference to an orc::ThreadSafeContext instance.
71  */
72 typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef;
73
74 /**
75  * A reference to an orc::ThreadSafeModule instance.
76  */
77 typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef;
78
79 /**
80  * A reference to an orc::JITTargetMachineBuilder instance.
81  */
82 typedef struct LLVMOrcOpaqueJITTargetMachineBuilder
83     *LLVMOrcJITTargetMachineBuilderRef;
84
85 /**
86  * A reference to an orc::LLJITBuilder instance.
87  */
88 typedef struct LLVMOrcOpaqueLLJITBuilder *LLVMOrcLLJITBuilderRef;
89
90 /**
91  * A reference to an orc::LLJIT instance.
92  */
93 typedef struct LLVMOrcOpaqueLLJIT *LLVMOrcLLJITRef;
94
95 /**
96  * Intern a string in the ExecutionSession's SymbolStringPool and return a
97  * reference to it. This increments the ref-count of the pool entry, and the
98  * returned value should be released once the client is done with it by
99  * calling LLVMOrReleaseSymbolStringPoolEntry.
100  *
101  * Since strings are uniqued within the SymbolStringPool
102  * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string
103  * equality.
104  *
105  * Note that this function does not perform linker-mangling on the string.
106  */
107 LLVMOrcSymbolStringPoolEntryRef
108 LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name);
109
110 /**
111  * Reduces the ref-count for of a SymbolStringPool entry.
112  */
113 void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
114
115 /**
116  * Dispose of a JITDylib::DefinitionGenerator. This should only be called if
117  * ownership has not been passed to a JITDylib (e.g. because some error
118  * prevented the client from calling LLVMOrcJITDylibAddGenerator).
119  */
120 void LLVMOrcDisposeJITDylibDefinitionGenerator(
121     LLVMOrcJITDylibDefinitionGeneratorRef DG);
122
123 /**
124  * Add a JITDylib::DefinitionGenerator to the given JITDylib.
125  *
126  * The JITDylib will take ownership of the given generator: The client is no
127  * longer responsible for managing its memory.
128  */
129 void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD,
130                                  LLVMOrcJITDylibDefinitionGeneratorRef DG);
131
132 /**
133  * Get a DynamicLibrarySearchGenerator that will reflect process symbols into
134  * the JITDylib. On success the resulting generator is owned by the client.
135  * Ownership is typically transferred by adding the instance to a JITDylib
136  * using LLVMOrcJITDylibAddGenerator,
137  *
138  * The GlobalPrefix argument specifies the character that appears on the front
139  * of linker-mangled symbols for the target platform (e.g. '_' on MachO).
140  * If non-null, this character will be stripped from the start of all symbol
141  * strings before passing the remaining substring to dlsym.
142  *
143  * The optional Filter and Ctx arguments can be used to supply a symbol name
144  * filter: Only symbols for which the filter returns true will be visible to
145  * JIT'd code. If the Filter argument is null then all process symbols will
146  * be visible to JIT'd code. Note that the symbol name passed to the Filter
147  * function is the full mangled symbol: The client is responsible for stripping
148  * the global prefix if present.
149  */
150 LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess(
151     LLVMOrcJITDylibDefinitionGeneratorRef *Result, char GlobalPrefx,
152     LLVMOrcSymbolPredicate Filter, void *FilterCtx);
153
154 /**
155  * Create a ThreadSafeContext containing a new LLVMContext.
156  *
157  * Ownership of the underlying ThreadSafeContext data is shared: Clients
158  * can and should dispose of their ThreadSafeContext as soon as they no longer
159  * need to refer to it directly. Other references (e.g. from ThreadSafeModules
160  * will keep the data alive as long as it is needed.
161  */
162 LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void);
163
164 /**
165  * Get a reference to the wrapped LLVMContext.
166  */
167 LLVMContextRef
168 LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx);
169
170 /**
171  * Dispose of a ThreadSafeContext.
172  */
173 void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx);
174
175 /**
176  * Create a ThreadSafeModule wrapper around the given LLVM module. This takes
177  * ownership of the M argument which should not be disposed of or referenced
178  * after this function returns.
179  *
180  * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT
181  * (e.g. by LLVMOrcLLJITAddLLVMIRModule), in which case the client is no longer
182  * responsible for it. If it is not transferred to the JIT then the client
183  * should call LLVMOrcDisposeThreadSafeModule to dispose of it.
184  */
185 LLVMOrcThreadSafeModuleRef
186 LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M,
187                                  LLVMOrcThreadSafeContextRef TSCtx);
188
189 /**
190  * Dispose of a ThreadSafeModule. This should only be called if ownership has
191  * not been passed to LLJIT (e.g. because some error prevented the client from
192  * adding this to the JIT).
193  */
194 void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM);
195
196 /**
197  * Create a JITTargetMachineBuilder by detecting the host.
198  *
199  * On success the client owns the resulting JITTargetMachineBuilder. It must be
200  * passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder) or disposed
201  * of by calling LLVMOrcDisposeJITTargetMachineBuilder.
202  */
203 LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost(
204     LLVMOrcJITTargetMachineBuilderRef *Result);
205
206 /**
207  * Create a JITTargetMachineBuilder from the given TargetMachine template.
208  *
209  * This operation takes ownership of the given TargetMachine and destroys it
210  * before returing. The resulting JITTargetMachineBuilder is owned by the client
211  * and must be passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder)
212  * or disposed of by calling LLVMOrcDisposeJITTargetMachineBuilder.
213  */
214 LLVMOrcJITTargetMachineBuilderRef
215 LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM);
216
217 /**
218  * Dispose of a JITTargetMachineBuilder.
219  */
220 void LLVMOrcDisposeJITTargetMachineBuilder(
221     LLVMOrcJITTargetMachineBuilderRef JTMB);
222
223 /**
224  * Create an LLJITTargetMachineBuilder.
225  *
226  * The client owns the resulting LLJITBuilder and should dispose of it using
227  * LLVMOrcDisposeLLJITBuilder once they are done with it.
228  */
229 LLVMOrcLLJITBuilderRef LLVMOrcCreateLLJITBuilder(void);
230
231 /**
232  * Dispose of an LLVMOrcLLJITBuilderRef. This should only be called if ownership
233  * has not been passed to LLVMOrcCreateLLJIT (e.g. because some error prevented
234  * that function from being called).
235  */
236 void LLVMOrcDisposeLLJITBuilder(LLVMOrcLLJITBuilderRef Builder);
237
238 /**
239  * Set the JITTargetMachineBuilder to be used when constructing the LLJIT
240  * instance. Calling this function is optional: if it is not called then the
241  * LLJITBuilder will use JITTargeTMachineBuilder::detectHost to construct a
242  * JITTargetMachineBuilder.
243  */
244 void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder(
245     LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB);
246
247 /**
248  * Create an LLJIT instance from an LLJITBuilder.
249  *
250  * This operation takes ownership of the Builder argument: clients should not
251  * dispose of the builder after calling this function (even if the function
252  * returns an error). If a null Builder argument is provided then a
253  * default-constructed LLJITBuilder will be used.
254  *
255  * On success the resulting LLJIT instance is uniquely owned by the client and
256  * automatically manages the memory of all JIT'd code and all modules that are
257  * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the
258  * LLJIT instance will free all memory managed by the JIT, including JIT'd code
259  * and not-yet compiled modules.
260  */
261 LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result,
262                                 LLVMOrcLLJITBuilderRef Builder);
263
264 /**
265  * Dispose of an LLJIT instance.
266  */
267 LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J);
268
269 /**
270  * Get a reference to the ExecutionSession for this LLJIT instance.
271  *
272  * The ExecutionSession is owned by the LLJIT instance. The client is not
273  * responsible for managing its memory.
274  */
275 LLVMOrcExecutionSessionRef LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J);
276
277 /**
278  * Return a reference to the Main JITDylib.
279  *
280  * The JITDylib is owned by the LLJIT instance. The client is not responsible
281  * for managing its memory.
282  */
283 LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J);
284
285 /**
286  * Return the target triple for this LLJIT instance. This string is owned by
287  * the LLJIT instance and should not be freed by the client.
288  */
289 const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J);
290
291 /**
292  * Returns the global prefix character according to the LLJIT's DataLayout.
293  */
294 char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J);
295
296 /**
297  * Mangles the given string according to the LLJIT instance's DataLayout, then
298  * interns the result in the SymbolStringPool and returns a reference to the
299  * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to
300  * decrement the ref-count on the pool entry once they are finished with this
301  * value.
302  */
303 LLVMOrcSymbolStringPoolEntryRef
304 LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName);
305
306 /**
307  * Add a buffer representing an object file to the given JITDylib in the given
308  * LLJIT instance. This operation transfers ownership of the buffer to the
309  * LLJIT instance. The buffer should not be disposed of or referenced once this
310  * function returns.
311  */
312 LLVMErrorRef LLVMOrcLLJITAddObjectFile(LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD,
313                                        LLVMMemoryBufferRef ObjBuffer);
314
315 /**
316  * Add an IR module to the given JITDylib of the given LLJIT instance. This
317  * operation transfers ownership of the TSM argument to the LLJIT instance.
318  * The TSM argument should not be 3disposed of or referenced once this
319  * function returns.
320  */
321 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule(LLVMOrcLLJITRef J,
322                                          LLVMOrcJITDylibRef JD,
323                                          LLVMOrcThreadSafeModuleRef TSM);
324 /**
325  * Look up the given symbol in the main JITDylib of the given LLJIT instance.
326  *
327  * This operation does not take ownership of the Name argument.
328  */
329 LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J,
330                                 LLVMOrcJITTargetAddress *Result,
331                                 const char *Name);
332
333 LLVM_C_EXTERN_C_END
334
335 #endif /* LLVM_C_ORC_H */