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
34LLVM_C_EXTERN_C_BEGIN
35
36/**
37 * Represents an address in the target process.
38 */
39typedef uint64_t LLVMOrcJITTargetAddress;
40
41/**
42 * Represents generic linkage flags for a symbol definition.
43 */
44typedef enum {
45 LLVMJITSymbolGenericFlagsExported = 1U << 0,
46 LLVMJITSymbolGenericFlagsWeak = 1U << 1,
47 LLVMJITSymbolGenericFlagsCallable = 1U << 2,
48 LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly = 1U << 3
49} LLVMJITSymbolGenericFlags;
50
51/**
52 * Represents target specific flags for a symbol definition.
53 */
54typedef uint8_t LLVMJITSymbolTargetFlags;
55
56/**
57 * Represents the linkage flags for a symbol definition.
58 */
59typedef struct {
60 uint8_t GenericFlags;
61 uint8_t TargetFlags;
62} LLVMJITSymbolFlags;
63
64/**
65 * Represents an evaluated symbol address and flags.
66 */
67typedef struct {
68 LLVMOrcJITTargetAddress Address;
69 LLVMJITSymbolFlags Flags;
70} LLVMJITEvaluatedSymbol;
71
72/**
73 * A reference to an orc::ExecutionSession instance.
74 */
75typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef;
76
77/**
78 * Error reporter function.
79 */
80typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err);
81
82/**
83 * A reference to an orc::SymbolStringPool.
84 */
85typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef;
86
87/**
88 * A reference to an orc::SymbolStringPool table entry.
89 */
90typedef struct LLVMOrcOpaqueSymbolStringPoolEntry
91 *LLVMOrcSymbolStringPoolEntryRef;
92
93/**
94 * Represents a pair of a symbol name and LLVMJITSymbolFlags.
95 */
96typedef struct {
97 LLVMOrcSymbolStringPoolEntryRef Name;
98 LLVMJITSymbolFlags Flags;
99} LLVMOrcCSymbolFlagsMapPair;
100
101/**
102 * Represents a list of (SymbolStringPtr, JITSymbolFlags) pairs that can be used
103 * to construct a SymbolFlagsMap.
104 */
105typedef LLVMOrcCSymbolFlagsMapPair *LLVMOrcCSymbolFlagsMapPairs;
106
107/**
108 * Represents a pair of a symbol name and an evaluated symbol.
109 */
110typedef struct {
111 LLVMOrcSymbolStringPoolEntryRef Name;
112 LLVMJITEvaluatedSymbol Sym;
113} LLVMJITCSymbolMapPair;
114
115/**
116 * Represents a list of (SymbolStringPtr, JITEvaluatedSymbol) pairs that can be
117 * used to construct a SymbolMap.
118 */
119typedef LLVMJITCSymbolMapPair *LLVMOrcCSymbolMapPairs;
120
121/**
122 * Lookup kind. This can be used by definition generators when deciding whether
123 * to produce a definition for a requested symbol.
124 *
125 * This enum should be kept in sync with llvm::orc::LookupKind.
126 */
127typedef enum {
128 LLVMOrcLookupKindStatic,
129 LLVMOrcLookupKindDLSym
130} LLVMOrcLookupKind;
131
132/**
133 * JITDylib lookup flags. This can be used by definition generators when
134 * deciding whether to produce a definition for a requested symbol.
135 *
136 * This enum should be kept in sync with llvm::orc::JITDylibLookupFlags.
137 */
138typedef enum {
139 LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly,
140 LLVMOrcJITDylibLookupFlagsMatchAllSymbols
141} LLVMOrcJITDylibLookupFlags;
142
143/**
144 * Symbol lookup flags for lookup sets. This should be kept in sync with
145 * llvm::orc::SymbolLookupFlags.
146 */
147typedef enum {
148 LLVMOrcSymbolLookupFlagsRequiredSymbol,
149 LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol
150} LLVMOrcSymbolLookupFlags;
151
152/**
153 * An element type for a symbol lookup set.
154 */
155typedef struct {
156 LLVMOrcSymbolStringPoolEntryRef Name;
157 LLVMOrcSymbolLookupFlags LookupFlags;
158} LLVMOrcCLookupSetElement;
159
160/**
161 * A set of symbols to look up / generate.
162 *
163 * The list is terminated with an element containing a null pointer for the
164 * Name field.
165 *
166 * If a client creates an instance of this type then they are responsible for
167 * freeing it, and for ensuring that all strings have been retained over the
168 * course of its life. Clients receiving a copy from a callback are not
169 * responsible for managing lifetime or retain counts.
170 */
171typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet;
172
173/**
174 * A reference to a uniquely owned orc::MaterializationUnit instance.
175 */
176typedef struct LLVMOrcOpaqueMaterializationUnit *LLVMOrcMaterializationUnitRef;
177
178/**
179 * A reference to a uniquely owned orc::MaterializationResponsibility instance.
180 *
181 * Ownership must be passed to a lower-level layer in a JIT stack.
182 */
183typedef struct LLVMOrcOpaqueMaterializationResponsibility
184 *LLVMOrcMaterializationResponsibilityRef;
185
186/**
187 * A reference to an orc::JITDylib instance.
188 */
189typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef;
190
191/**
192 * A MaterializationUnit materialize callback.
193 *
194 * Ownership of the Ctx and MR arguments passes to the callback which must
195 * adhere to the LLVMOrcMaterializationResponsibilityRef contract (see comment
196 * for that type).
197 *
198 * If this callback is called then the LLVMOrcMaterializationUnitDestroy
199 * callback will NOT be called.
200 */
201typedef void (*LLVMOrcMaterializationUnitMaterializeFunction)(
202 void *Ctx, LLVMOrcMaterializationResponsibilityRef MR);
203
204/**
205 * A MaterializationUnit discard callback.
206 *
207 * Ownership of JD and Symbol remain with the caller: These arguments should
208 * not be disposed of or released.
209 */
210typedef void (*LLVMOrcMaterializationUnitDiscardFunction)(
211 void *Ctx, LLVMOrcJITDylibRef JD, LLVMOrcSymbolStringPoolEntryRef Symbol);
212
213/**
214 * A MaterializationUnit destruction callback.
215 *
216 * If a custom MaterializationUnit is destroyed before its Materialize
217 * function is called then this function will be called to provide an
218 * opportunity for the underlying program representation to be destroyed.
219 */
220typedef void (*LLVMOrcMaterializationUnitDestroyFunction)(void *Ctx);
221
222/**
223 * A reference to an orc::ResourceTracker instance.
224 */
225typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef;
226
227/**
228 * A reference to an orc::DefinitionGenerator.
229 */
230typedef struct LLVMOrcOpaqueDefinitionGenerator
231 *LLVMOrcDefinitionGeneratorRef;
232
233/**
234 * An opaque lookup state object. Instances of this type can be captured to
235 * suspend a lookup while a custom generator function attempts to produce a
236 * definition.
237 *
238 * If a client captures a lookup state object then they must eventually call
239 * LLVMOrcLookupStateContinueLookup to restart the lookup. This is required
240 * in order to release memory allocated for the lookup state, even if errors
241 * have occurred while the lookup was suspended (if these errors have made the
242 * lookup impossible to complete then it will issue its own error before
243 * destruction).
244 */
245typedef struct LLVMOrcOpaqueLookupState *LLVMOrcLookupStateRef;
246
247/**
248 * A custom generator function. This can be used to create a custom generator
249 * object using LLVMOrcCreateCustomCAPIDefinitionGenerator. The resulting
250 * object can be attached to a JITDylib, via LLVMOrcJITDylibAddGenerator, to
251 * receive callbacks when lookups fail to match existing definitions.
252 *
253 * GeneratorObj will contain the address of the custom generator object.
254 *
255 * Ctx will contain the context object passed to
256 * LLVMOrcCreateCustomCAPIDefinitionGenerator.
257 *
258 * LookupState will contain a pointer to an LLVMOrcLookupStateRef object. This
259 * can optionally be modified to make the definition generation process
260 * asynchronous: If the LookupStateRef value is copied, and the original
261 * LLVMOrcLookupStateRef set to null, the lookup will be suspended. Once the
262 * asynchronous definition process has been completed clients must call
263 * LLVMOrcLookupStateContinueLookup to continue the lookup (this should be
264 * done unconditionally, even if errors have occurred in the mean time, to
265 * free the lookup state memory and notify the query object of the failures).
266 * If LookupState is captured this function must return LLVMErrorSuccess.
267 *
268 * The Kind argument can be inspected to determine the lookup kind (e.g.
269 * as-if-during-static-link, or as-if-during-dlsym).
270 *
271 * The JD argument specifies which JITDylib the definitions should be generated
272 * into.
273 *
274 * The JDLookupFlags argument can be inspected to determine whether the original
275 * lookup included non-exported symobls.
276 *
277 * Finally, the LookupSet argument contains the set of symbols that could not
278 * be found in JD already (the set of generation candidates).
279 */
280typedef LLVMErrorRef (*LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction)(
281 LLVMOrcDefinitionGeneratorRef GeneratorObj, void *Ctx,
282 LLVMOrcLookupStateRef *LookupState, LLVMOrcLookupKind Kind,
283 LLVMOrcJITDylibRef JD, LLVMOrcJITDylibLookupFlags JDLookupFlags,
284 LLVMOrcCLookupSet LookupSet, size_t LookupSetSize);
285
286/**
287 * Predicate function for SymbolStringPoolEntries.
288 */
289typedef int (*LLVMOrcSymbolPredicate)(void *Ctx,
290 LLVMOrcSymbolStringPoolEntryRef Sym);
291
292/**
293 * A reference to an orc::ThreadSafeContext instance.
294 */
295typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef;
296
297/**
298 * A reference to an orc::ThreadSafeModule instance.
299 */
300typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef;
301
302/**
303 * A reference to an orc::JITTargetMachineBuilder instance.
304 */
305typedef struct LLVMOrcOpaqueJITTargetMachineBuilder
306 *LLVMOrcJITTargetMachineBuilderRef;
307
308/**
309 * A reference to an orc::ObjectLayer instance.
310 */
311typedef struct LLVMOrcOpaqueObjectLayer *LLVMOrcObjectLayerRef;
312
313/**
314 * A reference to an orc::ObjectLinkingLayer instance.
315 */
316typedef struct LLVMOrcOpaqueObjectLinkingLayer *LLVMOrcObjectLinkingLayerRef;
317
318/**
319 * Attach a custom error reporter function to the ExecutionSession.
320 *
321 * The error reporter will be called to deliver failure notices that can not be
322 * directly reported to a caller. For example, failure to resolve symbols in
323 * the JIT linker is typically reported via the error reporter (callers
324 * requesting definitions from the JIT will typically be delivered a
325 * FailureToMaterialize error instead).
326 */
327void LLVMOrcExecutionSessionSetErrorReporter(
328 LLVMOrcExecutionSessionRef ES, LLVMOrcErrorReporterFunction ReportError,
329 void *Ctx);
330
331/**
332 * Return a reference to the SymbolStringPool for an ExecutionSession.
333 *
334 * Ownership of the pool remains with the ExecutionSession: The caller is
335 * not required to free the pool.
336 */
337LLVMOrcSymbolStringPoolRef
338LLVMOrcExecutionSessionGetSymbolStringPool(LLVMOrcExecutionSessionRef ES);
339
340/**
341 * Clear all unreferenced symbol string pool entries.
342 *
343 * This can be called at any time to release unused entries in the
344 * ExecutionSession's string pool. Since it locks the pool (preventing
345 * interning of any new strings) it is recommended that it only be called
346 * infrequently, ideally when the caller has reason to believe that some
347 * entries will have become unreferenced, e.g. after removing a module or
348 * closing a JITDylib.
349 */
350void LLVMOrcSymbolStringPoolClearDeadEntries(LLVMOrcSymbolStringPoolRef SSP);
351
352/**
353 * Intern a string in the ExecutionSession's SymbolStringPool and return a
354 * reference to it. This increments the ref-count of the pool entry, and the
355 * returned value should be released once the client is done with it by
356 * calling LLVMOrReleaseSymbolStringPoolEntry.
357 *
358 * Since strings are uniqued within the SymbolStringPool
359 * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string
360 * equality.
361 *
362 * Note that this function does not perform linker-mangling on the string.
363 */
364LLVMOrcSymbolStringPoolEntryRef
365LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name);
366
367/**
368 * Increments the ref-count for a SymbolStringPool entry.
369 */
370void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
371
372/**
373 * Reduces the ref-count for of a SymbolStringPool entry.
374 */
375void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
376
377const char *LLVMOrcSymbolStringPoolEntryStr(LLVMOrcSymbolStringPoolEntryRef S);
378
379/**
380 * Reduces the ref-count of a ResourceTracker.
381 */
382void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT);
383
384/**
385 * Transfers tracking of all resources associated with resource tracker SrcRT
386 * to resource tracker DstRT.
387 */
388void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT,
389 LLVMOrcResourceTrackerRef DstRT);
390
391/**
392 * Remove all resources associated with the given tracker. See
393 * ResourceTracker::remove().
394 */
395LLVMErrorRef LLVMOrcResourceTrackerRemove(LLVMOrcResourceTrackerRef RT);
396
397/**
398 * Dispose of a JITDylib::DefinitionGenerator. This should only be called if
399 * ownership has not been passed to a JITDylib (e.g. because some error
400 * prevented the client from calling LLVMOrcJITDylibAddGenerator).
401 */
402void LLVMOrcDisposeDefinitionGenerator(LLVMOrcDefinitionGeneratorRef DG);
403
404/**
405 * Dispose of a MaterializationUnit.
406 */
407void LLVMOrcDisposeMaterializationUnit(LLVMOrcMaterializationUnitRef MU);
408
409/**
410 * Create a custom MaterializationUnit.
411 *
412 * Name is a name for this MaterializationUnit to be used for identification
413 * and logging purposes (e.g. if this MaterializationUnit produces an
414 * object buffer then the name of that buffer will be derived from this name).
415 *
416 * The Syms list contains the names and linkages of the symbols provided by this
417 * unit. This function takes ownership of the elements of the Syms array. The
418 * Name fields of the array elements are taken to have been retained for this
419 * function. The client should *not* release the elements of the array, but is
420 * still responsible for destroyingthe array itself.
421 *
422 * The InitSym argument indicates whether or not this MaterializationUnit
423 * contains static initializers. If three are no static initializers (the common
424 * case) then this argument should be null. If there are static initializers
425 * then InitSym should be set to a unique name that also appears in the Syms
426 * list with the LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly flag
427 * set. This function takes ownership of the InitSym, which should have been
428 * retained twice on behalf of this function: once for the Syms entry and once
429 * for InitSym. If clients wish to use the InitSym value after this function
430 * returns they must retain it once more for themselves.
431 *
432 * If any of the symbols in the Syms list is looked up then the Materialize
433 * function will be called.
434 *
435 * If any of the symbols in the Syms list is overridden then the Discard
436 * function will be called.
437 *
438 * The caller owns the underling MaterializationUnit and is responsible for
439 * either passing it to a JITDylib (via LLVMOrcJITDylibDefine) or disposing
440 * of it by calling LLVMOrcDisposeMaterializationUnit.
441 */
442LLVMOrcMaterializationUnitRef LLVMOrcCreateCustomMaterializationUnit(
443 const char *Name, void *Ctx, LLVMOrcCSymbolFlagsMapPairs Syms,
444 size_t NumSyms, LLVMOrcSymbolStringPoolEntryRef InitSym,
445 LLVMOrcMaterializationUnitMaterializeFunction Materialize,
446 LLVMOrcMaterializationUnitDiscardFunction Discard,
447 LLVMOrcMaterializationUnitDestroyFunction Destroy);
448
449/**
450 * Create a MaterializationUnit to define the given symbols as pointing to
451 * the corresponding raw addresses.
452 *
453 * This function takes ownership of the elements of the Syms array. The Name
454 * fields of the array elements are taken to have been retained for this
455 * function. This allows the following pattern...
456 *
457 * size_t NumPairs;
458 * LLVMOrcCSymbolMapPairs Sym;
459 * -- Build Syms array --
460 * LLVMOrcMaterializationUnitRef MU =
461 * LLVMOrcAbsoluteSymbols(Syms, NumPairs);
462 *
463 * ... without requiring cleanup of the elements of the Sym array afterwards.
464 *
465 * The client is still responsible for deleting the Sym array itself.
466 *
467 * If a client wishes to reuse elements of the Sym array after this call they
468 * must explicitly retain each of the elements for themselves.
469 */
470LLVMOrcMaterializationUnitRef
471LLVMOrcAbsoluteSymbols(LLVMOrcCSymbolMapPairs Syms, size_t NumPairs);
472
473/**
474 * Create a "bare" JITDylib.
475 *
476 * The client is responsible for ensuring that the JITDylib's name is unique,
477 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
478 *
479 * This call does not install any library code or symbols into the newly
480 * created JITDylib. The client is responsible for all configuration.
481 */
482LLVMOrcJITDylibRef
483LLVMOrcExecutionSessionCreateBareJITDylib(LLVMOrcExecutionSessionRef ES,
484 const char *Name);
485
486/**
487 * Create a JITDylib.
488 *
489 * The client is responsible for ensuring that the JITDylib's name is unique,
490 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
491 *
492 * If a Platform is attached to the ExecutionSession then
493 * Platform::setupJITDylib will be called to install standard platform symbols
494 * (e.g. standard library interposes). If no Platform is installed then this
495 * call is equivalent to LLVMExecutionSessionRefCreateBareJITDylib and will
496 * always return success.
497 */
498LLVMErrorRef
499LLVMOrcExecutionSessionCreateJITDylib(LLVMOrcExecutionSessionRef ES,
500 LLVMOrcJITDylibRef *Result,
501 const char *Name);
502
503/**
504 * Returns the JITDylib with the given name, or NULL if no such JITDylib
505 * exists.
506 */
507LLVMOrcJITDylibRef
508LLVMOrcExecutionSessionGetJITDylibByName(LLVMOrcExecutionSessionRef ES,
509 const char *Name);
510
511/**
512 * Return a reference to a newly created resource tracker associated with JD.
513 * The tracker is returned with an initial ref-count of 1, and must be released
514 * with LLVMOrcReleaseResourceTracker when no longer needed.
515 */
516LLVMOrcResourceTrackerRef
517LLVMOrcJITDylibCreateResourceTracker(LLVMOrcJITDylibRef JD);
518
519/**
520 * Return a reference to the default resource tracker for the given JITDylib.
521 * This operation will increase the retain count of the tracker: Clients should
522 * call LLVMOrcReleaseResourceTracker when the result is no longer needed.
523 */
524LLVMOrcResourceTrackerRef
525LLVMOrcJITDylibGetDefaultResourceTracker(LLVMOrcJITDylibRef JD);
526
527/**
528 * Add the given MaterializationUnit to the given JITDylib.
529 *
530 * If this operation succeeds then JITDylib JD will take ownership of MU.
531 * If the operation fails then ownership remains with the caller who should
532 * call LLVMOrcDisposeMaterializationUnit to destroy it.
533 */
534LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD,
535 LLVMOrcMaterializationUnitRef MU);
536
537/**
538 * Calls remove on all trackers associated with this JITDylib, see
539 * JITDylib::clear().
540 */
541LLVMErrorRef LLVMOrcJITDylibClear(LLVMOrcJITDylibRef JD);
542
543/**
544 * Add a DefinitionGenerator to the given JITDylib.
545 *
546 * The JITDylib will take ownership of the given generator: The client is no
547 * longer responsible for managing its memory.
548 */
549void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD,
550 LLVMOrcDefinitionGeneratorRef DG);
551
552/**
553 * Create a custom generator.
554 */
555LLVMOrcDefinitionGeneratorRef LLVMOrcCreateCustomCAPIDefinitionGenerator(
556 LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction F, void *Ctx);
557
558/**
559 * Get a DynamicLibrarySearchGenerator that will reflect process symbols into
560 * the JITDylib. On success the resulting generator is owned by the client.
561 * Ownership is typically transferred by adding the instance to a JITDylib
562 * using LLVMOrcJITDylibAddGenerator,
563 *
564 * The GlobalPrefix argument specifies the character that appears on the front
565 * of linker-mangled symbols for the target platform (e.g. '_' on MachO).
566 * If non-null, this character will be stripped from the start of all symbol
567 * strings before passing the remaining substring to dlsym.
568 *
569 * The optional Filter and Ctx arguments can be used to supply a symbol name
570 * filter: Only symbols for which the filter returns true will be visible to
571 * JIT'd code. If the Filter argument is null then all process symbols will
572 * be visible to JIT'd code. Note that the symbol name passed to the Filter
573 * function is the full mangled symbol: The client is responsible for stripping
574 * the global prefix if present.
575 */
576LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess(
577 LLVMOrcDefinitionGeneratorRef *Result, char GlobalPrefx,
578 LLVMOrcSymbolPredicate Filter, void *FilterCtx);
579
580/**
581 * Create a ThreadSafeContext containing a new LLVMContext.
582 *
583 * Ownership of the underlying ThreadSafeContext data is shared: Clients
584 * can and should dispose of their ThreadSafeContext as soon as they no longer
585 * need to refer to it directly. Other references (e.g. from ThreadSafeModules)
586 * will keep the data alive as long as it is needed.
587 */
588LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void);
589
590/**
591 * Get a reference to the wrapped LLVMContext.
592 */
593LLVMContextRef
594LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx);
595
596/**
597 * Dispose of a ThreadSafeContext.
598 */
599void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx);
600
601/**
602 * Create a ThreadSafeModule wrapper around the given LLVM module. This takes
603 * ownership of the M argument which should not be disposed of or referenced
604 * after this function returns.
605 *
606 * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT
607 * (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer
608 * responsible for it. If it is not transferred to the JIT then the client
609 * should call LLVMOrcDisposeThreadSafeModule to dispose of it.
610 */
611LLVMOrcThreadSafeModuleRef
612LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M,
613 LLVMOrcThreadSafeContextRef TSCtx);
614
615/**
616 * Dispose of a ThreadSafeModule. This should only be called if ownership has
617 * not been passed to LLJIT (e.g. because some error prevented the client from
618 * adding this to the JIT).
619 */
620void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM);
621
622/**
623 * Create a JITTargetMachineBuilder by detecting the host.
624 *
625 * On success the client owns the resulting JITTargetMachineBuilder. It must be
626 * passed to a consuming operation (e.g.
627 * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling
628 * LLVMOrcDisposeJITTargetMachineBuilder.
629 */
630LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost(
631 LLVMOrcJITTargetMachineBuilderRef *Result);
632
633/**
634 * Create a JITTargetMachineBuilder from the given TargetMachine template.
635 *
636 * This operation takes ownership of the given TargetMachine and destroys it
637 * before returing. The resulting JITTargetMachineBuilder is owned by the client
638 * and must be passed to a consuming operation (e.g.
639 * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling
640 * LLVMOrcDisposeJITTargetMachineBuilder.
641 */
642LLVMOrcJITTargetMachineBuilderRef
643LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM);
644
645/**
646 * Dispose of a JITTargetMachineBuilder.
647 */
648void LLVMOrcDisposeJITTargetMachineBuilder(
649 LLVMOrcJITTargetMachineBuilderRef JTMB);
650
651/**
652 * Returns the target triple for the given JITTargetMachineBuilder as a string.
653 *
654 * The caller owns the resulting string as must dispose of it by calling
655 * LLVMOrcJITTargetMachineBuilderDisposeTargetTriple.
656 */
657char *LLVMOrcJITTargetMachineBuilderGetTargetTriple(
658 LLVMOrcJITTargetMachineBuilderRef JTMB);
659
660/**
661 * Sets the target triple for the given JITTargetMachineBuilder to the given
662 * string.
663 */
664void LLVMOrcJITTargetMachineBuilderSetTargetTriple(
665 LLVMOrcJITTargetMachineBuilderRef JTMB, const char *TargetTriple);
666
667/**
668 * Destroy a triple string returned by
669 * LLVMOrcJITTargetMachineBuilderGetTargetTriple.
670 */
671void LLVMOrcJITTargetMachineBuilderDisposeTargetTriple(
672 LLVMOrcJITTargetMachineBuilderRef JTMB, char *TargetTriple);
673
674/**
675 * Add an object to an ObjectLayer to the given JITDylib.
676 *
677 * Adds a buffer representing an object file to the given JITDylib using the
678 * given ObjectLayer instance. This operation transfers ownership of the buffer
679 * to the ObjectLayer instance. The buffer should not be disposed of or
680 * referenced once this function returns.
681 *
682 * Resources associated with the given object will be tracked by the given
683 * JITDylib's default ResourceTracker.
684 */
685LLVMErrorRef LLVMOrcObjectLayerAddObjectFile(LLVMOrcObjectLayerRef ObjLayer,
686 LLVMOrcJITDylibRef JD,
687 LLVMMemoryBufferRef ObjBuffer);
688
689/**
690 * Add an object to an ObjectLayer using the given ResourceTracker.
691 *
692 * Adds a buffer representing an object file to the given ResourceTracker's
693 * JITDylib using the given ObjectLayer instance. This operation transfers
694 * ownership of the buffer to the ObjectLayer instance. The buffer should not
695 * be disposed of or referenced once this function returns.
696 *
697 * Resources associated with the given object will be tracked by
698 * ResourceTracker RT.
699 */
700LLVMErrorRef
701LLVMOrcObjectLayerAddObjectFileWithRT(LLVMOrcObjectLayerRef ObjLayer,
702 LLVMOrcResourceTrackerRef RT,
703 LLVMMemoryBufferRef ObjBuffer);
704
705/**
706 * Emit an object buffer to an ObjectLayer.
707 *
708 * Ownership of the responsibility object and object buffer pass to this
709 * function. The client is not responsible for cleanup.
710 */
711void LLVMOrcObjectLayerEmit(LLVMOrcObjectLayerRef ObjLayer,
712 LLVMOrcMaterializationResponsibilityRef R,
713 LLVMMemoryBufferRef ObjBuffer);
714
715/**
716 * Dispose of an ObjectLayer.
717 */
718void LLVMOrcDisposeObjectLayer(LLVMOrcObjectLayerRef ObjLayer);
719
720LLVM_C_EXTERN_C_END
721
722#endif /* LLVM_C_ORC_H */
723