path: root/contrib/libs/llvm12/include/llvm-c/Orc.h

#pragma once

#ifdef __GNUC__
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wunused-parameter"
#endif

/*===---------------- llvm-c/Orc.h - OrcV2 C bindings -----------*- C++ -*-===*\
|*                                                                            *|
|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
|* Exceptions.                                                                *|
|* See https://llvm.org/LICENSE.txt for license information.                  *|
|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
|*                                                                            *|
|*===----------------------------------------------------------------------===*|
|*                                                                            *|
|* This header declares the C interface to libLLVMOrcJIT.a, which implements  *|
|* JIT compilation of LLVM IR. Minimal documentation of C API specific issues *|
|* (especially memory ownership rules) is provided. Core Orc concepts are     *|
|* documented in llvm/docs/ORCv2.rst and APIs are documented in the C++       *|
|* headers                                                                    *|
|*                                                                            *|
|* Many exotic languages can interoperate with C code but have a harder time  *|
|* with C++ due to name mangling. So in addition to C, this interface enables *|
|* tools written in such languages.                                           *|
|*                                                                            *|
|* Note: This interface is experimental. It is *NOT* stable, and may be       *|
|*       changed without warning. Only C API usage documentation is           *|
|*       provided. See the C++ documentation for all higher level ORC API     *|
|*       details.                                                             *|
|*                                                                            *|
\*===----------------------------------------------------------------------===*/

#ifndef LLVM_C_ORC_H
#define LLVM_C_ORC_H

#include "llvm-c/Error.h"
#include "llvm-c/TargetMachine.h"
#include "llvm-c/Types.h"

LLVM_C_EXTERN_C_BEGIN

/**
 * Represents an address in the target process.
 */
typedef uint64_t LLVMOrcJITTargetAddress;

/**
 * Represents generic linkage flags for a symbol definition. 
 */ 
typedef enum { 
  LLVMJITSymbolGenericFlagsExported = 1U << 0, 
  LLVMJITSymbolGenericFlagsWeak = 1U << 1 
} LLVMJITSymbolGenericFlags; 
 
/** 
 * Represents target specific flags for a symbol definition. 
 */ 
typedef uint8_t LLVMJITTargetSymbolFlags; 
 
/** 
 * Represents the linkage flags for a symbol definition. 
 */ 
typedef struct { 
  uint8_t GenericFlags; 
  uint8_t TargetFlags; 
} LLVMJITSymbolFlags; 
 
/** 
 * Represents an evaluated symbol address and flags. 
 */ 
typedef struct { 
  LLVMOrcJITTargetAddress Address; 
  LLVMJITSymbolFlags Flags; 
} LLVMJITEvaluatedSymbol; 
 
/** 
 * A reference to an orc::ExecutionSession instance.
 */
typedef struct LLVMOrcOpaqueExecutionSession *LLVMOrcExecutionSessionRef;

/**
 * Error reporter function. 
 */ 
typedef void (*LLVMOrcErrorReporterFunction)(void *Ctx, LLVMErrorRef Err); 
 
/** 
 * A reference to an orc::SymbolStringPool. 
 */ 
typedef struct LLVMOrcOpaqueSymbolStringPool *LLVMOrcSymbolStringPoolRef; 
 
/** 
 * A reference to an orc::SymbolStringPool table entry.
 */
typedef struct LLVMOrcOpaqueSymbolStringPoolEntry 
    *LLVMOrcSymbolStringPoolEntryRef;

/**
 * Represents a pair of a symbol name and an evaluated symbol. 
 */ 
typedef struct { 
  LLVMOrcSymbolStringPoolEntryRef Name; 
  LLVMJITEvaluatedSymbol Sym; 
} LLVMJITCSymbolMapPair; 
 
/** 
 * Represents a list of (SymbolStringPtr, JITEvaluatedSymbol) pairs that can be 
 * used to construct a SymbolMap. 
 */ 
typedef LLVMJITCSymbolMapPair *LLVMOrcCSymbolMapPairs; 
 
/** 
 * Lookup kind. This can be used by definition generators when deciding whether 
 * to produce a definition for a requested symbol. 
 * 
 * This enum should be kept in sync with llvm::orc::LookupKind. 
 */ 
typedef enum { 
  LLVMOrcLookupKindStatic, 
  LLVMOrcLookupKindDLSym 
} LLVMOrcLookupKind; 
 
/** 
 * JITDylib lookup flags. This can be used by definition generators when 
 * deciding whether to produce a definition for a requested symbol. 
 * 
 * This enum should be kept in sync with llvm::orc::JITDylibLookupFlags. 
 */ 
typedef enum { 
  LLVMOrcJITDylibLookupFlagsMatchExportedSymbolsOnly, 
  LLVMOrcJITDylibLookupFlagsMatchAllSymbols 
} LLVMOrcJITDylibLookupFlags; 
 
/** 
 * Symbol lookup flags for lookup sets. This should be kept in sync with 
 * llvm::orc::SymbolLookupFlags. 
 */ 
typedef enum { 
  LLVMOrcSymbolLookupFlagsRequiredSymbol, 
  LLVMOrcSymbolLookupFlagsWeaklyReferencedSymbol 
} LLVMOrcSymbolLookupFlags; 
 
/** 
 * An element type for a symbol lookup set. 
 */ 
typedef struct { 
  LLVMOrcSymbolStringPoolEntryRef Name; 
  LLVMOrcSymbolLookupFlags LookupFlags; 
} LLVMOrcCLookupSetElement; 
 
/** 
 * A set of symbols to look up / generate. 
 * 
 * The list is terminated with an element containing a null pointer for the 
 * Name field. 
 * 
 * If a client creates an instance of this type then they are responsible for 
 * freeing it, and for ensuring that all strings have been retained over the 
 * course of its life. Clients receiving a copy from a callback are not 
 * responsible for managing lifetime or retain counts. 
 */ 
typedef LLVMOrcCLookupSetElement *LLVMOrcCLookupSet; 
 
/** 
 * A reference to an orc::MaterializationUnit. 
 */ 
typedef struct LLVMOrcOpaqueMaterializationUnit *LLVMOrcMaterializationUnitRef; 
 
/** 
 * A reference to an orc::JITDylib instance.
 */
typedef struct LLVMOrcOpaqueJITDylib *LLVMOrcJITDylibRef;

/**
 * A reference to an orc::ResourceTracker instance. 
 */
typedef struct LLVMOrcOpaqueResourceTracker *LLVMOrcResourceTrackerRef; 

/**
 * A reference to an orc::DefinitionGenerator. 
 */ 
typedef struct LLVMOrcOpaqueDefinitionGenerator 
    *LLVMOrcDefinitionGeneratorRef; 
 
/** 
 * An opaque lookup state object. Instances of this type can be captured to 
 * suspend a lookup while a custom generator function attempts to produce a 
 * definition. 
 * 
 * If a client captures a lookup state object then they must eventually call 
 * LLVMOrcLookupStateContinueLookup to restart the lookup. This is required 
 * in order to release memory allocated for the lookup state, even if errors 
 * have occurred while the lookup was suspended (if these errors have made the 
 * lookup impossible to complete then it will issue its own error before 
 * destruction). 
 */ 
typedef struct LLVMOrcOpaqueLookupState *LLVMOrcLookupStateRef; 
 
/** 
 * A custom generator function. This can be used to create a custom generator 
 * object using LLVMOrcCreateCustomCAPIDefinitionGenerator. The resulting 
 * object can be attached to a JITDylib, via LLVMOrcJITDylibAddGenerator, to 
 * receive callbacks when lookups fail to match existing definitions. 
 * 
 * GeneratorObj will contain the address of the custom generator object. 
 * 
 * Ctx will contain the context object passed to 
 * LLVMOrcCreateCustomCAPIDefinitionGenerator. 
 * 
 * LookupState will contain a pointer to an LLVMOrcLookupStateRef object. This 
 * can optionally be modified to make the definition generation process 
 * asynchronous: If the LookupStateRef value is copied, and the original 
 * LLVMOrcLookupStateRef set to null, the lookup will be suspended. Once the 
 * asynchronous definition process has been completed clients must call 
 * LLVMOrcLookupStateContinueLookup to continue the lookup (this should be 
 * done unconditionally, even if errors have occurred in the mean time, to 
 * free the lookup state memory and notify the query object of the failures. If 
 * LookupState is captured this function must return LLVMErrorSuccess. 
 * 
 * The Kind argument can be inspected to determine the lookup kind (e.g. 
 * as-if-during-static-link, or as-if-during-dlsym). 
 * 
 * The JD argument specifies which JITDylib the definitions should be generated 
 * into. 
 * 
 * The JDLookupFlags argument can be inspected to determine whether the original 
 * lookup included non-exported symobls. 
 * 
 * Finally, the LookupSet argument contains the set of symbols that could not 
 * be found in JD already (the set of generation candidates). 
 */ 
typedef LLVMErrorRef (*LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction)( 
    LLVMOrcDefinitionGeneratorRef GeneratorObj, void *Ctx, 
    LLVMOrcLookupStateRef *LookupState, LLVMOrcLookupKind Kind, 
    LLVMOrcJITDylibRef JD, LLVMOrcJITDylibLookupFlags JDLookupFlags, 
    LLVMOrcCLookupSet LookupSet, size_t LookupSetSize); 
 
/** 
 * Predicate function for SymbolStringPoolEntries.
 */
typedef int (*LLVMOrcSymbolPredicate)(void *Ctx, 
                                      LLVMOrcSymbolStringPoolEntryRef Sym); 

/**
 * A reference to an orc::ThreadSafeContext instance.
 */
typedef struct LLVMOrcOpaqueThreadSafeContext *LLVMOrcThreadSafeContextRef;

/**
 * A reference to an orc::ThreadSafeModule instance.
 */
typedef struct LLVMOrcOpaqueThreadSafeModule *LLVMOrcThreadSafeModuleRef;

/**
 * A reference to an orc::JITTargetMachineBuilder instance.
 */
typedef struct LLVMOrcOpaqueJITTargetMachineBuilder
    *LLVMOrcJITTargetMachineBuilderRef;

/**
 * A reference to an orc::ObjectLayer instance. 
 */
typedef struct LLVMOrcOpaqueObjectLayer *LLVMOrcObjectLayerRef; 

/**
 * Attach a custom error reporter function to the ExecutionSession. 
 * 
 * The error reporter will be called to deliver failure notices that can not be 
 * directly reported to a caller. For example, failure to resolve symbols in 
 * the JIT linker is typically reported via the error reporter (callers 
 * requesting definitions from the JIT will typically be delivered a 
 * FailureToMaterialize error instead). 
 */
void LLVMOrcExecutionSessionSetErrorReporter( 
    LLVMOrcExecutionSessionRef ES, LLVMOrcErrorReporterFunction ReportError, 
    void *Ctx); 

/**
 * Return a reference to the SymbolStringPool for an ExecutionSession. 
 * 
 * Ownership of the pool remains with the ExecutionSession: The caller is 
 * not required to free the pool. 
 */ 
LLVMOrcSymbolStringPoolRef 
LLVMOrcExecutionSessionGetSymbolStringPool(LLVMOrcExecutionSessionRef ES); 
 
/** 
 * Clear all unreferenced symbol string pool entries. 
 * 
 * This can be called at any time to release unused entries in the 
 * ExecutionSession's string pool. Since it locks the pool (preventing 
 * interning of any new strings) it is recommended that it only be called 
 * infrequently, ideally when the caller has reason to believe that some 
 * entries will have become unreferenced, e.g. after removing a module or 
 * closing a JITDylib. 
 */ 
void LLVMOrcSymbolStringPoolClearDeadEntries(LLVMOrcSymbolStringPoolRef SSP); 
 
/** 
 * Intern a string in the ExecutionSession's SymbolStringPool and return a
 * reference to it. This increments the ref-count of the pool entry, and the
 * returned value should be released once the client is done with it by
 * calling LLVMOrReleaseSymbolStringPoolEntry.
 *
 * Since strings are uniqued within the SymbolStringPool
 * LLVMOrcSymbolStringPoolEntryRefs can be compared by value to test string
 * equality.
 *
 * Note that this function does not perform linker-mangling on the string.
 */
LLVMOrcSymbolStringPoolEntryRef
LLVMOrcExecutionSessionIntern(LLVMOrcExecutionSessionRef ES, const char *Name);

/**
 * Increments the ref-count for a SymbolStringPool entry. 
 */ 
void LLVMOrcRetainSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S); 
 
/** 
 * Reduces the ref-count for of a SymbolStringPool entry.
 */
void LLVMOrcReleaseSymbolStringPoolEntry(LLVMOrcSymbolStringPoolEntryRef S);

const char *LLVMOrcSymbolStringPoolEntryStr(LLVMOrcSymbolStringPoolEntryRef S); 
 
/**
 * Reduces the ref-count of a ResourceTracker. 
 */ 
void LLVMOrcReleaseResourceTracker(LLVMOrcResourceTrackerRef RT); 
 
/** 
 * Transfers tracking of all resources associated with resource tracker SrcRT 
 * to resource tracker DstRT. 
 */ 
void LLVMOrcResourceTrackerTransferTo(LLVMOrcResourceTrackerRef SrcRT, 
                                      LLVMOrcResourceTrackerRef DstRT); 
 
/** 
 * Remove all resources associated with the given tracker. See 
 * ResourceTracker::remove(). 
 */ 
LLVMErrorRef LLVMOrcResourceTrackerRemove(LLVMOrcResourceTrackerRef RT); 
 
/** 
 * Dispose of a JITDylib::DefinitionGenerator. This should only be called if
 * ownership has not been passed to a JITDylib (e.g. because some error
 * prevented the client from calling LLVMOrcJITDylibAddGenerator).
 */
void LLVMOrcDisposeDefinitionGenerator(LLVMOrcDefinitionGeneratorRef DG); 

/**
 * Dispose of a MaterializationUnit. 
 */ 
void LLVMOrcDisposeMaterializationUnit(LLVMOrcMaterializationUnitRef MU); 
 
/** 
 * Create a MaterializationUnit to define the given symbols as pointing to 
 * the corresponding raw addresses. 
 */ 
LLVMOrcMaterializationUnitRef 
LLVMOrcAbsoluteSymbols(LLVMOrcCSymbolMapPairs Syms, size_t NumPairs); 
 
/** 
 * Create a "bare" JITDylib. 
 *
 * The client is responsible for ensuring that the JITDylib's name is unique, 
 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first. 
 * 
 * This call does not install any library code or symbols into the newly 
 * created JITDylib. The client is responsible for all configuration. 
 */ 
LLVMOrcJITDylibRef 
LLVMOrcExecutionSessionCreateBareJITDylib(LLVMOrcExecutionSessionRef ES, 
                                          const char *Name); 
 
/** 
 * Create a JITDylib. 
 * 
 * The client is responsible for ensuring that the JITDylib's name is unique, 
 * e.g. by calling LLVMOrcExecutionSessionGetJTIDylibByName first. 
 * 
 * If a Platform is attached to the ExecutionSession then 
 * Platform::setupJITDylib will be called to install standard platform symbols 
 * (e.g. standard library interposes). If no Platform is installed then this 
 * call is equivalent to LLVMExecutionSessionRefCreateBareJITDylib and will 
 * always return success. 
 */ 
LLVMErrorRef 
LLVMOrcExecutionSessionCreateJITDylib(LLVMOrcExecutionSessionRef ES, 
                                      LLVMOrcJITDylibRef *Result, 
                                      const char *Name); 
 
/** 
 * Returns the JITDylib with the given name, or NULL if no such JITDylib 
 * exists. 
 */ 
LLVMOrcJITDylibRef 
LLVMOrcExecutionSessionGetJITDylibByName(LLVMOrcExecutionSessionRef ES, 
                                         const char *Name); 
 
/** 
 * Return a reference to a newly created resource tracker associated with JD. 
 * The tracker is returned with an initial ref-count of 1, and must be released 
 * with LLVMOrcReleaseResourceTracker when no longer needed. 
 */ 
LLVMOrcResourceTrackerRef 
LLVMOrcJITDylibCreateResourceTracker(LLVMOrcJITDylibRef JD); 
 
/** 
 * Return a reference to the default resource tracker for the given JITDylib. 
 * This operation will increase the retain count of the tracker: Clients should 
 * call LLVMOrcReleaseResourceTracker when the result is no longer needed. 
 */ 
LLVMOrcResourceTrackerRef 
LLVMOrcJITDylibGetDefaultResourceTracker(LLVMOrcJITDylibRef JD); 
 
/** 
 * Add the given MaterializationUnit to the given JITDylib. 
 * 
 * If this operation succeeds then JITDylib JD will take ownership of MU. 
 * If the operation fails then ownership remains with the caller who should 
 * call LLVMOrcDisposeMaterializationUnit to destroy it. 
 */ 
LLVMErrorRef LLVMOrcJITDylibDefine(LLVMOrcJITDylibRef JD, 
                                   LLVMOrcMaterializationUnitRef MU); 
 
/** 
 * Calls remove on all trackers associated with this JITDylib, see 
 * JITDylib::clear(). 
 */ 
LLVMErrorRef LLVMOrcJITDylibClear(LLVMOrcJITDylibRef JD); 
 
/** 
 * Add a DefinitionGenerator to the given JITDylib. 
 * 
 * The JITDylib will take ownership of the given generator: The client is no
 * longer responsible for managing its memory.
 */
void LLVMOrcJITDylibAddGenerator(LLVMOrcJITDylibRef JD,
                                 LLVMOrcDefinitionGeneratorRef DG); 

/**
 * Create a custom generator. 
 */ 
LLVMOrcDefinitionGeneratorRef LLVMOrcCreateCustomCAPIDefinitionGenerator( 
    LLVMOrcCAPIDefinitionGeneratorTryToGenerateFunction F, void *Ctx); 
 
/** 
 * Get a DynamicLibrarySearchGenerator that will reflect process symbols into
 * the JITDylib. On success the resulting generator is owned by the client.
 * Ownership is typically transferred by adding the instance to a JITDylib
 * using LLVMOrcJITDylibAddGenerator,
 *
 * The GlobalPrefix argument specifies the character that appears on the front
 * of linker-mangled symbols for the target platform (e.g. '_' on MachO).
 * If non-null, this character will be stripped from the start of all symbol
 * strings before passing the remaining substring to dlsym.
 *
 * The optional Filter and Ctx arguments can be used to supply a symbol name
 * filter: Only symbols for which the filter returns true will be visible to
 * JIT'd code. If the Filter argument is null then all process symbols will
 * be visible to JIT'd code. Note that the symbol name passed to the Filter
 * function is the full mangled symbol: The client is responsible for stripping
 * the global prefix if present.
 */
LLVMErrorRef LLVMOrcCreateDynamicLibrarySearchGeneratorForProcess(
    LLVMOrcDefinitionGeneratorRef *Result, char GlobalPrefx, 
    LLVMOrcSymbolPredicate Filter, void *FilterCtx);

/**
 * Create a ThreadSafeContext containing a new LLVMContext.
 *
 * Ownership of the underlying ThreadSafeContext data is shared: Clients
 * can and should dispose of their ThreadSafeContext as soon as they no longer
 * need to refer to it directly. Other references (e.g. from ThreadSafeModules) 
 * will keep the data alive as long as it is needed.
 */
LLVMOrcThreadSafeContextRef LLVMOrcCreateNewThreadSafeContext(void);

/**
 * Get a reference to the wrapped LLVMContext.
 */
LLVMContextRef
LLVMOrcThreadSafeContextGetContext(LLVMOrcThreadSafeContextRef TSCtx);

/**
 * Dispose of a ThreadSafeContext.
 */
void LLVMOrcDisposeThreadSafeContext(LLVMOrcThreadSafeContextRef TSCtx);

/**
 * Create a ThreadSafeModule wrapper around the given LLVM module. This takes
 * ownership of the M argument which should not be disposed of or referenced
 * after this function returns.
 *
 * Ownership of the ThreadSafeModule is unique: If it is transferred to the JIT
 * (e.g. by LLVMOrcLLJITAddLLVMIRModule) then the client is no longer 
 * responsible for it. If it is not transferred to the JIT then the client
 * should call LLVMOrcDisposeThreadSafeModule to dispose of it.
 */
LLVMOrcThreadSafeModuleRef
LLVMOrcCreateNewThreadSafeModule(LLVMModuleRef M,
                                 LLVMOrcThreadSafeContextRef TSCtx);

/**
 * Dispose of a ThreadSafeModule. This should only be called if ownership has
 * not been passed to LLJIT (e.g. because some error prevented the client from
 * adding this to the JIT).
 */
void LLVMOrcDisposeThreadSafeModule(LLVMOrcThreadSafeModuleRef TSM);

/**
 * Create a JITTargetMachineBuilder by detecting the host.
 *
 * On success the client owns the resulting JITTargetMachineBuilder. It must be
 * passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder) or disposed
 * of by calling LLVMOrcDisposeJITTargetMachineBuilder.
 */
LLVMErrorRef LLVMOrcJITTargetMachineBuilderDetectHost(
    LLVMOrcJITTargetMachineBuilderRef *Result);

/**
 * Create a JITTargetMachineBuilder from the given TargetMachine template.
 *
 * This operation takes ownership of the given TargetMachine and destroys it
 * before returing. The resulting JITTargetMachineBuilder is owned by the client
 * and must be passed to a consuming operation (e.g. LLVMOrcCreateLLJITBuilder)
 * or disposed of by calling LLVMOrcDisposeJITTargetMachineBuilder.
 */
LLVMOrcJITTargetMachineBuilderRef
LLVMOrcJITTargetMachineBuilderCreateFromTargetMachine(LLVMTargetMachineRef TM);

/**
 * Dispose of a JITTargetMachineBuilder.
 */
void LLVMOrcDisposeJITTargetMachineBuilder(
    LLVMOrcJITTargetMachineBuilderRef JTMB);

/**
 * Dispose of an ObjectLayer. 
 */
void LLVMOrcDisposeObjectLayer(LLVMOrcObjectLayerRef ObjLayer); 

LLVM_C_EXTERN_C_END

#endif /* LLVM_C_ORC_H */

#ifdef __GNUC__
#pragma GCC diagnostic pop
#endif