1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
|
/*===---------------- llvm-c/Orc.h - OrcV2 C bindings -----------*- C++ -*-===*\
|* *|
|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|
|* Exceptions. *|
|* See https://llvm.org/LICENSE.txt for license information. *|
|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|
|* *|
|*===----------------------------------------------------------------------===*|
|* *|
|* This header declares the C interface to libLLVMOrcJIT.a, which implements *|
|* JIT compilation of LLVM IR. Minimal documentation of C API specific issues *|
|* (especially memory ownership rules) is provided. Core Orc concepts are *|
|* documented in llvm/docs/ORCv2.rst and APIs are documented in the C++ *|
|* headers *|
|* *|
|* Many exotic languages can interoperate with C code but have a harder time *|
|* with C++ due to name mangling. So in addition to C, this interface enables *|
|* tools written in such languages. *|
|* *|
|* Note: This interface is experimental. It is *NOT* stable, and may be *|
|* changed without warning. Only C API usage documentation is *|
|* provided. See the C++ documentation for all higher level ORC API *|
|* details. *|
|* *|
\*===----------------------------------------------------------------------===*/
#ifndef LLVM_C_ORC_H
#define LLVM_C_ORC_H
#include "llvm-c/Error.h"
#include "llvm-c/TargetMachine.h"
#include "llvm-c/Types.h"
LLVM_C_EXTERN_C_BEGIN
/**
* Represents an address in the target process.
*/
typedef uint64_t LLVMOrcJITTargetAddress;
/**
* Represents generic linkage flags for a symbol definition.
*/
typedef enum {
LLVMJITSymbolGenericFlagsExported = 1U << 0,
LLVMJITSymbolGenericFlagsWeak = 1U << 1
} LLVMJITSymbolGenericFlags;
/**
* Represents target specific flags for a symbol definition.
*/
typedef uint8_t LLVMJITTargetSymbolFlags;
/**
* Represents the linkage flags for a symbol definition.
*/
typedef struct {
uint8_t GenericFlags;
uint8_t TargetFlags;
} LLVMJITSymbolFlags;
/**
* Represents an evaluated symbol address and flags.
*/
typedef struct {
LLVMOrcJITTargetAddress Address;
LLVMJITSymbolFlags Flags;
} LLVMJITEvaluatedSymbol;
/**
* A reference to an orc::ExecutionSession instance.
*/
typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef;
/**
* Error reporter function.
*/
typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err);
/**
* A reference to an orc::SymbolStringPool.
*/
typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef;
/**
* A reference to an orc::SymbolStringPool table entry.
*/
typedef struct LLVMOrcOpaqueSymbolStringPoolEntry
*LLVMOrcSymbolStringPoolEntryRef;
/**
* Represents a pair of a symbol name and an evaluated symbol.
*/
typedef struct {
LLVMOrcSymbolStringPoolEntryRef Name;
LLVMJITEvaluatedSymbol Sym;
} LLVMJITCSymbolMapPair;
/**
* Represents a list of (SymbolStringPtr, JITEvaluatedSymbol) pairs that can be
* used to construct a SymbolMap.
*/
typedef LLVMJITCSymbolMapPair *LLVMOrcCSymbolMapPairs;
/**
* Lookup kind. This can be used by definition generators when deciding whether
* to produce a definition for a requested symbol.
*
* This enum should be kept in sync with llvm::orc::LookupKind.
*/
typedef enum {
LLVMOrcLookupKindStatic,
LLVMOrcLookupKindDLSym
} LLVMOrcLookupKind;
/**
* JITDylib lookup flags. This can be used by definition generators when
* deciding whether to produce a definition for a requested symbol.
*
* This enum should be kept in sync with llvm::orc::JITDylibLookupFlags.
*/
typedef enum {
LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly,
LLVMOrcJITDylibLookupFlagsMatchAllSymbols
} LLVMOrcJITDylibLookupFlags;
/**
* Symbol lookup flags for lookup sets. This should be kept in sync with
* llvm::orc::SymbolLookupFlags.
*/
typedef enum {
LLVMOrcSymbolLookupFlagsRequiredSymbol,
LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol
} LLVMOrcSymbolLookupFlags;
/**
* An element type for a symbol lookup set.
*/
typedef struct {
LLVMOrcSymbolStringPoolEntryRef Name;
LLVMOrcSymbolLookupFlags LookupFlags;
} LLVMOrcCLookupSetElement;
/**
* A set of symbols to look up / generate.
*
* The list is terminated with an element containing a null pointer for the
* Name field.
*
* If a client creates an instance of this type then they are responsible for
* freeing it, and for ensuring that all strings have been retained over the
* course of its life. Clients receiving a copy from a callback are not
* responsible for managing lifetime or retain counts.
*/
typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet;
/**
* A reference to an orc::MaterializationUnit.
*/
typedef struct LLVMOrcOpaqueMaterializationUnit *LLVMOrcMaterializationUnitRef;
/**
* A reference to an orc::JITDylib instance.
*/
typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef;
/**
* A reference to an orc::ResourceTracker instance.
*/
typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef;
/**
* A reference to an orc::DefinitionGenerator.
*/
typedef struct LLVMOrcOpaqueDefinitionGenerator
*LLVMOrcDefinitionGeneratorRef;
/**
* An opaque lookup state object. Instances of this type can be captured to
* suspend a lookup while a custom generator function attempts to produce a
* definition.
*
* If a client captures a lookup state object then they must eventually call
* LLVMOrcLookupStateContinueLookup to restart the lookup. This is required
* in order to release memory allocated for the lookup state, even if errors
* have occurred while the lookup was suspended (if these errors have made the
* lookup impossible to complete then it will issue its own error before
* destruction).
*/
typedef struct LLVMOrcOpaqueLookupState *LLVMOrcLookupStateRef;
/**
* A custom generator function. This can be used to create a custom generator
* object using LLVMOrcCreateCustomCAPIDefinitionGenerator. The resulting
* object can be attached to a JITDylib, via LLVMOrcJITDylibAddGenerator, to
* receive callbacks when lookups fail to match existing definitions.
*
* GeneratorObj will contain the address of the custom generator object.
*
* Ctx will contain the context object passed to
* LLVMOrcCreateCustomCAPIDefinitionGenerator.
*
* LookupState will contain a pointer to an LLVMOrcLookupStateRef object. This
* can optionally be modified to make the definition generation process
* asynchronous: If the LookupStateRef value is copied, and the original
* LLVMOrcLookupStateRef set to null, the lookup will be suspended. Once the
* asynchronous definition process has been completed clients must call
* LLVMOrcLookupStateContinueLookup to continue the lookup (this should be
* done unconditionally, even if errors have occurred in the mean time, to
* free the lookup state memory and notify the query object of the failures. If
* LookupState is captured this function must return LLVMErrorSuccess.
*
* The Kind argument can be inspected to determine the lookup kind (e.g.
* as-if-during-static-link, or as-if-during-dlsym).
*
* The JD argument specifies which JITDylib the definitions should be generated
* into.
*
* The JDLookupFlags argument can be inspected to determine whether the original
* lookup included non-exported symobls.
*
* Finally, the LookupSet argument contains the set of symbols that could not
* be found in JD already (the set of generation candidates).
*/
typedef LLVMErrorRef (*LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction)(
LLVMOrcDefinitionGeneratorRef GeneratorObj, void *Ctx,
LLVMOrcLookupStateRef *LookupState, LLVMOrcLookupKind Kind,
LLVMOrcJITDylibRef JD, LLVMOrcJITDylibLookupFlags JDLookupFlags,
LLVMOrcCLookupSet LookupSet, size_t LookupSetSize);
/**
* Predicate function for SymbolStringPoolEntries.
*/
typedef int (*LLVMOrcSymbolPredicate)(void *Ctx,
LLVMOrcSymbolStringPoolEntryRef Sym);
/**
* A reference to an orc::ThreadSafeContext instance.
*/
typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef;
/**
* A reference to an orc::ThreadSafeModule instance.
*/
typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef;
/**
* A reference to an orc::JITTargetMachineBuilder instance.
*/
typedef struct LLVMOrcOpaqueJITTargetMachineBuilder
*LLVMOrcJITTargetMachineBuilderRef;
/**
* A reference to an orc::ObjectLayer instance.
*/
typedef struct LLVMOrcOpaqueObjectLayer *LLVMOrcObjectLayerRef;
/**
* Attach a custom error reporter function to the ExecutionSession.
*
* The error reporter will be called to deliver failure notices that can not be
* directly reported to a caller. For example, failure to resolve symbols in
* the JIT linker is typically reported via the error reporter (callers
* requesting definitions from the JIT will typically be delivered a
* FailureToMaterialize error instead).
*/
void LLVMOrcExecutionSessionSetErrorReporter(
LLVMOrcExecutionSessionRef ES, LLVMOrcErrorReporterFunction ReportError,
void *Ctx);
/**
* Return a reference to the SymbolStringPool for an ExecutionSession.
*
* Ownership of the pool remains with the ExecutionSession: The caller is
* not required to free the pool.
*/
LLVMOrcSymbolStringPoolRef
LLVMOrcExecutionSessionGetSymbolStringPool(LLVMOrcExecutionSessionRef ES);
/**
* Clear all unreferenced symbol string pool entries.
*
* This can be called at any time to release unused entries in the
* ExecutionSession's string pool. Since it locks the pool (preventing
* interning of any new strings) it is recommended that it only be called
* infrequently, ideally when the caller has reason to believe that some
* entries will have become unreferenced, e.g. after removing a module or
* closing a JITDylib.
*/
void LLVMOrcSymbolStringPoolClearDeadEntries(LLVMOrcSymbolStringPoolRef SSP);
/**
* Intern a string in the ExecutionSession's SymbolStringPool and return a
* reference to it. This increments the ref-count of the pool entry, and the
* returned value should be released once the client is done with it by
* calling LLVMOrReleaseSymbolStringPoolEntry.
*
* Since strings are uniqued within the SymbolStringPool
* LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string
* equality.
*
* Note that this function does not perform linker-mangling on the string.
*/
LLVMOrcSymbolStringPoolEntryRef
LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name);
/**
* Increments the ref-count for a SymbolStringPool entry.
*/
void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
/**
* Reduces the ref-count for of a SymbolStringPool entry.
*/
void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);
const char *LLVMOrcSymbolStringPoolEntryStr(LLVMOrcSymbolStringPoolEntryRef S);
/**
* Reduces the ref-count of a ResourceTracker.
*/
void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT);
/**
* Transfers tracking of all resources associated with resource tracker SrcRT
* to resource tracker DstRT.
*/
void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT,
LLVMOrcResourceTrackerRef DstRT);
/**
* Remove all resources associated with the given tracker. See
* ResourceTracker::remove().
*/
LLVMErrorRef LLVMOrcResourceTrackerRemove(LLVMOrcResourceTrackerRef RT);
/**
* Dispose of a JITDylib::DefinitionGenerator. This should only be called if
* ownership has not been passed to a JITDylib (e.g. because some error
* prevented the client from calling LLVMOrcJITDylibAddGenerator).
*/
void LLVMOrcDisposeDefinitionGenerator(LLVMOrcDefinitionGeneratorRef DG);
/**
* Dispose of a MaterializationUnit.
*/
void LLVMOrcDisposeMaterializationUnit(LLVMOrcMaterializationUnitRef MU);
/**
* Create a MaterializationUnit to define the given symbols as pointing to
* the corresponding raw addresses.
*/
LLVMOrcMaterializationUnitRef
LLVMOrcAbsoluteSymbols(LLVMOrcCSymbolMapPairs Syms, size_t NumPairs);
/**
* Create a "bare" JITDylib.
*
* The client is responsible for ensuring that the JITDylib's name is unique,
* e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
*
* This call does not install any library code or symbols into the newly
* created JITDylib. The client is responsible for all configuration.
*/
LLVMOrcJITDylibRef
LLVMOrcExecutionSessionCreateBareJITDylib(LLVMOrcExecutionSessionRef ES,
const char *Name);
/**
* Create a JITDylib.
*
* The client is responsible for ensuring that the JITDylib's name is unique,
* e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first.
*
* If a Platform is attached to the ExecutionSession then
* Platform::setupJITDylib will be called to install standard platform symbols
* (e.g. standard library interposes). If no Platform is installed then this
* call is equivalent to LLVMExecutionSessionRefCreateBareJITDylib and will
* always return success.
*/
LLVMErrorRef
LLVMOrcExecutionSessionCreateJITDylib(LLVMOrcExecutionSessionRef ES,
LLVMOrcJITDylibRef *Result,
const char *Name);
/**
* Returns the JITDylib with the given name, or NULL if no such JITDylib
* exists.
*/
LLVMOrcJITDylibRef
LLVMOrcExecutionSessionGetJITDylibByName(LLVMOrcExecutionSessionRef ES,
const char *Name);
/**
* Return a reference to a newly created resource tracker associated with JD.
* The tracker is returned with an initial ref-count of 1, and must be released
* with LLVMOrcReleaseResourceTracker when no longer needed.
*/
LLVMOrcResourceTrackerRef
LLVMOrcJITDylibCreateResourceTracker(LLVMOrcJITDylibRef JD);
/**
* Return a reference to the default resource tracker for the given JITDylib.
* This operation will increase the retain count of the tracker: Clients should
* call LLVMOrcReleaseResourceTracker when the result is no longer needed.
*/
LLVMOrcResourceTrackerRef
LLVMOrcJITDylibGetDefaultResourceTracker(LLVMOrcJITDylibRef JD);
/**
* Add the given MaterializationUnit to the given JITDylib.
*
* If this operation succeeds then JITDylib JD will take ownership of MU.
* If the operation fails then ownership remains with the caller who should
* call LLVMOrcDisposeMaterializationUnit to destroy it.
*/
LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD,
LLVMOrcMaterializationUnitRef MU);
/**
* Calls remove on all trackers associated with this JITDylib, see
* JITDylib::clear().
*/
LLVMErrorRef LLVMOrcJITDylibClear(LLVMOrcJITDylibRef JD);
/**
* Add a DefinitionGenerator to the given JITDylib.
*
* The JITDylib will take ownership of the given generator: The client is no
* longer responsible for managing its memory.
*/
void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD,
LLVMOrcDefinitionGeneratorRef DG);
/**
* Create a custom generator.
*/
LLVMOrcDefinitionGeneratorRef LLVMOrcCreateCustomCAPIDefinitionGenerator(
LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction F, void *Ctx);
/**
* Get a DynamicLibrarySearchGenerator that will reflect process symbols into
* the JITDylib. On success the resulting generator is owned by the client.
* Ownership is typically transferred by adding the instance to a JITDylib
* using LLVMOrcJITDylibAddGenerator,
*
* The GlobalPrefix argument specifies the character that appears on the front
* of linker-mangled symbols for the target platform (e.g. '_' on MachO).
* If non-null, this character will be stripped from the start of all symbol
* strings before passing the remaining substring to dlsym.
*
* The optional Filter and Ctx arguments can be used to supply a symbol name
* filter: Only symbols for which the filter returns true will be visible to
* JIT'd code. If the Filter argument is null then all process symbols will
* be visible to JIT'd code. Note that the symbol name passed to the Filter
* function is the full mangled symbol: The client is responsible for stripping
* the global prefix if present.
*/
LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess(
LLVMOrcDefinitionGeneratorRef *Result, char GlobalPrefx,
LLVMOrcSymbolPredicate Filter, void *FilterCtx);
/**
* Create a ThreadSafeContext containing a new LLVMContext.
*
* Ownership of the underlying ThreadSafeContext data is shared: Clients
* can and should dispose of their ThreadSafeContext as soon as they no longer
* need to refer to it directly. Other references (e.g. from ThreadSafeModules)
* will keep the data alive as long as it is needed.
*/
LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void);
/**
* Get a reference to the wrapped LLVMContext.
*/
LLVMContextRef
LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx);
/**
* Dispose of a ThreadSafeContext.
*/
void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx);
/**
* Create a ThreadSafeModule wrapper around the given LLVM module. This takes
* ownership of the M argument which should not be disposed of or referenced
* after this function returns.
*
* Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT
* (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer
* responsible for it. If it is not transferred to the JIT then the client
* should call LLVMOrcDisposeThreadSafeModule to dispose of it.
*/
LLVMOrcThreadSafeModuleRef
LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M,
LLVMOrcThreadSafeContextRef TSCtx);
/**
* Dispose of a ThreadSafeModule. This should only be called if ownership has
* not been passed to LLJIT (e.g. because some error prevented the client from
* adding this to the JIT).
*/
void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM);
/**
* Create a JITTargetMachineBuilder by detecting the host.
*
* On success the client owns the resulting JITTargetMachineBuilder. It must be
* passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder) or disposed
* of by calling LLVMOrcDisposeJITTargetMachineBuilder.
*/
LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost(
LLVMOrcJITTargetMachineBuilderRef *Result);
/**
* Create a JITTargetMachineBuilder from the given TargetMachine template.
*
* This operation takes ownership of the given TargetMachine and destroys it
* before returing. The resulting JITTargetMachineBuilder is owned by the client
* and must be passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder)
* or disposed of by calling LLVMOrcDisposeJITTargetMachineBuilder.
*/
LLVMOrcJITTargetMachineBuilderRef
LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM);
/**
* Dispose of a JITTargetMachineBuilder.
*/
void LLVMOrcDisposeJITTargetMachineBuilder(
LLVMOrcJITTargetMachineBuilderRef JTMB);
/**
* Dispose of an ObjectLayer.
*/
void LLVMOrcDisposeObjectLayer(LLVMOrcObjectLayerRef ObjLayer);
LLVM_C_EXTERN_C_END
#endif /* LLVM_C_ORC_H */
|