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_H 25#define LLVM_C_LLJIT_H 26 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 32LLVM_C_EXTERN_C_BEGIN 33 34/** 35 * @defgroup LLVMCExecutionEngineLLJIT LLJIT 36 * @ingroup LLVMCExecutionEngine 37 * 38 * @{ 39 */ 40 41/** 42 * A function for constructing an ObjectLinkingLayer instance to be used 43 * by an LLJIT instance. 44 * 45 * Clients can call LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator to 46 * set the creator function to use when constructing an LLJIT instance. 47 * This can be used to override the default linking layer implementation 48 * that would otherwise be chosen by LLJITBuilder. 49 * 50 * Object linking layers returned by this function will become owned by the 51 * LLJIT instance. The client is not responsible for managing their lifetimes 52 * after the function returns. 53 */ 54typedef LLVMOrcObjectLayerRef ( 55 *LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction)( 56 void *Ctx, LLVMOrcExecutionSessionRef ES, const char *Triple); 57 58/** 59 * A reference to an orc::LLJITBuilder instance. 60 */ 61typedef struct LLVMOrcOpaqueLLJITBuilder *LLVMOrcLLJITBuilderRef; 62 63/** 64 * A reference to an orc::LLJIT instance. 65 */ 66typedef struct LLVMOrcOpaqueLLJIT *LLVMOrcLLJITRef; 67 68/** 69 * Create an LLVMOrcLLJITBuilder. 70 * 71 * The client owns the resulting LLJITBuilder and should dispose of it using 72 * LLVMOrcDisposeLLJITBuilder once they are done with it. 73 */ 74LLVMOrcLLJITBuilderRef LLVMOrcCreateLLJITBuilder(void); 75 76/** 77 * Dispose of an LLVMOrcLLJITBuilderRef. This should only be called if ownership 78 * has not been passed to LLVMOrcCreateLLJIT (e.g. because some error prevented 79 * that function from being called). 80 */ 81void LLVMOrcDisposeLLJITBuilder(LLVMOrcLLJITBuilderRef Builder); 82 83/** 84 * Set the JITTargetMachineBuilder to be used when constructing the LLJIT 85 * instance. Calling this function is optional: if it is not called then the 86 * LLJITBuilder will use JITTargeTMachineBuilder::detectHost to construct a 87 * JITTargetMachineBuilder. 88 * 89 * This function takes ownership of the JTMB argument: clients should not 90 * dispose of the JITTargetMachineBuilder after calling this function. 91 */ 92void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder( 93 LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB); 94 95/** 96 * Set an ObjectLinkingLayer creator function for this LLJIT instance. 97 */ 98void LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator( 99 LLVMOrcLLJITBuilderRef Builder, 100 LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction F, void *Ctx); 101 102/** 103 * Create an LLJIT instance from an LLJITBuilder. 104 * 105 * This operation takes ownership of the Builder argument: clients should not 106 * dispose of the builder after calling this function (even if the function 107 * returns an error). If a null Builder argument is provided then a 108 * default-constructed LLJITBuilder will be used. 109 * 110 * On success the resulting LLJIT instance is uniquely owned by the client and 111 * automatically manages the memory of all JIT'd code and all modules that are 112 * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the 113 * LLJIT instance will free all memory managed by the JIT, including JIT'd code 114 * and not-yet compiled modules. 115 */ 116LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result, 117 LLVMOrcLLJITBuilderRef Builder); 118 119/** 120 * Dispose of an LLJIT instance. 121 */ 122LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J); 123 124/** 125 * Get a reference to the ExecutionSession for this LLJIT instance. 126 * 127 * The ExecutionSession is owned by the LLJIT instance. The client is not 128 * responsible for managing its memory. 129 */ 130LLVMOrcExecutionSessionRef LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J); 131 132/** 133 * Return a reference to the Main JITDylib. 134 * 135 * The JITDylib is owned by the LLJIT instance. The client is not responsible 136 * for managing its memory. 137 */ 138LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J); 139 140/** 141 * Return the target triple for this LLJIT instance. This string is owned by 142 * the LLJIT instance and should not be freed by the client. 143 */ 144const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J); 145 146/** 147 * Returns the global prefix character according to the LLJIT's DataLayout. 148 */ 149char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J); 150 151/** 152 * Mangles the given string according to the LLJIT instance's DataLayout, then 153 * interns the result in the SymbolStringPool and returns a reference to the 154 * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to 155 * decrement the ref-count on the pool entry once they are finished with this 156 * value. 157 */ 158LLVMOrcSymbolStringPoolEntryRef 159LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName); 160 161/** 162 * Add a buffer representing an object file to the given JITDylib in the given 163 * LLJIT instance. This operation transfers ownership of the buffer to the 164 * LLJIT instance. The buffer should not be disposed of or referenced once this 165 * function returns. 166 * 167 * Resources associated with the given object will be tracked by the given 168 * JITDylib's default resource tracker. 169 */ 170LLVMErrorRef LLVMOrcLLJITAddObjectFile(LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD, 171 LLVMMemoryBufferRef ObjBuffer); 172 173/** 174 * Add a buffer representing an object file to the given ResourceTracker's 175 * JITDylib in the given LLJIT instance. This operation transfers ownership of 176 * the buffer to the LLJIT instance. The buffer should not be disposed of or 177 * referenced once this function returns. 178 * 179 * Resources associated with the given object will be tracked by ResourceTracker 180 * RT. 181 */ 182LLVMErrorRef LLVMOrcLLJITAddObjectFileWithRT(LLVMOrcLLJITRef J, 183 LLVMOrcResourceTrackerRef RT, 184 LLVMMemoryBufferRef ObjBuffer); 185 186/** 187 * Add an IR module to the given JITDylib in the given LLJIT instance. This 188 * operation transfers ownership of the TSM argument to the LLJIT instance. 189 * The TSM argument should not be disposed of or referenced once this 190 * function returns. 191 * 192 * Resources associated with the given Module will be tracked by the given 193 * JITDylib's default resource tracker. 194 */ 195LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule(LLVMOrcLLJITRef J, 196 LLVMOrcJITDylibRef JD, 197 LLVMOrcThreadSafeModuleRef TSM); 198 199/** 200 * Add an IR module to the given ResourceTracker's JITDylib in the given LLJIT 201 * instance. This operation transfers ownership of the TSM argument to the LLJIT 202 * instance. The TSM argument should not be disposed of or referenced once this 203 * function returns. 204 * 205 * Resources associated with the given Module will be tracked by ResourceTracker 206 * RT. 207 */ 208LLVMErrorRef LLVMOrcLLJITAddLLVMIRModuleWithRT(LLVMOrcLLJITRef J, 209 LLVMOrcResourceTrackerRef JD, 210 LLVMOrcThreadSafeModuleRef TSM); 211 212/** 213 * Look up the given symbol in the main JITDylib of the given LLJIT instance. 214 * 215 * This operation does not take ownership of the Name argument. 216 */ 217LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J, 218 LLVMOrcExecutorAddress *Result, 219 const char *Name); 220 221/** 222 * Returns a non-owning reference to the LLJIT instance's object linking layer. 223 */ 224LLVMOrcObjectLayerRef LLVMOrcLLJITGetObjLinkingLayer(LLVMOrcLLJITRef J); 225 226/** 227 * Returns a non-owning reference to the LLJIT instance's object linking layer. 228 */ 229LLVMOrcObjectTransformLayerRef 230LLVMOrcLLJITGetObjTransformLayer(LLVMOrcLLJITRef J); 231 232/** 233 * Returns a non-owning reference to the LLJIT instance's IR transform layer. 234 */ 235LLVMOrcIRTransformLayerRef LLVMOrcLLJITGetIRTransformLayer(LLVMOrcLLJITRef J); 236 237/** 238 * Get the LLJIT instance's default data layout string. 239 * 240 * This string is owned by the LLJIT instance and does not need to be freed 241 * by the caller. 242 */ 243const char *LLVMOrcLLJITGetDataLayoutStr(LLVMOrcLLJITRef J); 244 245/** 246 * @} 247 */ 248 249LLVM_C_EXTERN_C_END 250 251#endif /* LLVM_C_LLJIT_H */ 252