include/llvm-c/LLJIT.h

0001 /*===----------- llvm-c/LLJIT.h - OrcV2 LLJIT C bindings ----------*- C -*-===*\
0002 |*                                                                            *|
0003 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
0004 |* Exceptions.                                                                *|
0005 |* See https://llvm.org/LICENSE.txt for license information.                  *|
0006 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
0007 |*                                                                            *|
0008 |*===----------------------------------------------------------------------===*|
0009 |*                                                                            *|
0010 |* This header declares the C interface to the LLJIT class in                 *|
0011 |* libLLVMOrcJIT.a, which provides a simple MCJIT-like ORC JIT.               *|
0012 |*                                                                            *|
0013 |* Many exotic languages can interoperate with C code but have a harder time  *|
0014 |* with C++ due to name mangling. So in addition to C, this interface enables *|
0015 |* tools written in such languages.                                           *|
0016 |*                                                                            *|
0017 |* Note: This interface is experimental. It is *NOT* stable, and may be       *|
0018 |*       changed without warning. Only C API usage documentation is           *|
0019 |*       provided. See the C++ documentation for all higher level ORC API     *|
0020 |*       details.                                                             *|
0021 |*                                                                            *|
0022 \*===----------------------------------------------------------------------===*/
0023
0024 #ifndef LLVM_C_LLJIT_H
0025 #define LLVM_C_LLJIT_H
0026
0027 #include "llvm-c/Error.h"
0028 #include "llvm-c/Orc.h"
0029 #include "llvm-c/TargetMachine.h"
0030 #include "llvm-c/Types.h"
0031
0032 LLVM_C_EXTERN_C_BEGIN
0033
0034 /**
0035  * @defgroup LLVMCExecutionEngineLLJIT LLJIT
0036  * @ingroup LLVMCExecutionEngine
0037  *
0038  * @{
0039  */
0040
0041 /**
0042  * A function for constructing an ObjectLinkingLayer instance to be used
0043  * by an LLJIT instance.
0044  *
0045  * Clients can call LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator to
0046  * set the creator function to use when constructing an LLJIT instance.
0047  * This can be used to override the default linking layer implementation
0048  * that would otherwise be chosen by LLJITBuilder.
0049  *
0050  * Object linking layers returned by this function will become owned by the
0051  * LLJIT instance. The client is not responsible for managing their lifetimes
0052  * after the function returns.
0053  */
0054 typedef LLVMOrcObjectLayerRef (
0055     *LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction)(
0056     void *Ctx, LLVMOrcExecutionSessionRef ES, const char *Triple);
0057
0058 /**
0059  * A reference to an orc::LLJITBuilder instance.
0060  */
0061 typedef struct LLVMOrcOpaqueLLJITBuilder *LLVMOrcLLJITBuilderRef;
0062
0063 /**
0064  * A reference to an orc::LLJIT instance.
0065  */
0066 typedef struct LLVMOrcOpaqueLLJIT *LLVMOrcLLJITRef;
0067
0068 /**
0069  * Create an LLVMOrcLLJITBuilder.
0070  *
0071  * The client owns the resulting LLJITBuilder and should dispose of it using
0072  * LLVMOrcDisposeLLJITBuilder once they are done with it.
0073  */
0074 LLVMOrcLLJITBuilderRef LLVMOrcCreateLLJITBuilder(void);
0075
0076 /**
0077  * Dispose of an LLVMOrcLLJITBuilderRef. This should only be called if ownership
0078  * has not been passed to LLVMOrcCreateLLJIT (e.g. because some error prevented
0079  * that function from being called).
0080  */
0081 void LLVMOrcDisposeLLJITBuilder(LLVMOrcLLJITBuilderRef Builder);
0082
0083 /**
0084  * Set the JITTargetMachineBuilder to be used when constructing the LLJIT
0085  * instance. Calling this function is optional: if it is not called then the
0086  * LLJITBuilder will use JITTargeTMachineBuilder::detectHost to construct a
0087  * JITTargetMachineBuilder.
0088  *
0089  * This function takes ownership of the JTMB argument: clients should not
0090  * dispose of the JITTargetMachineBuilder after calling this function.
0091  */
0092 void LLVMOrcLLJITBuilderSetJITTargetMachineBuilder(
0093     LLVMOrcLLJITBuilderRef Builder, LLVMOrcJITTargetMachineBuilderRef JTMB);
0094
0095 /**
0096  * Set an ObjectLinkingLayer creator function for this LLJIT instance.
0097  */
0098 void LLVMOrcLLJITBuilderSetObjectLinkingLayerCreator(
0099     LLVMOrcLLJITBuilderRef Builder,
0100     LLVMOrcLLJITBuilderObjectLinkingLayerCreatorFunction F, void *Ctx);
0101
0102 /**
0103  * Create an LLJIT instance from an LLJITBuilder.
0104  *
0105  * This operation takes ownership of the Builder argument: clients should not
0106  * dispose of the builder after calling this function (even if the function
0107  * returns an error). If a null Builder argument is provided then a
0108  * default-constructed LLJITBuilder will be used.
0109  *
0110  * On success the resulting LLJIT instance is uniquely owned by the client and
0111  * automatically manages the memory of all JIT'd code and all modules that are
0112  * transferred to it (e.g. via LLVMOrcLLJITAddLLVMIRModule). Disposing of the
0113  * LLJIT instance will free all memory managed by the JIT, including JIT'd code
0114  * and not-yet compiled modules.
0115  */
0116 LLVMErrorRef LLVMOrcCreateLLJIT(LLVMOrcLLJITRef *Result,
0117                                 LLVMOrcLLJITBuilderRef Builder);
0118
0119 /**
0120  * Dispose of an LLJIT instance.
0121  */
0122 LLVMErrorRef LLVMOrcDisposeLLJIT(LLVMOrcLLJITRef J);
0123
0124 /**
0125  * Get a reference to the ExecutionSession for this LLJIT instance.
0126  *
0127  * The ExecutionSession is owned by the LLJIT instance. The client is not
0128  * responsible for managing its memory.
0129  */
0130 LLVMOrcExecutionSessionRef LLVMOrcLLJITGetExecutionSession(LLVMOrcLLJITRef J);
0131
0132 /**
0133  * Return a reference to the Main JITDylib.
0134  *
0135  * The JITDylib is owned by the LLJIT instance. The client is not responsible
0136  * for managing its memory.
0137  */
0138 LLVMOrcJITDylibRef LLVMOrcLLJITGetMainJITDylib(LLVMOrcLLJITRef J);
0139
0140 /**
0141  * Return the target triple for this LLJIT instance. This string is owned by
0142  * the LLJIT instance and should not be freed by the client.
0143  */
0144 const char *LLVMOrcLLJITGetTripleString(LLVMOrcLLJITRef J);
0145
0146 /**
0147  * Returns the global prefix character according to the LLJIT's DataLayout.
0148  */
0149 char LLVMOrcLLJITGetGlobalPrefix(LLVMOrcLLJITRef J);
0150
0151 /**
0152  * Mangles the given string according to the LLJIT instance's DataLayout, then
0153  * interns the result in the SymbolStringPool and returns a reference to the
0154  * pool entry. Clients should call LLVMOrcReleaseSymbolStringPoolEntry to
0155  * decrement the ref-count on the pool entry once they are finished with this
0156  * value.
0157  */
0158 LLVMOrcSymbolStringPoolEntryRef
0159 LLVMOrcLLJITMangleAndIntern(LLVMOrcLLJITRef J, const char *UnmangledName);
0160
0161 /**
0162  * Add a buffer representing an object file to the given JITDylib in the given
0163  * LLJIT instance. This operation transfers ownership of the buffer to the
0164  * LLJIT instance. The buffer should not be disposed of or referenced once this
0165  * function returns.
0166  *
0167  * Resources associated with the given object will be tracked by the given
0168  * JITDylib's default resource tracker.
0169  */
0170 LLVMErrorRef LLVMOrcLLJITAddObjectFile(LLVMOrcLLJITRef J, LLVMOrcJITDylibRef JD,
0171                                        LLVMMemoryBufferRef ObjBuffer);
0172
0173 /**
0174  * Add a buffer representing an object file to the given ResourceTracker's
0175  * JITDylib in the given LLJIT instance. This operation transfers ownership of
0176  * the buffer to the LLJIT instance. The buffer should not be disposed of or
0177  * referenced once this function returns.
0178  *
0179  * Resources associated with the given object will be tracked by ResourceTracker
0180  * RT.
0181  */
0182 LLVMErrorRef LLVMOrcLLJITAddObjectFileWithRT(LLVMOrcLLJITRef J,
0183                                              LLVMOrcResourceTrackerRef RT,
0184                                              LLVMMemoryBufferRef ObjBuffer);
0185
0186 /**
0187  * Add an IR module to the given JITDylib in the given LLJIT instance. This
0188  * operation transfers ownership of the TSM argument to the LLJIT instance.
0189  * The TSM argument should not be disposed of or referenced once this
0190  * function returns.
0191  *
0192  * Resources associated with the given Module will be tracked by the given
0193  * JITDylib's default resource tracker.
0194  */
0195 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModule(LLVMOrcLLJITRef J,
0196                                          LLVMOrcJITDylibRef JD,
0197                                          LLVMOrcThreadSafeModuleRef TSM);
0198
0199 /**
0200  * Add an IR module to the given ResourceTracker's JITDylib in the given LLJIT
0201  * instance. This operation transfers ownership of the TSM argument to the LLJIT
0202  * instance. The TSM argument should not be disposed of or referenced once this
0203  * function returns.
0204  *
0205  * Resources associated with the given Module will be tracked by ResourceTracker
0206  * RT.
0207  */
0208 LLVMErrorRef LLVMOrcLLJITAddLLVMIRModuleWithRT(LLVMOrcLLJITRef J,
0209                                                LLVMOrcResourceTrackerRef JD,
0210                                                LLVMOrcThreadSafeModuleRef TSM);
0211
0212 /**
0213  * Look up the given symbol in the main JITDylib of the given LLJIT instance.
0214  *
0215  * This operation does not take ownership of the Name argument.
0216  */
0217 LLVMErrorRef LLVMOrcLLJITLookup(LLVMOrcLLJITRef J,
0218                                 LLVMOrcExecutorAddress *Result,
0219                                 const char *Name);
0220
0221 /**
0222  * Returns a non-owning reference to the LLJIT instance's object linking layer.
0223  */
0224 LLVMOrcObjectLayerRef LLVMOrcLLJITGetObjLinkingLayer(LLVMOrcLLJITRef J);
0225
0226 /**
0227  * Returns a non-owning reference to the LLJIT instance's object linking layer.
0228  */
0229 LLVMOrcObjectTransformLayerRef
0230 LLVMOrcLLJITGetObjTransformLayer(LLVMOrcLLJITRef J);
0231
0232 /**
0233  * Returns a non-owning reference to the LLJIT instance's IR transform layer.
0234  */
0235 LLVMOrcIRTransformLayerRef LLVMOrcLLJITGetIRTransformLayer(LLVMOrcLLJITRef J);
0236
0237 /**
0238  * Get the LLJIT instance's default data layout string.
0239  *
0240  * This string is owned by the LLJIT instance and does not need to be freed
0241  * by the caller.
0242  */
0243 const char *LLVMOrcLLJITGetDataLayoutStr(LLVMOrcLLJITRef J);
0244
0245 /**
0246  * @}
0247  */
0248
0249 LLVM_C_EXTERN_C_END
0250
0251 #endif /* LLVM_C_LLJIT_H */