JITSymbol.h revision 360784
1//===- JITSymbol.h - JIT symbol abstraction ---------------------*- 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// Abstraction for target process addresses. 10// 11//===----------------------------------------------------------------------===// 12 13#ifndef LLVM_EXECUTIONENGINE_JITSYMBOL_H 14#define LLVM_EXECUTIONENGINE_JITSYMBOL_H 15 16#include <algorithm> 17#include <cassert> 18#include <cstddef> 19#include <cstdint> 20#include <functional> 21#include <map> 22#include <set> 23#include <string> 24 25#include "llvm/ADT/BitmaskEnum.h" 26#include "llvm/ADT/FunctionExtras.h" 27#include "llvm/ADT/StringRef.h" 28#include "llvm/Support/Error.h" 29 30namespace llvm { 31 32class GlobalValue; 33 34namespace object { 35 36class SymbolRef; 37 38} // end namespace object 39 40/// Represents an address in the target process's address space. 41using JITTargetAddress = uint64_t; 42 43/// Convert a JITTargetAddress to a pointer. 44/// 45/// Note: This is a raw cast of the address bit pattern to the given pointer 46/// type. When casting to a function pointer in order to execute JIT'd code 47/// jitTargetAddressToFunction should be preferred, as it will also perform 48/// pointer signing on targets that require it. 49template <typename T> T jitTargetAddressToPointer(JITTargetAddress Addr) { 50 static_assert(std::is_pointer<T>::value, "T must be a pointer type"); 51 uintptr_t IntPtr = static_cast<uintptr_t>(Addr); 52 assert(IntPtr == Addr && "JITTargetAddress value out of range for uintptr_t"); 53 return reinterpret_cast<T>(IntPtr); 54} 55 56/// Convert a JITTargetAddress to a callable function pointer. 57/// 58/// Casts the given address to a callable function pointer. This operation 59/// will perform pointer signing for platforms that require it (e.g. arm64e). 60template <typename T> T jitTargetAddressToFunction(JITTargetAddress Addr) { 61 static_assert( 62 std::is_pointer<T>::value && 63 std::is_function<typename std::remove_pointer<T>::type>::value, 64 "T must be a function pointer type"); 65 return jitTargetAddressToPointer<T>(Addr); 66} 67 68/// Convert a pointer to a JITTargetAddress. 69template <typename T> JITTargetAddress pointerToJITTargetAddress(T *Ptr) { 70 return static_cast<JITTargetAddress>(reinterpret_cast<uintptr_t>(Ptr)); 71} 72 73/// Flags for symbols in the JIT. 74class JITSymbolFlags { 75public: 76 using UnderlyingType = uint8_t; 77 using TargetFlagsType = uint8_t; 78 79 enum FlagNames : UnderlyingType { 80 None = 0, 81 HasError = 1U << 0, 82 Weak = 1U << 1, 83 Common = 1U << 2, 84 Absolute = 1U << 3, 85 Exported = 1U << 4, 86 Callable = 1U << 5, 87 LLVM_MARK_AS_BITMASK_ENUM(/* LargestValue = */ Callable) 88 }; 89 90 /// Default-construct a JITSymbolFlags instance. 91 JITSymbolFlags() = default; 92 93 /// Construct a JITSymbolFlags instance from the given flags. 94 JITSymbolFlags(FlagNames Flags) : Flags(Flags) {} 95 96 /// Construct a JITSymbolFlags instance from the given flags and target 97 /// flags. 98 JITSymbolFlags(FlagNames Flags, TargetFlagsType TargetFlags) 99 : TargetFlags(TargetFlags), Flags(Flags) {} 100 101 /// Implicitly convert to bool. Returs true if any flag is set. 102 explicit operator bool() const { return Flags != None || TargetFlags != 0; } 103 104 /// Compare for equality. 105 bool operator==(const JITSymbolFlags &RHS) const { 106 return Flags == RHS.Flags && TargetFlags == RHS.TargetFlags; 107 } 108 109 /// Bitwise AND-assignment for FlagNames. 110 JITSymbolFlags &operator&=(const FlagNames &RHS) { 111 Flags &= RHS; 112 return *this; 113 } 114 115 /// Bitwise OR-assignment for FlagNames. 116 JITSymbolFlags &operator|=(const FlagNames &RHS) { 117 Flags |= RHS; 118 return *this; 119 } 120 121 /// Return true if there was an error retrieving this symbol. 122 bool hasError() const { 123 return (Flags & HasError) == HasError; 124 } 125 126 /// Returns true if the Weak flag is set. 127 bool isWeak() const { 128 return (Flags & Weak) == Weak; 129 } 130 131 /// Returns true if the Common flag is set. 132 bool isCommon() const { 133 return (Flags & Common) == Common; 134 } 135 136 /// Returns true if the symbol isn't weak or common. 137 bool isStrong() const { 138 return !isWeak() && !isCommon(); 139 } 140 141 /// Returns true if the Exported flag is set. 142 bool isExported() const { 143 return (Flags & Exported) == Exported; 144 } 145 146 /// Returns true if the given symbol is known to be callable. 147 bool isCallable() const { return (Flags & Callable) == Callable; } 148 149 /// Get the underlying flags value as an integer. 150 UnderlyingType getRawFlagsValue() const { 151 return static_cast<UnderlyingType>(Flags); 152 } 153 154 /// Return a reference to the target-specific flags. 155 TargetFlagsType& getTargetFlags() { return TargetFlags; } 156 157 /// Return a reference to the target-specific flags. 158 const TargetFlagsType& getTargetFlags() const { return TargetFlags; } 159 160 /// Construct a JITSymbolFlags value based on the flags of the given global 161 /// value. 162 static JITSymbolFlags fromGlobalValue(const GlobalValue &GV); 163 164 /// Construct a JITSymbolFlags value based on the flags of the given libobject 165 /// symbol. 166 static Expected<JITSymbolFlags> 167 fromObjectSymbol(const object::SymbolRef &Symbol); 168 169private: 170 TargetFlagsType TargetFlags = 0; 171 FlagNames Flags = None; 172}; 173 174inline JITSymbolFlags operator&(const JITSymbolFlags &LHS, 175 const JITSymbolFlags::FlagNames &RHS) { 176 JITSymbolFlags Tmp = LHS; 177 Tmp &= RHS; 178 return Tmp; 179} 180 181inline JITSymbolFlags operator|(const JITSymbolFlags &LHS, 182 const JITSymbolFlags::FlagNames &RHS) { 183 JITSymbolFlags Tmp = LHS; 184 Tmp |= RHS; 185 return Tmp; 186} 187 188/// ARM-specific JIT symbol flags. 189/// FIXME: This should be moved into a target-specific header. 190class ARMJITSymbolFlags { 191public: 192 ARMJITSymbolFlags() = default; 193 194 enum FlagNames { 195 None = 0, 196 Thumb = 1 << 0 197 }; 198 199 operator JITSymbolFlags::TargetFlagsType&() { return Flags; } 200 201 static ARMJITSymbolFlags fromObjectSymbol(const object::SymbolRef &Symbol); 202 203private: 204 JITSymbolFlags::TargetFlagsType Flags = 0; 205}; 206 207/// Represents a symbol that has been evaluated to an address already. 208class JITEvaluatedSymbol { 209public: 210 JITEvaluatedSymbol() = default; 211 212 /// Create a 'null' symbol. 213 JITEvaluatedSymbol(std::nullptr_t) {} 214 215 /// Create a symbol for the given address and flags. 216 JITEvaluatedSymbol(JITTargetAddress Address, JITSymbolFlags Flags) 217 : Address(Address), Flags(Flags) {} 218 219 /// An evaluated symbol converts to 'true' if its address is non-zero. 220 explicit operator bool() const { return Address != 0; } 221 222 /// Return the address of this symbol. 223 JITTargetAddress getAddress() const { return Address; } 224 225 /// Return the flags for this symbol. 226 JITSymbolFlags getFlags() const { return Flags; } 227 228 /// Set the flags for this symbol. 229 void setFlags(JITSymbolFlags Flags) { this->Flags = std::move(Flags); } 230 231private: 232 JITTargetAddress Address = 0; 233 JITSymbolFlags Flags; 234}; 235 236/// Represents a symbol in the JIT. 237class JITSymbol { 238public: 239 using GetAddressFtor = unique_function<Expected<JITTargetAddress>()>; 240 241 /// Create a 'null' symbol, used to represent a "symbol not found" 242 /// result from a successful (non-erroneous) lookup. 243 JITSymbol(std::nullptr_t) 244 : CachedAddr(0) {} 245 246 /// Create a JITSymbol representing an error in the symbol lookup 247 /// process (e.g. a network failure during a remote lookup). 248 JITSymbol(Error Err) 249 : Err(std::move(Err)), Flags(JITSymbolFlags::HasError) {} 250 251 /// Create a symbol for a definition with a known address. 252 JITSymbol(JITTargetAddress Addr, JITSymbolFlags Flags) 253 : CachedAddr(Addr), Flags(Flags) {} 254 255 /// Construct a JITSymbol from a JITEvaluatedSymbol. 256 JITSymbol(JITEvaluatedSymbol Sym) 257 : CachedAddr(Sym.getAddress()), Flags(Sym.getFlags()) {} 258 259 /// Create a symbol for a definition that doesn't have a known address 260 /// yet. 261 /// @param GetAddress A functor to materialize a definition (fixing the 262 /// address) on demand. 263 /// 264 /// This constructor allows a JIT layer to provide a reference to a symbol 265 /// definition without actually materializing the definition up front. The 266 /// user can materialize the definition at any time by calling the getAddress 267 /// method. 268 JITSymbol(GetAddressFtor GetAddress, JITSymbolFlags Flags) 269 : GetAddress(std::move(GetAddress)), CachedAddr(0), Flags(Flags) {} 270 271 JITSymbol(const JITSymbol&) = delete; 272 JITSymbol& operator=(const JITSymbol&) = delete; 273 274 JITSymbol(JITSymbol &&Other) 275 : GetAddress(std::move(Other.GetAddress)), Flags(std::move(Other.Flags)) { 276 if (Flags.hasError()) 277 Err = std::move(Other.Err); 278 else 279 CachedAddr = std::move(Other.CachedAddr); 280 } 281 282 JITSymbol& operator=(JITSymbol &&Other) { 283 GetAddress = std::move(Other.GetAddress); 284 Flags = std::move(Other.Flags); 285 if (Flags.hasError()) 286 Err = std::move(Other.Err); 287 else 288 CachedAddr = std::move(Other.CachedAddr); 289 return *this; 290 } 291 292 ~JITSymbol() { 293 if (Flags.hasError()) 294 Err.~Error(); 295 else 296 CachedAddr.~JITTargetAddress(); 297 } 298 299 /// Returns true if the symbol exists, false otherwise. 300 explicit operator bool() const { 301 return !Flags.hasError() && (CachedAddr || GetAddress); 302 } 303 304 /// Move the error field value out of this JITSymbol. 305 Error takeError() { 306 if (Flags.hasError()) 307 return std::move(Err); 308 return Error::success(); 309 } 310 311 /// Get the address of the symbol in the target address space. Returns 312 /// '0' if the symbol does not exist. 313 Expected<JITTargetAddress> getAddress() { 314 assert(!Flags.hasError() && "getAddress called on error value"); 315 if (GetAddress) { 316 if (auto CachedAddrOrErr = GetAddress()) { 317 GetAddress = nullptr; 318 CachedAddr = *CachedAddrOrErr; 319 assert(CachedAddr && "Symbol could not be materialized."); 320 } else 321 return CachedAddrOrErr.takeError(); 322 } 323 return CachedAddr; 324 } 325 326 JITSymbolFlags getFlags() const { return Flags; } 327 328private: 329 GetAddressFtor GetAddress; 330 union { 331 JITTargetAddress CachedAddr; 332 Error Err; 333 }; 334 JITSymbolFlags Flags; 335}; 336 337/// Symbol resolution interface. 338/// 339/// Allows symbol flags and addresses to be looked up by name. 340/// Symbol queries are done in bulk (i.e. you request resolution of a set of 341/// symbols, rather than a single one) to reduce IPC overhead in the case of 342/// remote JITing, and expose opportunities for parallel compilation. 343class JITSymbolResolver { 344public: 345 using LookupSet = std::set<StringRef>; 346 using LookupResult = std::map<StringRef, JITEvaluatedSymbol>; 347 using OnResolvedFunction = unique_function<void(Expected<LookupResult>)>; 348 349 virtual ~JITSymbolResolver() = default; 350 351 /// Returns the fully resolved address and flags for each of the given 352 /// symbols. 353 /// 354 /// This method will return an error if any of the given symbols can not be 355 /// resolved, or if the resolution process itself triggers an error. 356 virtual void lookup(const LookupSet &Symbols, 357 OnResolvedFunction OnResolved) = 0; 358 359 /// Returns the subset of the given symbols that should be materialized by 360 /// the caller. Only weak/common symbols should be looked up, as strong 361 /// definitions are implicitly always part of the caller's responsibility. 362 virtual Expected<LookupSet> 363 getResponsibilitySet(const LookupSet &Symbols) = 0; 364 365private: 366 virtual void anchor(); 367}; 368 369/// Legacy symbol resolution interface. 370class LegacyJITSymbolResolver : public JITSymbolResolver { 371public: 372 /// Performs lookup by, for each symbol, first calling 373 /// findSymbolInLogicalDylib and if that fails calling 374 /// findSymbol. 375 void lookup(const LookupSet &Symbols, OnResolvedFunction OnResolved) final; 376 377 /// Performs flags lookup by calling findSymbolInLogicalDylib and 378 /// returning the flags value for that symbol. 379 Expected<LookupSet> getResponsibilitySet(const LookupSet &Symbols) final; 380 381 /// This method returns the address of the specified symbol if it exists 382 /// within the logical dynamic library represented by this JITSymbolResolver. 383 /// Unlike findSymbol, queries through this interface should return addresses 384 /// for hidden symbols. 385 /// 386 /// This is of particular importance for the Orc JIT APIs, which support lazy 387 /// compilation by breaking up modules: Each of those broken out modules 388 /// must be able to resolve hidden symbols provided by the others. Clients 389 /// writing memory managers for MCJIT can usually ignore this method. 390 /// 391 /// This method will be queried by RuntimeDyld when checking for previous 392 /// definitions of common symbols. 393 virtual JITSymbol findSymbolInLogicalDylib(const std::string &Name) = 0; 394 395 /// This method returns the address of the specified function or variable. 396 /// It is used to resolve symbols during module linking. 397 /// 398 /// If the returned symbol's address is equal to ~0ULL then RuntimeDyld will 399 /// skip all relocations for that symbol, and the client will be responsible 400 /// for handling them manually. 401 virtual JITSymbol findSymbol(const std::string &Name) = 0; 402 403private: 404 virtual void anchor(); 405}; 406 407} // end namespace llvm 408 409#endif // LLVM_EXECUTIONENGINE_JITSYMBOL_H 410