1 //===- JITSymbol.h - JIT symbol abstraction ---------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // Abstraction for target process addresses.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_EXECUTIONENGINE_JITSYMBOL_H
15 #define LLVM_EXECUTIONENGINE_JITSYMBOL_H
26 #include "llvm/ADT/BitmaskEnum.h"
27 #include "llvm/ADT/StringRef.h"
28 #include "llvm/Support/Error.h"
38 } // end namespace object
40 /// Represents an address in the target process's address space.
41 using JITTargetAddress = uint64_t;
43 /// Convert a JITTargetAddress to a pointer.
44 template <typename T> T jitTargetAddressToPointer(JITTargetAddress Addr) {
45 static_assert(std::is_pointer<T>::value, "T must be a pointer type");
46 uintptr_t IntPtr = static_cast<uintptr_t>(Addr);
47 assert(IntPtr == Addr && "JITTargetAddress value out of range for uintptr_t");
48 return reinterpret_cast<T>(IntPtr);
51 template <typename T> JITTargetAddress pointerToJITTargetAddress(T *Ptr) {
52 return static_cast<JITTargetAddress>(reinterpret_cast<uintptr_t>(Ptr));
55 /// Flags for symbols in the JIT.
56 class JITSymbolFlags {
58 using UnderlyingType = uint8_t;
59 using TargetFlagsType = uint64_t;
61 enum FlagNames : UnderlyingType {
70 Materializing = 1U << 7,
71 LLVM_MARK_AS_BITMASK_ENUM(/* LargestValue = */ Materializing)
74 static JITSymbolFlags stripTransientFlags(JITSymbolFlags Orig) {
75 return static_cast<FlagNames>(Orig.Flags & ~Lazy & ~Materializing);
78 /// Default-construct a JITSymbolFlags instance.
79 JITSymbolFlags() = default;
81 /// Construct a JITSymbolFlags instance from the given flags.
82 JITSymbolFlags(FlagNames Flags) : Flags(Flags) {}
84 /// Construct a JITSymbolFlags instance from the given flags and target
86 JITSymbolFlags(FlagNames Flags, TargetFlagsType TargetFlags)
87 : Flags(Flags), TargetFlags(TargetFlags) {}
89 /// Implicitly convert to bool. Returs true if any flag is set.
90 explicit operator bool() const { return Flags != None || TargetFlags != 0; }
92 /// Compare for equality.
93 bool operator==(const JITSymbolFlags &RHS) const {
94 return Flags == RHS.Flags && TargetFlags == RHS.TargetFlags;
97 /// Bitwise AND-assignment for FlagNames.
98 JITSymbolFlags &operator&=(const FlagNames &RHS) {
103 /// Bitwise OR-assignment for FlagNames.
104 JITSymbolFlags &operator|=(const FlagNames &RHS) {
109 /// Return true if there was an error retrieving this symbol.
110 bool hasError() const {
111 return (Flags & HasError) == HasError;
114 /// Returns true if this is a lazy symbol.
115 /// This flag is used internally by the JIT APIs to track
116 /// materialization states.
117 bool isLazy() const { return Flags & Lazy; }
119 /// Returns true if this symbol is in the process of being
121 bool isMaterializing() const { return Flags & Materializing; }
123 /// Returns true if this symbol is fully materialized.
124 /// (i.e. neither lazy, nor materializing).
125 bool isMaterialized() const { return !(Flags & (Lazy | Materializing)); }
127 /// Returns true if the Weak flag is set.
128 bool isWeak() const {
129 return (Flags & Weak) == Weak;
132 /// Returns true if the Common flag is set.
133 bool isCommon() const {
134 return (Flags & Common) == Common;
137 /// Returns true if the symbol isn't weak or common.
138 bool isStrong() const {
139 return !isWeak() && !isCommon();
142 /// Returns true if the Exported flag is set.
143 bool isExported() const {
144 return (Flags & Exported) == Exported;
147 /// Returns true if the given symbol is known to be callable.
148 bool isCallable() const { return (Flags & Callable) == Callable; }
150 /// Get the underlying flags value as an integer.
151 UnderlyingType getRawFlagsValue() const {
152 return static_cast<UnderlyingType>(Flags);
155 /// Return a reference to the target-specific flags.
156 TargetFlagsType& getTargetFlags() { return TargetFlags; }
158 /// Return a reference to the target-specific flags.
159 const TargetFlagsType& getTargetFlags() const { return TargetFlags; }
161 /// Construct a JITSymbolFlags value based on the flags of the given global
163 static JITSymbolFlags fromGlobalValue(const GlobalValue &GV);
165 /// Construct a JITSymbolFlags value based on the flags of the given libobject
167 static Expected<JITSymbolFlags>
168 fromObjectSymbol(const object::SymbolRef &Symbol);
171 FlagNames Flags = None;
172 TargetFlagsType TargetFlags = 0;
175 inline JITSymbolFlags operator&(const JITSymbolFlags &LHS,
176 const JITSymbolFlags::FlagNames &RHS) {
177 JITSymbolFlags Tmp = LHS;
182 inline JITSymbolFlags operator|(const JITSymbolFlags &LHS,
183 const JITSymbolFlags::FlagNames &RHS) {
184 JITSymbolFlags Tmp = LHS;
189 /// ARM-specific JIT symbol flags.
190 /// FIXME: This should be moved into a target-specific header.
191 class ARMJITSymbolFlags {
193 ARMJITSymbolFlags() = default;
200 operator JITSymbolFlags::TargetFlagsType&() { return Flags; }
202 static ARMJITSymbolFlags fromObjectSymbol(const object::SymbolRef &Symbol);
205 JITSymbolFlags::TargetFlagsType Flags = 0;
208 /// Represents a symbol that has been evaluated to an address already.
209 class JITEvaluatedSymbol {
211 JITEvaluatedSymbol() = default;
213 /// Create a 'null' symbol.
214 JITEvaluatedSymbol(std::nullptr_t) {}
216 /// Create a symbol for the given address and flags.
217 JITEvaluatedSymbol(JITTargetAddress Address, JITSymbolFlags Flags)
218 : Address(Address), Flags(Flags) {}
220 /// An evaluated symbol converts to 'true' if its address is non-zero.
221 explicit operator bool() const { return Address != 0; }
223 /// Return the address of this symbol.
224 JITTargetAddress getAddress() const { return Address; }
226 /// Return the flags for this symbol.
227 JITSymbolFlags getFlags() const { return Flags; }
229 /// Set the flags for this symbol.
230 void setFlags(JITSymbolFlags Flags) { this->Flags = std::move(Flags); }
233 JITTargetAddress Address = 0;
234 JITSymbolFlags Flags;
237 /// Represents a symbol in the JIT.
240 using GetAddressFtor = std::function<Expected<JITTargetAddress>()>;
242 /// Create a 'null' symbol, used to represent a "symbol not found"
243 /// result from a successful (non-erroneous) lookup.
244 JITSymbol(std::nullptr_t)
247 /// Create a JITSymbol representing an error in the symbol lookup
248 /// process (e.g. a network failure during a remote lookup).
250 : Err(std::move(Err)), Flags(JITSymbolFlags::HasError) {}
252 /// Create a symbol for a definition with a known address.
253 JITSymbol(JITTargetAddress Addr, JITSymbolFlags Flags)
254 : CachedAddr(Addr), Flags(Flags) {}
256 /// Construct a JITSymbol from a JITEvaluatedSymbol.
257 JITSymbol(JITEvaluatedSymbol Sym)
258 : CachedAddr(Sym.getAddress()), Flags(Sym.getFlags()) {}
260 /// Create a symbol for a definition that doesn't have a known address
262 /// @param GetAddress A functor to materialize a definition (fixing the
263 /// address) on demand.
265 /// This constructor allows a JIT layer to provide a reference to a symbol
266 /// definition without actually materializing the definition up front. The
267 /// user can materialize the definition at any time by calling the getAddress
269 JITSymbol(GetAddressFtor GetAddress, JITSymbolFlags Flags)
270 : GetAddress(std::move(GetAddress)), CachedAddr(0), Flags(Flags) {}
272 JITSymbol(const JITSymbol&) = delete;
273 JITSymbol& operator=(const JITSymbol&) = delete;
275 JITSymbol(JITSymbol &&Other)
276 : GetAddress(std::move(Other.GetAddress)), Flags(std::move(Other.Flags)) {
277 if (Flags.hasError())
278 Err = std::move(Other.Err);
280 CachedAddr = std::move(Other.CachedAddr);
283 JITSymbol& operator=(JITSymbol &&Other) {
284 GetAddress = std::move(Other.GetAddress);
285 Flags = std::move(Other.Flags);
286 if (Flags.hasError())
287 Err = std::move(Other.Err);
289 CachedAddr = std::move(Other.CachedAddr);
294 if (Flags.hasError())
297 CachedAddr.~JITTargetAddress();
300 /// Returns true if the symbol exists, false otherwise.
301 explicit operator bool() const {
302 return !Flags.hasError() && (CachedAddr || GetAddress);
305 /// Move the error field value out of this JITSymbol.
307 if (Flags.hasError())
308 return std::move(Err);
309 return Error::success();
312 /// Get the address of the symbol in the target address space. Returns
313 /// '0' if the symbol does not exist.
314 Expected<JITTargetAddress> getAddress() {
315 assert(!Flags.hasError() && "getAddress called on error value");
317 if (auto CachedAddrOrErr = GetAddress()) {
318 GetAddress = nullptr;
319 CachedAddr = *CachedAddrOrErr;
320 assert(CachedAddr && "Symbol could not be materialized.");
322 return CachedAddrOrErr.takeError();
327 JITSymbolFlags getFlags() const { return Flags; }
330 GetAddressFtor GetAddress;
332 JITTargetAddress CachedAddr;
335 JITSymbolFlags Flags;
338 /// Symbol resolution interface.
340 /// Allows symbol flags and addresses to be looked up by name.
341 /// Symbol queries are done in bulk (i.e. you request resolution of a set of
342 /// symbols, rather than a single one) to reduce IPC overhead in the case of
343 /// remote JITing, and expose opportunities for parallel compilation.
344 class JITSymbolResolver {
346 using LookupSet = std::set<StringRef>;
347 using LookupResult = std::map<StringRef, JITEvaluatedSymbol>;
348 using OnResolvedFunction = std::function<void(Expected<LookupResult>)>;
350 virtual ~JITSymbolResolver() = default;
352 /// Returns the fully resolved address and flags for each of the given
355 /// This method will return an error if any of the given symbols can not be
356 /// resolved, or if the resolution process itself triggers an error.
357 virtual void lookup(const LookupSet &Symbols,
358 OnResolvedFunction OnResolved) = 0;
360 /// Returns the subset of the given symbols that should be materialized by
361 /// the caller. Only weak/common symbols should be looked up, as strong
362 /// definitions are implicitly always part of the caller's responsibility.
363 virtual Expected<LookupSet>
364 getResponsibilitySet(const LookupSet &Symbols) = 0;
367 virtual void anchor();
370 /// Legacy symbol resolution interface.
371 class LegacyJITSymbolResolver : public JITSymbolResolver {
373 /// Performs lookup by, for each symbol, first calling
374 /// findSymbolInLogicalDylib and if that fails calling
376 void lookup(const LookupSet &Symbols, OnResolvedFunction OnResolved) final;
378 /// Performs flags lookup by calling findSymbolInLogicalDylib and
379 /// returning the flags value for that symbol.
380 Expected<LookupSet> getResponsibilitySet(const LookupSet &Symbols) final;
382 /// This method returns the address of the specified symbol if it exists
383 /// within the logical dynamic library represented by this JITSymbolResolver.
384 /// Unlike findSymbol, queries through this interface should return addresses
385 /// for hidden symbols.
387 /// This is of particular importance for the Orc JIT APIs, which support lazy
388 /// compilation by breaking up modules: Each of those broken out modules
389 /// must be able to resolve hidden symbols provided by the others. Clients
390 /// writing memory managers for MCJIT can usually ignore this method.
392 /// This method will be queried by RuntimeDyld when checking for previous
393 /// definitions of common symbols.
394 virtual JITSymbol findSymbolInLogicalDylib(const std::string &Name) = 0;
396 /// This method returns the address of the specified function or variable.
397 /// It is used to resolve symbols during module linking.
399 /// If the returned symbol's address is equal to ~0ULL then RuntimeDyld will
400 /// skip all relocations for that symbol, and the client will be responsible
401 /// for handling them manually.
402 virtual JITSymbol findSymbol(const std::string &Name) = 0;
405 virtual void anchor();
408 } // end namespace llvm
410 #endif // LLVM_EXECUTIONENGINE_JITSYMBOL_H