xref: /freebsd/contrib/llvm-project/llvm/lib/ExecutionEngine/MCJIT/MCJIT.h (revision 924226fba12cc9a228c73b956e1b7fa24c60b055)
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 
18 namespace llvm {
19 class MCJIT;
20 class Module;
21 class 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.
27 class LinkingSymbolResolver : public LegacyJITSymbolResolver {
28 public:
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 
40 private:
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 
66 class 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() {
76     }
77     ~OwningModuleContainer() {
78       freeModulePtrSet(AddedModules);
79       freeModulePtrSet(LoadedModules);
80       freeModulePtrSet(FinalizedModules);
81     }
82 
83     ModulePtrSet::iterator begin_added() { return AddedModules.begin(); }
84     ModulePtrSet::iterator end_added() { return AddedModules.end(); }
85     iterator_range<ModulePtrSet::iterator> added() {
86       return make_range(begin_added(), end_added());
87     }
88 
89     ModulePtrSet::iterator begin_loaded() { return LoadedModules.begin(); }
90     ModulePtrSet::iterator end_loaded() { return LoadedModules.end(); }
91 
92     ModulePtrSet::iterator begin_finalized() { return FinalizedModules.begin(); }
93     ModulePtrSet::iterator end_finalized() { return FinalizedModules.end(); }
94 
95     void addModule(std::unique_ptr<Module> M) {
96       AddedModules.insert(M.release());
97     }
98 
99     bool removeModule(Module *M) {
100       return AddedModules.erase(M) || LoadedModules.erase(M) ||
101              FinalizedModules.erase(M);
102     }
103 
104     bool hasModuleBeenAddedButNotLoaded(Module *M) {
105       return AddedModules.contains(M);
106     }
107 
108     bool hasModuleBeenLoaded(Module *M) {
109       // If the module is in either the "loaded" or "finalized" sections it
110       // has been loaded.
111       return LoadedModules.contains(M) || FinalizedModules.contains(M);
112     }
113 
114     bool hasModuleBeenFinalized(Module *M) {
115       return FinalizedModules.contains(M);
116     }
117 
118     bool ownsModule(Module* M) {
119       return AddedModules.contains(M) || LoadedModules.contains(M) ||
120              FinalizedModules.contains(M);
121     }
122 
123     void markModuleAsLoaded(Module *M) {
124       // This checks against logic errors in the MCJIT implementation.
125       // This function should never be called with either a Module that MCJIT
126       // does not own or a Module that has already been loaded and/or finalized.
127       assert(AddedModules.count(M) &&
128              "markModuleAsLoaded: Module not found in AddedModules");
129 
130       // Remove the module from the "Added" set.
131       AddedModules.erase(M);
132 
133       // Add the Module to the "Loaded" set.
134       LoadedModules.insert(M);
135     }
136 
137     void markModuleAsFinalized(Module *M) {
138       // This checks against logic errors in the MCJIT implementation.
139       // This function should never be called with either a Module that MCJIT
140       // does not own, a Module that has not been loaded or a Module that has
141       // already been finalized.
142       assert(LoadedModules.count(M) &&
143              "markModuleAsFinalized: Module not found in LoadedModules");
144 
145       // Remove the module from the "Loaded" section of the list.
146       LoadedModules.erase(M);
147 
148       // Add the Module to the "Finalized" section of the list by inserting it
149       // before the 'end' iterator.
150       FinalizedModules.insert(M);
151     }
152 
153     void markAllLoadedModulesAsFinalized() {
154       for (Module *M : LoadedModules)
155         FinalizedModules.insert(M);
156       LoadedModules.clear();
157     }
158 
159   private:
160     ModulePtrSet AddedModules;
161     ModulePtrSet LoadedModules;
162     ModulePtrSet FinalizedModules;
163 
164     void freeModulePtrSet(ModulePtrSet& MPS) {
165       // Go through the module set and delete everything.
166       for (Module *M : MPS)
167         delete M;
168       MPS.clear();
169     }
170   };
171 
172   std::unique_ptr<TargetMachine> TM;
173   MCContext *Ctx;
174   std::shared_ptr<MCJITMemoryManager> MemMgr;
175   LinkingSymbolResolver Resolver;
176   RuntimeDyld Dyld;
177   std::vector<JITEventListener*> EventListeners;
178 
179   OwningModuleContainer OwnedModules;
180 
181   SmallVector<object::OwningBinary<object::Archive>, 2> Archives;
182   SmallVector<std::unique_ptr<MemoryBuffer>, 2> Buffers;
183 
184   SmallVector<std::unique_ptr<object::ObjectFile>, 2> LoadedObjects;
185 
186   // An optional ObjectCache to be notified of compiled objects and used to
187   // perform lookup of pre-compiled code to avoid re-compilation.
188   ObjectCache *ObjCache;
189 
190   Function *FindFunctionNamedInModulePtrSet(StringRef FnName,
191                                             ModulePtrSet::iterator I,
192                                             ModulePtrSet::iterator E);
193 
194   GlobalVariable *FindGlobalVariableNamedInModulePtrSet(StringRef Name,
195                                                         bool AllowInternal,
196                                                         ModulePtrSet::iterator I,
197                                                         ModulePtrSet::iterator E);
198 
199   void runStaticConstructorsDestructorsInModulePtrSet(bool isDtors,
200                                                       ModulePtrSet::iterator I,
201                                                       ModulePtrSet::iterator E);
202 
203 public:
204   ~MCJIT() override;
205 
206   /// @name ExecutionEngine interface implementation
207   /// @{
208   void addModule(std::unique_ptr<Module> M) override;
209   void addObjectFile(std::unique_ptr<object::ObjectFile> O) override;
210   void addObjectFile(object::OwningBinary<object::ObjectFile> O) override;
211   void addArchive(object::OwningBinary<object::Archive> O) override;
212   bool removeModule(Module *M) override;
213 
214   /// FindFunctionNamed - Search all of the active modules to find the function that
215   /// defines FnName.  This is very slow operation and shouldn't be used for
216   /// general code.
217   Function *FindFunctionNamed(StringRef FnName) override;
218 
219   /// FindGlobalVariableNamed - Search all of the active modules to find the
220   /// global variable that defines Name.  This is very slow operation and
221   /// shouldn't be used for general code.
222   GlobalVariable *FindGlobalVariableNamed(StringRef Name,
223                                           bool AllowInternal = false) override;
224 
225   /// Sets the object manager that MCJIT should use to avoid compilation.
226   void setObjectCache(ObjectCache *manager) override;
227 
228   void setProcessAllSections(bool ProcessAllSections) override {
229     Dyld.setProcessAllSections(ProcessAllSections);
230   }
231 
232   void generateCodeForModule(Module *M) override;
233 
234   /// finalizeObject - ensure the module is fully processed and is usable.
235   ///
236   /// It is the user-level function for completing the process of making the
237   /// object usable for execution. It should be called after sections within an
238   /// object have been relocated using mapSectionAddress.  When this method is
239   /// called the MCJIT execution engine will reapply relocations for a loaded
240   /// object.
241   /// Is it OK to finalize a set of modules, add modules and finalize again.
242   // FIXME: Do we really need both of these?
243   void finalizeObject() override;
244   virtual void finalizeModule(Module *);
245   void finalizeLoadedModules();
246 
247   /// runStaticConstructorsDestructors - This method is used to execute all of
248   /// the static constructors or destructors for a program.
249   ///
250   /// \param isDtors - Run the destructors instead of constructors.
251   void runStaticConstructorsDestructors(bool isDtors) override;
252 
253   void *getPointerToFunction(Function *F) override;
254 
255   GenericValue runFunction(Function *F,
256                            ArrayRef<GenericValue> ArgValues) override;
257 
258   /// getPointerToNamedFunction - This method returns the address of the
259   /// specified function by using the dlsym function call.  As such it is only
260   /// useful for resolving library symbols, not code generated symbols.
261   ///
262   /// If AbortOnFailure is false and no function with the given name is
263   /// found, this function silently returns a null pointer. Otherwise,
264   /// it prints a message to stderr and aborts.
265   ///
266   void *getPointerToNamedFunction(StringRef Name,
267                                   bool AbortOnFailure = true) override;
268 
269   /// mapSectionAddress - map a section to its target address space value.
270   /// Map the address of a JIT section as returned from the memory manager
271   /// to the address in the target process as the running code will see it.
272   /// This is the address which will be used for relocation resolution.
273   void mapSectionAddress(const void *LocalAddress,
274                          uint64_t TargetAddress) override {
275     Dyld.mapSectionAddress(LocalAddress, TargetAddress);
276   }
277   void RegisterJITEventListener(JITEventListener *L) override;
278   void UnregisterJITEventListener(JITEventListener *L) override;
279 
280   // If successful, these function will implicitly finalize all loaded objects.
281   // To get a function address within MCJIT without causing a finalize, use
282   // getSymbolAddress.
283   uint64_t getGlobalValueAddress(const std::string &Name) override;
284   uint64_t getFunctionAddress(const std::string &Name) override;
285 
286   TargetMachine *getTargetMachine() override { return TM.get(); }
287 
288   /// @}
289   /// @name (Private) Registration Interfaces
290   /// @{
291 
292   static void Register() {
293     MCJITCtor = createJIT;
294   }
295 
296   static ExecutionEngine *
297   createJIT(std::unique_ptr<Module> M, std::string *ErrorStr,
298             std::shared_ptr<MCJITMemoryManager> MemMgr,
299             std::shared_ptr<LegacyJITSymbolResolver> Resolver,
300             std::unique_ptr<TargetMachine> TM);
301 
302   // @}
303 
304   // Takes a mangled name and returns the corresponding JITSymbol (if a
305   // definition of that mangled name has been added to the JIT).
306   JITSymbol findSymbol(const std::string &Name, bool CheckFunctionsOnly);
307 
308   // DEPRECATED - Please use findSymbol instead.
309   //
310   // This is not directly exposed via the ExecutionEngine API, but it is
311   // used by the LinkingMemoryManager.
312   //
313   // getSymbolAddress takes an unmangled name and returns the corresponding
314   // JITSymbol if a definition of the name has been added to the JIT.
315   uint64_t getSymbolAddress(const std::string &Name,
316                             bool CheckFunctionsOnly);
317 
318 protected:
319   /// emitObject -- Generate a JITed object in memory from the specified module
320   /// Currently, MCJIT only supports a single module and the module passed to
321   /// this function call is expected to be the contained module.  The module
322   /// is passed as a parameter here to prepare for multiple module support in
323   /// the future.
324   std::unique_ptr<MemoryBuffer> emitObject(Module *M);
325 
326   void notifyObjectLoaded(const object::ObjectFile &Obj,
327                           const RuntimeDyld::LoadedObjectInfo &L);
328   void notifyFreeingObject(const object::ObjectFile &Obj);
329 
330   JITSymbol findExistingSymbol(const std::string &Name);
331   Module *findModuleForSymbol(const std::string &Name, bool CheckFunctionsOnly);
332 };
333 
334 } // end llvm namespace
335 
336 #endif // LLVM_LIB_EXECUTIONENGINE_MCJIT_MCJIT_H
337