1 //===-- RuntimeDyld.h - Run-time dynamic linker for MC-JIT ------*- C++ -*-===// 2 // 3 // The LLVM Compiler Infrastructure 4 // 5 // This file is distributed under the University of Illinois Open Source 6 // License. See LICENSE.TXT for details. 7 // 8 //===----------------------------------------------------------------------===// 9 // 10 // Interface for the runtime dynamic linker facilities of the MC-JIT. 11 // 12 //===----------------------------------------------------------------------===// 13 14 #ifndef LLVM_EXECUTIONENGINE_RUNTIMEDYLD_H 15 #define LLVM_EXECUTIONENGINE_RUNTIMEDYLD_H 16 17 #include "JITSymbolFlags.h" 18 #include "llvm/ADT/STLExtras.h" 19 #include "llvm/DebugInfo/DIContext.h" 20 #include "llvm/Object/ObjectFile.h" 21 #include "llvm/Support/Memory.h" 22 #include <map> 23 #include <memory> 24 #include <utility> 25 26 namespace llvm { 27 28 class StringRef; 29 30 namespace object { 31 class ObjectFile; 32 template <typename T> class OwningBinary; 33 } 34 35 /// Base class for errors originating in RuntimeDyld, e.g. missing relocation 36 /// support. 37 class RuntimeDyldError : public ErrorInfo<RuntimeDyldError> { 38 public: 39 static char ID; 40 RuntimeDyldError(std::string ErrMsg) : ErrMsg(std::move(ErrMsg)) {} 41 void log(raw_ostream &OS) const override; 42 const std::string &getErrorMessage() const { return ErrMsg; } 43 std::error_code convertToErrorCode() const override; 44 private: 45 std::string ErrMsg; 46 }; 47 48 class RuntimeDyldImpl; 49 class RuntimeDyldCheckerImpl; 50 51 class RuntimeDyld { 52 friend class RuntimeDyldCheckerImpl; 53 54 RuntimeDyld(const RuntimeDyld &) = delete; 55 void operator=(const RuntimeDyld &) = delete; 56 57 protected: 58 // Change the address associated with a section when resolving relocations. 59 // Any relocations already associated with the symbol will be re-resolved. 60 void reassignSectionAddress(unsigned SectionID, uint64_t Addr); 61 public: 62 63 /// \brief Information about a named symbol. 64 class SymbolInfo : public JITSymbolBase { 65 public: 66 SymbolInfo(std::nullptr_t) : JITSymbolBase(JITSymbolFlags::None), Address(0) {} 67 SymbolInfo(uint64_t Address, JITSymbolFlags Flags) 68 : JITSymbolBase(Flags), Address(Address) {} 69 explicit operator bool() const { return Address != 0; } 70 uint64_t getAddress() const { return Address; } 71 private: 72 uint64_t Address; 73 }; 74 75 /// \brief Information about the loaded object. 76 class LoadedObjectInfo : public llvm::LoadedObjectInfo { 77 friend class RuntimeDyldImpl; 78 public: 79 typedef std::map<object::SectionRef, unsigned> ObjSectionToIDMap; 80 81 LoadedObjectInfo(RuntimeDyldImpl &RTDyld, ObjSectionToIDMap ObjSecToIDMap) 82 : RTDyld(RTDyld), ObjSecToIDMap(std::move(ObjSecToIDMap)) {} 83 84 virtual object::OwningBinary<object::ObjectFile> 85 getObjectForDebug(const object::ObjectFile &Obj) const = 0; 86 87 uint64_t 88 getSectionLoadAddress(const object::SectionRef &Sec) const override; 89 90 protected: 91 virtual void anchor(); 92 93 RuntimeDyldImpl &RTDyld; 94 ObjSectionToIDMap ObjSecToIDMap; 95 }; 96 97 template <typename Derived> struct LoadedObjectInfoHelper : LoadedObjectInfo { 98 protected: 99 LoadedObjectInfoHelper(const LoadedObjectInfoHelper &) = default; 100 LoadedObjectInfoHelper() = default; 101 102 public: 103 LoadedObjectInfoHelper(RuntimeDyldImpl &RTDyld, 104 LoadedObjectInfo::ObjSectionToIDMap ObjSecToIDMap) 105 : LoadedObjectInfo(RTDyld, std::move(ObjSecToIDMap)) {} 106 std::unique_ptr<llvm::LoadedObjectInfo> clone() const override { 107 return llvm::make_unique<Derived>(static_cast<const Derived &>(*this)); 108 } 109 }; 110 111 /// \brief Memory Management. 112 class MemoryManager { 113 friend class RuntimeDyld; 114 public: 115 MemoryManager() : FinalizationLocked(false) {} 116 virtual ~MemoryManager() {} 117 118 /// Allocate a memory block of (at least) the given size suitable for 119 /// executable code. The SectionID is a unique identifier assigned by the 120 /// RuntimeDyld instance, and optionally recorded by the memory manager to 121 /// access a loaded section. 122 virtual uint8_t *allocateCodeSection(uintptr_t Size, unsigned Alignment, 123 unsigned SectionID, 124 StringRef SectionName) = 0; 125 126 /// Allocate a memory block of (at least) the given size suitable for data. 127 /// The SectionID is a unique identifier assigned by the JIT engine, and 128 /// optionally recorded by the memory manager to access a loaded section. 129 virtual uint8_t *allocateDataSection(uintptr_t Size, unsigned Alignment, 130 unsigned SectionID, 131 StringRef SectionName, 132 bool IsReadOnly) = 0; 133 134 /// Inform the memory manager about the total amount of memory required to 135 /// allocate all sections to be loaded: 136 /// \p CodeSize - the total size of all code sections 137 /// \p DataSizeRO - the total size of all read-only data sections 138 /// \p DataSizeRW - the total size of all read-write data sections 139 /// 140 /// Note that by default the callback is disabled. To enable it 141 /// redefine the method needsToReserveAllocationSpace to return true. 142 virtual void reserveAllocationSpace(uintptr_t CodeSize, uint32_t CodeAlign, 143 uintptr_t RODataSize, 144 uint32_t RODataAlign, 145 uintptr_t RWDataSize, 146 uint32_t RWDataAlign) {} 147 148 /// Override to return true to enable the reserveAllocationSpace callback. 149 virtual bool needsToReserveAllocationSpace() { return false; } 150 151 /// Register the EH frames with the runtime so that c++ exceptions work. 152 /// 153 /// \p Addr parameter provides the local address of the EH frame section 154 /// data, while \p LoadAddr provides the address of the data in the target 155 /// address space. If the section has not been remapped (which will usually 156 /// be the case for local execution) these two values will be the same. 157 virtual void registerEHFrames(uint8_t *Addr, uint64_t LoadAddr, 158 size_t Size) = 0; 159 virtual void deregisterEHFrames(uint8_t *addr, uint64_t LoadAddr, 160 size_t Size) = 0; 161 162 /// This method is called when object loading is complete and section page 163 /// permissions can be applied. It is up to the memory manager implementation 164 /// to decide whether or not to act on this method. The memory manager will 165 /// typically allocate all sections as read-write and then apply specific 166 /// permissions when this method is called. Code sections cannot be executed 167 /// until this function has been called. In addition, any cache coherency 168 /// operations needed to reliably use the memory are also performed. 169 /// 170 /// Returns true if an error occurred, false otherwise. 171 virtual bool finalizeMemory(std::string *ErrMsg = nullptr) = 0; 172 173 /// This method is called after an object has been loaded into memory but 174 /// before relocations are applied to the loaded sections. 175 /// 176 /// Memory managers which are preparing code for execution in an external 177 /// address space can use this call to remap the section addresses for the 178 /// newly loaded object. 179 /// 180 /// For clients that do not need access to an ExecutionEngine instance this 181 /// method should be preferred to its cousin 182 /// MCJITMemoryManager::notifyObjectLoaded as this method is compatible with 183 /// ORC JIT stacks. 184 virtual void notifyObjectLoaded(RuntimeDyld &RTDyld, 185 const object::ObjectFile &Obj) {} 186 187 private: 188 virtual void anchor(); 189 bool FinalizationLocked; 190 }; 191 192 /// \brief Symbol resolution. 193 class SymbolResolver { 194 public: 195 virtual ~SymbolResolver() {} 196 197 /// This method returns the address of the specified symbol if it exists 198 /// within the logical dynamic library represented by this 199 /// RTDyldMemoryManager. Unlike findSymbol, queries through this 200 /// interface should return addresses for hidden symbols. 201 /// 202 /// This is of particular importance for the Orc JIT APIs, which support lazy 203 /// compilation by breaking up modules: Each of those broken out modules 204 /// must be able to resolve hidden symbols provided by the others. Clients 205 /// writing memory managers for MCJIT can usually ignore this method. 206 /// 207 /// This method will be queried by RuntimeDyld when checking for previous 208 /// definitions of common symbols. 209 virtual SymbolInfo findSymbolInLogicalDylib(const std::string &Name) = 0; 210 211 /// This method returns the address of the specified function or variable. 212 /// It is used to resolve symbols during module linking. 213 /// 214 /// If the returned symbol's address is equal to ~0ULL then RuntimeDyld will 215 /// skip all relocations for that symbol, and the client will be responsible 216 /// for handling them manually. 217 virtual SymbolInfo findSymbol(const std::string &Name) = 0; 218 219 private: 220 virtual void anchor(); 221 }; 222 223 /// \brief Construct a RuntimeDyld instance. 224 RuntimeDyld(MemoryManager &MemMgr, SymbolResolver &Resolver); 225 ~RuntimeDyld(); 226 227 /// Add the referenced object file to the list of objects to be loaded and 228 /// relocated. 229 std::unique_ptr<LoadedObjectInfo> loadObject(const object::ObjectFile &O); 230 231 /// Get the address of our local copy of the symbol. This may or may not 232 /// be the address used for relocation (clients can copy the data around 233 /// and resolve relocatons based on where they put it). 234 void *getSymbolLocalAddress(StringRef Name) const; 235 236 /// Get the target address and flags for the named symbol. 237 /// This address is the one used for relocation. 238 SymbolInfo getSymbol(StringRef Name) const; 239 240 /// Resolve the relocations for all symbols we currently know about. 241 void resolveRelocations(); 242 243 /// Map a section to its target address space value. 244 /// Map the address of a JIT section as returned from the memory manager 245 /// to the address in the target process as the running code will see it. 246 /// This is the address which will be used for relocation resolution. 247 void mapSectionAddress(const void *LocalAddress, uint64_t TargetAddress); 248 249 /// Register any EH frame sections that have been loaded but not previously 250 /// registered with the memory manager. Note, RuntimeDyld is responsible 251 /// for identifying the EH frame and calling the memory manager with the 252 /// EH frame section data. However, the memory manager itself will handle 253 /// the actual target-specific EH frame registration. 254 void registerEHFrames(); 255 256 void deregisterEHFrames(); 257 258 bool hasError(); 259 StringRef getErrorString(); 260 261 /// By default, only sections that are "required for execution" are passed to 262 /// the RTDyldMemoryManager, and other sections are discarded. Passing 'true' 263 /// to this method will cause RuntimeDyld to pass all sections to its 264 /// memory manager regardless of whether they are "required to execute" in the 265 /// usual sense. This is useful for inspecting metadata sections that may not 266 /// contain relocations, E.g. Debug info, stackmaps. 267 /// 268 /// Must be called before the first object file is loaded. 269 void setProcessAllSections(bool ProcessAllSections) { 270 assert(!Dyld && "setProcessAllSections must be called before loadObject."); 271 this->ProcessAllSections = ProcessAllSections; 272 } 273 274 /// Perform all actions needed to make the code owned by this RuntimeDyld 275 /// instance executable: 276 /// 277 /// 1) Apply relocations. 278 /// 2) Register EH frames. 279 /// 3) Update memory permissions*. 280 /// 281 /// * Finalization is potentially recursive**, and the 3rd step will only be 282 /// applied by the outermost call to finalize. This allows different 283 /// RuntimeDyld instances to share a memory manager without the innermost 284 /// finalization locking the memory and causing relocation fixup errors in 285 /// outer instances. 286 /// 287 /// ** Recursive finalization occurs when one RuntimeDyld instances needs the 288 /// address of a symbol owned by some other instance in order to apply 289 /// relocations. 290 /// 291 void finalizeWithMemoryManagerLocking(); 292 293 private: 294 // RuntimeDyldImpl is the actual class. RuntimeDyld is just the public 295 // interface. 296 std::unique_ptr<RuntimeDyldImpl> Dyld; 297 MemoryManager &MemMgr; 298 SymbolResolver &Resolver; 299 bool ProcessAllSections; 300 RuntimeDyldCheckerImpl *Checker; 301 }; 302 303 } // end namespace llvm 304 305 #endif // LLVM_EXECUTIONENGINE_RUNTIMEDYLD_H 306
