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 * @defgroup LLVMCExecutionEngineORC On-Request-Compilation
38 * @ingroup LLVMCExecutionEngine
39 *
40 * @{
41 */
42
43/**
44 * Represents an address in the executor process.
45 */
46typedef uint64_t LLVMOrcJITTargetAddress;
47
48/**
49 * Represents an address in the executor process.
50 */
51typedef uint64_t LLVMOrcExecutorAddress;
52
53/**
54 * Represents generic linkage flags for a symbol definition.
55 */
56typedef enum {
57 LLVMJITSymbolGenericFlagsNone = 0,
58 LLVMJITSymbolGenericFlagsExported = 1U << 0,
59 LLVMJITSymbolGenericFlagsWeak = 1U << 1,
60 LLVMJITSymbolGenericFlagsCallable = 1U << 2,
61 LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly = 1U << 3
62} LLVMJITSymbolGenericFlags;
63
64/**
65 * Represents target specific flags for a symbol definition.
66 */
67typedef uint8_t LLVMJITSymbolTargetFlags;
68
69/**
70 * Represents the linkage flags for a symbol definition.
71 */
72typedef struct {
73 uint8_t GenericFlags;
74 uint8_t TargetFlags;
75} LLVMJITSymbolFlags;
76
77/**
78 * Represents an evaluated symbol address and flags.
79 */
80typedef struct {
81 LLVMOrcExecutorAddress Address;
82 LLVMJITSymbolFlags Flags;
83} LLVMJITEvaluatedSymbol;
84
85/**
86 * A reference to an orc::ExecutionSession instance.
87 */
88typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef;
89
90/**
91 * Error reporter function.
92 */
93typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err);
94
95/**
96 * A reference to an orc::SymbolStringPool.
97 */
98typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef;
99
100/**
101 * A reference to an orc::SymbolStringPool table entry.
102 */
103typedef struct LLVMOrcOpaqueSymbolStringPoolEntry
104 *LLVMOrcSymbolStringPoolEntryRef;
105
106/**
107 * Represents a pair of a symbol name and LLVMJITSymbolFlags.
108 */
109typedef struct {
110 LLVMOrcSymbolStringPoolEntryRef Name;
111 LLVMJITSymbolFlags Flags;
112} LLVMOrcCSymbolFlagsMapPair;
113
114/**
115 * Represents a list of (SymbolStringPtr, JITSymbolFlags) pairs that can be used
116 * to construct a SymbolFlagsMap.
117 */
118typedef LLVMOrcCSymbolFlagsMapPair *LLVMOrcCSymbolFlagsMapPairs;
119
120/**
121 * Represents a pair of a symbol name and an evaluated symbol.
122 */
123typedef struct {
124 LLVMOrcSymbolStringPoolEntryRef Name;
125 LLVMJITEvaluatedSymbol Sym;
126} LLVMOrcCSymbolMapPair;
127
128/**
129 * Represents a list of (SymbolStringPtr, JITEvaluatedSymbol) pairs that can be
130 * used to construct a SymbolMap.
131 */
132typedef LLVMOrcCSymbolMapPair *LLVMOrcCSymbolMapPairs;
133
134/**
135 * Represents a SymbolAliasMapEntry
136 */
137typedef struct {
138 LLVMOrcSymbolStringPoolEntryRef Name;
139 LLVMJITSymbolFlags Flags;
140} LLVMOrcCSymbolAliasMapEntry;
141
142/**
143 * Represents a pair of a symbol name and SymbolAliasMapEntry.
144 */
145typedef struct {
146 LLVMOrcSymbolStringPoolEntryRef Name;
147 LLVMOrcCSymbolAliasMapEntry Entry;
148} LLVMOrcCSymbolAliasMapPair;
149
150/**
151 * Represents a list of (SymbolStringPtr, (SymbolStringPtr, JITSymbolFlags))
152 * pairs that can be used to construct a SymbolFlagsMap.
153 */
154typedef LLVMOrcCSymbolAliasMapPair *LLVMOrcCSymbolAliasMapPairs;
155
156/**
157 * A reference to an orc::JITDylib instance.
158 */
159typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef;
160
161/**
162 * Represents a list of LLVMOrcSymbolStringPoolEntryRef and the associated
163 * length.
164 */
165typedef struct {
166 LLVMOrcSymbolStringPoolEntryRef *Symbols;
167 size_t Length;
168} LLVMOrcCSymbolsList;
169
170/**
171 * Represents a pair of a JITDylib and LLVMOrcCSymbolsList.
172 */
173typedef struct {
174 LLVMOrcJITDylibRef JD;
175 LLVMOrcCSymbolsList Names;
176} LLVMOrcCDependenceMapPair;
177
178/**
179 * Represents a list of (JITDylibRef, (LLVMOrcSymbolStringPoolEntryRef*,
180 * size_t)) pairs that can be used to construct a SymbolDependenceMap.
181 */
182typedef LLVMOrcCDependenceMapPair *LLVMOrcCDependenceMapPairs;
183
184/**
185 * A set of symbols that share dependencies.
186 */
187typedef struct {
188 LLVMOrcCSymbolsList Symbols;
189 LLVMOrcCDependenceMapPairs Dependencies;
190 size_t NumDependencies;
191} LLVMOrcCSymbolDependenceGroup;
192
193/**
194 * Lookup kind. This can be used by definition generators when deciding whether
195 * to produce a definition for a requested symbol.
196 *
197 * This enum should be kept in sync with llvm::orc::LookupKind.
198 */
199typedef enum {
200 LLVMOrcLookupKindStatic,
201 LLVMOrcLookupKindDLSym
202} LLVMOrcLookupKind;
203
204/**
205 * JITDylib lookup flags. This can be used by definition generators when
206 * deciding whether to produce a definition for a requested symbol.
207 *
208 * This enum should be kept in sync with llvm::orc::JITDylibLookupFlags.
209 */
210typedef enum {
211 LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly,
212 LLVMOrcJITDylibLookupFlagsMatchAllSymbols
213} LLVMOrcJITDylibLookupFlags;
214
215/**
216 * An element type for a JITDylib search order.
217 */
218typedef struct {
219 LLVMOrcJITDylibRef JD;
220 LLVMOrcJITDylibLookupFlags JDLookupFlags;
221} LLVMOrcCJITDylibSearchOrderElement;
222
223/**
224 * A JITDylib search order.
225 *
226 * The list is terminated with an element containing a null pointer for the JD
227 * field.
228 */
229typedef LLVMOrcCJITDylibSearchOrderElement *LLVMOrcCJITDylibSearchOrder;
230
231/**
232 * Symbol lookup flags for lookup sets. This should be kept in sync with
233 * llvm::orc::SymbolLookupFlags.
234 */
235typedef enum {
236 LLVMOrcSymbolLookupFlagsRequiredSymbol,
237 LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol
238} LLVMOrcSymbolLookupFlags;
239
240/**
241 * An element type for a symbol lookup set.
242 */
243typedef struct {
244 LLVMOrcSymbolStringPoolEntryRef Name;
245 LLVMOrcSymbolLookupFlags LookupFlags;
246} LLVMOrcCLookupSetElement;
247
248/**
249 * A set of symbols to look up / generate.
250 *
251 * The list is terminated with an element containing a null pointer for the
252 * Name field.
253 *
254 * If a client creates an instance of this type then they are responsible for
255 * freeing it, and for ensuring that all strings have been retained over the
256 * course of its life. Clients receiving a copy from a callback are not
257 * responsible for managing lifetime or retain counts.
258 */
259typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet;
260
261/**
262 * A reference to a uniquely owned orc::MaterializationUnit instance.
263 */
264typedef struct LLVMOrcOpaqueMaterializationUnit *LLVMOrcMaterializationUnitRef;
265
266/**
267 * A reference to a uniquely owned orc::MaterializationResponsibility instance.
268 *
269 * Ownership must be passed to a lower-level layer in a JIT stack.
270 */
271typedef struct LLVMOrcOpaqueMaterializationResponsibility
272 *LLVMOrcMaterializationResponsibilityRef;
273
274/**
275 * A MaterializationUnit materialize callback.
276 *
277 * Ownership of the Ctx and MR arguments passes to the callback which must
278 * adhere to the LLVMOrcMaterializationResponsibilityRef contract (see comment
279 * for that type).
280 *
281 * If this callback is called then the LLVMOrcMaterializationUnitDestroy
282 * callback will NOT be called.
283 */
284typedef void (*LLVMOrcMaterializationUnitMaterializeFunction)(
285 void *Ctx, LLVMOrcMaterializationResponsibilityRef MR);
286
287/**
288 * A MaterializationUnit discard callback.
289 *
290 * Ownership of JD and Symbol remain with the caller: These arguments should
291 * not be disposed of or released.
292 */
293typedef void (*LLVMOrcMaterializationUnitDiscardFunction)(
294 void *Ctx, LLVMOrcJITDylibRef JD, LLVMOrcSymbolStringPoolEntryRef Symbol);
295
296/**
297 * A MaterializationUnit destruction callback.
298 *
299 * If a custom MaterializationUnit is destroyed before its Materialize
300 * function is called then this function will be called to provide an
301 * opportunity for the underlying program representation to be destroyed.
302 */
303typedef void (*LLVMOrcMaterializationUnitDestroyFunction)(void *Ctx);
304
305/**
306 * A reference to an orc::ResourceTracker instance.
307 */
308typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef;
309
310/**
311 * A reference to an orc::DefinitionGenerator.
312 */
313typedef struct LLVMOrcOpaqueDefinitionGenerator
314 *LLVMOrcDefinitionGeneratorRef;
315
316/**
317 * An opaque lookup state object. Instances of this type can be captured to
318 * suspend a lookup while a custom generator function attempts to produce a
319 * definition.
320 *
321 * If a client captures a lookup state object then they must eventually call
322 * LLVMOrcLookupStateContinueLookup to restart the lookup. This is required
323 * in order to release memory allocated for the lookup state, even if errors
324 * have occurred while the lookup was suspended (if these errors have made the
325 * lookup impossible to complete then it will issue its own error before
326 * destruction).
327 */
328typedef struct LLVMOrcOpaqueLookupState *LLVMOrcLookupStateRef;
329
330/**
331 * A custom generator function. This can be used to create a custom generator
332 * object using LLVMOrcCreateCustomCAPIDefinitionGenerator. The resulting
333 * object can be attached to a JITDylib, via LLVMOrcJITDylibAddGenerator, to
334 * receive callbacks when lookups fail to match existing definitions.
335 *
336 * GeneratorObj will contain the address of the custom generator object.
337 *
338 * Ctx will contain the context object passed to
339 * LLVMOrcCreateCustomCAPIDefinitionGenerator.
340 *
341 * LookupState will contain a pointer to an LLVMOrcLookupStateRef object. This
342 * can optionally be modified to make the definition generation process
343 * asynchronous: If the LookupStateRef value is copied, and the original
344 * LLVMOrcLookupStateRef set to null, the lookup will be suspended. Once the
345 * asynchronous definition process has been completed clients must call
346 * LLVMOrcLookupStateContinueLookup to continue the lookup (this should be
347 * done unconditionally, even if errors have occurred in the mean time, to
348 * free the lookup state memory and notify the query object of the failures).
349 * If LookupState is captured this function must return LLVMErrorSuccess.
350 *
351 * The Kind argument can be inspected to determine the lookup kind (e.g.
352 * as-if-during-static-link, or as-if-during-dlsym).
353 *
354 * The JD argument specifies which JITDylib the definitions should be generated
355 * into.
356 *
357 * The JDLookupFlags argument can be inspected to determine whether the original
358 * lookup included non-exported symbols.
359 *
360 * Finally, the LookupSet argument contains the set of symbols that could not
361 * be found in JD already (the set of generation candidates).
362 */
363typedef LLVMErrorRef (*LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction)(
364 LLVMOrcDefinitionGeneratorRef GeneratorObj, void *Ctx,
365 LLVMOrcLookupStateRef *LookupState, LLVMOrcLookupKind Kind,
366 LLVMOrcJITDylibRef JD, LLVMOrcJITDylibLookupFlags JDLookupFlags,
367 LLVMOrcCLookupSet LookupSet, size_t LookupSetSize);
368
369/**
370 * Disposer for a custom generator.
371 *
372 * Will be called by ORC when the JITDylib that the generator is attached to
373 * is destroyed.
374 */
375typedef void (*LLVMOrcDisposeCAPIDefinitionGeneratorFunction)(void *Ctx);
376
377/**
378 * Predicate function for SymbolStringPoolEntries.
379 */
380typedef int (*LLVMOrcSymbolPredicate)(void *Ctx,
381 LLVMOrcSymbolStringPoolEntryRef Sym);
382
383/**
384 * A reference to an orc::ThreadSafeContext instance.
385 */
386typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef;
387
388/**
389 * A reference to an orc::ThreadSafeModule instance.
390 */
391typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef;
392
393/**
394 * A function for inspecting/mutating IR modules, suitable for use with
395 * LLVMOrcThreadSafeModuleWithModuleDo.
396 */
397typedef LLVMErrorRef (*LLVMOrcGenericIRModuleOperationFunction)(
398 void *Ctx, LLVMModuleRef M);
399
400/**
401 * A reference to an orc::JITTargetMachineBuilder instance.
402 */
403typedef struct LLVMOrcOpaqueJITTargetMachineBuilder
404 *LLVMOrcJITTargetMachineBuilderRef;
405
406/**
407 * A reference to an orc::ObjectLayer instance.
408 */
409typedef struct LLVMOrcOpaqueObjectLayer *LLVMOrcObjectLayerRef;
410
411/**
412 * A reference to an orc::ObjectLinkingLayer instance.
413 */
414typedef struct LLVMOrcOpaqueObjectLinkingLayer *LLVMOrcObjectLinkingLayerRef;
415
416/**
417 * A reference to an orc::IRTransformLayer instance.
418 */
419typedef struct LLVMOrcOpaqueIRTransformLayer *LLVMOrcIRTransformLayerRef;
420
421/**
422 * A function for applying transformations as part of an transform layer.
423 *
424 * Implementations of this type are responsible for managing the lifetime
425 * of the Module pointed to by ModInOut: If the LLVMModuleRef value is
426 * overwritten then the function is responsible for disposing of the incoming
427 * module. If the module is simply accessed/mutated in-place then ownership
428 * returns to the caller and the function does not need to do any lifetime
429 * management.
430 *
431 * Clients can call LLVMOrcLLJITGetIRTransformLayer to obtain the transform
432 * layer of a LLJIT instance, and use LLVMOrcIRTransformLayerSetTransform
433 * to set the function. This can be used to override the default transform
434 * layer.
435 */
436typedef LLVMErrorRef (*LLVMOrcIRTransformLayerTransformFunction)(
437 void *Ctx, LLVMOrcThreadSafeModuleRef *ModInOut,
438 LLVMOrcMaterializationResponsibilityRef MR);
439
440/**
441 * A reference to an orc::ObjectTransformLayer instance.
442 */
443typedef struct LLVMOrcOpaqueObjectTransformLayer
444 *LLVMOrcObjectTransformLayerRef;
445
446/**
447 * A function for applying transformations to an object file buffer.
448 *
449 * Implementations of this type are responsible for managing the lifetime
450 * of the memory buffer pointed to by ObjInOut: If the LLVMMemoryBufferRef
451 * value is overwritten then the function is responsible for disposing of the
452 * incoming buffer. If the buffer is simply accessed/mutated in-place then
453 * ownership returns to the caller and the function does not need to do any
454 * lifetime management.
455 *
456 * The transform is allowed to return an error, in which case the ObjInOut
457 * buffer should be disposed of and set to null.
458 */
459typedef LLVMErrorRef (*LLVMOrcObjectTransformLayerTransformFunction)(
460 void *Ctx, LLVMMemoryBufferRef *ObjInOut);
461
462/**
463 * A reference to an orc::IndirectStubsManager instance.
464 */
465typedef struct LLVMOrcOpaqueIndirectStubsManager
466 *LLVMOrcIndirectStubsManagerRef;
467
468/**
469 * A reference to an orc::LazyCallThroughManager instance.
470 */
471typedef struct LLVMOrcOpaqueLazyCallThroughManager
472 *LLVMOrcLazyCallThroughManagerRef;
473
474/**
475 * A reference to an orc::DumpObjects object.
476 *
477 * Can be used to dump object files to disk with unique names. Useful as an
478 * ObjectTransformLayer transform.
479 */
480typedef struct LLVMOrcOpaqueDumpObjects *LLVMOrcDumpObjectsRef;
481
482/**
483 * Attach a custom error reporter function to the ExecutionSession.
484 *
485 * The error reporter will be called to deliver failure notices that can not be
486 * directly reported to a caller. For example, failure to resolve symbols in
487 * the JIT linker is typically reported via the error reporter (callers
488 * requesting definitions from the JIT will typically be delivered a
489 * FailureToMaterialize error instead).
490 */
491void LLVMOrcExecutionSessionSetErrorReporter(
492 LLVMOrcExecutionSessionRef ES, LLVMOrcErrorReporterFunction ReportError,
493 void *Ctx);
494
495/**
496 * Return a reference to the SymbolStringPool for an ExecutionSession.
497 *
498 * Ownership of the pool remains with the ExecutionSession: The caller is
499 * not required to free the pool.
500 */
501LLVMOrcSymbolStringPoolRef
502LLVMOrcExecutionSessionGetSymbolStringPool(LLVMOrcExecutionSessionRef ES);
503
504/**
505 * Clear all unreferenced symbol string pool entries.
506 *
507 * This can be called at any time to release unused entries in the
508 * ExecutionSession's string pool. Since it locks the pool (preventing
509 * interning of any new strings) it is recommended that it only be called
510 * infrequently, ideally when the caller has reason to believe that some
511 * entries will have become unreferenced, e.g. after removing a module or
512 * closing a JITDylib.
513 */
514void LLVMOrcSymbolStringPoolClearDeadEntries(LLVMOrcSymbolStringPoolRef SSP);
515
516/**
517 * Intern a string in the ExecutionSession's SymbolStringPool and return a
518 * reference to it. This increments the ref-count of the pool entry, and the
519 * returned value should be released once the client is done with it by
520 * calling LLVMOrcReleaseSymbolStringPoolEntry.
521 *
522 * Since strings are uniqued within the SymbolStringPool
523 * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string
524 * equality.
525 *
526 * Note that this function does not perform linker-mangling on the string.
527 */
528LLVMOrcSymbolStringPoolEntryRef
529LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name);
530
531/**
532 * Callback type for ExecutionSession lookups.
533 *
534 * If Err is LLVMErrorSuccess then Result will contain a pointer to a
535 * list of ( SymbolStringPtr, JITEvaluatedSymbol ) pairs of length NumPairs.
536 *
537 * If Err is a failure value then Result and Ctx are undefined and should
538 * not be accessed. The Callback is responsible for handling the error
539 * value (e.g. by calling LLVMGetErrorMessage + LLVMDisposeErrorMessage).
540 *
541 * The caller retains ownership of the Result array and will release all
542 * contained symbol names. Clients are responsible for retaining any symbol
543 * names that they wish to hold after the function returns.
544 */
545typedef void (*LLVMOrcExecutionSessionLookupHandleResultFunction)(
546 LLVMErrorRef Err, LLVMOrcCSymbolMapPairs Result, size_t NumPairs,
547 void *Ctx);
548
549/**
550 * Look up symbols in an execution session.
551 *
552 * This is a wrapper around the general ExecutionSession::lookup function.
553 *
554 * The SearchOrder argument contains a list of (JITDylibs, JITDylibSearchFlags)
555 * pairs that describe the search order. The JITDylibs will be searched in the
556 * given order to try to find the symbols in the Symbols argument.
557 *
558 * The Symbols argument should contain a null-terminated array of
559 * (SymbolStringPtr, SymbolLookupFlags) pairs describing the symbols to be
560 * searched for. This function takes ownership of the elements of the Symbols
561 * array. The Name fields of the Symbols elements are taken to have been
562 * retained by the client for this function. The client should *not* release the
563 * Name fields, but are still responsible for destroying the array itself.
564 *
565 * The HandleResult function will be called once all searched for symbols have
566 * been found, or an error occurs. The HandleResult function will be passed an
567 * LLVMErrorRef indicating success or failure, and (on success) a
568 * null-terminated LLVMOrcCSymbolMapPairs array containing the function result,
569 * and the Ctx value passed to the lookup function.
570 *
571 * The client is fully responsible for managing the lifetime of the Ctx object.
572 * A common idiom is to allocate the context prior to the lookup and deallocate
573 * it in the handler.
574 *
575 * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE!
576 */
577void LLVMOrcExecutionSessionLookup(
578 LLVMOrcExecutionSessionRef ES, LLVMOrcLookupKind K,
579 LLVMOrcCJITDylibSearchOrder SearchOrder, size_t SearchOrderSize,
580 LLVMOrcCLookupSet Symbols, size_t SymbolsSize,
581 LLVMOrcExecutionSessionLookupHandleResultFunction HandleResult, void *Ctx);
582
583/**
584 * Increments the ref-count for a SymbolStringPool entry.
585 */
586void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
587
588/**
589 * Reduces the ref-count for of a SymbolStringPool entry.
590 */
591void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
592
593/**
594 * Return the c-string for the given symbol. This string will remain valid until
595 * the entry is freed (once all LLVMOrcSymbolStringPoolEntryRefs have been
596 * released).
597 */
598const char *LLVMOrcSymbolStringPoolEntryStr(LLVMOrcSymbolStringPoolEntryRef S);
599
600/**
601 * Reduces the ref-count of a ResourceTracker.
602 */
603void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT);
604
605/**
606 * Transfers tracking of all resources associated with resource tracker SrcRT
607 * to resource tracker DstRT.
608 */
609void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT,
610 LLVMOrcResourceTrackerRef DstRT);
611
612/**
613 * Remove all resources associated with the given tracker. See
614 * ResourceTracker::remove().
615 */
616LLVMErrorRef LLVMOrcResourceTrackerRemove(LLVMOrcResourceTrackerRef RT);
617
618/**
619 * Dispose of a JITDylib::DefinitionGenerator. This should only be called if
620 * ownership has not been passed to a JITDylib (e.g. because some error
621 * prevented the client from calling LLVMOrcJITDylibAddGenerator).
622 */
623void LLVMOrcDisposeDefinitionGenerator(LLVMOrcDefinitionGeneratorRef DG);
624
625/**
626 * Dispose of a MaterializationUnit.
627 */
628void LLVMOrcDisposeMaterializationUnit(LLVMOrcMaterializationUnitRef MU);
629
630/**
631 * Create a custom MaterializationUnit.
632 *
633 * Name is a name for this MaterializationUnit to be used for identification
634 * and logging purposes (e.g. if this MaterializationUnit produces an
635 * object buffer then the name of that buffer will be derived from this name).
636 *
637 * The Syms list contains the names and linkages of the symbols provided by this
638 * unit. This function takes ownership of the elements of the Syms array. The
639 * Name fields of the array elements are taken to have been retained for this
640 * function. The client should *not* release the elements of the array, but is
641 * still responsible for destroying the array itself.
642 *
643 * The InitSym argument indicates whether or not this MaterializationUnit
644 * contains static initializers. If three are no static initializers (the common
645 * case) then this argument should be null. If there are static initializers
646 * then InitSym should be set to a unique name that also appears in the Syms
647 * list with the LLVMJITSymbolGenericFlagsMaterializationSideEffectsOnly flag
648 * set. This function takes ownership of the InitSym, which should have been
649 * retained twice on behalf of this function: once for the Syms entry and once
650 * for InitSym. If clients wish to use the InitSym value after this function
651 * returns they must retain it once more for themselves.
652 *
653 * If any of the symbols in the Syms list is looked up then the Materialize
654 * function will be called.
655 *
656 * If any of the symbols in the Syms list is overridden then the Discard
657 * function will be called.
658 *
659 * The caller owns the underling MaterializationUnit and is responsible for
660 * either passing it to a JITDylib (via LLVMOrcJITDylibDefine) or disposing
661 * of it by calling LLVMOrcDisposeMaterializationUnit.
662 */
663LLVMOrcMaterializationUnitRef LLVMOrcCreateCustomMaterializationUnit(
664 const char *Name, void *Ctx, LLVMOrcCSymbolFlagsMapPairs Syms,
665 size_t NumSyms, LLVMOrcSymbolStringPoolEntryRef InitSym,
666 LLVMOrcMaterializationUnitMaterializeFunction Materialize,
667 LLVMOrcMaterializationUnitDiscardFunction Discard,
668 LLVMOrcMaterializationUnitDestroyFunction Destroy);
669
670/**
671 * Create a MaterializationUnit to define the given symbols as pointing to
672 * the corresponding raw addresses.
673 *
674 * This function takes ownership of the elements of the Syms array. The Name
675 * fields of the array elements are taken to have been retained for this
676 * function. This allows the following pattern...
677 *
678 * size_t NumPairs;
679 * LLVMOrcCSymbolMapPairs Sym;
680 * -- Build Syms array --
681 * LLVMOrcMaterializationUnitRef MU =
682 * LLVMOrcAbsoluteSymbols(Syms, NumPairs);
683 *
684 * ... without requiring cleanup of the elements of the Sym array afterwards.
685 *
686 * The client is still responsible for deleting the Sym array itself.
687 *
688 * If a client wishes to reuse elements of the Sym array after this call they
689 * must explicitly retain each of the elements for themselves.
690 */
691LLVMOrcMaterializationUnitRef
692LLVMOrcAbsoluteSymbols(LLVMOrcCSymbolMapPairs Syms, size_t NumPairs);
693
694/**
695 * Create a MaterializationUnit to define lazy re-expots. These are callable
696 * entry points that call through to the given symbols.
697 *
698 * This function takes ownership of the CallableAliases array. The Name
699 * fields of the array elements are taken to have been retained for this
700 * function. This allows the following pattern...
701 *
702 * size_t NumPairs;
703 * LLVMOrcCSymbolAliasMapPairs CallableAliases;
704 * -- Build CallableAliases array --
705 * LLVMOrcMaterializationUnitRef MU =
706 * LLVMOrcLazyReexports(LCTM, ISM, JD, CallableAliases, NumPairs);
707 *
708 * ... without requiring cleanup of the elements of the CallableAliases array afterwards.
709 *
710 * The client is still responsible for deleting the CallableAliases array itself.
711 *
712 * If a client wishes to reuse elements of the CallableAliases array after this call they
713 * must explicitly retain each of the elements for themselves.
714 */
715LLVMOrcMaterializationUnitRef LLVMOrcLazyReexports(
716 LLVMOrcLazyCallThroughManagerRef LCTM, LLVMOrcIndirectStubsManagerRef ISM,
717 LLVMOrcJITDylibRef SourceRef, LLVMOrcCSymbolAliasMapPairs CallableAliases,
718 size_t NumPairs);
719// TODO: ImplSymbolMad SrcJDLoc
720
721/**
722 * Disposes of the passed MaterializationResponsibility object.
723 *
724 * This should only be done after the symbols covered by the object have either
725 * been resolved and emitted (via
726 * LLVMOrcMaterializationResponsibilityNotifyResolved and
727 * LLVMOrcMaterializationResponsibilityNotifyEmitted) or failed (via
728 * LLVMOrcMaterializationResponsibilityFailMaterialization).
729 */
730void LLVMOrcDisposeMaterializationResponsibility(
731 LLVMOrcMaterializationResponsibilityRef MR);
732
733/**
734 * Returns the target JITDylib that these symbols are being materialized into.
735 */
736LLVMOrcJITDylibRef LLVMOrcMaterializationResponsibilityGetTargetDylib(
737 LLVMOrcMaterializationResponsibilityRef MR);
738
739/**
740 * Returns the ExecutionSession for this MaterializationResponsibility.
741 */
742LLVMOrcExecutionSessionRef
743LLVMOrcMaterializationResponsibilityGetExecutionSession(
744 LLVMOrcMaterializationResponsibilityRef MR);
745
746/**
747 * Returns the symbol flags map for this responsibility instance.
748 *
749 * The length of the array is returned in NumPairs and the caller is responsible
750 * for the returned memory and needs to call LLVMOrcDisposeCSymbolFlagsMap.
751 *
752 * To use the returned symbols beyond the livetime of the
753 * MaterializationResponsibility requires the caller to retain the symbols
754 * explicitly.
755 */
756LLVMOrcCSymbolFlagsMapPairs LLVMOrcMaterializationResponsibilityGetSymbols(
757 LLVMOrcMaterializationResponsibilityRef MR, size_t *NumPairs);
758
759/**
760 * Disposes of the passed LLVMOrcCSymbolFlagsMap.
761 *
762 * Does not release the entries themselves.
763 */
764void LLVMOrcDisposeCSymbolFlagsMap(LLVMOrcCSymbolFlagsMapPairs Pairs);
765
766/**
767 * Returns the initialization pseudo-symbol, if any. This symbol will also
768 * be present in the SymbolFlagsMap for this MaterializationResponsibility
769 * object.
770 *
771 * The returned symbol is not retained over any mutating operation of the
772 * MaterializationResponsbility or beyond the lifetime thereof.
773 */
774LLVMOrcSymbolStringPoolEntryRef
775LLVMOrcMaterializationResponsibilityGetInitializerSymbol(
776 LLVMOrcMaterializationResponsibilityRef MR);
777
778/**
779 * Returns the names of any symbols covered by this
780 * MaterializationResponsibility object that have queries pending. This
781 * information can be used to return responsibility for unrequested symbols
782 * back to the JITDylib via the delegate method.
783 */
784LLVMOrcSymbolStringPoolEntryRef *
785LLVMOrcMaterializationResponsibilityGetRequestedSymbols(
786 LLVMOrcMaterializationResponsibilityRef MR, size_t *NumSymbols);
787
788/**
789 * Disposes of the passed LLVMOrcSymbolStringPoolEntryRef* .
790 *
791 * Does not release the symbols themselves.
792 */
793void LLVMOrcDisposeSymbols(LLVMOrcSymbolStringPoolEntryRef *Symbols);
794
795/**
796 * Notifies the target JITDylib that the given symbols have been resolved.
797 * This will update the given symbols' addresses in the JITDylib, and notify
798 * any pending queries on the given symbols of their resolution. The given
799 * symbols must be ones covered by this MaterializationResponsibility
800 * instance. Individual calls to this method may resolve a subset of the
801 * symbols, but all symbols must have been resolved prior to calling emit.
802 *
803 * This method will return an error if any symbols being resolved have been
804 * moved to the error state due to the failure of a dependency. If this
805 * method returns an error then clients should log it and call
806 * LLVMOrcMaterializationResponsibilityFailMaterialization. If no dependencies
807 * have been registered for the symbols covered by this
808 * MaterializationResponsibility then this method is guaranteed to return
809 * LLVMErrorSuccess.
810 */
811LLVMErrorRef LLVMOrcMaterializationResponsibilityNotifyResolved(
812 LLVMOrcMaterializationResponsibilityRef MR, LLVMOrcCSymbolMapPairs Symbols,
813 size_t NumPairs);
814
815/**
816 * Notifies the target JITDylib (and any pending queries on that JITDylib)
817 * that all symbols covered by this MaterializationResponsibility instance
818 * have been emitted.
819 *
820 * This function takes ownership of the symbols in the Dependencies struct.
821 * This allows the following pattern...
822 *
823 * LLVMOrcSymbolStringPoolEntryRef Names[] = {...};
824 * LLVMOrcCDependenceMapPair Dependence = {JD, {Names, sizeof(Names)}}
825 * LLVMOrcMaterializationResponsibilityAddDependencies(JD, Name, &Dependence,
826 * 1);
827 *
828 * ... without requiring cleanup of the elements of the Names array afterwards.
829 *
830 * The client is still responsible for deleting the Dependencies.Names arrays,
831 * and the Dependencies array itself.
832 *
833 * This method will return an error if any symbols being resolved have been
834 * moved to the error state due to the failure of a dependency. If this
835 * method returns an error then clients should log it and call
836 * LLVMOrcMaterializationResponsibilityFailMaterialization.
837 * If no dependencies have been registered for the symbols covered by this
838 * MaterializationResponsibility then this method is guaranteed to return
839 * LLVMErrorSuccess.
840 */
841LLVMErrorRef LLVMOrcMaterializationResponsibilityNotifyEmitted(
842 LLVMOrcMaterializationResponsibilityRef MR,
843 LLVMOrcCSymbolDependenceGroup *SymbolDepGroups, size_t NumSymbolDepGroups);
844
845/**
846 * Attempt to claim responsibility for new definitions. This method can be
847 * used to claim responsibility for symbols that are added to a
848 * materialization unit during the compilation process (e.g. literal pool
849 * symbols). Symbol linkage rules are the same as for symbols that are
850 * defined up front: duplicate strong definitions will result in errors.
851 * Duplicate weak definitions will be discarded (in which case they will
852 * not be added to this responsibility instance).
853 *
854 * This method can be used by materialization units that want to add
855 * additional symbols at materialization time (e.g. stubs, compile
856 * callbacks, metadata)
857 */
858LLVMErrorRef LLVMOrcMaterializationResponsibilityDefineMaterializing(
859 LLVMOrcMaterializationResponsibilityRef MR,
860 LLVMOrcCSymbolFlagsMapPairs Pairs, size_t NumPairs);
861
862/**
863 * Notify all not-yet-emitted covered by this MaterializationResponsibility
864 * instance that an error has occurred.
865 * This will remove all symbols covered by this MaterializationResponsibility
866 * from the target JITDylib, and send an error to any queries waiting on
867 * these symbols.
868 */
869void LLVMOrcMaterializationResponsibilityFailMaterialization(
870 LLVMOrcMaterializationResponsibilityRef MR);
871
872/**
873 * Transfers responsibility to the given MaterializationUnit for all
874 * symbols defined by that MaterializationUnit. This allows
875 * materializers to break up work based on run-time information (e.g.
876 * by introspecting which symbols have actually been looked up and
877 * materializing only those).
878 */
879LLVMErrorRef LLVMOrcMaterializationResponsibilityReplace(
880 LLVMOrcMaterializationResponsibilityRef MR,
881 LLVMOrcMaterializationUnitRef MU);
882
883/**
884 * Delegates responsibility for the given symbols to the returned
885 * materialization responsibility. Useful for breaking up work between
886 * threads, or different kinds of materialization processes.
887 *
888 * The caller retains responsibility of the the passed
889 * MaterializationResponsibility.
890 */
891LLVMErrorRef LLVMOrcMaterializationResponsibilityDelegate(
892 LLVMOrcMaterializationResponsibilityRef MR,
893 LLVMOrcSymbolStringPoolEntryRef *Symbols, size_t NumSymbols,
894 LLVMOrcMaterializationResponsibilityRef *Result);
895
896/**
897 * Create a "bare" JITDylib.
898 *
899 * The client is responsible for ensuring that the JITDylib's name is unique,
900 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
901 *
902 * This call does not install any library code or symbols into the newly
903 * created JITDylib. The client is responsible for all configuration.
904 */
905LLVMOrcJITDylibRef
906LLVMOrcExecutionSessionCreateBareJITDylib(LLVMOrcExecutionSessionRef ES,
907 const char *Name);
908
909/**
910 * Create a JITDylib.
911 *
912 * The client is responsible for ensuring that the JITDylib's name is unique,
913 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
914 *
915 * If a Platform is attached to the ExecutionSession then
916 * Platform::setupJITDylib will be called to install standard platform symbols
917 * (e.g. standard library interposes). If no Platform is installed then this
918 * call is equivalent to LLVMExecutionSessionRefCreateBareJITDylib and will
919 * always return success.
920 */
921LLVMErrorRef
922LLVMOrcExecutionSessionCreateJITDylib(LLVMOrcExecutionSessionRef ES,
923 LLVMOrcJITDylibRef *Result,
924 const char *Name);
925
926/**
927 * Returns the JITDylib with the given name, or NULL if no such JITDylib
928 * exists.
929 */
930LLVMOrcJITDylibRef
931LLVMOrcExecutionSessionGetJITDylibByName(LLVMOrcExecutionSessionRef ES,
932 const char *Name);
933
934/**
935 * Return a reference to a newly created resource tracker associated with JD.
936 * The tracker is returned with an initial ref-count of 1, and must be released
937 * with LLVMOrcReleaseResourceTracker when no longer needed.
938 */
939LLVMOrcResourceTrackerRef
940LLVMOrcJITDylibCreateResourceTracker(LLVMOrcJITDylibRef JD);
941
942/**
943 * Return a reference to the default resource tracker for the given JITDylib.
944 * This operation will increase the retain count of the tracker: Clients should
945 * call LLVMOrcReleaseResourceTracker when the result is no longer needed.
946 */
947LLVMOrcResourceTrackerRef
948LLVMOrcJITDylibGetDefaultResourceTracker(LLVMOrcJITDylibRef JD);
949
950/**
951 * Add the given MaterializationUnit to the given JITDylib.
952 *
953 * If this operation succeeds then JITDylib JD will take ownership of MU.
954 * If the operation fails then ownership remains with the caller who should
955 * call LLVMOrcDisposeMaterializationUnit to destroy it.
956 */
957LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD,
958 LLVMOrcMaterializationUnitRef MU);
959
960/**
961 * Calls remove on all trackers associated with this JITDylib, see
962 * JITDylib::clear().
963 */
964LLVMErrorRef LLVMOrcJITDylibClear(LLVMOrcJITDylibRef JD);
965
966/**
967 * Add a DefinitionGenerator to the given JITDylib.
968 *
969 * The JITDylib will take ownership of the given generator: The client is no
970 * longer responsible for managing its memory.
971 */
972void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD,
973 LLVMOrcDefinitionGeneratorRef DG);
974
975/**
976 * Create a custom generator.
977 *
978 * The F argument will be used to implement the DefinitionGenerator's
979 * tryToGenerate method (see
980 * LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction).
981 *
982 * Ctx is a context object that will be passed to F. This argument is
983 * permitted to be null.
984 *
985 * Dispose is the disposal function for Ctx. This argument is permitted to be
986 * null (in which case the client is responsible for the lifetime of Ctx).
987 */
988LLVMOrcDefinitionGeneratorRef LLVMOrcCreateCustomCAPIDefinitionGenerator(
989 LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction F, void *Ctx,
990 LLVMOrcDisposeCAPIDefinitionGeneratorFunction Dispose);
991
992/**
993 * Continue a lookup that was suspended in a generator (see
994 * LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction).
995 */
996void LLVMOrcLookupStateContinueLookup(LLVMOrcLookupStateRef S,
997 LLVMErrorRef Err);
998
999/**
1000 * Get a DynamicLibrarySearchGenerator that will reflect process symbols into
1001 * the JITDylib. On success the resulting generator is owned by the client.
1002 * Ownership is typically transferred by adding the instance to a JITDylib
1003 * using LLVMOrcJITDylibAddGenerator,
1004 *
1005 * The GlobalPrefix argument specifies the character that appears on the front
1006 * of linker-mangled symbols for the target platform (e.g. '_' on MachO).
1007 * If non-null, this character will be stripped from the start of all symbol
1008 * strings before passing the remaining substring to dlsym.
1009 *
1010 * The optional Filter and Ctx arguments can be used to supply a symbol name
1011 * filter: Only symbols for which the filter returns true will be visible to
1012 * JIT'd code. If the Filter argument is null then all process symbols will
1013 * be visible to JIT'd code. Note that the symbol name passed to the Filter
1014 * function is the full mangled symbol: The client is responsible for stripping
1015 * the global prefix if present.
1016 */
1017LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess(
1018 LLVMOrcDefinitionGeneratorRef *Result, char GlobalPrefx,
1019 LLVMOrcSymbolPredicate Filter, void *FilterCtx);
1020
1021/**
1022 * Get a LLVMOrcCreateDynamicLibararySearchGeneratorForPath that will reflect
1023 * library symbols into the JITDylib. On success the resulting generator is
1024 * owned by the client. Ownership is typically transferred by adding the
1025 * instance to a JITDylib using LLVMOrcJITDylibAddGenerator,
1026 *
1027 * The GlobalPrefix argument specifies the character that appears on the front
1028 * of linker-mangled symbols for the target platform (e.g. '_' on MachO).
1029 * If non-null, this character will be stripped from the start of all symbol
1030 * strings before passing the remaining substring to dlsym.
1031 *
1032 * The optional Filter and Ctx arguments can be used to supply a symbol name
1033 * filter: Only symbols for which the filter returns true will be visible to
1034 * JIT'd code. If the Filter argument is null then all library symbols will
1035 * be visible to JIT'd code. Note that the symbol name passed to the Filter
1036 * function is the full mangled symbol: The client is responsible for stripping
1037 * the global prefix if present.
1038 *
1039 * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE!
1040 *
1041 */
1042LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForPath(
1043 LLVMOrcDefinitionGeneratorRef *Result, const char *FileName,
1044 char GlobalPrefix, LLVMOrcSymbolPredicate Filter, void *FilterCtx);
1045
1046/**
1047 * Get a LLVMOrcCreateStaticLibrarySearchGeneratorForPath that will reflect
1048 * static library symbols into the JITDylib. On success the resulting
1049 * generator is owned by the client. Ownership is typically transferred by
1050 * adding the instance to a JITDylib using LLVMOrcJITDylibAddGenerator,
1051 *
1052 * Call with the optional TargetTriple argument will succeed if the file at
1053 * the given path is a static library or a MachO universal binary containing a
1054 * static library that is compatible with the given triple. Otherwise it will
1055 * return an error.
1056 *
1057 * THIS API IS EXPERIMENTAL AND LIKELY TO CHANGE IN THE NEAR FUTURE!
1058 *
1059 */
1060LLVMErrorRef LLVMOrcCreateStaticLibrarySearchGeneratorForPath(
1061 LLVMOrcDefinitionGeneratorRef *Result, LLVMOrcObjectLayerRef ObjLayer,
1062 const char *FileName);
1063
1064/**
1065 * Create a ThreadSafeContextRef containing a new LLVMContext.
1066 *
1067 * Ownership of the underlying ThreadSafeContext data is shared: Clients
1068 * can and should dispose of their ThreadSafeContextRef as soon as they no
1069 * longer need to refer to it directly. Other references (e.g. from
1070 * ThreadSafeModules) will keep the underlying data alive as long as it is
1071 * needed.
1072 */
1073LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void);
1074
1075/**
1076 * Create a ThreadSafeContextRef from a given LLVMContext, which must not be
1077 * associated with any existing ThreadSafeContext.
1078 *
1079 * The underlying ThreadSafeContext will take ownership of the LLVMContext
1080 * object, so clients should not free the LLVMContext passed to this
1081 * function.
1082 *
1083 * Ownership of the underlying ThreadSafeContext data is shared: Clients
1084 * can and should dispose of their ThreadSafeContextRef as soon as they no
1085 * longer need to refer to it directly. Other references (e.g. from
1086 * ThreadSafeModules) will keep the underlying data alive as long as it is
1087 * needed.
1088 */
1089LLVMOrcThreadSafeContextRef
1090LLVMOrcCreateNewThreadSafeContextFromLLVMContext(LLVMContextRef Ctx);
1091
1092/**
1093 * Dispose of a ThreadSafeContext.
1094 */
1095void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx);
1096
1097/**
1098 * Create a ThreadSafeModule wrapper around the given LLVM module. This takes
1099 * ownership of the M argument which should not be disposed of or referenced
1100 * after this function returns.
1101 *
1102 * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT
1103 * (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer
1104 * responsible for it. If it is not transferred to the JIT then the client
1105 * should call LLVMOrcDisposeThreadSafeModule to dispose of it.
1106 */
1107LLVMOrcThreadSafeModuleRef
1108LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M,
1109 LLVMOrcThreadSafeContextRef TSCtx);
1110
1111/**
1112 * Dispose of a ThreadSafeModule. This should only be called if ownership has
1113 * not been passed to LLJIT (e.g. because some error prevented the client from
1114 * adding this to the JIT).
1115 */
1116void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM);
1117
1118/**
1119 * Apply the given function to the module contained in this ThreadSafeModule.
1120 */
1121LLVMErrorRef
1122LLVMOrcThreadSafeModuleWithModuleDo(LLVMOrcThreadSafeModuleRef TSM,
1123 LLVMOrcGenericIRModuleOperationFunction F,
1124 void *Ctx);
1125
1126/**
1127 * Create a JITTargetMachineBuilder by detecting the host.
1128 *
1129 * On success the client owns the resulting JITTargetMachineBuilder. It must be
1130 * passed to a consuming operation (e.g.
1131 * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling
1132 * LLVMOrcDisposeJITTargetMachineBuilder.
1133 */
1134LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost(
1135 LLVMOrcJITTargetMachineBuilderRef *Result);
1136
1137/**
1138 * Create a JITTargetMachineBuilder from the given TargetMachine template.
1139 *
1140 * This operation takes ownership of the given TargetMachine and destroys it
1141 * before returing. The resulting JITTargetMachineBuilder is owned by the client
1142 * and must be passed to a consuming operation (e.g.
1143 * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling
1144 * LLVMOrcDisposeJITTargetMachineBuilder.
1145 */
1146LLVMOrcJITTargetMachineBuilderRef
1147LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM);
1148
1149/**
1150 * Dispose of a JITTargetMachineBuilder.
1151 */
1152void LLVMOrcDisposeJITTargetMachineBuilder(
1153 LLVMOrcJITTargetMachineBuilderRef JTMB);
1154
1155/**
1156 * Returns the target triple for the given JITTargetMachineBuilder as a string.
1157 *
1158 * The caller owns the resulting string as must dispose of it by calling
1159 * LLVMDisposeMessage
1160 */
1161char *LLVMOrcJITTargetMachineBuilderGetTargetTriple(
1162 LLVMOrcJITTargetMachineBuilderRef JTMB);
1163
1164/**
1165 * Sets the target triple for the given JITTargetMachineBuilder to the given
1166 * string.
1167 */
1168void LLVMOrcJITTargetMachineBuilderSetTargetTriple(
1169 LLVMOrcJITTargetMachineBuilderRef JTMB, const char *TargetTriple);
1170
1171/**
1172 * Add an object to an ObjectLayer to the given JITDylib.
1173 *
1174 * Adds a buffer representing an object file to the given JITDylib using the
1175 * given ObjectLayer instance. This operation transfers ownership of the buffer
1176 * to the ObjectLayer instance. The buffer should not be disposed of or
1177 * referenced once this function returns.
1178 *
1179 * Resources associated with the given object will be tracked by the given
1180 * JITDylib's default ResourceTracker.
1181 */
1182LLVMErrorRef LLVMOrcObjectLayerAddObjectFile(LLVMOrcObjectLayerRef ObjLayer,
1183 LLVMOrcJITDylibRef JD,
1184 LLVMMemoryBufferRef ObjBuffer);
1185
1186/**
1187 * Add an object to an ObjectLayer using the given ResourceTracker.
1188 *
1189 * Adds a buffer representing an object file to the given ResourceTracker's
1190 * JITDylib using the given ObjectLayer instance. This operation transfers
1191 * ownership of the buffer to the ObjectLayer instance. The buffer should not
1192 * be disposed of or referenced once this function returns.
1193 *
1194 * Resources associated with the given object will be tracked by
1195 * ResourceTracker RT.
1196 */
1197LLVMErrorRef
1198LLVMOrcObjectLayerAddObjectFileWithRT(LLVMOrcObjectLayerRef ObjLayer,
1199 LLVMOrcResourceTrackerRef RT,
1200 LLVMMemoryBufferRef ObjBuffer);
1201
1202/**
1203 * Emit an object buffer to an ObjectLayer.
1204 *
1205 * Ownership of the responsibility object and object buffer pass to this
1206 * function. The client is not responsible for cleanup.
1207 */
1208void LLVMOrcObjectLayerEmit(LLVMOrcObjectLayerRef ObjLayer,
1209 LLVMOrcMaterializationResponsibilityRef R,
1210 LLVMMemoryBufferRef ObjBuffer);
1211
1212/**
1213 * Dispose of an ObjectLayer.
1214 */
1215void LLVMOrcDisposeObjectLayer(LLVMOrcObjectLayerRef ObjLayer);
1216
1217void LLVMOrcIRTransformLayerEmit(LLVMOrcIRTransformLayerRef IRTransformLayer,
1218 LLVMOrcMaterializationResponsibilityRef MR,
1219 LLVMOrcThreadSafeModuleRef TSM);
1220
1221/**
1222 * Set the transform function of the provided transform layer, passing through a
1223 * pointer to user provided context.
1224 */
1225void LLVMOrcIRTransformLayerSetTransform(
1226 LLVMOrcIRTransformLayerRef IRTransformLayer,
1227 LLVMOrcIRTransformLayerTransformFunction TransformFunction, void *Ctx);
1228
1229/**
1230 * Set the transform function on an LLVMOrcObjectTransformLayer.
1231 */
1232void LLVMOrcObjectTransformLayerSetTransform(
1233 LLVMOrcObjectTransformLayerRef ObjTransformLayer,
1234 LLVMOrcObjectTransformLayerTransformFunction TransformFunction, void *Ctx);
1235
1236/**
1237 * Create a LocalIndirectStubsManager from the given target triple.
1238 *
1239 * The resulting IndirectStubsManager is owned by the client
1240 * and must be disposed of by calling LLVMOrcDisposeDisposeIndirectStubsManager.
1241 */
1242LLVMOrcIndirectStubsManagerRef
1243LLVMOrcCreateLocalIndirectStubsManager(const char *TargetTriple);
1244
1245/**
1246 * Dispose of an IndirectStubsManager.
1247 */
1248void LLVMOrcDisposeIndirectStubsManager(LLVMOrcIndirectStubsManagerRef ISM);
1249
1250LLVMErrorRef LLVMOrcCreateLocalLazyCallThroughManager(
1251 const char *TargetTriple, LLVMOrcExecutionSessionRef ES,
1252 LLVMOrcJITTargetAddress ErrorHandlerAddr,
1253 LLVMOrcLazyCallThroughManagerRef *LCTM);
1254
1255/**
1256 * Dispose of an LazyCallThroughManager.
1257 */
1258void LLVMOrcDisposeLazyCallThroughManager(
1259 LLVMOrcLazyCallThroughManagerRef LCTM);
1260
1261/**
1262 * Create a DumpObjects instance.
1263 *
1264 * DumpDir specifies the path to write dumped objects to. DumpDir may be empty
1265 * in which case files will be dumped to the working directory.
1266 *
1267 * IdentifierOverride specifies a file name stem to use when dumping objects.
1268 * If empty then each MemoryBuffer's identifier will be used (with a .o suffix
1269 * added if not already present). If an identifier override is supplied it will
1270 * be used instead, along with an incrementing counter (since all buffers will
1271 * use the same identifier, the resulting files will be named <ident>.o,
1272 * <ident>.2.o, <ident>.3.o, and so on). IdentifierOverride should not contain
1273 * an extension, as a .o suffix will be added by DumpObjects.
1274 */
1275LLVMOrcDumpObjectsRef LLVMOrcCreateDumpObjects(const char *DumpDir,
1276 const char *IdentifierOverride);
1277
1278/**
1279 * Dispose of a DumpObjects instance.
1280 */
1281void LLVMOrcDisposeDumpObjects(LLVMOrcDumpObjectsRef DumpObjects);
1282
1283/**
1284 * Dump the contents of the given MemoryBuffer.
1285 */
1286LLVMErrorRef LLVMOrcDumpObjects_CallOperator(LLVMOrcDumpObjectsRef DumpObjects,
1287 LLVMMemoryBufferRef *ObjBuffer);
1288
1289/**
1290 * @}
1291 */
1292
1293LLVM_C_EXTERN_C_END
1294
1295#endif /* LLVM_C_ORC_H */
1296