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