1 //===- ExecutorProcessControl.h - Executor process control APIs -*- 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 // Utilities for interacting with the executor processes. 10 // 11 //===----------------------------------------------------------------------===// 12 13 #ifndef LLVM_EXECUTIONENGINE_ORC_EXECUTORPROCESSCONTROL_H 14 #define LLVM_EXECUTIONENGINE_ORC_EXECUTORPROCESSCONTROL_H 15 16 #include "llvm/ADT/StringRef.h" 17 #include "llvm/ExecutionEngine/JITLink/JITLinkMemoryManager.h" 18 #include "llvm/ExecutionEngine/Orc/Shared/ExecutorAddress.h" 19 #include "llvm/ExecutionEngine/Orc/Shared/TargetProcessControlTypes.h" 20 #include "llvm/ExecutionEngine/Orc/Shared/WrapperFunctionUtils.h" 21 #include "llvm/ExecutionEngine/Orc/SymbolStringPool.h" 22 #include "llvm/ExecutionEngine/Orc/TaskDispatch.h" 23 #include "llvm/Support/DynamicLibrary.h" 24 #include "llvm/Support/MSVCErrorWorkarounds.h" 25 #include "llvm/TargetParser/Triple.h" 26 27 #include <future> 28 #include <mutex> 29 #include <vector> 30 31 namespace llvm { 32 namespace orc { 33 34 class ExecutionSession; 35 class SymbolLookupSet; 36 37 /// ExecutorProcessControl supports interaction with a JIT target process. 38 class ExecutorProcessControl { 39 friend class ExecutionSession; 40 public: 41 42 /// A handler or incoming WrapperFunctionResults -- either return values from 43 /// callWrapper* calls, or incoming JIT-dispatch requests. 44 /// 45 /// IncomingWFRHandlers are constructible from 46 /// unique_function<void(shared::WrapperFunctionResult)>s using the 47 /// runInPlace function or a RunWithDispatch object. 48 class IncomingWFRHandler { 49 friend class ExecutorProcessControl; 50 public: 51 IncomingWFRHandler() = default; 52 explicit operator bool() const { return !!H; } 53 void operator()(shared::WrapperFunctionResult WFR) { H(std::move(WFR)); } 54 private: 55 template <typename FnT> IncomingWFRHandler(FnT &&Fn) 56 : H(std::forward<FnT>(Fn)) {} 57 58 unique_function<void(shared::WrapperFunctionResult)> H; 59 }; 60 61 /// Constructs an IncomingWFRHandler from a function object that is callable 62 /// as void(shared::WrapperFunctionResult). The function object will be called 63 /// directly. This should be used with care as it may block listener threads 64 /// in remote EPCs. It is only suitable for simple tasks (e.g. setting a 65 /// future), or for performing some quick analysis before dispatching "real" 66 /// work as a Task. 67 class RunInPlace { 68 public: 69 template <typename FnT> 70 IncomingWFRHandler operator()(FnT &&Fn) { 71 return IncomingWFRHandler(std::forward<FnT>(Fn)); 72 } 73 }; 74 75 /// Constructs an IncomingWFRHandler from a function object by creating a new 76 /// function object that dispatches the original using a TaskDispatcher, 77 /// wrapping the original as a GenericNamedTask. 78 /// 79 /// This is the default approach for running WFR handlers. 80 class RunAsTask { 81 public: 82 RunAsTask(TaskDispatcher &D) : D(D) {} 83 84 template <typename FnT> 85 IncomingWFRHandler operator()(FnT &&Fn) { 86 return IncomingWFRHandler( 87 [&D = this->D, Fn = std::move(Fn)] 88 (shared::WrapperFunctionResult WFR) mutable { 89 D.dispatch( 90 makeGenericNamedTask( 91 [Fn = std::move(Fn), WFR = std::move(WFR)]() mutable { 92 Fn(std::move(WFR)); 93 }, "WFR handler task")); 94 }); 95 } 96 private: 97 TaskDispatcher &D; 98 }; 99 100 /// APIs for manipulating memory in the target process. 101 class MemoryAccess { 102 public: 103 /// Callback function for asynchronous writes. 104 using WriteResultFn = unique_function<void(Error)>; 105 106 virtual ~MemoryAccess(); 107 108 virtual void writeUInt8sAsync(ArrayRef<tpctypes::UInt8Write> Ws, 109 WriteResultFn OnWriteComplete) = 0; 110 111 virtual void writeUInt16sAsync(ArrayRef<tpctypes::UInt16Write> Ws, 112 WriteResultFn OnWriteComplete) = 0; 113 114 virtual void writeUInt32sAsync(ArrayRef<tpctypes::UInt32Write> Ws, 115 WriteResultFn OnWriteComplete) = 0; 116 117 virtual void writeUInt64sAsync(ArrayRef<tpctypes::UInt64Write> Ws, 118 WriteResultFn OnWriteComplete) = 0; 119 120 virtual void writeBuffersAsync(ArrayRef<tpctypes::BufferWrite> Ws, 121 WriteResultFn OnWriteComplete) = 0; 122 123 virtual void writePointersAsync(ArrayRef<tpctypes::PointerWrite> Ws, 124 WriteResultFn OnWriteComplete) = 0; 125 126 Error writeUInt8s(ArrayRef<tpctypes::UInt8Write> Ws) { 127 std::promise<MSVCPError> ResultP; 128 auto ResultF = ResultP.get_future(); 129 writeUInt8sAsync(Ws, 130 [&](Error Err) { ResultP.set_value(std::move(Err)); }); 131 return ResultF.get(); 132 } 133 134 Error writeUInt16s(ArrayRef<tpctypes::UInt16Write> Ws) { 135 std::promise<MSVCPError> ResultP; 136 auto ResultF = ResultP.get_future(); 137 writeUInt16sAsync(Ws, 138 [&](Error Err) { ResultP.set_value(std::move(Err)); }); 139 return ResultF.get(); 140 } 141 142 Error writeUInt32s(ArrayRef<tpctypes::UInt32Write> Ws) { 143 std::promise<MSVCPError> ResultP; 144 auto ResultF = ResultP.get_future(); 145 writeUInt32sAsync(Ws, 146 [&](Error Err) { ResultP.set_value(std::move(Err)); }); 147 return ResultF.get(); 148 } 149 150 Error writeUInt64s(ArrayRef<tpctypes::UInt64Write> Ws) { 151 std::promise<MSVCPError> ResultP; 152 auto ResultF = ResultP.get_future(); 153 writeUInt64sAsync(Ws, 154 [&](Error Err) { ResultP.set_value(std::move(Err)); }); 155 return ResultF.get(); 156 } 157 158 Error writeBuffers(ArrayRef<tpctypes::BufferWrite> Ws) { 159 std::promise<MSVCPError> ResultP; 160 auto ResultF = ResultP.get_future(); 161 writeBuffersAsync(Ws, 162 [&](Error Err) { ResultP.set_value(std::move(Err)); }); 163 return ResultF.get(); 164 } 165 166 Error writePointers(ArrayRef<tpctypes::PointerWrite> Ws) { 167 std::promise<MSVCPError> ResultP; 168 auto ResultF = ResultP.get_future(); 169 writePointersAsync(Ws, 170 [&](Error Err) { ResultP.set_value(std::move(Err)); }); 171 return ResultF.get(); 172 } 173 }; 174 175 /// A pair of a dylib and a set of symbols to be looked up. 176 struct LookupRequest { 177 LookupRequest(tpctypes::DylibHandle Handle, const SymbolLookupSet &Symbols) 178 : Handle(Handle), Symbols(Symbols) {} 179 tpctypes::DylibHandle Handle; 180 const SymbolLookupSet &Symbols; 181 }; 182 183 /// Contains the address of the dispatch function and context that the ORC 184 /// runtime can use to call functions in the JIT. 185 struct JITDispatchInfo { 186 ExecutorAddr JITDispatchFunction; 187 ExecutorAddr JITDispatchContext; 188 }; 189 190 ExecutorProcessControl(std::shared_ptr<SymbolStringPool> SSP, 191 std::unique_ptr<TaskDispatcher> D) 192 : SSP(std::move(SSP)), D(std::move(D)) {} 193 194 virtual ~ExecutorProcessControl(); 195 196 /// Return the ExecutionSession associated with this instance. 197 /// Not callable until the ExecutionSession has been associated. 198 ExecutionSession &getExecutionSession() { 199 assert(ES && "No ExecutionSession associated yet"); 200 return *ES; 201 } 202 203 /// Intern a symbol name in the SymbolStringPool. 204 SymbolStringPtr intern(StringRef SymName) { return SSP->intern(SymName); } 205 206 /// Return a shared pointer to the SymbolStringPool for this instance. 207 std::shared_ptr<SymbolStringPool> getSymbolStringPool() const { return SSP; } 208 209 TaskDispatcher &getDispatcher() { return *D; } 210 211 /// Return the Triple for the target process. 212 const Triple &getTargetTriple() const { return TargetTriple; } 213 214 /// Get the page size for the target process. 215 unsigned getPageSize() const { return PageSize; } 216 217 /// Get the JIT dispatch function and context address for the executor. 218 const JITDispatchInfo &getJITDispatchInfo() const { return JDI; } 219 220 /// Return a MemoryAccess object for the target process. 221 MemoryAccess &getMemoryAccess() const { 222 assert(MemAccess && "No MemAccess object set."); 223 return *MemAccess; 224 } 225 226 /// Return a JITLinkMemoryManager for the target process. 227 jitlink::JITLinkMemoryManager &getMemMgr() const { 228 assert(MemMgr && "No MemMgr object set"); 229 return *MemMgr; 230 } 231 232 /// Returns the bootstrap map. 233 const StringMap<std::vector<char>> &getBootstrapMap() const { 234 return BootstrapMap; 235 } 236 237 /// Look up and SPS-deserialize a bootstrap map value. 238 /// 239 /// 240 template <typename T, typename SPSTagT> 241 Error getBootstrapMapValue(StringRef Key, std::optional<T> &Val) const { 242 Val = std::nullopt; 243 244 auto I = BootstrapMap.find(Key); 245 if (I == BootstrapMap.end()) 246 return Error::success(); 247 248 T Tmp; 249 shared::SPSInputBuffer IB(I->second.data(), I->second.size()); 250 if (!shared::SPSArgList<SPSTagT>::deserialize(IB, Tmp)) 251 return make_error<StringError>("Could not deserialize value for key " + 252 Key, 253 inconvertibleErrorCode()); 254 255 Val = std::move(Tmp); 256 return Error::success(); 257 } 258 259 /// Returns the bootstrap symbol map. 260 const StringMap<ExecutorAddr> &getBootstrapSymbolsMap() const { 261 return BootstrapSymbols; 262 } 263 264 /// For each (ExecutorAddr&, StringRef) pair, looks up the string in the 265 /// bootstrap symbols map and writes its address to the ExecutorAddr if 266 /// found. If any symbol is not found then the function returns an error. 267 Error getBootstrapSymbols( 268 ArrayRef<std::pair<ExecutorAddr &, StringRef>> Pairs) const { 269 for (const auto &KV : Pairs) { 270 auto I = BootstrapSymbols.find(KV.second); 271 if (I == BootstrapSymbols.end()) 272 return make_error<StringError>("Symbol \"" + KV.second + 273 "\" not found " 274 "in bootstrap symbols map", 275 inconvertibleErrorCode()); 276 277 KV.first = I->second; 278 } 279 return Error::success(); 280 } 281 282 /// Load the dynamic library at the given path and return a handle to it. 283 /// If LibraryPath is null this function will return the global handle for 284 /// the target process. 285 virtual Expected<tpctypes::DylibHandle> loadDylib(const char *DylibPath) = 0; 286 287 /// Search for symbols in the target process. 288 /// 289 /// The result of the lookup is a 2-dimensional array of target addresses 290 /// that correspond to the lookup order. If a required symbol is not 291 /// found then this method will return an error. If a weakly referenced 292 /// symbol is not found then it be assigned a '0' value. 293 virtual Expected<std::vector<tpctypes::LookupResult>> 294 lookupSymbols(ArrayRef<LookupRequest> Request) = 0; 295 296 /// Run function with a main-like signature. 297 virtual Expected<int32_t> runAsMain(ExecutorAddr MainFnAddr, 298 ArrayRef<std::string> Args) = 0; 299 300 // TODO: move this to ORC runtime. 301 /// Run function with a int (*)(void) signature. 302 virtual Expected<int32_t> runAsVoidFunction(ExecutorAddr VoidFnAddr) = 0; 303 304 // TODO: move this to ORC runtime. 305 /// Run function with a int (*)(int) signature. 306 virtual Expected<int32_t> runAsIntFunction(ExecutorAddr IntFnAddr, 307 int Arg) = 0; 308 309 /// Run a wrapper function in the executor. The given WFRHandler will be 310 /// called on the result when it is returned. 311 /// 312 /// The wrapper function should be callable as: 313 /// 314 /// \code{.cpp} 315 /// CWrapperFunctionResult fn(uint8_t *Data, uint64_t Size); 316 /// \endcode{.cpp} 317 virtual void callWrapperAsync(ExecutorAddr WrapperFnAddr, 318 IncomingWFRHandler OnComplete, 319 ArrayRef<char> ArgBuffer) = 0; 320 321 /// Run a wrapper function in the executor using the given Runner to dispatch 322 /// OnComplete when the result is ready. 323 template <typename RunPolicyT, typename FnT> 324 void callWrapperAsync(RunPolicyT &&Runner, ExecutorAddr WrapperFnAddr, 325 FnT &&OnComplete, ArrayRef<char> ArgBuffer) { 326 callWrapperAsync( 327 WrapperFnAddr, Runner(std::forward<FnT>(OnComplete)), ArgBuffer); 328 } 329 330 /// Run a wrapper function in the executor. OnComplete will be dispatched 331 /// as a GenericNamedTask using this instance's TaskDispatch object. 332 template <typename FnT> 333 void callWrapperAsync(ExecutorAddr WrapperFnAddr, FnT &&OnComplete, 334 ArrayRef<char> ArgBuffer) { 335 callWrapperAsync(RunAsTask(*D), WrapperFnAddr, 336 std::forward<FnT>(OnComplete), ArgBuffer); 337 } 338 339 /// Run a wrapper function in the executor. The wrapper function should be 340 /// callable as: 341 /// 342 /// \code{.cpp} 343 /// CWrapperFunctionResult fn(uint8_t *Data, uint64_t Size); 344 /// \endcode{.cpp} 345 shared::WrapperFunctionResult callWrapper(ExecutorAddr WrapperFnAddr, 346 ArrayRef<char> ArgBuffer) { 347 std::promise<shared::WrapperFunctionResult> RP; 348 auto RF = RP.get_future(); 349 callWrapperAsync( 350 RunInPlace(), WrapperFnAddr, 351 [&](shared::WrapperFunctionResult R) { 352 RP.set_value(std::move(R)); 353 }, ArgBuffer); 354 return RF.get(); 355 } 356 357 /// Run a wrapper function using SPS to serialize the arguments and 358 /// deserialize the results. 359 template <typename SPSSignature, typename RunPolicyT, typename SendResultT, 360 typename... ArgTs> 361 void callSPSWrapperAsync(RunPolicyT &&Runner, ExecutorAddr WrapperFnAddr, 362 SendResultT &&SendResult, const ArgTs &...Args) { 363 shared::WrapperFunction<SPSSignature>::callAsync( 364 [this, WrapperFnAddr, Runner = std::move(Runner)] 365 (auto &&SendResult, const char *ArgData, size_t ArgSize) mutable { 366 this->callWrapperAsync(std::move(Runner), WrapperFnAddr, 367 std::move(SendResult), 368 ArrayRef<char>(ArgData, ArgSize)); 369 }, 370 std::forward<SendResultT>(SendResult), Args...); 371 } 372 373 /// Run a wrapper function using SPS to serialize the arguments and 374 /// deserialize the results. 375 template <typename SPSSignature, typename SendResultT, typename... ArgTs> 376 void callSPSWrapperAsync(ExecutorAddr WrapperFnAddr, SendResultT &&SendResult, 377 const ArgTs &...Args) { 378 callSPSWrapperAsync<SPSSignature>(RunAsTask(*D), WrapperFnAddr, 379 std::forward<SendResultT>(SendResult), 380 Args...); 381 } 382 383 /// Run a wrapper function using SPS to serialize the arguments and 384 /// deserialize the results. 385 /// 386 /// If SPSSignature is a non-void function signature then the second argument 387 /// (the first in the Args list) should be a reference to a return value. 388 template <typename SPSSignature, typename... WrapperCallArgTs> 389 Error callSPSWrapper(ExecutorAddr WrapperFnAddr, 390 WrapperCallArgTs &&...WrapperCallArgs) { 391 return shared::WrapperFunction<SPSSignature>::call( 392 [this, WrapperFnAddr](const char *ArgData, size_t ArgSize) { 393 return callWrapper(WrapperFnAddr, ArrayRef<char>(ArgData, ArgSize)); 394 }, 395 std::forward<WrapperCallArgTs>(WrapperCallArgs)...); 396 } 397 398 /// Disconnect from the target process. 399 /// 400 /// This should be called after the JIT session is shut down. 401 virtual Error disconnect() = 0; 402 403 protected: 404 405 std::shared_ptr<SymbolStringPool> SSP; 406 std::unique_ptr<TaskDispatcher> D; 407 ExecutionSession *ES = nullptr; 408 Triple TargetTriple; 409 unsigned PageSize = 0; 410 JITDispatchInfo JDI; 411 MemoryAccess *MemAccess = nullptr; 412 jitlink::JITLinkMemoryManager *MemMgr = nullptr; 413 StringMap<std::vector<char>> BootstrapMap; 414 StringMap<ExecutorAddr> BootstrapSymbols; 415 }; 416 417 class InProcessMemoryAccess : public ExecutorProcessControl::MemoryAccess { 418 public: 419 InProcessMemoryAccess(bool IsArch64Bit) : IsArch64Bit(IsArch64Bit) {} 420 void writeUInt8sAsync(ArrayRef<tpctypes::UInt8Write> Ws, 421 WriteResultFn OnWriteComplete) override; 422 423 void writeUInt16sAsync(ArrayRef<tpctypes::UInt16Write> Ws, 424 WriteResultFn OnWriteComplete) override; 425 426 void writeUInt32sAsync(ArrayRef<tpctypes::UInt32Write> Ws, 427 WriteResultFn OnWriteComplete) override; 428 429 void writeUInt64sAsync(ArrayRef<tpctypes::UInt64Write> Ws, 430 WriteResultFn OnWriteComplete) override; 431 432 void writeBuffersAsync(ArrayRef<tpctypes::BufferWrite> Ws, 433 WriteResultFn OnWriteComplete) override; 434 435 void writePointersAsync(ArrayRef<tpctypes::PointerWrite> Ws, 436 WriteResultFn OnWriteComplete) override; 437 438 private: 439 bool IsArch64Bit; 440 }; 441 442 /// A ExecutorProcessControl instance that asserts if any of its methods are 443 /// used. Suitable for use is unit tests, and by ORC clients who haven't moved 444 /// to ExecutorProcessControl-based APIs yet. 445 class UnsupportedExecutorProcessControl : public ExecutorProcessControl, 446 private InProcessMemoryAccess { 447 public: 448 UnsupportedExecutorProcessControl( 449 std::shared_ptr<SymbolStringPool> SSP = nullptr, 450 std::unique_ptr<TaskDispatcher> D = nullptr, const std::string &TT = "", 451 unsigned PageSize = 0) 452 : ExecutorProcessControl( 453 SSP ? std::move(SSP) : std::make_shared<SymbolStringPool>(), 454 D ? std::move(D) : std::make_unique<InPlaceTaskDispatcher>()), 455 InProcessMemoryAccess(Triple(TT).isArch64Bit()) { 456 this->TargetTriple = Triple(TT); 457 this->PageSize = PageSize; 458 this->MemAccess = this; 459 } 460 461 Expected<tpctypes::DylibHandle> loadDylib(const char *DylibPath) override { 462 llvm_unreachable("Unsupported"); 463 } 464 465 Expected<std::vector<tpctypes::LookupResult>> 466 lookupSymbols(ArrayRef<LookupRequest> Request) override { 467 llvm_unreachable("Unsupported"); 468 } 469 470 Expected<int32_t> runAsMain(ExecutorAddr MainFnAddr, 471 ArrayRef<std::string> Args) override { 472 llvm_unreachable("Unsupported"); 473 } 474 475 Expected<int32_t> runAsVoidFunction(ExecutorAddr VoidFnAddr) override { 476 llvm_unreachable("Unsupported"); 477 } 478 479 Expected<int32_t> runAsIntFunction(ExecutorAddr IntFnAddr, int Arg) override { 480 llvm_unreachable("Unsupported"); 481 } 482 483 void callWrapperAsync(ExecutorAddr WrapperFnAddr, 484 IncomingWFRHandler OnComplete, 485 ArrayRef<char> ArgBuffer) override { 486 llvm_unreachable("Unsupported"); 487 } 488 489 Error disconnect() override { return Error::success(); } 490 }; 491 492 /// A ExecutorProcessControl implementation targeting the current process. 493 class SelfExecutorProcessControl : public ExecutorProcessControl, 494 private InProcessMemoryAccess { 495 public: 496 SelfExecutorProcessControl( 497 std::shared_ptr<SymbolStringPool> SSP, std::unique_ptr<TaskDispatcher> D, 498 Triple TargetTriple, unsigned PageSize, 499 std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgr); 500 501 /// Create a SelfExecutorProcessControl with the given symbol string pool and 502 /// memory manager. 503 /// If no symbol string pool is given then one will be created. 504 /// If no memory manager is given a jitlink::InProcessMemoryManager will 505 /// be created and used by default. 506 static Expected<std::unique_ptr<SelfExecutorProcessControl>> 507 Create(std::shared_ptr<SymbolStringPool> SSP = nullptr, 508 std::unique_ptr<TaskDispatcher> D = nullptr, 509 std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgr = nullptr); 510 511 Expected<tpctypes::DylibHandle> loadDylib(const char *DylibPath) override; 512 513 Expected<std::vector<tpctypes::LookupResult>> 514 lookupSymbols(ArrayRef<LookupRequest> Request) override; 515 516 Expected<int32_t> runAsMain(ExecutorAddr MainFnAddr, 517 ArrayRef<std::string> Args) override; 518 519 Expected<int32_t> runAsVoidFunction(ExecutorAddr VoidFnAddr) override; 520 521 Expected<int32_t> runAsIntFunction(ExecutorAddr IntFnAddr, int Arg) override; 522 523 void callWrapperAsync(ExecutorAddr WrapperFnAddr, 524 IncomingWFRHandler OnComplete, 525 ArrayRef<char> ArgBuffer) override; 526 527 Error disconnect() override; 528 529 private: 530 static shared::CWrapperFunctionResult 531 jitDispatchViaWrapperFunctionManager(void *Ctx, const void *FnTag, 532 const char *Data, size_t Size); 533 534 std::unique_ptr<jitlink::JITLinkMemoryManager> OwnedMemMgr; 535 char GlobalManglingPrefix = 0; 536 }; 537 538 } // end namespace orc 539 } // end namespace llvm 540 541 #endif // LLVM_EXECUTIONENGINE_ORC_EXECUTORPROCESSCONTROL_H 542