1321369Sdim//===- RuntimeDyld.h - Run-time dynamic linker for MC-JIT -------*- C++ -*-===// 2221337Sdim// 3353358Sdim// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4353358Sdim// See https://llvm.org/LICENSE.txt for license information. 5353358Sdim// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6221337Sdim// 7221337Sdim//===----------------------------------------------------------------------===// 8221337Sdim// 9221337Sdim// Interface for the runtime dynamic linker facilities of the MC-JIT. 10221337Sdim// 11221337Sdim//===----------------------------------------------------------------------===// 12221337Sdim 13249423Sdim#ifndef LLVM_EXECUTIONENGINE_RUNTIMEDYLD_H 14249423Sdim#define LLVM_EXECUTIONENGINE_RUNTIMEDYLD_H 15221337Sdim 16360784Sdim#include "llvm/ADT/FunctionExtras.h" 17288943Sdim#include "llvm/ADT/STLExtras.h" 18314564Sdim#include "llvm/ADT/StringRef.h" 19309124Sdim#include "llvm/DebugInfo/DIContext.h" 20314564Sdim#include "llvm/ExecutionEngine/JITSymbol.h" 21296417Sdim#include "llvm/Object/ObjectFile.h" 22314564Sdim#include "llvm/Support/Error.h" 23314564Sdim#include <algorithm> 24314564Sdim#include <cassert> 25314564Sdim#include <cstddef> 26314564Sdim#include <cstdint> 27296417Sdim#include <map> 28280031Sdim#include <memory> 29314564Sdim#include <string> 30314564Sdim#include <system_error> 31221337Sdim 32221337Sdimnamespace llvm { 33221337Sdim 34276479Sdimnamespace object { 35321369Sdim 36321369Sdimtemplate <typename T> class OwningBinary; 37321369Sdim 38314564Sdim} // end namespace object 39276479Sdim 40309124Sdim/// Base class for errors originating in RuntimeDyld, e.g. missing relocation 41309124Sdim/// support. 42309124Sdimclass RuntimeDyldError : public ErrorInfo<RuntimeDyldError> { 43309124Sdimpublic: 44309124Sdim static char ID; 45314564Sdim 46309124Sdim RuntimeDyldError(std::string ErrMsg) : ErrMsg(std::move(ErrMsg)) {} 47314564Sdim 48309124Sdim void log(raw_ostream &OS) const override; 49309124Sdim const std::string &getErrorMessage() const { return ErrMsg; } 50309124Sdim std::error_code convertToErrorCode() const override; 51314564Sdim 52309124Sdimprivate: 53309124Sdim std::string ErrMsg; 54309124Sdim}; 55309124Sdim 56221337Sdimclass RuntimeDyldImpl; 57221337Sdim 58221337Sdimclass RuntimeDyld { 59234353Sdimprotected: 60234353Sdim // Change the address associated with a section when resolving relocations. 61234353Sdim // Any relocations already associated with the symbol will be re-resolved. 62234353Sdim void reassignSectionAddress(unsigned SectionID, uint64_t Addr); 63314564Sdim 64221337Sdimpublic: 65353358Sdim using NotifyStubEmittedFunction = std::function<void( 66353358Sdim StringRef FileName, StringRef SectionName, StringRef SymbolName, 67353358Sdim unsigned SectionID, uint32_t StubOffset)>; 68353358Sdim 69341825Sdim /// Information about the loaded object. 70288943Sdim class LoadedObjectInfo : public llvm::LoadedObjectInfo { 71280031Sdim friend class RuntimeDyldImpl; 72314564Sdim 73280031Sdim public: 74321369Sdim using ObjSectionToIDMap = std::map<object::SectionRef, unsigned>; 75280031Sdim 76296417Sdim LoadedObjectInfo(RuntimeDyldImpl &RTDyld, ObjSectionToIDMap ObjSecToIDMap) 77309124Sdim : RTDyld(RTDyld), ObjSecToIDMap(std::move(ObjSecToIDMap)) {} 78296417Sdim 79280031Sdim virtual object::OwningBinary<object::ObjectFile> 80280031Sdim getObjectForDebug(const object::ObjectFile &Obj) const = 0; 81280031Sdim 82296417Sdim uint64_t 83296417Sdim getSectionLoadAddress(const object::SectionRef &Sec) const override; 84280031Sdim 85280031Sdim protected: 86280031Sdim virtual void anchor(); 87280031Sdim 88280031Sdim RuntimeDyldImpl &RTDyld; 89296417Sdim ObjSectionToIDMap ObjSecToIDMap; 90280031Sdim }; 91280031Sdim 92341825Sdim /// Memory Management. 93288943Sdim class MemoryManager { 94296417Sdim friend class RuntimeDyld; 95314564Sdim 96288943Sdim public: 97314564Sdim MemoryManager() = default; 98314564Sdim virtual ~MemoryManager() = default; 99288943Sdim 100288943Sdim /// Allocate a memory block of (at least) the given size suitable for 101288943Sdim /// executable code. The SectionID is a unique identifier assigned by the 102288943Sdim /// RuntimeDyld instance, and optionally recorded by the memory manager to 103288943Sdim /// access a loaded section. 104288943Sdim virtual uint8_t *allocateCodeSection(uintptr_t Size, unsigned Alignment, 105288943Sdim unsigned SectionID, 106288943Sdim StringRef SectionName) = 0; 107288943Sdim 108288943Sdim /// Allocate a memory block of (at least) the given size suitable for data. 109288943Sdim /// The SectionID is a unique identifier assigned by the JIT engine, and 110288943Sdim /// optionally recorded by the memory manager to access a loaded section. 111288943Sdim virtual uint8_t *allocateDataSection(uintptr_t Size, unsigned Alignment, 112288943Sdim unsigned SectionID, 113288943Sdim StringRef SectionName, 114288943Sdim bool IsReadOnly) = 0; 115288943Sdim 116288943Sdim /// Inform the memory manager about the total amount of memory required to 117288943Sdim /// allocate all sections to be loaded: 118288943Sdim /// \p CodeSize - the total size of all code sections 119288943Sdim /// \p DataSizeRO - the total size of all read-only data sections 120288943Sdim /// \p DataSizeRW - the total size of all read-write data sections 121288943Sdim /// 122288943Sdim /// Note that by default the callback is disabled. To enable it 123288943Sdim /// redefine the method needsToReserveAllocationSpace to return true. 124296417Sdim virtual void reserveAllocationSpace(uintptr_t CodeSize, uint32_t CodeAlign, 125296417Sdim uintptr_t RODataSize, 126296417Sdim uint32_t RODataAlign, 127296417Sdim uintptr_t RWDataSize, 128296417Sdim uint32_t RWDataAlign) {} 129288943Sdim 130288943Sdim /// Override to return true to enable the reserveAllocationSpace callback. 131288943Sdim virtual bool needsToReserveAllocationSpace() { return false; } 132288943Sdim 133288943Sdim /// Register the EH frames with the runtime so that c++ exceptions work. 134288943Sdim /// 135288943Sdim /// \p Addr parameter provides the local address of the EH frame section 136288943Sdim /// data, while \p LoadAddr provides the address of the data in the target 137288943Sdim /// address space. If the section has not been remapped (which will usually 138288943Sdim /// be the case for local execution) these two values will be the same. 139288943Sdim virtual void registerEHFrames(uint8_t *Addr, uint64_t LoadAddr, 140288943Sdim size_t Size) = 0; 141321369Sdim virtual void deregisterEHFrames() = 0; 142288943Sdim 143288943Sdim /// This method is called when object loading is complete and section page 144288943Sdim /// permissions can be applied. It is up to the memory manager implementation 145288943Sdim /// to decide whether or not to act on this method. The memory manager will 146288943Sdim /// typically allocate all sections as read-write and then apply specific 147288943Sdim /// permissions when this method is called. Code sections cannot be executed 148288943Sdim /// until this function has been called. In addition, any cache coherency 149288943Sdim /// operations needed to reliably use the memory are also performed. 150288943Sdim /// 151288943Sdim /// Returns true if an error occurred, false otherwise. 152288943Sdim virtual bool finalizeMemory(std::string *ErrMsg = nullptr) = 0; 153288943Sdim 154296417Sdim /// This method is called after an object has been loaded into memory but 155296417Sdim /// before relocations are applied to the loaded sections. 156296417Sdim /// 157296417Sdim /// Memory managers which are preparing code for execution in an external 158296417Sdim /// address space can use this call to remap the section addresses for the 159296417Sdim /// newly loaded object. 160296417Sdim /// 161296417Sdim /// For clients that do not need access to an ExecutionEngine instance this 162296417Sdim /// method should be preferred to its cousin 163296417Sdim /// MCJITMemoryManager::notifyObjectLoaded as this method is compatible with 164296417Sdim /// ORC JIT stacks. 165296417Sdim virtual void notifyObjectLoaded(RuntimeDyld &RTDyld, 166296417Sdim const object::ObjectFile &Obj) {} 167296417Sdim 168288943Sdim private: 169288943Sdim virtual void anchor(); 170288943Sdim 171314564Sdim bool FinalizationLocked = false; 172288943Sdim }; 173288943Sdim 174341825Sdim /// Construct a RuntimeDyld instance. 175314564Sdim RuntimeDyld(MemoryManager &MemMgr, JITSymbolResolver &Resolver); 176314564Sdim RuntimeDyld(const RuntimeDyld &) = delete; 177321369Sdim RuntimeDyld &operator=(const RuntimeDyld &) = delete; 178221337Sdim ~RuntimeDyld(); 179221337Sdim 180280031Sdim /// Add the referenced object file to the list of objects to be loaded and 181280031Sdim /// relocated. 182280031Sdim std::unique_ptr<LoadedObjectInfo> loadObject(const object::ObjectFile &O); 183239462Sdim 184239462Sdim /// Get the address of our local copy of the symbol. This may or may not 185239462Sdim /// be the address used for relocation (clients can copy the data around 186239462Sdim /// and resolve relocatons based on where they put it). 187288943Sdim void *getSymbolLocalAddress(StringRef Name) const; 188239462Sdim 189353358Sdim /// Get the section ID for the section containing the given symbol. 190353358Sdim unsigned getSymbolSectionID(StringRef Name) const; 191353358Sdim 192288943Sdim /// Get the target address and flags for the named symbol. 193288943Sdim /// This address is the one used for relocation. 194314564Sdim JITEvaluatedSymbol getSymbol(StringRef Name) const; 195243830Sdim 196341825Sdim /// Returns a copy of the symbol table. This can be used by on-finalized 197341825Sdim /// callbacks to extract the symbol table before throwing away the 198341825Sdim /// RuntimeDyld instance. Because the map keys (StringRefs) are backed by 199341825Sdim /// strings inside the RuntimeDyld instance, the map should be processed 200341825Sdim /// before the RuntimeDyld instance is discarded. 201341825Sdim std::map<StringRef, JITEvaluatedSymbol> getSymbolTable() const; 202341825Sdim 203239462Sdim /// Resolve the relocations for all symbols we currently know about. 204221337Sdim void resolveRelocations(); 205234353Sdim 206249423Sdim /// Map a section to its target address space value. 207234353Sdim /// Map the address of a JIT section as returned from the memory manager 208234353Sdim /// to the address in the target process as the running code will see it. 209234353Sdim /// This is the address which will be used for relocation resolution. 210243830Sdim void mapSectionAddress(const void *LocalAddress, uint64_t TargetAddress); 211234353Sdim 212353358Sdim /// Returns the section's working memory. 213353358Sdim StringRef getSectionContent(unsigned SectionID) const; 214353358Sdim 215353358Sdim /// If the section was loaded, return the section's load address, 216353358Sdim /// otherwise return None. 217353358Sdim uint64_t getSectionLoadAddress(unsigned SectionID) const; 218353358Sdim 219353358Sdim /// Set the NotifyStubEmitted callback. This is used for debugging 220353358Sdim /// purposes. A callback is made for each stub that is generated. 221353358Sdim void setNotifyStubEmitted(NotifyStubEmittedFunction NotifyStubEmitted) { 222353358Sdim this->NotifyStubEmitted = std::move(NotifyStubEmitted); 223353358Sdim } 224353358Sdim 225261991Sdim /// Register any EH frame sections that have been loaded but not previously 226261991Sdim /// registered with the memory manager. Note, RuntimeDyld is responsible 227261991Sdim /// for identifying the EH frame and calling the memory manager with the 228261991Sdim /// EH frame section data. However, the memory manager itself will handle 229261991Sdim /// the actual target-specific EH frame registration. 230261991Sdim void registerEHFrames(); 231261991Sdim 232261991Sdim void deregisterEHFrames(); 233261991Sdim 234276479Sdim bool hasError(); 235221337Sdim StringRef getErrorString(); 236276479Sdim 237276479Sdim /// By default, only sections that are "required for execution" are passed to 238276479Sdim /// the RTDyldMemoryManager, and other sections are discarded. Passing 'true' 239276479Sdim /// to this method will cause RuntimeDyld to pass all sections to its 240276479Sdim /// memory manager regardless of whether they are "required to execute" in the 241276479Sdim /// usual sense. This is useful for inspecting metadata sections that may not 242276479Sdim /// contain relocations, E.g. Debug info, stackmaps. 243276479Sdim /// 244276479Sdim /// Must be called before the first object file is loaded. 245276479Sdim void setProcessAllSections(bool ProcessAllSections) { 246276479Sdim assert(!Dyld && "setProcessAllSections must be called before loadObject."); 247276479Sdim this->ProcessAllSections = ProcessAllSections; 248276479Sdim } 249288943Sdim 250296417Sdim /// Perform all actions needed to make the code owned by this RuntimeDyld 251296417Sdim /// instance executable: 252296417Sdim /// 253296417Sdim /// 1) Apply relocations. 254296417Sdim /// 2) Register EH frames. 255296417Sdim /// 3) Update memory permissions*. 256296417Sdim /// 257296417Sdim /// * Finalization is potentially recursive**, and the 3rd step will only be 258296417Sdim /// applied by the outermost call to finalize. This allows different 259296417Sdim /// RuntimeDyld instances to share a memory manager without the innermost 260296417Sdim /// finalization locking the memory and causing relocation fixup errors in 261296417Sdim /// outer instances. 262296417Sdim /// 263296417Sdim /// ** Recursive finalization occurs when one RuntimeDyld instances needs the 264296417Sdim /// address of a symbol owned by some other instance in order to apply 265296417Sdim /// relocations. 266296417Sdim /// 267296417Sdim void finalizeWithMemoryManagerLocking(); 268296417Sdim 269288943Sdimprivate: 270344779Sdim friend void 271344779Sdim jitLinkForORC(object::ObjectFile &Obj, 272344779Sdim std::unique_ptr<MemoryBuffer> UnderlyingBuffer, 273344779Sdim RuntimeDyld::MemoryManager &MemMgr, JITSymbolResolver &Resolver, 274344779Sdim bool ProcessAllSections, 275360784Sdim unique_function<Error(std::unique_ptr<LoadedObjectInfo>, 276360784Sdim std::map<StringRef, JITEvaluatedSymbol>)> 277344779Sdim OnLoaded, 278360784Sdim unique_function<void(Error)> OnEmitted); 279344779Sdim 280288943Sdim // RuntimeDyldImpl is the actual class. RuntimeDyld is just the public 281288943Sdim // interface. 282288943Sdim std::unique_ptr<RuntimeDyldImpl> Dyld; 283288943Sdim MemoryManager &MemMgr; 284314564Sdim JITSymbolResolver &Resolver; 285288943Sdim bool ProcessAllSections; 286353358Sdim NotifyStubEmittedFunction NotifyStubEmitted; 287221337Sdim}; 288221337Sdim 289344779Sdim// Asynchronous JIT link for ORC. 290344779Sdim// 291344779Sdim// Warning: This API is experimental and probably should not be used by anyone 292344779Sdim// but ORC's RTDyldObjectLinkingLayer2. Internally it constructs a RuntimeDyld 293344779Sdim// instance and uses continuation passing to perform the fix-up and finalize 294344779Sdim// steps asynchronously. 295360784Sdimvoid jitLinkForORC( 296360784Sdim object::ObjectFile &Obj, std::unique_ptr<MemoryBuffer> UnderlyingBuffer, 297360784Sdim RuntimeDyld::MemoryManager &MemMgr, JITSymbolResolver &Resolver, 298360784Sdim bool ProcessAllSections, 299360784Sdim unique_function<Error(std::unique_ptr<RuntimeDyld::LoadedObjectInfo>, 300360784Sdim std::map<StringRef, JITEvaluatedSymbol>)> 301360784Sdim OnLoaded, 302360784Sdim unique_function<void(Error)> OnEmitted); 303344779Sdim 304221337Sdim} // end namespace llvm 305221337Sdim 306296417Sdim#endif // LLVM_EXECUTIONENGINE_RUNTIMEDYLD_H 307