LLVM  3.7.0
RuntimeDyld.h
Go to the documentation of this file.
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/ADT/StringRef.h"
20 #include "llvm/Support/Memory.h"
22 #include <memory>
23 
24 namespace llvm {
25 
26 namespace object {
27  class ObjectFile;
28  template <typename T> class OwningBinary;
29 }
30 
31 class RuntimeDyldImpl;
33 
34 class RuntimeDyld {
35  friend class RuntimeDyldCheckerImpl;
36 
37  RuntimeDyld(const RuntimeDyld &) = delete;
38  void operator=(const RuntimeDyld &) = delete;
39 
40 protected:
41  // Change the address associated with a section when resolving relocations.
42  // Any relocations already associated with the symbol will be re-resolved.
43  void reassignSectionAddress(unsigned SectionID, uint64_t Addr);
44 public:
45 
46  /// \brief Information about a named symbol.
47  class SymbolInfo : public JITSymbolBase {
48  public:
49  SymbolInfo(std::nullptr_t) : JITSymbolBase(JITSymbolFlags::None), Address(0) {}
50  SymbolInfo(uint64_t Address, JITSymbolFlags Flags)
51  : JITSymbolBase(Flags), Address(Address) {}
52  explicit operator bool() const { return Address != 0; }
53  uint64_t getAddress() const { return Address; }
54  private:
55  uint64_t Address;
56  };
57 
58  /// \brief Information about the loaded object.
60  friend class RuntimeDyldImpl;
61  public:
63  unsigned EndIdx)
64  : RTDyld(RTDyld), BeginIdx(BeginIdx), EndIdx(EndIdx) { }
65 
67  getObjectForDebug(const object::ObjectFile &Obj) const = 0;
68 
69  uint64_t getSectionLoadAddress(StringRef Name) const;
70 
71  protected:
72  virtual void anchor();
73 
75  unsigned BeginIdx, EndIdx;
76  };
77 
78  template <typename Derived> struct LoadedObjectInfoHelper : LoadedObjectInfo {
80  unsigned EndIdx)
81  : LoadedObjectInfo(RTDyld, BeginIdx, EndIdx) {}
82  std::unique_ptr<llvm::LoadedObjectInfo> clone() const override {
83  return llvm::make_unique<Derived>(static_cast<const Derived &>(*this));
84  }
85  };
86 
87  /// \brief Memory Management.
88  class MemoryManager {
89  public:
90  virtual ~MemoryManager() {};
91 
92  /// Allocate a memory block of (at least) the given size suitable for
93  /// executable code. The SectionID is a unique identifier assigned by the
94  /// RuntimeDyld instance, and optionally recorded by the memory manager to
95  /// access a loaded section.
96  virtual uint8_t *allocateCodeSection(uintptr_t Size, unsigned Alignment,
97  unsigned SectionID,
98  StringRef SectionName) = 0;
99 
100  /// Allocate a memory block of (at least) the given size suitable for data.
101  /// The SectionID is a unique identifier assigned by the JIT engine, and
102  /// optionally recorded by the memory manager to access a loaded section.
103  virtual uint8_t *allocateDataSection(uintptr_t Size, unsigned Alignment,
104  unsigned SectionID,
105  StringRef SectionName,
106  bool IsReadOnly) = 0;
107 
108  /// Inform the memory manager about the total amount of memory required to
109  /// allocate all sections to be loaded:
110  /// \p CodeSize - the total size of all code sections
111  /// \p DataSizeRO - the total size of all read-only data sections
112  /// \p DataSizeRW - the total size of all read-write data sections
113  ///
114  /// Note that by default the callback is disabled. To enable it
115  /// redefine the method needsToReserveAllocationSpace to return true.
116  virtual void reserveAllocationSpace(uintptr_t CodeSize,
117  uintptr_t DataSizeRO,
118  uintptr_t DataSizeRW) {}
119 
120  /// Override to return true to enable the reserveAllocationSpace callback.
121  virtual bool needsToReserveAllocationSpace() { return false; }
122 
123  /// Register the EH frames with the runtime so that c++ exceptions work.
124  ///
125  /// \p Addr parameter provides the local address of the EH frame section
126  /// data, while \p LoadAddr provides the address of the data in the target
127  /// address space. If the section has not been remapped (which will usually
128  /// be the case for local execution) these two values will be the same.
129  virtual void registerEHFrames(uint8_t *Addr, uint64_t LoadAddr,
130  size_t Size) = 0;
131  virtual void deregisterEHFrames(uint8_t *addr, uint64_t LoadAddr,
132  size_t Size) = 0;
133 
134  /// This method is called when object loading is complete and section page
135  /// permissions can be applied. It is up to the memory manager implementation
136  /// to decide whether or not to act on this method. The memory manager will
137  /// typically allocate all sections as read-write and then apply specific
138  /// permissions when this method is called. Code sections cannot be executed
139  /// until this function has been called. In addition, any cache coherency
140  /// operations needed to reliably use the memory are also performed.
141  ///
142  /// Returns true if an error occurred, false otherwise.
143  virtual bool finalizeMemory(std::string *ErrMsg = nullptr) = 0;
144 
145  private:
146  virtual void anchor();
147  };
148 
149  /// \brief Symbol resolution.
151  public:
152  virtual ~SymbolResolver() {};
153 
154  /// This method returns the address of the specified function or variable.
155  /// It is used to resolve symbols during module linking.
156  ///
157  /// If the returned symbol's address is equal to ~0ULL then RuntimeDyld will
158  /// skip all relocations for that symbol, and the client will be responsible
159  /// for handling them manually.
160  virtual SymbolInfo findSymbol(const std::string &Name) = 0;
161 
162  /// This method returns the address of the specified symbol if it exists
163  /// within the logical dynamic library represented by this
164  /// RTDyldMemoryManager. Unlike getSymbolAddress, queries through this
165  /// interface should return addresses for hidden symbols.
166  ///
167  /// This is of particular importance for the Orc JIT APIs, which support lazy
168  /// compilation by breaking up modules: Each of those broken out modules
169  /// must be able to resolve hidden symbols provided by the others. Clients
170  /// writing memory managers for MCJIT can usually ignore this method.
171  ///
172  /// This method will be queried by RuntimeDyld when checking for previous
173  /// definitions of common symbols. It will *not* be queried by default when
174  /// resolving external symbols (this minimises the link-time overhead for
175  /// MCJIT clients who don't care about Orc features). If you are writing a
176  /// RTDyldMemoryManager for Orc and want "external" symbol resolution to
177  /// search the logical dylib, you should override your getSymbolAddress
178  /// method call this method directly.
179  virtual SymbolInfo findSymbolInLogicalDylib(const std::string &Name) = 0;
180  private:
181  virtual void anchor();
182  };
183 
184  /// \brief Construct a RuntimeDyld instance.
185  RuntimeDyld(MemoryManager &MemMgr, SymbolResolver &Resolver);
186  ~RuntimeDyld();
187 
188  /// Add the referenced object file to the list of objects to be loaded and
189  /// relocated.
190  std::unique_ptr<LoadedObjectInfo> loadObject(const object::ObjectFile &O);
191 
192  /// Get the address of our local copy of the symbol. This may or may not
193  /// be the address used for relocation (clients can copy the data around
194  /// and resolve relocatons based on where they put it).
195  void *getSymbolLocalAddress(StringRef Name) const;
196 
197  /// Get the target address and flags for the named symbol.
198  /// This address is the one used for relocation.
199  SymbolInfo getSymbol(StringRef Name) const;
200 
201  /// Resolve the relocations for all symbols we currently know about.
202  void resolveRelocations();
203 
204  /// Map a section to its target address space value.
205  /// Map the address of a JIT section as returned from the memory manager
206  /// to the address in the target process as the running code will see it.
207  /// This is the address which will be used for relocation resolution.
208  void mapSectionAddress(const void *LocalAddress, uint64_t TargetAddress);
209 
210  /// Register any EH frame sections that have been loaded but not previously
211  /// registered with the memory manager. Note, RuntimeDyld is responsible
212  /// for identifying the EH frame and calling the memory manager with the
213  /// EH frame section data. However, the memory manager itself will handle
214  /// the actual target-specific EH frame registration.
215  void registerEHFrames();
216 
217  void deregisterEHFrames();
218 
219  bool hasError();
221 
222  /// By default, only sections that are "required for execution" are passed to
223  /// the RTDyldMemoryManager, and other sections are discarded. Passing 'true'
224  /// to this method will cause RuntimeDyld to pass all sections to its
225  /// memory manager regardless of whether they are "required to execute" in the
226  /// usual sense. This is useful for inspecting metadata sections that may not
227  /// contain relocations, E.g. Debug info, stackmaps.
228  ///
229  /// Must be called before the first object file is loaded.
230  void setProcessAllSections(bool ProcessAllSections) {
231  assert(!Dyld && "setProcessAllSections must be called before loadObject.");
232  this->ProcessAllSections = ProcessAllSections;
233  }
234 
235 private:
236  // RuntimeDyldImpl is the actual class. RuntimeDyld is just the public
237  // interface.
238  std::unique_ptr<RuntimeDyldImpl> Dyld;
239  MemoryManager &MemMgr;
240  SymbolResolver &Resolver;
241  bool ProcessAllSections;
242  RuntimeDyldCheckerImpl *Checker;
243 };
244 
245 } // end namespace llvm
246 
247 #endif
Information about the loaded object.
Definition: RuntimeDyld.h:59
std::unique_ptr< LoadedObjectInfo > loadObject(const object::ObjectFile &O)
Add the referenced object file to the list of objects to be loaded and relocated. ...
void registerEHFrames()
Register any EH frame sections that have been loaded but not previously registered with the memory ma...
StringRef getErrorString()
uint64_t getAddress() const
Definition: RuntimeDyld.h:53
This class is the base class for all object file types.
Definition: ObjectFile.h:176
Base class for symbols in the JIT.
SymbolInfo getSymbol(StringRef Name) const
Get the target address and flags for the named symbol.
SymbolInfo(uint64_t Address, JITSymbolFlags Flags)
Definition: RuntimeDyld.h:50
virtual bool needsToReserveAllocationSpace()
Override to return true to enable the reserveAllocationSpace callback.
Definition: RuntimeDyld.h:121
virtual void deregisterEHFrames(uint8_t *addr, uint64_t LoadAddr, size_t Size)=0
virtual void reserveAllocationSpace(uintptr_t CodeSize, uintptr_t DataSizeRO, uintptr_t DataSizeRW)
Inform the memory manager about the total amount of memory required to allocate all sections to be lo...
Definition: RuntimeDyld.h:116
void * getSymbolLocalAddress(StringRef Name) const
Get the address of our local copy of the symbol.
void setProcessAllSections(bool ProcessAllSections)
By default, only sections that are "required for execution" are passed to the RTDyldMemoryManager, and other sections are discarded.
Definition: RuntimeDyld.h:230
virtual bool finalizeMemory(std::string *ErrMsg=nullptr)=0
This method is called when object loading is complete and section page permissions can be applied...
JITSymbolFlags
Flags for symbols in the JIT.
LoadedObjectInfo(RuntimeDyldImpl &RTDyld, unsigned BeginIdx, unsigned EndIdx)
Definition: RuntimeDyld.h:62
virtual SymbolInfo findSymbol(const std::string &Name)=0
This method returns the address of the specified function or variable.
LoadedObjectInfoHelper(RuntimeDyldImpl &RTDyld, unsigned BeginIdx, unsigned EndIdx)
Definition: RuntimeDyld.h:79
virtual uint8_t * allocateDataSection(uintptr_t Size, unsigned Alignment, unsigned SectionID, StringRef SectionName, bool IsReadOnly)=0
Allocate a memory block of (at least) the given size suitable for data.
virtual uint8_t * allocateCodeSection(uintptr_t Size, unsigned Alignment, unsigned SectionID, StringRef SectionName)=0
Allocate a memory block of (at least) the given size suitable for executable code.
virtual object::OwningBinary< object::ObjectFile > getObjectForDebug(const object::ObjectFile &Obj) const =0
uint64_t TargetAddress
Represents an address in the target process's address space.
Definition: JITSymbol.h:26
uint64_t getSectionLoadAddress(StringRef Name) const
Obtain the Load Address of a section by Name.
An inferface for inquiring the load address of a loaded object file to be used by the DIContext imple...
Definition: DIContext.h:142
virtual SymbolInfo findSymbolInLogicalDylib(const std::string &Name)=0
This method returns the address of the specified symbol if it exists within the logical dynamic libra...
std::unique_ptr< llvm::LoadedObjectInfo > clone() const override
Obtain a copy of this LoadedObjectInfo.
Definition: RuntimeDyld.h:82
Information about a named symbol.
Definition: RuntimeDyld.h:47
void resolveRelocations()
Resolve the relocations for all symbols we currently know about.
SymbolInfo(std::nullptr_t)
Definition: RuntimeDyld.h:49
void reassignSectionAddress(unsigned SectionID, uint64_t Addr)
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:40
virtual void registerEHFrames(uint8_t *Addr, uint64_t LoadAddr, size_t Size)=0
Register the EH frames with the runtime so that c++ exceptions work.
void mapSectionAddress(const void *LocalAddress, uint64_t TargetAddress)
Map a section to its target address space value.
void * addr