255 lines · c
1/*===----------- llvm-c/LLJIT.h - OrcV2 LLJIT 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 the LLJIT class in *|11|* libLLVMOrcJIT.a, which provides a simple MCJIT-like ORC JIT. *|12|* *|13|* Many exotic languages can interoperate with C code but have a harder time *|14|* with C++ due to name mangling. So in addition to C, this interface enables *|15|* tools written in such languages. *|16|* *|17|* Note: This interface is experimental. It is *NOT* stable, and may be *|18|* changed without warning. Only C API usage documentation is *|19|* provided. See the C++ documentation for all higher level ORC API *|20|* details. *|21|* *|22\*===----------------------------------------------------------------------===*/23 24#ifndef LLVM_C_LLJIT_H25#define LLVM_C_LLJIT_H26 27#include "llvm-c/Error.h"28#include "llvm-c/Orc.h"29#include "llvm-c/TargetMachine.h"30#include "llvm-c/Types.h"31#include "llvm-c/Visibility.h"32 33LLVM_C_EXTERN_C_BEGIN34 35/**36 * @defgroup LLVMCExecutionEngineLLJIT LLJIT37 * @ingroup LLVMCExecutionEngine38 *39 * @{40 */41 42/**43 * A function for constructing an ObjectLinkingLayer instance to be used44 * by an LLJIT instance.45 *46 * Clients can call LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator to47 * set the creator function to use when constructing an LLJIT instance.48 * This can be used to override the default linking layer implementation49 * that would otherwise be chosen by LLJITBuilder.50 *51 * Object linking layers returned by this function will become owned by the52 * LLJIT instance. The client is not responsible for managing their lifetimes53 * after the function returns.54 */55typedef LLVMOrcObjectLayerRef (56 *LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction)(57 void *Ctx, LLVMOrcExecutionSessionRef ES, const char *Triple);58 59/**60 * A reference to an orc::LLJITBuilder instance.61 */62typedef struct LLVMOrcOpaqueLLJITBuilder *LLVMOrcLLJITBuilderRef;63 64/**65 * A reference to an orc::LLJIT instance.66 */67typedef struct LLVMOrcOpaqueLLJIT *LLVMOrcLLJITRef;68 69/**70 * Create an LLVMOrcLLJITBuilder.71 *72 * The client owns the resulting LLJITBuilder and should dispose of it using73 * LLVMOrcDisposeLLJITBuilder once they are done with it.74 */75LLVM_C_ABI LLVMOrcLLJITBuilderRef LLVMOrcCreateLLJITBuilder(void);76 77/**78 * Dispose of an LLVMOrcLLJITBuilderRef. This should only be called if ownership79 * has not been passed to LLVMOrcCreateLLJIT (e.g. because some error prevented80 * that function from being called).81 */82LLVM_C_ABI void LLVMOrcDisposeLLJITBuilder(LLVMOrcLLJITBuilderRef Builder);83 84/**85 * Set the JITTargetMachineBuilder to be used when constructing the LLJIT86 * instance. Calling this function is optional: if it is not called then the87 * LLJITBuilder will use JITTargeTMachineBuilder::detectHost to construct a88 * JITTargetMachineBuilder.89 *90 * This function takes ownership of the JTMB argument: clients should not91 * dispose of the JITTargetMachineBuilder after calling this function.92 */93LLVM_C_ABI void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder(94 LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB);95 96/**97 * Set an ObjectLinkingLayer creator function for this LLJIT instance.98 */99LLVM_C_ABI void LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator(100 LLVMOrcLLJITBuilderRef Builder,101 LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction F, void *Ctx);102 103/**104 * Create an LLJIT instance from an LLJITBuilder.105 *106 * This operation takes ownership of the Builder argument: clients should not107 * dispose of the builder after calling this function (even if the function108 * returns an error). If a null Builder argument is provided then a109 * default-constructed LLJITBuilder will be used.110 *111 * On success the resulting LLJIT instance is uniquely owned by the client and112 * automatically manages the memory of all JIT'd code and all modules that are113 * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the114 * LLJIT instance will free all memory managed by the JIT, including JIT'd code115 * and not-yet compiled modules.116 */117LLVM_C_ABI LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result,118 LLVMOrcLLJITBuilderRef Builder);119 120/**121 * Dispose of an LLJIT instance.122 */123LLVM_C_ABI LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J);124 125/**126 * Get a reference to the ExecutionSession for this LLJIT instance.127 *128 * The ExecutionSession is owned by the LLJIT instance. The client is not129 * responsible for managing its memory.130 */131LLVM_C_ABI LLVMOrcExecutionSessionRef132LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J);133 134/**135 * Return a reference to the Main JITDylib.136 *137 * The JITDylib is owned by the LLJIT instance. The client is not responsible138 * for managing its memory.139 */140LLVM_C_ABI LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J);141 142/**143 * Return the target triple for this LLJIT instance. This string is owned by144 * the LLJIT instance and should not be freed by the client.145 */146LLVM_C_ABI const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J);147 148/**149 * Returns the global prefix character according to the LLJIT's DataLayout.150 */151LLVM_C_ABI char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J);152 153/**154 * Mangles the given string according to the LLJIT instance's DataLayout, then155 * interns the result in the SymbolStringPool and returns a reference to the156 * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to157 * decrement the ref-count on the pool entry once they are finished with this158 * value.159 */160LLVM_C_ABI LLVMOrcSymbolStringPoolEntryRef161LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName);162 163/**164 * Add a buffer representing an object file to the given JITDylib in the given165 * LLJIT instance. This operation transfers ownership of the buffer to the166 * LLJIT instance. The buffer should not be disposed of or referenced once this167 * function returns.168 *169 * Resources associated with the given object will be tracked by the given170 * JITDylib's default resource tracker.171 */172LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITAddObjectFile(173 LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD, LLVMMemoryBufferRef ObjBuffer);174 175/**176 * Add a buffer representing an object file to the given ResourceTracker's177 * JITDylib in the given LLJIT instance. This operation transfers ownership of178 * the buffer to the LLJIT instance. The buffer should not be disposed of or179 * referenced once this function returns.180 *181 * Resources associated with the given object will be tracked by ResourceTracker182 * RT.183 */184LLVM_C_ABI LLVMErrorRef185LLVMOrcLLJITAddObjectFileWithRT(LLVMOrcLLJITRef J, LLVMOrcResourceTrackerRef RT,186 LLVMMemoryBufferRef ObjBuffer);187 188/**189 * Add an IR module to the given JITDylib in the given LLJIT instance. This190 * operation transfers ownership of the TSM argument to the LLJIT instance.191 * The TSM argument should not be disposed of or referenced once this192 * function returns.193 *194 * Resources associated with the given Module will be tracked by the given195 * JITDylib's default resource tracker.196 */197LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule(198 LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD, LLVMOrcThreadSafeModuleRef TSM);199 200/**201 * Add an IR module to the given ResourceTracker's JITDylib in the given LLJIT202 * instance. This operation transfers ownership of the TSM argument to the LLJIT203 * instance. The TSM argument should not be disposed of or referenced once this204 * function returns.205 *206 * Resources associated with the given Module will be tracked by ResourceTracker207 * RT.208 */209LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITAddLLVMIRModuleWithRT(210 LLVMOrcLLJITRef J, LLVMOrcResourceTrackerRef JD,211 LLVMOrcThreadSafeModuleRef TSM);212 213/**214 * Look up the given symbol in the main JITDylib of the given LLJIT instance.215 *216 * This operation does not take ownership of the Name argument.217 */218LLVM_C_ABI LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J,219 LLVMOrcExecutorAddress *Result,220 const char *Name);221 222/**223 * Returns a non-owning reference to the LLJIT instance's object linking layer.224 */225LLVM_C_ABI LLVMOrcObjectLayerRef226LLVMOrcLLJITGetObjLinkingLayer(LLVMOrcLLJITRef J);227 228/**229 * Returns a non-owning reference to the LLJIT instance's object linking layer.230 */231LLVM_C_ABI LLVMOrcObjectTransformLayerRef232LLVMOrcLLJITGetObjTransformLayer(LLVMOrcLLJITRef J);233 234/**235 * Returns a non-owning reference to the LLJIT instance's IR transform layer.236 */237LLVM_C_ABI LLVMOrcIRTransformLayerRef238LLVMOrcLLJITGetIRTransformLayer(LLVMOrcLLJITRef J);239 240/**241 * Get the LLJIT instance's default data layout string.242 *243 * This string is owned by the LLJIT instance and does not need to be freed244 * by the caller.245 */246LLVM_C_ABI const char *LLVMOrcLLJITGetDataLayoutStr(LLVMOrcLLJITRef J);247 248/**249 * @}250 */251 252LLVM_C_EXTERN_C_END253 254#endif /* LLVM_C_LLJIT_H */255