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