1 /*===---------------- llvm-c/Orc.h - OrcV2 C bindings -----------*- C++ -*-===*\ 2 |* *| 3 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM *| 4 |* Exceptions. *| 5 |* See https://llvm.org/LICENSE.txt for license information. *| 6 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *| 7 |* *| 8 |*===----------------------------------------------------------------------===*| 9 |* *| 10 |* This header declares the C interface to libLLVMOrcJIT.a, which implements *| 11 |* JIT compilation of LLVM IR. Minimal documentation of C API specific issues *| 12 |* (especially memory ownership rules) is provided. Core Orc concepts are *| 13 |* documented in llvm/docs/ORCv2.rst and APIs are documented in the C++ *| 14 |* headers *| 15 |* *| 16 |* Many exotic languages can interoperate with C code but have a harder time *| 17 |* with C++ due to name mangling. So in addition to C, this interface enables *| 18 |* tools written in such languages. *| 19 |* *| 20 |* Note: This interface is experimental. It is *NOT* stable, and may be *| 21 |* changed without warning. Only C API usage documentation is *| 22 |* provided. See the C++ documentation for all higher level ORC API *| 23 |* details. *| 24 |* *| 25 \*===----------------------------------------------------------------------===*/ 26 27 #ifndef LLVM_C_ORC_H 28 #define LLVM_C_ORC_H 29 30 #include "llvm-c/Error.h" 31 #include "llvm-c/TargetMachine.h" 32 #include "llvm-c/Types.h" 33 34 LLVM_C_EXTERN_C_BEGIN 35 36 /** 37 * @defgroup LLVMCExecutionEngineORC On-Request-Compilation 38 * @ingroup LLVMCExecutionEngine 39 * 40 * @{ 41 */ 42 43 /** 44 * Represents an address in the executor process. 45 */ 46 typedef uint64_t LLVMOrcJITTargetAddress; 47 48 /** 49 * Represents an address in the executor process. 50 */ 51 typedef uint64_t LLVMOrcExecutorAddress; 52 53 /** 54 * Represents generic linkage flags for a symbol definition. 55 */ 56 typedef 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 */ 67 typedef uint8_t LLVMJITSymbolTargetFlags; 68 69 /** 70 * Represents the linkage flags for a symbol definition. 71 */ 72 typedef struct { 73 uint8_t GenericFlags; 74 uint8_t TargetFlags; 75 } LLVMJITSymbolFlags; 76 77 /** 78 * Represents an evaluated symbol address and flags. 79 */ 80 typedef struct { 81 LLVMOrcExecutorAddress Address; 82 LLVMJITSymbolFlags Flags; 83 } LLVMJITEvaluatedSymbol; 84 85 /** 86 * A reference to an orc::ExecutionSession instance. 87 */ 88 typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef; 89 90 /** 91 * Error reporter function. 92 */ 93 typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err); 94 95 /** 96 * A reference to an orc::SymbolStringPool. 97 */ 98 typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef; 99 100 /** 101 * A reference to an orc::SymbolStringPool table entry. 102 */ 103 typedef struct LLVMOrcOpaqueSymbolStringPoolEntry 104 *LLVMOrcSymbolStringPoolEntryRef; 105 106 /** 107 * Represents a pair of a symbol name and LLVMJITSymbolFlags. 108 */ 109 typedef 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 */ 118 typedef LLVMOrcCSymbolFlagsMapPair *LLVMOrcCSymbolFlagsMapPairs; 119 120 /** 121 * Represents a pair of a symbol name and an evaluated symbol. 122 */ 123 typedef 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 */ 132 typedef LLVMOrcCSymbolMapPair *LLVMOrcCSymbolMapPairs; 133 134 /** 135 * Represents a SymbolAliasMapEntry 136 */ 137 typedef struct { 138 LLVMOrcSymbolStringPoolEntryRef Name; 139 LLVMJITSymbolFlags Flags; 140 } LLVMOrcCSymbolAliasMapEntry; 141 142 /** 143 * Represents a pair of a symbol name and SymbolAliasMapEntry. 144 */ 145 typedef 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 */ 154 typedef LLVMOrcCSymbolAliasMapPair *LLVMOrcCSymbolAliasMapPairs; 155 156 /** 157 * A reference to an orc::JITDylib instance. 158 */ 159 typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef; 160 161 /** 162 * Represents a list of LLVMOrcSymbolStringPoolEntryRef and the associated 163 * length. 164 */ 165 typedef struct { 166 LLVMOrcSymbolStringPoolEntryRef *Symbols; 167 size_t Length; 168 } LLVMOrcCSymbolsList; 169 170 /** 171 * Represents a pair of a JITDylib and LLVMOrcCSymbolsList. 172 */ 173 typedef 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 */ 182 typedef LLVMOrcCDependenceMapPair *LLVMOrcCDependenceMapPairs; 183 184 /** 185 * A set of symbols that share dependencies. 186 */ 187 typedef 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 */ 199 typedef 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 */ 210 typedef enum { 211 LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly, 212 LLVMOrcJITDylibLookupFlagsMatchAllSymbols 213 } LLVMOrcJITDylibLookupFlags; 214 215 /** 216 * An element type for a JITDylib search order. 217 */ 218 typedef 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 */ 229 typedef LLVMOrcCJITDylibSearchOrderElement *LLVMOrcCJITDylibSearchOrder; 230 231 /** 232 * Symbol lookup flags for lookup sets. This should be kept in sync with 233 * llvm::orc::SymbolLookupFlags. 234 */ 235 typedef enum { 236 LLVMOrcSymbolLookupFlagsRequiredSymbol, 237 LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol 238 } LLVMOrcSymbolLookupFlags; 239 240 /** 241 * An element type for a symbol lookup set. 242 */ 243 typedef 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 */ 259 typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet; 260 261 /** 262 * A reference to a uniquely owned orc::MaterializationUnit instance. 263 */ 264 typedef 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 */ 271 typedef 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 */ 284 typedef 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 */ 293 typedef 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 */ 303 typedef void (*LLVMOrcMaterializationUnitDestroyFunction)(void *Ctx); 304 305 /** 306 * A reference to an orc::ResourceTracker instance. 307 */ 308 typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef; 309 310 /** 311 * A reference to an orc::DefinitionGenerator. 312 */ 313 typedef 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 */ 328 typedef 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 */ 363 typedef 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 */ 375 typedef void (*LLVMOrcDisposeCAPIDefinitionGeneratorFunction)(void *Ctx); 376 377 /** 378 * Predicate function for SymbolStringPoolEntries. 379 */ 380 typedef int (*LLVMOrcSymbolPredicate)(void *Ctx, 381 LLVMOrcSymbolStringPoolEntryRef Sym); 382 383 /** 384 * A reference to an orc::ThreadSafeContext instance. 385 */ 386 typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef; 387 388 /** 389 * A reference to an orc::ThreadSafeModule instance. 390 */ 391 typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef; 392 393 /** 394 * A function for inspecting/mutating IR modules, suitable for use with 395 * LLVMOrcThreadSafeModuleWithModuleDo. 396 */ 397 typedef LLVMErrorRef (*LLVMOrcGenericIRModuleOperationFunction)( 398 void *Ctx, LLVMModuleRef M); 399 400 /** 401 * A reference to an orc::JITTargetMachineBuilder instance. 402 */ 403 typedef struct LLVMOrcOpaqueJITTargetMachineBuilder 404 *LLVMOrcJITTargetMachineBuilderRef; 405 406 /** 407 * A reference to an orc::ObjectLayer instance. 408 */ 409 typedef struct LLVMOrcOpaqueObjectLayer *LLVMOrcObjectLayerRef; 410 411 /** 412 * A reference to an orc::ObjectLinkingLayer instance. 413 */ 414 typedef struct LLVMOrcOpaqueObjectLinkingLayer *LLVMOrcObjectLinkingLayerRef; 415 416 /** 417 * A reference to an orc::IRTransformLayer instance. 418 */ 419 typedef 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 */ 436 typedef LLVMErrorRef (*LLVMOrcIRTransformLayerTransformFunction)( 437 void *Ctx, LLVMOrcThreadSafeModuleRef *ModInOut, 438 LLVMOrcMaterializationResponsibilityRef MR); 439 440 /** 441 * A reference to an orc::ObjectTransformLayer instance. 442 */ 443 typedef 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 */ 459 typedef LLVMErrorRef (*LLVMOrcObjectTransformLayerTransformFunction)( 460 void *Ctx, LLVMMemoryBufferRef *ObjInOut); 461 462 /** 463 * A reference to an orc::IndirectStubsManager instance. 464 */ 465 typedef struct LLVMOrcOpaqueIndirectStubsManager 466 *LLVMOrcIndirectStubsManagerRef; 467 468 /** 469 * A reference to an orc::LazyCallThroughManager instance. 470 */ 471 typedef 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 */ 480 typedef 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 */ 491 void 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 */ 501 LLVMOrcSymbolStringPoolRef 502 LLVMOrcExecutionSessionGetSymbolStringPool(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 */ 514 void 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 */ 528 LLVMOrcSymbolStringPoolEntryRef 529 LLVMOrcExecutionSessionIntern(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 */ 545 typedef 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 */ 577 void 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 */ 586 void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S); 587 588 /** 589 * Reduces the ref-count for of a SymbolStringPool entry. 590 */ 591 void 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 */ 598 const char *LLVMOrcSymbolStringPoolEntryStr(LLVMOrcSymbolStringPoolEntryRef S); 599 600 /** 601 * Reduces the ref-count of a ResourceTracker. 602 */ 603 void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT); 604 605 /** 606 * Transfers tracking of all resources associated with resource tracker SrcRT 607 * to resource tracker DstRT. 608 */ 609 void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT, 610 LLVMOrcResourceTrackerRef DstRT); 611 612 /** 613 * Remove all resources associated with the given tracker. See 614 * ResourceTracker::remove(). 615 */ 616 LLVMErrorRef 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 */ 623 void LLVMOrcDisposeDefinitionGenerator(LLVMOrcDefinitionGeneratorRef DG); 624 625 /** 626 * Dispose of a MaterializationUnit. 627 */ 628 void 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 */ 663 LLVMOrcMaterializationUnitRef 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 */ 691 LLVMOrcMaterializationUnitRef 692 LLVMOrcAbsoluteSymbols(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 */ 715 LLVMOrcMaterializationUnitRef 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 */ 730 void LLVMOrcDisposeMaterializationResponsibility( 731 LLVMOrcMaterializationResponsibilityRef MR); 732 733 /** 734 * Returns the target JITDylib that these symbols are being materialized into. 735 */ 736 LLVMOrcJITDylibRef LLVMOrcMaterializationResponsibilityGetTargetDylib( 737 LLVMOrcMaterializationResponsibilityRef MR); 738 739 /** 740 * Returns the ExecutionSession for this MaterializationResponsibility. 741 */ 742 LLVMOrcExecutionSessionRef 743 LLVMOrcMaterializationResponsibilityGetExecutionSession( 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 */ 756 LLVMOrcCSymbolFlagsMapPairs LLVMOrcMaterializationResponsibilityGetSymbols( 757 LLVMOrcMaterializationResponsibilityRef MR, size_t *NumPairs); 758 759 /** 760 * Disposes of the passed LLVMOrcCSymbolFlagsMap. 761 * 762 * Does not release the entries themselves. 763 */ 764 void 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 */ 774 LLVMOrcSymbolStringPoolEntryRef 775 LLVMOrcMaterializationResponsibilityGetInitializerSymbol( 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 */ 784 LLVMOrcSymbolStringPoolEntryRef * 785 LLVMOrcMaterializationResponsibilityGetRequestedSymbols( 786 LLVMOrcMaterializationResponsibilityRef MR, size_t *NumSymbols); 787 788 /** 789 * Disposes of the passed LLVMOrcSymbolStringPoolEntryRef* . 790 * 791 * Does not release the symbols themselves. 792 */ 793 void 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 */ 811 LLVMErrorRef 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 */ 841 LLVMErrorRef 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 */ 858 LLVMErrorRef 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 */ 869 void 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 */ 879 LLVMErrorRef 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 */ 891 LLVMErrorRef 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 */ 905 LLVMOrcJITDylibRef 906 LLVMOrcExecutionSessionCreateBareJITDylib(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 */ 921 LLVMErrorRef 922 LLVMOrcExecutionSessionCreateJITDylib(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 */ 930 LLVMOrcJITDylibRef 931 LLVMOrcExecutionSessionGetJITDylibByName(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 */ 939 LLVMOrcResourceTrackerRef 940 LLVMOrcJITDylibCreateResourceTracker(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 */ 947 LLVMOrcResourceTrackerRef 948 LLVMOrcJITDylibGetDefaultResourceTracker(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 */ 957 LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD, 958 LLVMOrcMaterializationUnitRef MU); 959 960 /** 961 * Calls remove on all trackers associated with this JITDylib, see 962 * JITDylib::clear(). 963 */ 964 LLVMErrorRef 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 */ 972 void 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 */ 988 LLVMOrcDefinitionGeneratorRef 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 */ 996 void 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 */ 1017 LLVMErrorRef 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 */ 1042 LLVMErrorRef 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 */ 1060 LLVMErrorRef LLVMOrcCreateStaticLibrarySearchGeneratorForPath( 1061 LLVMOrcDefinitionGeneratorRef *Result, LLVMOrcObjectLayerRef ObjLayer, 1062 const char *FileName, const char *TargetTriple); 1063 1064 /** 1065 * Create a ThreadSafeContext containing a new LLVMContext. 1066 * 1067 * Ownership of the underlying ThreadSafeContext data is shared: Clients 1068 * can and should dispose of their ThreadSafeContext as soon as they no longer 1069 * need to refer to it directly. Other references (e.g. from ThreadSafeModules) 1070 * will keep the data alive as long as it is needed. 1071 */ 1072 LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void); 1073 1074 /** 1075 * Get a reference to the wrapped LLVMContext. 1076 */ 1077 LLVMContextRef 1078 LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx); 1079 1080 /** 1081 * Dispose of a ThreadSafeContext. 1082 */ 1083 void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx); 1084 1085 /** 1086 * Create a ThreadSafeModule wrapper around the given LLVM module. This takes 1087 * ownership of the M argument which should not be disposed of or referenced 1088 * after this function returns. 1089 * 1090 * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT 1091 * (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer 1092 * responsible for it. If it is not transferred to the JIT then the client 1093 * should call LLVMOrcDisposeThreadSafeModule to dispose of it. 1094 */ 1095 LLVMOrcThreadSafeModuleRef 1096 LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M, 1097 LLVMOrcThreadSafeContextRef TSCtx); 1098 1099 /** 1100 * Dispose of a ThreadSafeModule. This should only be called if ownership has 1101 * not been passed to LLJIT (e.g. because some error prevented the client from 1102 * adding this to the JIT). 1103 */ 1104 void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM); 1105 1106 /** 1107 * Apply the given function to the module contained in this ThreadSafeModule. 1108 */ 1109 LLVMErrorRef 1110 LLVMOrcThreadSafeModuleWithModuleDo(LLVMOrcThreadSafeModuleRef TSM, 1111 LLVMOrcGenericIRModuleOperationFunction F, 1112 void *Ctx); 1113 1114 /** 1115 * Create a JITTargetMachineBuilder by detecting the host. 1116 * 1117 * On success the client owns the resulting JITTargetMachineBuilder. It must be 1118 * passed to a consuming operation (e.g. 1119 * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling 1120 * LLVMOrcDisposeJITTargetMachineBuilder. 1121 */ 1122 LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost( 1123 LLVMOrcJITTargetMachineBuilderRef *Result); 1124 1125 /** 1126 * Create a JITTargetMachineBuilder from the given TargetMachine template. 1127 * 1128 * This operation takes ownership of the given TargetMachine and destroys it 1129 * before returing. The resulting JITTargetMachineBuilder is owned by the client 1130 * and must be passed to a consuming operation (e.g. 1131 * LLVMOrcLLJITBuilderSetJITTargetMachineBuilder) or disposed of by calling 1132 * LLVMOrcDisposeJITTargetMachineBuilder. 1133 */ 1134 LLVMOrcJITTargetMachineBuilderRef 1135 LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM); 1136 1137 /** 1138 * Dispose of a JITTargetMachineBuilder. 1139 */ 1140 void LLVMOrcDisposeJITTargetMachineBuilder( 1141 LLVMOrcJITTargetMachineBuilderRef JTMB); 1142 1143 /** 1144 * Returns the target triple for the given JITTargetMachineBuilder as a string. 1145 * 1146 * The caller owns the resulting string as must dispose of it by calling 1147 * LLVMDisposeMessage 1148 */ 1149 char *LLVMOrcJITTargetMachineBuilderGetTargetTriple( 1150 LLVMOrcJITTargetMachineBuilderRef JTMB); 1151 1152 /** 1153 * Sets the target triple for the given JITTargetMachineBuilder to the given 1154 * string. 1155 */ 1156 void LLVMOrcJITTargetMachineBuilderSetTargetTriple( 1157 LLVMOrcJITTargetMachineBuilderRef JTMB, const char *TargetTriple); 1158 1159 /** 1160 * Add an object to an ObjectLayer to the given JITDylib. 1161 * 1162 * Adds a buffer representing an object file to the given JITDylib using the 1163 * given ObjectLayer instance. This operation transfers ownership of the buffer 1164 * to the ObjectLayer instance. The buffer should not be disposed of or 1165 * referenced once this function returns. 1166 * 1167 * Resources associated with the given object will be tracked by the given 1168 * JITDylib's default ResourceTracker. 1169 */ 1170 LLVMErrorRef LLVMOrcObjectLayerAddObjectFile(LLVMOrcObjectLayerRef ObjLayer, 1171 LLVMOrcJITDylibRef JD, 1172 LLVMMemoryBufferRef ObjBuffer); 1173 1174 /** 1175 * Add an object to an ObjectLayer using the given ResourceTracker. 1176 * 1177 * Adds a buffer representing an object file to the given ResourceTracker's 1178 * JITDylib using the given ObjectLayer instance. This operation transfers 1179 * ownership of the buffer to the ObjectLayer instance. The buffer should not 1180 * be disposed of or referenced once this function returns. 1181 * 1182 * Resources associated with the given object will be tracked by 1183 * ResourceTracker RT. 1184 */ 1185 LLVMErrorRef 1186 LLVMOrcObjectLayerAddObjectFileWithRT(LLVMOrcObjectLayerRef ObjLayer, 1187 LLVMOrcResourceTrackerRef RT, 1188 LLVMMemoryBufferRef ObjBuffer); 1189 1190 /** 1191 * Emit an object buffer to an ObjectLayer. 1192 * 1193 * Ownership of the responsibility object and object buffer pass to this 1194 * function. The client is not responsible for cleanup. 1195 */ 1196 void LLVMOrcObjectLayerEmit(LLVMOrcObjectLayerRef ObjLayer, 1197 LLVMOrcMaterializationResponsibilityRef R, 1198 LLVMMemoryBufferRef ObjBuffer); 1199 1200 /** 1201 * Dispose of an ObjectLayer. 1202 */ 1203 void LLVMOrcDisposeObjectLayer(LLVMOrcObjectLayerRef ObjLayer); 1204 1205 void LLVMOrcIRTransformLayerEmit(LLVMOrcIRTransformLayerRef IRTransformLayer, 1206 LLVMOrcMaterializationResponsibilityRef MR, 1207 LLVMOrcThreadSafeModuleRef TSM); 1208 1209 /** 1210 * Set the transform function of the provided transform layer, passing through a 1211 * pointer to user provided context. 1212 */ 1213 void LLVMOrcIRTransformLayerSetTransform( 1214 LLVMOrcIRTransformLayerRef IRTransformLayer, 1215 LLVMOrcIRTransformLayerTransformFunction TransformFunction, void *Ctx); 1216 1217 /** 1218 * Set the transform function on an LLVMOrcObjectTransformLayer. 1219 */ 1220 void LLVMOrcObjectTransformLayerSetTransform( 1221 LLVMOrcObjectTransformLayerRef ObjTransformLayer, 1222 LLVMOrcObjectTransformLayerTransformFunction TransformFunction, void *Ctx); 1223 1224 /** 1225 * Create a LocalIndirectStubsManager from the given target triple. 1226 * 1227 * The resulting IndirectStubsManager is owned by the client 1228 * and must be disposed of by calling LLVMOrcDisposeDisposeIndirectStubsManager. 1229 */ 1230 LLVMOrcIndirectStubsManagerRef 1231 LLVMOrcCreateLocalIndirectStubsManager(const char *TargetTriple); 1232 1233 /** 1234 * Dispose of an IndirectStubsManager. 1235 */ 1236 void LLVMOrcDisposeIndirectStubsManager(LLVMOrcIndirectStubsManagerRef ISM); 1237 1238 LLVMErrorRef LLVMOrcCreateLocalLazyCallThroughManager( 1239 const char *TargetTriple, LLVMOrcExecutionSessionRef ES, 1240 LLVMOrcJITTargetAddress ErrorHandlerAddr, 1241 LLVMOrcLazyCallThroughManagerRef *LCTM); 1242 1243 /** 1244 * Dispose of an LazyCallThroughManager. 1245 */ 1246 void LLVMOrcDisposeLazyCallThroughManager( 1247 LLVMOrcLazyCallThroughManagerRef LCTM); 1248 1249 /** 1250 * Create a DumpObjects instance. 1251 * 1252 * DumpDir specifies the path to write dumped objects to. DumpDir may be empty 1253 * in which case files will be dumped to the working directory. 1254 * 1255 * IdentifierOverride specifies a file name stem to use when dumping objects. 1256 * If empty then each MemoryBuffer's identifier will be used (with a .o suffix 1257 * added if not already present). If an identifier override is supplied it will 1258 * be used instead, along with an incrementing counter (since all buffers will 1259 * use the same identifier, the resulting files will be named <ident>.o, 1260 * <ident>.2.o, <ident>.3.o, and so on). IdentifierOverride should not contain 1261 * an extension, as a .o suffix will be added by DumpObjects. 1262 */ 1263 LLVMOrcDumpObjectsRef LLVMOrcCreateDumpObjects(const char *DumpDir, 1264 const char *IdentifierOverride); 1265 1266 /** 1267 * Dispose of a DumpObjects instance. 1268 */ 1269 void LLVMOrcDisposeDumpObjects(LLVMOrcDumpObjectsRef DumpObjects); 1270 1271 /** 1272 * Dump the contents of the given MemoryBuffer. 1273 */ 1274 LLVMErrorRef LLVMOrcDumpObjects_CallOperator(LLVMOrcDumpObjectsRef DumpObjects, 1275 LLVMMemoryBufferRef *ObjBuffer); 1276 1277 /** 1278 * @} 1279 */ 1280 1281 LLVM_C_EXTERN_C_END 1282 1283 #endif /* LLVM_C_ORC_H */ 1284