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 jitLinkForORC(
271 object::OwningBinary<object::ObjectFile> O,
272 RuntimeDyld::MemoryManager &MemMgr, JITSymbolResolver &Resolver,
273 bool ProcessAllSections,
274 unique_function<Error(const object::ObjectFile &Obj, LoadedObjectInfo &,
275 std::map<StringRef, JITEvaluatedSymbol>)>
276 OnLoaded,
277 unique_function<void(object::OwningBinary<object::ObjectFile> O,
278 std::unique_ptr<LoadedObjectInfo>, Error)>
279 OnEmitted);
280
281 // RuntimeDyldImpl is the actual class. RuntimeDyld is just the public
282 // interface.
283 std::unique_ptr<RuntimeDyldImpl> Dyld;
284 MemoryManager &MemMgr;
285 JITSymbolResolver &Resolver;
286 bool ProcessAllSections;
287 NotifyStubEmittedFunction NotifyStubEmitted;
288};
289
290// Asynchronous JIT link for ORC.
291//
292// Warning: This API is experimental and probably should not be used by anyone
293// but ORC's RTDyldObjectLinkingLayer2. Internally it constructs a RuntimeDyld
294// instance and uses continuation passing to perform the fix-up and finalize
295// steps asynchronously.
296void jitLinkForORC(
297 object::OwningBinary<object::ObjectFile> O,
298 RuntimeDyld::MemoryManager &MemMgr, JITSymbolResolver &Resolver,
299 bool ProcessAllSections,
300 unique_function<Error(const object::ObjectFile &Obj,
301 RuntimeDyld::LoadedObjectInfo &,
302 std::map<StringRef, JITEvaluatedSymbol>)>
303 OnLoaded,
304 unique_function<void(object::OwningBinary<object::ObjectFile>,
305 std::unique_ptr<RuntimeDyld::LoadedObjectInfo>, Error)>
306 OnEmitted);
307
308} // end namespace llvm
309
310#endif // LLVM_EXECUTIONENGINE_RUNTIMEDYLD_H
311