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/DylibManager.h" 19 #include "llvm/ExecutionEngine/Orc/Shared/ExecutorAddress.h" 20 #include "llvm/ExecutionEngine/Orc/Shared/TargetProcessControlTypes.h" 21 #include "llvm/ExecutionEngine/Orc/Shared/WrapperFunctionUtils.h" 22 #include "llvm/ExecutionEngine/Orc/SymbolStringPool.h" 23 #include "llvm/ExecutionEngine/Orc/TaskDispatch.h" 24 #include "llvm/Support/DynamicLibrary.h" 25 #include "llvm/Support/MSVCErrorWorkarounds.h" 26 #include "llvm/TargetParser/Triple.h" 27 28 #include <future> 29 #include <mutex> 30 #include <vector> 31 32 namespace llvm { 33 namespace orc { 34 35 class ExecutionSession; 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 /// Contains the address of the dispatch function and context that the ORC 176 /// runtime can use to call functions in the JIT. 177 struct JITDispatchInfo { 178 ExecutorAddr JITDispatchFunction; 179 ExecutorAddr JITDispatchContext; 180 }; 181 182 ExecutorProcessControl(std::shared_ptr<SymbolStringPool> SSP, 183 std::unique_ptr<TaskDispatcher> D) 184 : SSP(std::move(SSP)), D(std::move(D)) {} 185 186 virtual ~ExecutorProcessControl(); 187 188 /// Return the ExecutionSession associated with this instance. 189 /// Not callable until the ExecutionSession has been associated. 190 ExecutionSession &getExecutionSession() { 191 assert(ES && "No ExecutionSession associated yet"); 192 return *ES; 193 } 194 195 /// Intern a symbol name in the SymbolStringPool. 196 SymbolStringPtr intern(StringRef SymName) { return SSP->intern(SymName); } 197 198 /// Return a shared pointer to the SymbolStringPool for this instance. 199 std::shared_ptr<SymbolStringPool> getSymbolStringPool() const { return SSP; } 200 201 TaskDispatcher &getDispatcher() { return *D; } 202 203 /// Return the Triple for the target process. 204 const Triple &getTargetTriple() const { return TargetTriple; } 205 206 /// Get the page size for the target process. 207 unsigned getPageSize() const { return PageSize; } 208 209 /// Get the JIT dispatch function and context address for the executor. 210 const JITDispatchInfo &getJITDispatchInfo() const { return JDI; } 211 212 /// Return a MemoryAccess object for the target process. 213 MemoryAccess &getMemoryAccess() const { 214 assert(MemAccess && "No MemAccess object set."); 215 return *MemAccess; 216 } 217 218 /// Return a JITLinkMemoryManager for the target process. 219 jitlink::JITLinkMemoryManager &getMemMgr() const { 220 assert(MemMgr && "No MemMgr object set"); 221 return *MemMgr; 222 } 223 224 /// Return the DylibManager for the target process. 225 DylibManager &getDylibMgr() const { 226 assert(DylibMgr && "No DylibMgr object set"); 227 return *DylibMgr; 228 } 229 230 /// Returns the bootstrap map. 231 const StringMap<std::vector<char>> &getBootstrapMap() const { 232 return BootstrapMap; 233 } 234 235 /// Look up and SPS-deserialize a bootstrap map value. 236 template <typename T, typename SPSTagT> 237 Error getBootstrapMapValue(StringRef Key, std::optional<T> &Val) const { 238 Val = std::nullopt; 239 240 auto I = BootstrapMap.find(Key); 241 if (I == BootstrapMap.end()) 242 return Error::success(); 243 244 T Tmp; 245 shared::SPSInputBuffer IB(I->second.data(), I->second.size()); 246 if (!shared::SPSArgList<SPSTagT>::deserialize(IB, Tmp)) 247 return make_error<StringError>("Could not deserialize value for key " + 248 Key, 249 inconvertibleErrorCode()); 250 251 Val = std::move(Tmp); 252 return Error::success(); 253 } 254 255 /// Returns the bootstrap symbol map. 256 const StringMap<ExecutorAddr> &getBootstrapSymbolsMap() const { 257 return BootstrapSymbols; 258 } 259 260 /// For each (ExecutorAddr&, StringRef) pair, looks up the string in the 261 /// bootstrap symbols map and writes its address to the ExecutorAddr if 262 /// found. If any symbol is not found then the function returns an error. 263 Error getBootstrapSymbols( 264 ArrayRef<std::pair<ExecutorAddr &, StringRef>> Pairs) const { 265 for (const auto &KV : Pairs) { 266 auto I = BootstrapSymbols.find(KV.second); 267 if (I == BootstrapSymbols.end()) 268 return make_error<StringError>("Symbol \"" + KV.second + 269 "\" not found " 270 "in bootstrap symbols map", 271 inconvertibleErrorCode()); 272 273 KV.first = I->second; 274 } 275 return Error::success(); 276 } 277 278 /// Run function with a main-like signature. 279 virtual Expected<int32_t> runAsMain(ExecutorAddr MainFnAddr, 280 ArrayRef<std::string> Args) = 0; 281 282 // TODO: move this to ORC runtime. 283 /// Run function with a int (*)(void) signature. 284 virtual Expected<int32_t> runAsVoidFunction(ExecutorAddr VoidFnAddr) = 0; 285 286 // TODO: move this to ORC runtime. 287 /// Run function with a int (*)(int) signature. 288 virtual Expected<int32_t> runAsIntFunction(ExecutorAddr IntFnAddr, 289 int Arg) = 0; 290 291 /// Run a wrapper function in the executor. The given WFRHandler will be 292 /// called on the result when it is returned. 293 /// 294 /// The wrapper function should be callable as: 295 /// 296 /// \code{.cpp} 297 /// CWrapperFunctionResult fn(uint8_t *Data, uint64_t Size); 298 /// \endcode{.cpp} 299 virtual void callWrapperAsync(ExecutorAddr WrapperFnAddr, 300 IncomingWFRHandler OnComplete, 301 ArrayRef<char> ArgBuffer) = 0; 302 303 /// Run a wrapper function in the executor using the given Runner to dispatch 304 /// OnComplete when the result is ready. 305 template <typename RunPolicyT, typename FnT> 306 void callWrapperAsync(RunPolicyT &&Runner, ExecutorAddr WrapperFnAddr, 307 FnT &&OnComplete, ArrayRef<char> ArgBuffer) { 308 callWrapperAsync( 309 WrapperFnAddr, Runner(std::forward<FnT>(OnComplete)), ArgBuffer); 310 } 311 312 /// Run a wrapper function in the executor. OnComplete will be dispatched 313 /// as a GenericNamedTask using this instance's TaskDispatch object. 314 template <typename FnT> 315 void callWrapperAsync(ExecutorAddr WrapperFnAddr, FnT &&OnComplete, 316 ArrayRef<char> ArgBuffer) { 317 callWrapperAsync(RunAsTask(*D), WrapperFnAddr, 318 std::forward<FnT>(OnComplete), ArgBuffer); 319 } 320 321 /// Run a wrapper function in the executor. The wrapper function should be 322 /// callable as: 323 /// 324 /// \code{.cpp} 325 /// CWrapperFunctionResult fn(uint8_t *Data, uint64_t Size); 326 /// \endcode{.cpp} 327 shared::WrapperFunctionResult callWrapper(ExecutorAddr WrapperFnAddr, 328 ArrayRef<char> ArgBuffer) { 329 std::promise<shared::WrapperFunctionResult> RP; 330 auto RF = RP.get_future(); 331 callWrapperAsync( 332 RunInPlace(), WrapperFnAddr, 333 [&](shared::WrapperFunctionResult R) { 334 RP.set_value(std::move(R)); 335 }, ArgBuffer); 336 return RF.get(); 337 } 338 339 /// Run a wrapper function using SPS to serialize the arguments and 340 /// deserialize the results. 341 template <typename SPSSignature, typename RunPolicyT, typename SendResultT, 342 typename... ArgTs> 343 void callSPSWrapperAsync(RunPolicyT &&Runner, ExecutorAddr WrapperFnAddr, 344 SendResultT &&SendResult, const ArgTs &...Args) { 345 shared::WrapperFunction<SPSSignature>::callAsync( 346 [this, WrapperFnAddr, Runner = std::move(Runner)] 347 (auto &&SendResult, const char *ArgData, size_t ArgSize) mutable { 348 this->callWrapperAsync(std::move(Runner), WrapperFnAddr, 349 std::move(SendResult), 350 ArrayRef<char>(ArgData, ArgSize)); 351 }, 352 std::forward<SendResultT>(SendResult), Args...); 353 } 354 355 /// Run a wrapper function using SPS to serialize the arguments and 356 /// deserialize the results. 357 template <typename SPSSignature, typename SendResultT, typename... ArgTs> 358 void callSPSWrapperAsync(ExecutorAddr WrapperFnAddr, SendResultT &&SendResult, 359 const ArgTs &...Args) { 360 callSPSWrapperAsync<SPSSignature>(RunAsTask(*D), WrapperFnAddr, 361 std::forward<SendResultT>(SendResult), 362 Args...); 363 } 364 365 /// Run a wrapper function using SPS to serialize the arguments and 366 /// deserialize the results. 367 /// 368 /// If SPSSignature is a non-void function signature then the second argument 369 /// (the first in the Args list) should be a reference to a return value. 370 template <typename SPSSignature, typename... WrapperCallArgTs> 371 Error callSPSWrapper(ExecutorAddr WrapperFnAddr, 372 WrapperCallArgTs &&...WrapperCallArgs) { 373 return shared::WrapperFunction<SPSSignature>::call( 374 [this, WrapperFnAddr](const char *ArgData, size_t ArgSize) { 375 return callWrapper(WrapperFnAddr, ArrayRef<char>(ArgData, ArgSize)); 376 }, 377 std::forward<WrapperCallArgTs>(WrapperCallArgs)...); 378 } 379 380 /// Disconnect from the target process. 381 /// 382 /// This should be called after the JIT session is shut down. 383 virtual Error disconnect() = 0; 384 385 protected: 386 387 std::shared_ptr<SymbolStringPool> SSP; 388 std::unique_ptr<TaskDispatcher> D; 389 ExecutionSession *ES = nullptr; 390 Triple TargetTriple; 391 unsigned PageSize = 0; 392 JITDispatchInfo JDI; 393 MemoryAccess *MemAccess = nullptr; 394 jitlink::JITLinkMemoryManager *MemMgr = nullptr; 395 DylibManager *DylibMgr = nullptr; 396 StringMap<std::vector<char>> BootstrapMap; 397 StringMap<ExecutorAddr> BootstrapSymbols; 398 }; 399 400 class InProcessMemoryAccess : public ExecutorProcessControl::MemoryAccess { 401 public: 402 InProcessMemoryAccess(bool IsArch64Bit) : IsArch64Bit(IsArch64Bit) {} 403 void writeUInt8sAsync(ArrayRef<tpctypes::UInt8Write> Ws, 404 WriteResultFn OnWriteComplete) override; 405 406 void writeUInt16sAsync(ArrayRef<tpctypes::UInt16Write> Ws, 407 WriteResultFn OnWriteComplete) override; 408 409 void writeUInt32sAsync(ArrayRef<tpctypes::UInt32Write> Ws, 410 WriteResultFn OnWriteComplete) override; 411 412 void writeUInt64sAsync(ArrayRef<tpctypes::UInt64Write> Ws, 413 WriteResultFn OnWriteComplete) override; 414 415 void writeBuffersAsync(ArrayRef<tpctypes::BufferWrite> Ws, 416 WriteResultFn OnWriteComplete) override; 417 418 void writePointersAsync(ArrayRef<tpctypes::PointerWrite> Ws, 419 WriteResultFn OnWriteComplete) override; 420 421 private: 422 bool IsArch64Bit; 423 }; 424 425 /// A ExecutorProcessControl instance that asserts if any of its methods are 426 /// used. Suitable for use is unit tests, and by ORC clients who haven't moved 427 /// to ExecutorProcessControl-based APIs yet. 428 class UnsupportedExecutorProcessControl : public ExecutorProcessControl, 429 private InProcessMemoryAccess { 430 public: 431 UnsupportedExecutorProcessControl( 432 std::shared_ptr<SymbolStringPool> SSP = nullptr, 433 std::unique_ptr<TaskDispatcher> D = nullptr, const std::string &TT = "", 434 unsigned PageSize = 0) 435 : ExecutorProcessControl( 436 SSP ? std::move(SSP) : std::make_shared<SymbolStringPool>(), 437 D ? std::move(D) : std::make_unique<InPlaceTaskDispatcher>()), 438 InProcessMemoryAccess(Triple(TT).isArch64Bit()) { 439 this->TargetTriple = Triple(TT); 440 this->PageSize = PageSize; 441 this->MemAccess = this; 442 } 443 444 Expected<int32_t> runAsMain(ExecutorAddr MainFnAddr, 445 ArrayRef<std::string> Args) override { 446 llvm_unreachable("Unsupported"); 447 } 448 449 Expected<int32_t> runAsVoidFunction(ExecutorAddr VoidFnAddr) override { 450 llvm_unreachable("Unsupported"); 451 } 452 453 Expected<int32_t> runAsIntFunction(ExecutorAddr IntFnAddr, int Arg) override { 454 llvm_unreachable("Unsupported"); 455 } 456 457 void callWrapperAsync(ExecutorAddr WrapperFnAddr, 458 IncomingWFRHandler OnComplete, 459 ArrayRef<char> ArgBuffer) override { 460 llvm_unreachable("Unsupported"); 461 } 462 463 Error disconnect() override { return Error::success(); } 464 }; 465 466 /// A ExecutorProcessControl implementation targeting the current process. 467 class SelfExecutorProcessControl : public ExecutorProcessControl, 468 private InProcessMemoryAccess, 469 private DylibManager { 470 public: 471 SelfExecutorProcessControl( 472 std::shared_ptr<SymbolStringPool> SSP, std::unique_ptr<TaskDispatcher> D, 473 Triple TargetTriple, unsigned PageSize, 474 std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgr); 475 476 /// Create a SelfExecutorProcessControl with the given symbol string pool and 477 /// memory manager. 478 /// If no symbol string pool is given then one will be created. 479 /// If no memory manager is given a jitlink::InProcessMemoryManager will 480 /// be created and used by default. 481 static Expected<std::unique_ptr<SelfExecutorProcessControl>> 482 Create(std::shared_ptr<SymbolStringPool> SSP = nullptr, 483 std::unique_ptr<TaskDispatcher> D = nullptr, 484 std::unique_ptr<jitlink::JITLinkMemoryManager> MemMgr = nullptr); 485 486 Expected<int32_t> runAsMain(ExecutorAddr MainFnAddr, 487 ArrayRef<std::string> Args) override; 488 489 Expected<int32_t> runAsVoidFunction(ExecutorAddr VoidFnAddr) override; 490 491 Expected<int32_t> runAsIntFunction(ExecutorAddr IntFnAddr, int Arg) override; 492 493 void callWrapperAsync(ExecutorAddr WrapperFnAddr, 494 IncomingWFRHandler OnComplete, 495 ArrayRef<char> ArgBuffer) override; 496 497 Error disconnect() override; 498 499 private: 500 static shared::CWrapperFunctionResult 501 jitDispatchViaWrapperFunctionManager(void *Ctx, const void *FnTag, 502 const char *Data, size_t Size); 503 504 Expected<tpctypes::DylibHandle> loadDylib(const char *DylibPath) override; 505 506 void lookupSymbolsAsync(ArrayRef<LookupRequest> Request, 507 SymbolLookupCompleteFn F) override; 508 509 std::unique_ptr<jitlink::JITLinkMemoryManager> OwnedMemMgr; 510 char GlobalManglingPrefix = 0; 511 }; 512 513 } // end namespace orc 514 } // end namespace llvm 515 516 #endif // LLVM_EXECUTIONENGINE_ORC_EXECUTORPROCESSCONTROL_H 517