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