1//===-- MCJIT.h - Class definition for the MCJIT ----------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLVM_LIB_EXECUTIONENGINE_MCJIT_MCJIT_H
10#define LLVM_LIB_EXECUTIONENGINE_MCJIT_MCJIT_H
11
12#include "llvm/ADT/SmallPtrSet.h"
13#include "llvm/ADT/SmallVector.h"
14#include "llvm/ExecutionEngine/ExecutionEngine.h"
15#include "llvm/ExecutionEngine/RTDyldMemoryManager.h"
16#include "llvm/ExecutionEngine/RuntimeDyld.h"
17
18namespace llvm {
19class MCJIT;
20class Module;
21class ObjectCache;
22
23// This is a helper class that the MCJIT execution engine uses for linking
24// functions across modules that it owns. It aggregates the memory manager
25// that is passed in to the MCJIT constructor and defers most functionality
26// to that object.
27class LinkingSymbolResolver : public LegacyJITSymbolResolver {
28public:
29 LinkingSymbolResolver(MCJIT &Parent,
30 std::shared_ptr<LegacyJITSymbolResolver> Resolver)
31 : ParentEngine(Parent), ClientResolver(std::move(Resolver)) {}
32
33 JITSymbol findSymbol(const std::string &Name) override;
34
35 // MCJIT doesn't support logical dylibs.
36 JITSymbol findSymbolInLogicalDylib(const std::string &Name) override {
37 return nullptr;
38 }
39
40private:
41 MCJIT &ParentEngine;
42 std::shared_ptr<LegacyJITSymbolResolver> ClientResolver;
43 void anchor() override;
44};
45
46// About Module states: added->loaded->finalized.
47//
48// The purpose of the "added" state is having modules in standby. (added=known
49// but not compiled). The idea is that you can add a module to provide function
50// definitions but if nothing in that module is referenced by a module in which
51// a function is executed (note the wording here because it's not exactly the
52// ideal case) then the module never gets compiled. This is sort of lazy
53// compilation.
54//
55// The purpose of the "loaded" state (loaded=compiled and required sections
56// copied into local memory but not yet ready for execution) is to have an
57// intermediate state wherein clients can remap the addresses of sections, using
58// MCJIT::mapSectionAddress, (in preparation for later copying to a new location
59// or an external process) before relocations and page permissions are applied.
60//
61// It might not be obvious at first glance, but the "remote-mcjit" case in the
62// lli tool does this. In that case, the intermediate action is taken by the
63// RemoteMemoryManager in response to the notifyObjectLoaded function being
64// called.
65
66class MCJIT : public ExecutionEngine {
67 MCJIT(std::unique_ptr<Module> M, std::unique_ptr<TargetMachine> tm,
68 std::shared_ptr<MCJITMemoryManager> MemMgr,
69 std::shared_ptr<LegacyJITSymbolResolver> Resolver);
70
71 typedef llvm::SmallPtrSet<Module *, 4> ModulePtrSet;
72
73 class OwningModuleContainer {
74 public:
75 OwningModuleContainer() = default;
76 ~OwningModuleContainer() {
77 freeModulePtrSet(MPS&: AddedModules);
78 freeModulePtrSet(MPS&: LoadedModules);
79 freeModulePtrSet(MPS&: FinalizedModules);
80 }
81
82 ModulePtrSet::iterator begin_added() { return AddedModules.begin(); }
83 ModulePtrSet::iterator end_added() { return AddedModules.end(); }
84 iterator_range<ModulePtrSet::iterator> added() {
85 return make_range(x: begin_added(), y: end_added());
86 }
87
88 ModulePtrSet::iterator begin_loaded() { return LoadedModules.begin(); }
89 ModulePtrSet::iterator end_loaded() { return LoadedModules.end(); }
90
91 ModulePtrSet::iterator begin_finalized() { return FinalizedModules.begin(); }
92 ModulePtrSet::iterator end_finalized() { return FinalizedModules.end(); }
93
94 void addModule(std::unique_ptr<Module> M) {
95 AddedModules.insert(Ptr: M.release());
96 }
97
98 bool removeModule(Module *M) {
99 return AddedModules.erase(Ptr: M) || LoadedModules.erase(Ptr: M) ||
100 FinalizedModules.erase(Ptr: M);
101 }
102
103 bool hasModuleBeenAddedButNotLoaded(Module *M) {
104 return AddedModules.contains(Ptr: M);
105 }
106
107 bool hasModuleBeenLoaded(Module *M) {
108 // If the module is in either the "loaded" or "finalized" sections it
109 // has been loaded.
110 return LoadedModules.contains(Ptr: M) || FinalizedModules.contains(Ptr: M);
111 }
112
113 bool hasModuleBeenFinalized(Module *M) {
114 return FinalizedModules.contains(Ptr: M);
115 }
116
117 bool ownsModule(Module* M) {
118 return AddedModules.contains(Ptr: M) || LoadedModules.contains(Ptr: M) ||
119 FinalizedModules.contains(Ptr: M);
120 }
121
122 void markModuleAsLoaded(Module *M) {
123 // This checks against logic errors in the MCJIT implementation.
124 // This function should never be called with either a Module that MCJIT
125 // does not own or a Module that has already been loaded and/or finalized.
126 assert(AddedModules.count(M) &&
127 "markModuleAsLoaded: Module not found in AddedModules");
128
129 // Remove the module from the "Added" set.
130 AddedModules.erase(Ptr: M);
131
132 // Add the Module to the "Loaded" set.
133 LoadedModules.insert(Ptr: M);
134 }
135
136 void markModuleAsFinalized(Module *M) {
137 // This checks against logic errors in the MCJIT implementation.
138 // This function should never be called with either a Module that MCJIT
139 // does not own, a Module that has not been loaded or a Module that has
140 // already been finalized.
141 assert(LoadedModules.count(M) &&
142 "markModuleAsFinalized: Module not found in LoadedModules");
143
144 // Remove the module from the "Loaded" section of the list.
145 LoadedModules.erase(Ptr: M);
146
147 // Add the Module to the "Finalized" section of the list by inserting it
148 // before the 'end' iterator.
149 FinalizedModules.insert(Ptr: M);
150 }
151
152 void markAllLoadedModulesAsFinalized() {
153 for (Module *M : LoadedModules)
154 FinalizedModules.insert(Ptr: M);
155 LoadedModules.clear();
156 }
157
158 private:
159 ModulePtrSet AddedModules;
160 ModulePtrSet LoadedModules;
161 ModulePtrSet FinalizedModules;
162
163 void freeModulePtrSet(ModulePtrSet& MPS) {
164 // Go through the module set and delete everything.
165 for (Module *M : MPS)
166 delete M;
167 MPS.clear();
168 }
169 };
170
171 std::unique_ptr<TargetMachine> TM;
172 MCContext *Ctx;
173 std::shared_ptr<MCJITMemoryManager> MemMgr;
174 LinkingSymbolResolver Resolver;
175 RuntimeDyld Dyld;
176 std::vector<JITEventListener*> EventListeners;
177
178 OwningModuleContainer OwnedModules;
179
180 SmallVector<object::OwningBinary<object::Archive>, 2> Archives;
181 SmallVector<std::unique_ptr<MemoryBuffer>, 2> Buffers;
182
183 SmallVector<std::unique_ptr<object::ObjectFile>, 2> LoadedObjects;
184
185 // An optional ObjectCache to be notified of compiled objects and used to
186 // perform lookup of pre-compiled code to avoid re-compilation.
187 ObjectCache *ObjCache;
188
189 Function *FindFunctionNamedInModulePtrSet(StringRef FnName,
190 ModulePtrSet::iterator I,
191 ModulePtrSet::iterator E);
192
193 GlobalVariable *FindGlobalVariableNamedInModulePtrSet(StringRef Name,
194 bool AllowInternal,
195 ModulePtrSet::iterator I,
196 ModulePtrSet::iterator E);
197
198 void runStaticConstructorsDestructorsInModulePtrSet(bool isDtors,
199 ModulePtrSet::iterator I,
200 ModulePtrSet::iterator E);
201
202public:
203 ~MCJIT() override;
204
205 /// @name ExecutionEngine interface implementation
206 /// @{
207 void addModule(std::unique_ptr<Module> M) override;
208 void addObjectFile(std::unique_ptr<object::ObjectFile> O) override;
209 void addObjectFile(object::OwningBinary<object::ObjectFile> O) override;
210 void addArchive(object::OwningBinary<object::Archive> O) override;
211 bool removeModule(Module *M) override;
212
213 /// FindFunctionNamed - Search all of the active modules to find the function that
214 /// defines FnName. This is very slow operation and shouldn't be used for
215 /// general code.
216 Function *FindFunctionNamed(StringRef FnName) override;
217
218 /// FindGlobalVariableNamed - Search all of the active modules to find the
219 /// global variable that defines Name. This is very slow operation and
220 /// shouldn't be used for general code.
221 GlobalVariable *FindGlobalVariableNamed(StringRef Name,
222 bool AllowInternal = false) override;
223
224 /// Sets the object manager that MCJIT should use to avoid compilation.
225 void setObjectCache(ObjectCache *manager) override;
226
227 void setProcessAllSections(bool ProcessAllSections) override {
228 Dyld.setProcessAllSections(ProcessAllSections);
229 }
230
231 void generateCodeForModule(Module *M) override;
232
233 /// finalizeObject - ensure the module is fully processed and is usable.
234 ///
235 /// It is the user-level function for completing the process of making the
236 /// object usable for execution. It should be called after sections within an
237 /// object have been relocated using mapSectionAddress. When this method is
238 /// called the MCJIT execution engine will reapply relocations for a loaded
239 /// object.
240 /// Is it OK to finalize a set of modules, add modules and finalize again.
241 // FIXME: Do we really need both of these?
242 void finalizeObject() override;
243 virtual void finalizeModule(Module *);
244 void finalizeLoadedModules();
245
246 /// runStaticConstructorsDestructors - This method is used to execute all of
247 /// the static constructors or destructors for a program.
248 ///
249 /// \param isDtors - Run the destructors instead of constructors.
250 void runStaticConstructorsDestructors(bool isDtors) override;
251
252 void *getPointerToFunction(Function *F) override;
253
254 GenericValue runFunction(Function *F,
255 ArrayRef<GenericValue> ArgValues) override;
256
257 /// getPointerToNamedFunction - This method returns the address of the
258 /// specified function by using the dlsym function call. As such it is only
259 /// useful for resolving library symbols, not code generated symbols.
260 ///
261 /// If AbortOnFailure is false and no function with the given name is
262 /// found, this function silently returns a null pointer. Otherwise,
263 /// it prints a message to stderr and aborts.
264 ///
265 void *getPointerToNamedFunction(StringRef Name,
266 bool AbortOnFailure = true) override;
267
268 /// mapSectionAddress - map a section to its target address space value.
269 /// Map the address of a JIT section as returned from the memory manager
270 /// to the address in the target process as the running code will see it.
271 /// This is the address which will be used for relocation resolution.
272 void mapSectionAddress(const void *LocalAddress,
273 uint64_t TargetAddress) override {
274 Dyld.mapSectionAddress(LocalAddress, TargetAddress);
275 }
276 void RegisterJITEventListener(JITEventListener *L) override;
277 void UnregisterJITEventListener(JITEventListener *L) override;
278
279 // If successful, these function will implicitly finalize all loaded objects.
280 // To get a function address within MCJIT without causing a finalize, use
281 // getSymbolAddress.
282 uint64_t getGlobalValueAddress(const std::string &Name) override;
283 uint64_t getFunctionAddress(const std::string &Name) override;
284
285 TargetMachine *getTargetMachine() override { return TM.get(); }
286
287 /// @}
288 /// @name (Private) Registration Interfaces
289 /// @{
290
291 static void Register() {
292 MCJITCtor = createJIT;
293 }
294
295 static ExecutionEngine *
296 createJIT(std::unique_ptr<Module> M, std::string *ErrorStr,
297 std::shared_ptr<MCJITMemoryManager> MemMgr,
298 std::shared_ptr<LegacyJITSymbolResolver> Resolver,
299 std::unique_ptr<TargetMachine> TM);
300
301 // @}
302
303 // Takes a mangled name and returns the corresponding JITSymbol (if a
304 // definition of that mangled name has been added to the JIT).
305 JITSymbol findSymbol(const std::string &Name, bool CheckFunctionsOnly);
306
307 // DEPRECATED - Please use findSymbol instead.
308 //
309 // This is not directly exposed via the ExecutionEngine API, but it is
310 // used by the LinkingMemoryManager.
311 //
312 // getSymbolAddress takes an unmangled name and returns the corresponding
313 // JITSymbol if a definition of the name has been added to the JIT.
314 uint64_t getSymbolAddress(const std::string &Name,
315 bool CheckFunctionsOnly);
316
317protected:
318 /// emitObject -- Generate a JITed object in memory from the specified module
319 /// Currently, MCJIT only supports a single module and the module passed to
320 /// this function call is expected to be the contained module. The module
321 /// is passed as a parameter here to prepare for multiple module support in
322 /// the future.
323 std::unique_ptr<MemoryBuffer> emitObject(Module *M);
324
325 void notifyObjectLoaded(const object::ObjectFile &Obj,
326 const RuntimeDyld::LoadedObjectInfo &L);
327 void notifyFreeingObject(const object::ObjectFile &Obj);
328
329 JITSymbol findExistingSymbol(const std::string &Name);
330 Module *findModuleForSymbol(const std::string &Name, bool CheckFunctionsOnly);
331};
332
333} // end llvm namespace
334
335#endif // LLVM_LIB_EXECUTIONENGINE_MCJIT_MCJIT_H
336