1 //===-- Process.h -----------------------------------------------*- 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 #ifndef LLDB_TARGET_PROCESS_H 10 #define LLDB_TARGET_PROCESS_H 11 12 #include "lldb/Host/Config.h" 13 14 #include <climits> 15 16 #include <chrono> 17 #include <list> 18 #include <memory> 19 #include <mutex> 20 #include <string> 21 #include <unordered_set> 22 #include <vector> 23 24 #include "lldb/Breakpoint/BreakpointSiteList.h" 25 #include "lldb/Core/Communication.h" 26 #include "lldb/Core/LoadedModuleInfoList.h" 27 #include "lldb/Core/PluginInterface.h" 28 #include "lldb/Core/ThreadSafeValue.h" 29 #include "lldb/Core/UserSettingsController.h" 30 #include "lldb/Host/HostThread.h" 31 #include "lldb/Host/ProcessLaunchInfo.h" 32 #include "lldb/Host/ProcessRunLock.h" 33 #include "lldb/Symbol/ObjectFile.h" 34 #include "lldb/Target/ExecutionContextScope.h" 35 #include "lldb/Target/InstrumentationRuntime.h" 36 #include "lldb/Target/Memory.h" 37 #include "lldb/Target/MemoryTagManager.h" 38 #include "lldb/Target/QueueList.h" 39 #include "lldb/Target/ThreadList.h" 40 #include "lldb/Target/ThreadPlanStack.h" 41 #include "lldb/Target/Trace.h" 42 #include "lldb/Utility/ArchSpec.h" 43 #include "lldb/Utility/Broadcaster.h" 44 #include "lldb/Utility/Event.h" 45 #include "lldb/Utility/Listener.h" 46 #include "lldb/Utility/NameMatches.h" 47 #include "lldb/Utility/ProcessInfo.h" 48 #include "lldb/Utility/Status.h" 49 #include "lldb/Utility/StructuredData.h" 50 #include "lldb/Utility/TraceGDBRemotePackets.h" 51 #include "lldb/Utility/UnimplementedError.h" 52 #include "lldb/Utility/UserIDResolver.h" 53 #include "lldb/lldb-private.h" 54 55 #include "llvm/ADT/ArrayRef.h" 56 #include "llvm/Support/Threading.h" 57 #include "llvm/Support/VersionTuple.h" 58 59 namespace lldb_private { 60 61 template <typename B, typename S> struct Range; 62 63 class ProcessExperimentalProperties : public Properties { 64 public: 65 ProcessExperimentalProperties(); 66 }; 67 68 class ProcessProperties : public Properties { 69 public: 70 // Pass nullptr for "process" if the ProcessProperties are to be the global 71 // copy 72 ProcessProperties(lldb_private::Process *process); 73 74 ~ProcessProperties() override; 75 76 bool GetDisableMemoryCache() const; 77 uint64_t GetMemoryCacheLineSize() const; 78 Args GetExtraStartupCommands() const; 79 void SetExtraStartupCommands(const Args &args); 80 FileSpec GetPythonOSPluginPath() const; 81 uint32_t GetVirtualAddressableBits() const; 82 void SetVirtualAddressableBits(uint32_t bits); 83 void SetPythonOSPluginPath(const FileSpec &file); 84 bool GetIgnoreBreakpointsInExpressions() const; 85 void SetIgnoreBreakpointsInExpressions(bool ignore); 86 bool GetUnwindOnErrorInExpressions() const; 87 void SetUnwindOnErrorInExpressions(bool ignore); 88 bool GetStopOnSharedLibraryEvents() const; 89 void SetStopOnSharedLibraryEvents(bool stop); 90 bool GetDisableLangRuntimeUnwindPlans() const; 91 void SetDisableLangRuntimeUnwindPlans(bool disable); 92 bool GetDetachKeepsStopped() const; 93 void SetDetachKeepsStopped(bool keep_stopped); 94 bool GetWarningsOptimization() const; 95 bool GetWarningsUnsupportedLanguage() const; 96 bool GetStopOnExec() const; 97 std::chrono::seconds GetUtilityExpressionTimeout() const; 98 std::chrono::seconds GetInterruptTimeout() const; 99 bool GetOSPluginReportsAllThreads() const; 100 void SetOSPluginReportsAllThreads(bool does_report); 101 bool GetSteppingRunsAllThreads() const; 102 FollowForkMode GetFollowForkMode() const; 103 104 protected: 105 Process *m_process; // Can be nullptr for global ProcessProperties 106 std::unique_ptr<ProcessExperimentalProperties> m_experimental_properties_up; 107 }; 108 109 // ProcessAttachInfo 110 // 111 // Describes any information that is required to attach to a process. 112 113 class ProcessAttachInfo : public ProcessInstanceInfo { 114 public: 115 ProcessAttachInfo() = default; 116 117 ProcessAttachInfo(const ProcessLaunchInfo &launch_info) 118 : m_resume_count(0), m_wait_for_launch(false), m_ignore_existing(true), 119 m_continue_once_attached(false), m_detach_on_error(true), 120 m_async(false) { 121 ProcessInfo::operator=(launch_info); 122 SetProcessPluginName(launch_info.GetProcessPluginName()); 123 SetResumeCount(launch_info.GetResumeCount()); 124 SetListener(launch_info.GetListener()); 125 SetHijackListener(launch_info.GetHijackListener()); 126 m_detach_on_error = launch_info.GetDetachOnError(); 127 } 128 129 bool GetWaitForLaunch() const { return m_wait_for_launch; } 130 131 void SetWaitForLaunch(bool b) { m_wait_for_launch = b; } 132 133 bool GetAsync() const { return m_async; } 134 135 void SetAsync(bool b) { m_async = b; } 136 137 bool GetIgnoreExisting() const { return m_ignore_existing; } 138 139 void SetIgnoreExisting(bool b) { m_ignore_existing = b; } 140 141 bool GetContinueOnceAttached() const { return m_continue_once_attached; } 142 143 void SetContinueOnceAttached(bool b) { m_continue_once_attached = b; } 144 145 uint32_t GetResumeCount() const { return m_resume_count; } 146 147 void SetResumeCount(uint32_t c) { m_resume_count = c; } 148 149 const char *GetProcessPluginName() const { 150 return (m_plugin_name.empty() ? nullptr : m_plugin_name.c_str()); 151 } 152 153 void SetProcessPluginName(llvm::StringRef plugin) { 154 m_plugin_name = std::string(plugin); 155 } 156 157 void Clear() { 158 ProcessInstanceInfo::Clear(); 159 m_plugin_name.clear(); 160 m_resume_count = 0; 161 m_wait_for_launch = false; 162 m_ignore_existing = true; 163 m_continue_once_attached = false; 164 } 165 166 bool ProcessInfoSpecified() const { 167 if (GetExecutableFile()) 168 return true; 169 if (GetProcessID() != LLDB_INVALID_PROCESS_ID) 170 return true; 171 if (GetParentProcessID() != LLDB_INVALID_PROCESS_ID) 172 return true; 173 return false; 174 } 175 176 lldb::ListenerSP GetHijackListener() const { return m_hijack_listener_sp; } 177 178 void SetHijackListener(const lldb::ListenerSP &listener_sp) { 179 m_hijack_listener_sp = listener_sp; 180 } 181 182 bool GetDetachOnError() const { return m_detach_on_error; } 183 184 void SetDetachOnError(bool enable) { m_detach_on_error = enable; } 185 186 // Get and set the actual listener that will be used for the process events 187 lldb::ListenerSP GetListener() const { return m_listener_sp; } 188 189 void SetListener(const lldb::ListenerSP &listener_sp) { 190 m_listener_sp = listener_sp; 191 } 192 193 lldb::ListenerSP GetListenerForProcess(Debugger &debugger); 194 195 protected: 196 lldb::ListenerSP m_listener_sp; 197 lldb::ListenerSP m_hijack_listener_sp; 198 std::string m_plugin_name; 199 uint32_t m_resume_count = 0; // How many times do we resume after launching 200 bool m_wait_for_launch = false; 201 bool m_ignore_existing = true; 202 bool m_continue_once_attached = false; // Supports the use-case scenario of 203 // immediately continuing the process 204 // once attached. 205 bool m_detach_on_error = 206 true; // If we are debugging remotely, instruct the stub to 207 // detach rather than killing the target on error. 208 bool m_async = 209 false; // Use an async attach where we start the attach and return 210 // immediately (used by GUI programs with --waitfor so they can 211 // call SBProcess::Stop() to cancel attach) 212 }; 213 214 // This class tracks the Modification state of the process. Things that can 215 // currently modify the program are running the program (which will up the 216 // StopID) and writing memory (which will up the MemoryID.) 217 // FIXME: Should we also include modification of register states? 218 219 class ProcessModID { 220 friend bool operator==(const ProcessModID &lhs, const ProcessModID &rhs); 221 222 public: 223 ProcessModID() = default; 224 225 ProcessModID(const ProcessModID &rhs) 226 : m_stop_id(rhs.m_stop_id), m_memory_id(rhs.m_memory_id) {} 227 228 const ProcessModID &operator=(const ProcessModID &rhs) { 229 if (this != &rhs) { 230 m_stop_id = rhs.m_stop_id; 231 m_memory_id = rhs.m_memory_id; 232 } 233 return *this; 234 } 235 236 ~ProcessModID() = default; 237 238 uint32_t BumpStopID() { 239 const uint32_t prev_stop_id = m_stop_id++; 240 if (!IsLastResumeForUserExpression()) 241 m_last_natural_stop_id++; 242 return prev_stop_id; 243 } 244 245 void BumpMemoryID() { m_memory_id++; } 246 247 void BumpResumeID() { 248 m_resume_id++; 249 if (m_running_user_expression > 0) 250 m_last_user_expression_resume = m_resume_id; 251 } 252 253 bool IsRunningUtilityFunction() const { 254 return m_running_utility_function > 0; 255 } 256 257 uint32_t GetStopID() const { return m_stop_id; } 258 uint32_t GetLastNaturalStopID() const { return m_last_natural_stop_id; } 259 uint32_t GetMemoryID() const { return m_memory_id; } 260 uint32_t GetResumeID() const { return m_resume_id; } 261 uint32_t GetLastUserExpressionResumeID() const { 262 return m_last_user_expression_resume; 263 } 264 265 bool MemoryIDEqual(const ProcessModID &compare) const { 266 return m_memory_id == compare.m_memory_id; 267 } 268 269 bool StopIDEqual(const ProcessModID &compare) const { 270 return m_stop_id == compare.m_stop_id; 271 } 272 273 void SetInvalid() { m_stop_id = UINT32_MAX; } 274 275 bool IsValid() const { return m_stop_id != UINT32_MAX; } 276 277 bool IsLastResumeForUserExpression() const { 278 // If we haven't yet resumed the target, then it can't be for a user 279 // expression... 280 if (m_resume_id == 0) 281 return false; 282 283 return m_resume_id == m_last_user_expression_resume; 284 } 285 286 void SetRunningUserExpression(bool on) { 287 if (on) 288 m_running_user_expression++; 289 else 290 m_running_user_expression--; 291 } 292 293 void SetRunningUtilityFunction(bool on) { 294 if (on) 295 m_running_utility_function++; 296 else { 297 assert(m_running_utility_function > 0 && 298 "Called SetRunningUtilityFunction(false) without calling " 299 "SetRunningUtilityFunction(true) before?"); 300 m_running_utility_function--; 301 } 302 } 303 304 void SetStopEventForLastNaturalStopID(lldb::EventSP event_sp) { 305 m_last_natural_stop_event = std::move(event_sp); 306 } 307 308 lldb::EventSP GetStopEventForStopID(uint32_t stop_id) const { 309 if (stop_id == m_last_natural_stop_id) 310 return m_last_natural_stop_event; 311 return lldb::EventSP(); 312 } 313 314 private: 315 uint32_t m_stop_id = 0; 316 uint32_t m_last_natural_stop_id = 0; 317 uint32_t m_resume_id = 0; 318 uint32_t m_memory_id = 0; 319 uint32_t m_last_user_expression_resume = 0; 320 uint32_t m_running_user_expression = false; 321 uint32_t m_running_utility_function = 0; 322 lldb::EventSP m_last_natural_stop_event; 323 }; 324 325 inline bool operator==(const ProcessModID &lhs, const ProcessModID &rhs) { 326 if (lhs.StopIDEqual(rhs) && lhs.MemoryIDEqual(rhs)) 327 return true; 328 else 329 return false; 330 } 331 332 inline bool operator!=(const ProcessModID &lhs, const ProcessModID &rhs) { 333 return (!lhs.StopIDEqual(rhs) || !lhs.MemoryIDEqual(rhs)); 334 } 335 336 /// \class Process Process.h "lldb/Target/Process.h" 337 /// A plug-in interface definition class for debugging a process. 338 class Process : public std::enable_shared_from_this<Process>, 339 public ProcessProperties, 340 public Broadcaster, 341 public ExecutionContextScope, 342 public PluginInterface { 343 friend class FunctionCaller; // For WaitForStateChangeEventsPrivate 344 friend class Debugger; // For PopProcessIOHandler and ProcessIOHandlerIsActive 345 friend class DynamicLoader; // For LoadOperatingSystemPlugin 346 friend class ProcessEventData; 347 friend class StopInfo; 348 friend class Target; 349 friend class ThreadList; 350 351 public: 352 /// Broadcaster event bits definitions. 353 enum { 354 eBroadcastBitStateChanged = (1 << 0), 355 eBroadcastBitInterrupt = (1 << 1), 356 eBroadcastBitSTDOUT = (1 << 2), 357 eBroadcastBitSTDERR = (1 << 3), 358 eBroadcastBitProfileData = (1 << 4), 359 eBroadcastBitStructuredData = (1 << 5), 360 }; 361 362 enum { 363 eBroadcastInternalStateControlStop = (1 << 0), 364 eBroadcastInternalStateControlPause = (1 << 1), 365 eBroadcastInternalStateControlResume = (1 << 2) 366 }; 367 368 typedef Range<lldb::addr_t, lldb::addr_t> LoadRange; 369 // We use a read/write lock to allow on or more clients to access the process 370 // state while the process is stopped (reader). We lock the write lock to 371 // control access to the process while it is running (readers, or clients 372 // that want the process stopped can block waiting for the process to stop, 373 // or just try to lock it to see if they can immediately access the stopped 374 // process. If the try read lock fails, then the process is running. 375 typedef ProcessRunLock::ProcessRunLocker StopLocker; 376 377 // These two functions fill out the Broadcaster interface: 378 379 static ConstString &GetStaticBroadcasterClass(); 380 381 ConstString &GetBroadcasterClass() const override { 382 return GetStaticBroadcasterClass(); 383 } 384 385 /// A notification structure that can be used by clients to listen 386 /// for changes in a process's lifetime. 387 /// 388 /// \see RegisterNotificationCallbacks (const Notifications&) @see 389 /// UnregisterNotificationCallbacks (const Notifications&) 390 typedef struct { 391 void *baton; 392 void (*initialize)(void *baton, Process *process); 393 void (*process_state_changed)(void *baton, Process *process, 394 lldb::StateType state); 395 } Notifications; 396 397 class ProcessEventData : public EventData { 398 friend class Process; 399 400 public: 401 ProcessEventData(); 402 ProcessEventData(const lldb::ProcessSP &process, lldb::StateType state); 403 404 ~ProcessEventData() override; 405 406 static ConstString GetFlavorString(); 407 408 ConstString GetFlavor() const override; 409 410 lldb::ProcessSP GetProcessSP() const { return m_process_wp.lock(); } 411 412 lldb::StateType GetState() const { return m_state; } 413 bool GetRestarted() const { return m_restarted; } 414 415 size_t GetNumRestartedReasons() { return m_restarted_reasons.size(); } 416 417 const char *GetRestartedReasonAtIndex(size_t idx) { 418 return ((idx < m_restarted_reasons.size()) 419 ? m_restarted_reasons[idx].c_str() 420 : nullptr); 421 } 422 423 bool GetInterrupted() const { return m_interrupted; } 424 425 void Dump(Stream *s) const override; 426 427 virtual bool ShouldStop(Event *event_ptr, bool &found_valid_stopinfo); 428 429 void DoOnRemoval(Event *event_ptr) override; 430 431 static const Process::ProcessEventData * 432 GetEventDataFromEvent(const Event *event_ptr); 433 434 static lldb::ProcessSP GetProcessFromEvent(const Event *event_ptr); 435 436 static lldb::StateType GetStateFromEvent(const Event *event_ptr); 437 438 static bool GetRestartedFromEvent(const Event *event_ptr); 439 440 static size_t GetNumRestartedReasons(const Event *event_ptr); 441 442 static const char *GetRestartedReasonAtIndex(const Event *event_ptr, 443 size_t idx); 444 445 static void AddRestartedReason(Event *event_ptr, const char *reason); 446 447 static void SetRestartedInEvent(Event *event_ptr, bool new_value); 448 449 static bool GetInterruptedFromEvent(const Event *event_ptr); 450 451 static void SetInterruptedInEvent(Event *event_ptr, bool new_value); 452 453 static bool SetUpdateStateOnRemoval(Event *event_ptr); 454 455 private: 456 void SetUpdateStateOnRemoval() { m_update_state++; } 457 458 void SetRestarted(bool new_value) { m_restarted = new_value; } 459 460 void SetInterrupted(bool new_value) { m_interrupted = new_value; } 461 462 void AddRestartedReason(const char *reason) { 463 m_restarted_reasons.push_back(reason); 464 } 465 466 lldb::ProcessWP m_process_wp; 467 lldb::StateType m_state = lldb::eStateInvalid; 468 std::vector<std::string> m_restarted_reasons; 469 bool m_restarted = false; // For "eStateStopped" events, this is true if the 470 // target was automatically restarted. 471 int m_update_state = 0; 472 bool m_interrupted = false; 473 474 ProcessEventData(const ProcessEventData &) = delete; 475 const ProcessEventData &operator=(const ProcessEventData &) = delete; 476 }; 477 478 /// Construct with a shared pointer to a target, and the Process listener. 479 /// Uses the Host UnixSignalsSP by default. 480 Process(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp); 481 482 /// Construct with a shared pointer to a target, the Process listener, and 483 /// the appropriate UnixSignalsSP for the process. 484 Process(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp, 485 const lldb::UnixSignalsSP &unix_signals_sp); 486 487 /// Destructor. 488 /// 489 /// The destructor is virtual since this class is designed to be inherited 490 /// from by the plug-in instance. 491 ~Process() override; 492 493 static void SettingsInitialize(); 494 495 static void SettingsTerminate(); 496 497 static ProcessProperties &GetGlobalProperties(); 498 499 /// Find a Process plug-in that can debug \a module using the currently 500 /// selected architecture. 501 /// 502 /// Scans all loaded plug-in interfaces that implement versions of the 503 /// Process plug-in interface and returns the first instance that can debug 504 /// the file. 505 /// 506 /// \see Process::CanDebug () 507 static lldb::ProcessSP FindPlugin(lldb::TargetSP target_sp, 508 llvm::StringRef plugin_name, 509 lldb::ListenerSP listener_sp, 510 const FileSpec *crash_file_path, 511 bool can_connect); 512 513 /// Static function that can be used with the \b host function 514 /// Host::StartMonitoringChildProcess (). 515 /// 516 /// This function can be used by lldb_private::Process subclasses when they 517 /// want to watch for a local process and have its exit status automatically 518 /// set when the host child process exits. Subclasses should call 519 /// Host::StartMonitoringChildProcess () with: 520 /// callback = Process::SetHostProcessExitStatus 521 /// pid = Process::GetID() 522 /// monitor_signals = false 523 static bool 524 SetProcessExitStatus(lldb::pid_t pid, // The process ID we want to monitor 525 bool exited, 526 int signo, // Zero for no signal 527 int status); // Exit value of process if signal is zero 528 529 lldb::ByteOrder GetByteOrder() const; 530 531 uint32_t GetAddressByteSize() const; 532 533 /// Returns the pid of the process or LLDB_INVALID_PROCESS_ID if there is 534 /// no known pid. 535 lldb::pid_t GetID() const { return m_pid; } 536 537 /// Sets the stored pid. 538 /// 539 /// This does not change the pid of underlying process. 540 void SetID(lldb::pid_t new_pid) { m_pid = new_pid; } 541 542 uint32_t GetUniqueID() const { return m_process_unique_id; } 543 544 /// Check if a plug-in instance can debug the file in \a module. 545 /// 546 /// Each plug-in is given a chance to say whether it can debug the file in 547 /// \a module. If the Process plug-in instance can debug a file on the 548 /// current system, it should return \b true. 549 /// 550 /// \return 551 /// Returns \b true if this Process plug-in instance can 552 /// debug the executable, \b false otherwise. 553 virtual bool CanDebug(lldb::TargetSP target, 554 bool plugin_specified_by_name) = 0; 555 556 /// This object is about to be destroyed, do any necessary cleanup. 557 /// 558 /// Subclasses that override this method should always call this superclass 559 /// method. 560 virtual void Finalize(); 561 562 /// Return whether this object is valid (i.e. has not been finalized.) 563 /// 564 /// \return 565 /// Returns \b true if this Process has not been finalized 566 /// and \b false otherwise. 567 bool IsValid() const { return !m_finalizing; } 568 569 /// Return a multi-word command object that can be used to expose plug-in 570 /// specific commands. 571 /// 572 /// This object will be used to resolve plug-in commands and can be 573 /// triggered by a call to: 574 /// 575 /// (lldb) process command <args> 576 /// 577 /// \return 578 /// A CommandObject which can be one of the concrete subclasses 579 /// of CommandObject like CommandObjectRaw, CommandObjectParsed, 580 /// or CommandObjectMultiword. 581 virtual CommandObject *GetPluginCommandObject() { return nullptr; } 582 583 /// Launch a new process. 584 /// 585 /// Launch a new process by spawning a new process using the target object's 586 /// executable module's file as the file to launch. 587 /// 588 /// This function is not meant to be overridden by Process subclasses. It 589 /// will first call Process::WillLaunch (Module *) and if that returns \b 590 /// true, Process::DoLaunch (Module*, char const *[],char const *[],const 591 /// char *,const char *, const char *) will be called to actually do the 592 /// launching. If DoLaunch returns \b true, then Process::DidLaunch() will 593 /// be called. 594 /// 595 /// \param[in] launch_info 596 /// Details regarding the environment, STDIN/STDOUT/STDERR 597 /// redirection, working path, etc. related to the requested launch. 598 /// 599 /// \return 600 /// An error object. Call GetID() to get the process ID if 601 /// the error object is success. 602 virtual Status Launch(ProcessLaunchInfo &launch_info); 603 604 virtual Status LoadCore(); 605 606 virtual Status DoLoadCore() { 607 Status error; 608 error.SetErrorStringWithFormatv( 609 "error: {0} does not support loading core files.", GetPluginName()); 610 return error; 611 } 612 613 // FUTURE WORK: GetLoadImageUtilityFunction are the first use we've 614 // had of having other plugins cache data in the Process. This is handy for 615 // long-living plugins - like the Platform - which manage interactions whose 616 // lifetime is governed by the Process lifetime. If we find we need to do 617 // this more often, we should construct a general solution to the problem. 618 // The consensus suggestion was that we have a token based registry in the 619 // Process. Some undecided questions are (1) who manages the tokens. It's 620 // probably best that you add the element and get back a token that 621 // represents it. That will avoid collisions. But there may be some utility 622 // in the registerer controlling the token? (2) whether the thing added 623 // should be simply owned by Process, and just go away when it does (3) 624 // whether the registree should be notified of the Process' demise. 625 // 626 // We are postponing designing this till we have at least a second use case. 627 /// Get the cached UtilityFunction that assists in loading binary images 628 /// into the process. 629 /// 630 /// \param[in] platform 631 /// The platform fetching the UtilityFunction. 632 /// \param[in] factory 633 /// A function that will be called only once per-process in a 634 /// thread-safe way to create the UtilityFunction if it has not 635 /// been initialized yet. 636 /// 637 /// \return 638 /// The cached utility function or null if the platform is not the 639 /// same as the target's platform. 640 UtilityFunction *GetLoadImageUtilityFunction( 641 Platform *platform, 642 llvm::function_ref<std::unique_ptr<UtilityFunction>()> factory); 643 644 /// Get the dynamic loader plug-in for this process. 645 /// 646 /// The default action is to let the DynamicLoader plug-ins check the main 647 /// executable and the DynamicLoader will select itself automatically. 648 /// Subclasses can override this if inspecting the executable is not 649 /// desired, or if Process subclasses can only use a specific DynamicLoader 650 /// plug-in. 651 virtual DynamicLoader *GetDynamicLoader(); 652 653 // Returns AUXV structure found in many ELF-based environments. 654 // 655 // The default action is to return an empty data buffer. 656 // 657 // \return 658 // A data extractor containing the contents of the AUXV data. 659 virtual DataExtractor GetAuxvData(); 660 661 /// Sometimes processes know how to retrieve and load shared libraries. This 662 /// is normally done by DynamicLoader plug-ins, but sometimes the connection 663 /// to the process allows retrieving this information. The dynamic loader 664 /// plug-ins can use this function if they can't determine the current 665 /// shared library load state. 666 /// 667 /// \return 668 /// A status object indicating if the operation was sucessful or not. 669 virtual llvm::Error LoadModules() { 670 return llvm::make_error<llvm::StringError>("Not implemented.", 671 llvm::inconvertibleErrorCode()); 672 } 673 674 /// Query remote GDBServer for a detailed loaded library list 675 /// \return 676 /// The list of modules currently loaded by the process, or an error. 677 virtual llvm::Expected<LoadedModuleInfoList> GetLoadedModuleList() { 678 return llvm::createStringError(llvm::inconvertibleErrorCode(), 679 "Not implemented"); 680 } 681 682 /// Save core dump into the specified file. 683 /// 684 /// \param[in] outfile 685 /// Path to store core dump in. 686 /// 687 /// \return 688 /// true if saved successfully, false if saving the core dump 689 /// is not supported by the plugin, error otherwise. 690 virtual llvm::Expected<bool> SaveCore(llvm::StringRef outfile); 691 692 protected: 693 virtual JITLoaderList &GetJITLoaders(); 694 695 public: 696 /// Get the system architecture for this process. 697 virtual ArchSpec GetSystemArchitecture() { return {}; } 698 699 /// Get the system runtime plug-in for this process. 700 /// 701 /// \return 702 /// Returns a pointer to the SystemRuntime plugin for this Process 703 /// if one is available. Else returns nullptr. 704 virtual SystemRuntime *GetSystemRuntime(); 705 706 /// Attach to an existing process using the process attach info. 707 /// 708 /// This function is not meant to be overridden by Process subclasses. It 709 /// will first call WillAttach (lldb::pid_t) or WillAttach (const char *), 710 /// and if that returns \b true, DoAttach (lldb::pid_t) or DoAttach (const 711 /// char *) will be called to actually do the attach. If DoAttach returns \b 712 /// true, then Process::DidAttach() will be called. 713 /// 714 /// \param[in] attach_info 715 /// The process attach info. 716 /// 717 /// \return 718 /// Returns \a pid if attaching was successful, or 719 /// LLDB_INVALID_PROCESS_ID if attaching fails. 720 virtual Status Attach(ProcessAttachInfo &attach_info); 721 722 /// Attach to a remote system via a URL 723 /// 724 /// \param[in] remote_url 725 /// The URL format that we are connecting to. 726 /// 727 /// \return 728 /// Returns an error object. 729 virtual Status ConnectRemote(llvm::StringRef remote_url); 730 731 bool GetShouldDetach() const { return m_should_detach; } 732 733 void SetShouldDetach(bool b) { m_should_detach = b; } 734 735 /// Get the image vector for the current process. 736 /// 737 /// \return 738 /// The constant reference to the member m_image_tokens. 739 const std::vector<lldb::addr_t>& GetImageTokens() { return m_image_tokens; } 740 741 /// Get the image information address for the current process. 742 /// 743 /// Some runtimes have system functions that can help dynamic loaders locate 744 /// the dynamic loader information needed to observe shared libraries being 745 /// loaded or unloaded. This function is in the Process interface (as 746 /// opposed to the DynamicLoader interface) to ensure that remote debugging 747 /// can take advantage of this functionality. 748 /// 749 /// \return 750 /// The address of the dynamic loader information, or 751 /// LLDB_INVALID_ADDRESS if this is not supported by this 752 /// interface. 753 virtual lldb::addr_t GetImageInfoAddress(); 754 755 /// Called when the process is about to broadcast a public stop. 756 /// 757 /// There are public and private stops. Private stops are when the process 758 /// is doing things like stepping and the client doesn't need to know about 759 /// starts and stop that implement a thread plan. Single stepping over a 760 /// source line in code might end up being implemented by one or more 761 /// process starts and stops. Public stops are when clients will be notified 762 /// that the process is stopped. These events typically trigger UI updates 763 /// (thread stack frames to be displayed, variables to be displayed, and 764 /// more). This function can be overriden and allows process subclasses to 765 /// do something before the eBroadcastBitStateChanged event is sent to 766 /// public clients. 767 virtual void WillPublicStop() {} 768 769 /// Register for process and thread notifications. 770 /// 771 /// Clients can register notification callbacks by filling out a 772 /// Process::Notifications structure and calling this function. 773 /// 774 /// \param[in] callbacks 775 /// A structure that contains the notification baton and 776 /// callback functions. 777 /// 778 /// \see Process::Notifications 779 void RegisterNotificationCallbacks(const Process::Notifications &callbacks); 780 781 /// Unregister for process and thread notifications. 782 /// 783 /// Clients can unregister notification callbacks by passing a copy of the 784 /// original baton and callbacks in \a callbacks. 785 /// 786 /// \param[in] callbacks 787 /// A structure that contains the notification baton and 788 /// callback functions. 789 /// 790 /// \return 791 /// Returns \b true if the notification callbacks were 792 /// successfully removed from the process, \b false otherwise. 793 /// 794 /// \see Process::Notifications 795 bool UnregisterNotificationCallbacks(const Process::Notifications &callbacks); 796 797 //================================================================== 798 // Built in Process Control functions 799 //================================================================== 800 /// Resumes all of a process's threads as configured using the Thread run 801 /// control functions. 802 /// 803 /// Threads for a process should be updated with one of the run control 804 /// actions (resume, step, or suspend) that they should take when the 805 /// process is resumed. If no run control action is given to a thread it 806 /// will be resumed by default. 807 /// 808 /// This function is not meant to be overridden by Process subclasses. This 809 /// function will take care of disabling any breakpoints that threads may be 810 /// stopped at, single stepping, and re-enabling breakpoints, and enabling 811 /// the basic flow control that the plug-in instances need not worry about. 812 /// 813 /// N.B. This function also sets the Write side of the Run Lock, which is 814 /// unset when the corresponding stop event is pulled off the Public Event 815 /// Queue. If you need to resume the process without setting the Run Lock, 816 /// use PrivateResume (though you should only do that from inside the 817 /// Process class. 818 /// 819 /// \return 820 /// Returns an error object. 821 /// 822 /// \see Thread:Resume() 823 /// \see Thread:Step() 824 /// \see Thread:Suspend() 825 Status Resume(); 826 827 Status ResumeSynchronous(Stream *stream); 828 829 /// Halts a running process. 830 /// 831 /// This function is not meant to be overridden by Process subclasses. If 832 /// the process is successfully halted, a eStateStopped process event with 833 /// GetInterrupted will be broadcast. If false, we will halt the process 834 /// with no events generated by the halt. 835 /// 836 /// \param[in] clear_thread_plans 837 /// If true, when the process stops, clear all thread plans. 838 /// 839 /// \param[in] use_run_lock 840 /// Whether to release the run lock after the stop. 841 /// 842 /// \return 843 /// Returns an error object. If the error is empty, the process is 844 /// halted. 845 /// otherwise the halt has failed. 846 Status Halt(bool clear_thread_plans = false, bool use_run_lock = true); 847 848 /// Detaches from a running or stopped process. 849 /// 850 /// This function is not meant to be overridden by Process subclasses. 851 /// 852 /// \param[in] keep_stopped 853 /// If true, don't resume the process on detach. 854 /// 855 /// \return 856 /// Returns an error object. 857 Status Detach(bool keep_stopped); 858 859 /// Kills the process and shuts down all threads that were spawned to track 860 /// and monitor the process. 861 /// 862 /// This function is not meant to be overridden by Process subclasses. 863 /// 864 /// \param[in] force_kill 865 /// Whether lldb should force a kill (instead of a detach) from 866 /// the inferior process. Normally if lldb launched a binary and 867 /// Destory is called, lldb kills it. If lldb attached to a 868 /// running process and Destory is called, lldb detaches. If 869 /// this behavior needs to be over-ridden, this is the bool that 870 /// can be used. 871 /// 872 /// \return 873 /// Returns an error object. 874 Status Destroy(bool force_kill); 875 876 /// Sends a process a UNIX signal \a signal. 877 /// 878 /// This function is not meant to be overridden by Process subclasses. 879 /// 880 /// \return 881 /// Returns an error object. 882 Status Signal(int signal); 883 884 void SetUnixSignals(lldb::UnixSignalsSP &&signals_sp); 885 886 const lldb::UnixSignalsSP &GetUnixSignals(); 887 888 //================================================================== 889 // Plug-in Process Control Overrides 890 //================================================================== 891 892 /// Called before attaching to a process. 893 /// 894 /// Allow Process plug-ins to execute some code before attaching a process. 895 /// 896 /// \return 897 /// Returns an error object. 898 virtual Status WillAttachToProcessWithID(lldb::pid_t pid) { return Status(); } 899 900 /// Called before attaching to a process. 901 /// 902 /// Allow Process plug-ins to execute some code before attaching a process. 903 /// 904 /// \return 905 /// Returns an error object. 906 virtual Status WillAttachToProcessWithName(const char *process_name, 907 bool wait_for_launch) { 908 return Status(); 909 } 910 911 /// Attach to a remote system via a URL 912 /// 913 /// \param[in] remote_url 914 /// The URL format that we are connecting to. 915 /// 916 /// \return 917 /// Returns an error object. 918 virtual Status DoConnectRemote(llvm::StringRef remote_url) { 919 Status error; 920 error.SetErrorString("remote connections are not supported"); 921 return error; 922 } 923 924 /// Attach to an existing process using a process ID. 925 /// 926 /// \param[in] pid 927 /// The process ID that we should attempt to attach to. 928 /// 929 /// \param[in] attach_info 930 /// Information on how to do the attach. For example, GetUserID() 931 /// will return the uid to attach as. 932 /// 933 /// \return 934 /// Returns a successful Status attaching was successful, or 935 /// an appropriate (possibly platform-specific) error code if 936 /// attaching fails. 937 /// hanming : need flag 938 virtual Status DoAttachToProcessWithID(lldb::pid_t pid, 939 const ProcessAttachInfo &attach_info) { 940 Status error; 941 error.SetErrorStringWithFormatv( 942 "error: {0} does not support attaching to a process by pid", 943 GetPluginName()); 944 return error; 945 } 946 947 /// Attach to an existing process using a partial process name. 948 /// 949 /// \param[in] process_name 950 /// The name of the process to attach to. 951 /// 952 /// \param[in] attach_info 953 /// Information on how to do the attach. For example, GetUserID() 954 /// will return the uid to attach as. 955 /// 956 /// \return 957 /// Returns a successful Status attaching was successful, or 958 /// an appropriate (possibly platform-specific) error code if 959 /// attaching fails. 960 virtual Status 961 DoAttachToProcessWithName(const char *process_name, 962 const ProcessAttachInfo &attach_info) { 963 Status error; 964 error.SetErrorString("attach by name is not supported"); 965 return error; 966 } 967 968 /// Called after attaching a process. 969 /// 970 /// \param[in] process_arch 971 /// If you can figure out the process architecture after attach, fill it 972 /// in here. 973 /// 974 /// Allow Process plug-ins to execute some code after attaching to a 975 /// process. 976 virtual void DidAttach(ArchSpec &process_arch) { process_arch.Clear(); } 977 978 /// Called after a process re-execs itself. 979 /// 980 /// Allow Process plug-ins to execute some code after a process has exec'ed 981 /// itself. Subclasses typically should override DoDidExec() as the 982 /// lldb_private::Process class needs to remove its dynamic loader, runtime, 983 /// ABI and other plug-ins, as well as unload all shared libraries. 984 virtual void DidExec(); 985 986 /// Subclasses of Process should implement this function if they need to do 987 /// anything after a process exec's itself. 988 virtual void DoDidExec() {} 989 990 /// Called after a reported fork. 991 virtual void DidFork(lldb::pid_t child_pid, lldb::tid_t child_tid) {} 992 993 /// Called after a reported vfork. 994 virtual void DidVFork(lldb::pid_t child_pid, lldb::tid_t child_tid) {} 995 996 /// Called after reported vfork completion. 997 virtual void DidVForkDone() {} 998 999 /// Called before launching to a process. 1000 /// 1001 /// Allow Process plug-ins to execute some code before launching a process. 1002 /// 1003 /// \return 1004 /// Returns an error object. 1005 virtual Status WillLaunch(Module *module) { return Status(); } 1006 1007 /// Launch a new process. 1008 /// 1009 /// Launch a new process by spawning a new process using \a exe_module's 1010 /// file as the file to launch. Launch details are provided in \a 1011 /// launch_info. 1012 /// 1013 /// \param[in] exe_module 1014 /// The module from which to extract the file specification and 1015 /// launch. 1016 /// 1017 /// \param[in] launch_info 1018 /// Details (e.g. arguments, stdio redirection, etc.) for the 1019 /// requested launch. 1020 /// 1021 /// \return 1022 /// An Status instance indicating success or failure of the 1023 /// operation. 1024 virtual Status DoLaunch(Module *exe_module, ProcessLaunchInfo &launch_info) { 1025 Status error; 1026 error.SetErrorStringWithFormatv( 1027 "error: {0} does not support launching processes", GetPluginName()); 1028 return error; 1029 } 1030 1031 /// Called after launching a process. 1032 /// 1033 /// Allow Process plug-ins to execute some code after launching a process. 1034 virtual void DidLaunch() {} 1035 1036 /// Called before resuming to a process. 1037 /// 1038 /// Allow Process plug-ins to execute some code before resuming a process. 1039 /// 1040 /// \return 1041 /// Returns an error object. 1042 virtual Status WillResume() { return Status(); } 1043 1044 /// Resumes all of a process's threads as configured using the Thread run 1045 /// control functions. 1046 /// 1047 /// Threads for a process should be updated with one of the run control 1048 /// actions (resume, step, or suspend) that they should take when the 1049 /// process is resumed. If no run control action is given to a thread it 1050 /// will be resumed by default. 1051 /// 1052 /// \return 1053 /// Returns \b true if the process successfully resumes using 1054 /// the thread run control actions, \b false otherwise. 1055 /// 1056 /// \see Thread:Resume() 1057 /// \see Thread:Step() 1058 /// \see Thread:Suspend() 1059 virtual Status DoResume() { 1060 Status error; 1061 error.SetErrorStringWithFormatv( 1062 "error: {0} does not support resuming processes", GetPluginName()); 1063 return error; 1064 } 1065 1066 /// Called after resuming a process. 1067 /// 1068 /// Allow Process plug-ins to execute some code after resuming a process. 1069 virtual void DidResume() {} 1070 1071 /// Called before halting to a process. 1072 /// 1073 /// Allow Process plug-ins to execute some code before halting a process. 1074 /// 1075 /// \return 1076 /// Returns an error object. 1077 virtual Status WillHalt() { return Status(); } 1078 1079 /// Halts a running process. 1080 /// 1081 /// DoHalt must produce one and only one stop StateChanged event if it 1082 /// actually stops the process. If the stop happens through some natural 1083 /// event (for instance a SIGSTOP), then forwarding that event will do. 1084 /// Otherwise, you must generate the event manually. This function is called 1085 /// from the context of the private state thread. 1086 /// 1087 /// \param[out] caused_stop 1088 /// If true, then this Halt caused the stop, otherwise, the 1089 /// process was already stopped. 1090 /// 1091 /// \return 1092 /// Returns \b true if the process successfully halts, \b false 1093 /// otherwise. 1094 virtual Status DoHalt(bool &caused_stop) { 1095 Status error; 1096 error.SetErrorStringWithFormatv( 1097 "error: {0} does not support halting processes", GetPluginName()); 1098 return error; 1099 } 1100 1101 /// Called after halting a process. 1102 /// 1103 /// Allow Process plug-ins to execute some code after halting a process. 1104 virtual void DidHalt() {} 1105 1106 /// Called before detaching from a process. 1107 /// 1108 /// Allow Process plug-ins to execute some code before detaching from a 1109 /// process. 1110 /// 1111 /// \return 1112 /// Returns an error object. 1113 virtual Status WillDetach() { return Status(); } 1114 1115 /// Detaches from a running or stopped process. 1116 /// 1117 /// \return 1118 /// Returns \b true if the process successfully detaches, \b 1119 /// false otherwise. 1120 virtual Status DoDetach(bool keep_stopped) { 1121 Status error; 1122 error.SetErrorStringWithFormatv( 1123 "error: {0} does not support detaching from processes", 1124 GetPluginName()); 1125 return error; 1126 } 1127 1128 /// Called after detaching from a process. 1129 /// 1130 /// Allow Process plug-ins to execute some code after detaching from a 1131 /// process. 1132 virtual void DidDetach() {} 1133 1134 virtual bool DetachRequiresHalt() { return false; } 1135 1136 /// Called before sending a signal to a process. 1137 /// 1138 /// Allow Process plug-ins to execute some code before sending a signal to a 1139 /// process. 1140 /// 1141 /// \return 1142 /// Returns no error if it is safe to proceed with a call to 1143 /// Process::DoSignal(int), otherwise an error describing what 1144 /// prevents the signal from being sent. 1145 virtual Status WillSignal() { return Status(); } 1146 1147 /// Sends a process a UNIX signal \a signal. 1148 /// 1149 /// \return 1150 /// Returns an error object. 1151 virtual Status DoSignal(int signal) { 1152 Status error; 1153 error.SetErrorStringWithFormatv( 1154 "error: {0} does not support sending signals to processes", 1155 GetPluginName()); 1156 return error; 1157 } 1158 1159 virtual Status WillDestroy() { return Status(); } 1160 1161 virtual Status DoDestroy() = 0; 1162 1163 virtual void DidDestroy() {} 1164 1165 virtual bool DestroyRequiresHalt() { return true; } 1166 1167 /// Called after sending a signal to a process. 1168 /// 1169 /// Allow Process plug-ins to execute some code after sending a signal to a 1170 /// process. 1171 virtual void DidSignal() {} 1172 1173 /// Currently called as part of ShouldStop. 1174 /// FIXME: Should really happen when the target stops before the 1175 /// event is taken from the queue... 1176 /// 1177 /// This callback is called as the event 1178 /// is about to be queued up to allow Process plug-ins to execute some code 1179 /// prior to clients being notified that a process was stopped. Common 1180 /// operations include updating the thread list, invalidating any thread 1181 /// state (registers, stack, etc) prior to letting the notification go out. 1182 /// 1183 virtual void RefreshStateAfterStop() = 0; 1184 1185 /// Sometimes the connection to a process can detect the host OS version 1186 /// that the process is running on. The current platform should be checked 1187 /// first in case the platform is connected, but clients can fall back onto 1188 /// this function if the platform fails to identify the host OS version. The 1189 /// platform should be checked first in case you are running a simulator 1190 /// platform that might itself be running natively, but have different 1191 /// heuristics for figuring out which OS is is emulating. 1192 /// 1193 /// \return 1194 /// Returns the version tuple of the host OS. In case of failure an empty 1195 /// VersionTuple is returner. 1196 virtual llvm::VersionTuple GetHostOSVersion() { return llvm::VersionTuple(); } 1197 1198 /// \return the macCatalyst version of the host OS. 1199 virtual llvm::VersionTuple GetHostMacCatalystVersion() { return {}; } 1200 1201 /// Get the target object pointer for this module. 1202 /// 1203 /// \return 1204 /// A Target object pointer to the target that owns this 1205 /// module. 1206 Target &GetTarget() { return *m_target_wp.lock(); } 1207 1208 /// Get the const target object pointer for this module. 1209 /// 1210 /// \return 1211 /// A const Target object pointer to the target that owns this 1212 /// module. 1213 const Target &GetTarget() const { return *m_target_wp.lock(); } 1214 1215 /// Flush all data in the process. 1216 /// 1217 /// Flush the memory caches, all threads, and any other cached data in the 1218 /// process. 1219 /// 1220 /// This function can be called after a world changing event like adding a 1221 /// new symbol file, or after the process makes a large context switch (from 1222 /// boot ROM to booted into an OS). 1223 void Flush(); 1224 1225 /// Get accessor for the current process state. 1226 /// 1227 /// \return 1228 /// The current state of the process. 1229 /// 1230 /// \see lldb::StateType 1231 lldb::StateType GetState(); 1232 1233 lldb::ExpressionResults 1234 RunThreadPlan(ExecutionContext &exe_ctx, lldb::ThreadPlanSP &thread_plan_sp, 1235 const EvaluateExpressionOptions &options, 1236 DiagnosticManager &diagnostic_manager); 1237 1238 static const char *ExecutionResultAsCString(lldb::ExpressionResults result); 1239 1240 void GetStatus(Stream &ostrm); 1241 1242 size_t GetThreadStatus(Stream &ostrm, bool only_threads_with_stop_reason, 1243 uint32_t start_frame, uint32_t num_frames, 1244 uint32_t num_frames_with_source, 1245 bool stop_format); 1246 1247 void SendAsyncInterrupt(); 1248 1249 // Notify this process class that modules got loaded. 1250 // 1251 // If subclasses override this method, they must call this version before 1252 // doing anything in the subclass version of the function. 1253 virtual void ModulesDidLoad(ModuleList &module_list); 1254 1255 /// Retrieve the list of shared libraries that are loaded for this process 1256 /// This method is used on pre-macOS 10.12, pre-iOS 10, pre-tvOS 10, pre- 1257 /// watchOS 3 systems. The following two methods are for newer versions of 1258 /// those OSes. 1259 /// 1260 /// For certain platforms, the time it takes for the DynamicLoader plugin to 1261 /// read all of the shared libraries out of memory over a slow communication 1262 /// channel may be too long. In that instance, the gdb-remote stub may be 1263 /// able to retrieve the necessary information about the solibs out of 1264 /// memory and return a concise summary sufficient for the DynamicLoader 1265 /// plugin. 1266 /// 1267 /// \param [in] image_list_address 1268 /// The address where the table of shared libraries is stored in memory, 1269 /// if that is appropriate for this platform. Else this may be 1270 /// passed as LLDB_INVALID_ADDRESS. 1271 /// 1272 /// \param [in] image_count 1273 /// The number of shared libraries that are present in this process, if 1274 /// that is appropriate for this platofrm Else this may be passed as 1275 /// LLDB_INVALID_ADDRESS. 1276 /// 1277 /// \return 1278 /// A StructuredDataSP object which, if non-empty, will contain the 1279 /// information the DynamicLoader needs to get the initial scan of 1280 /// solibs resolved. 1281 virtual lldb_private::StructuredData::ObjectSP 1282 GetLoadedDynamicLibrariesInfos(lldb::addr_t image_list_address, 1283 lldb::addr_t image_count) { 1284 return StructuredData::ObjectSP(); 1285 } 1286 1287 // On macOS 10.12, tvOS 10, iOS 10, watchOS 3 and newer, debugserver can 1288 // return the full list of loaded shared libraries without needing any input. 1289 virtual lldb_private::StructuredData::ObjectSP 1290 GetLoadedDynamicLibrariesInfos() { 1291 return StructuredData::ObjectSP(); 1292 } 1293 1294 // On macOS 10.12, tvOS 10, iOS 10, watchOS 3 and newer, debugserver can 1295 // return information about binaries given their load addresses. 1296 virtual lldb_private::StructuredData::ObjectSP GetLoadedDynamicLibrariesInfos( 1297 const std::vector<lldb::addr_t> &load_addresses) { 1298 return StructuredData::ObjectSP(); 1299 } 1300 1301 // Get information about the library shared cache, if that exists 1302 // 1303 // On macOS 10.12, tvOS 10, iOS 10, watchOS 3 and newer, debugserver can 1304 // return information about the library shared cache (a set of standard 1305 // libraries that are loaded at the same location for all processes on a 1306 // system) in use. 1307 virtual lldb_private::StructuredData::ObjectSP GetSharedCacheInfo() { 1308 return StructuredData::ObjectSP(); 1309 } 1310 1311 /// Print a user-visible warning about a module being built with 1312 /// optimization 1313 /// 1314 /// Prints a async warning message to the user one time per Module where a 1315 /// function is found that was compiled with optimization, per Process. 1316 /// 1317 /// \param [in] sc 1318 /// A SymbolContext with eSymbolContextFunction and eSymbolContextModule 1319 /// pre-computed. 1320 void PrintWarningOptimization(const SymbolContext &sc); 1321 1322 /// Print a user-visible warning about a function written in a 1323 /// language that this version of LLDB doesn't support. 1324 /// 1325 /// \see PrintWarningOptimization 1326 void PrintWarningUnsupportedLanguage(const SymbolContext &sc); 1327 1328 virtual bool GetProcessInfo(ProcessInstanceInfo &info); 1329 1330 /// Get the exit status for a process. 1331 /// 1332 /// \return 1333 /// The process's return code, or -1 if the current process 1334 /// state is not eStateExited. 1335 int GetExitStatus(); 1336 1337 /// Get a textual description of what the process exited. 1338 /// 1339 /// \return 1340 /// The textual description of why the process exited, or nullptr 1341 /// if there is no description available. 1342 const char *GetExitDescription(); 1343 1344 virtual void DidExit() {} 1345 1346 lldb::addr_t GetCodeAddressMask(); 1347 lldb::addr_t GetDataAddressMask(); 1348 1349 void SetCodeAddressMask(lldb::addr_t code_address_mask) { 1350 m_code_address_mask = code_address_mask; 1351 } 1352 1353 void SetDataAddressMask(lldb::addr_t data_address_mask) { 1354 m_data_address_mask = data_address_mask; 1355 } 1356 1357 /// Get the Modification ID of the process. 1358 /// 1359 /// \return 1360 /// The modification ID of the process. 1361 ProcessModID GetModID() const { return m_mod_id; } 1362 1363 const ProcessModID &GetModIDRef() const { return m_mod_id; } 1364 1365 uint32_t GetStopID() const { return m_mod_id.GetStopID(); } 1366 1367 uint32_t GetResumeID() const { return m_mod_id.GetResumeID(); } 1368 1369 uint32_t GetLastUserExpressionResumeID() const { 1370 return m_mod_id.GetLastUserExpressionResumeID(); 1371 } 1372 1373 uint32_t GetLastNaturalStopID() const { 1374 return m_mod_id.GetLastNaturalStopID(); 1375 } 1376 1377 lldb::EventSP GetStopEventForStopID(uint32_t stop_id) const { 1378 return m_mod_id.GetStopEventForStopID(stop_id); 1379 } 1380 1381 /// Set accessor for the process exit status (return code). 1382 /// 1383 /// Sometimes a child exits and the exit can be detected by global functions 1384 /// (signal handler for SIGCHLD for example). This accessor allows the exit 1385 /// status to be set from an external source. 1386 /// 1387 /// Setting this will cause a eStateExited event to be posted to the process 1388 /// event queue. 1389 /// 1390 /// \param[in] exit_status 1391 /// The value for the process's return code. 1392 /// 1393 /// \see lldb::StateType 1394 virtual bool SetExitStatus(int exit_status, const char *cstr); 1395 1396 /// Check if a process is still alive. 1397 /// 1398 /// \return 1399 /// Returns \b true if the process is still valid, \b false 1400 /// otherwise. 1401 virtual bool IsAlive(); 1402 1403 virtual bool IsLiveDebugSession() const { return true; }; 1404 1405 /// Before lldb detaches from a process, it warns the user that they are 1406 /// about to lose their debug session. In some cases, this warning doesn't 1407 /// need to be emitted -- for instance, with core file debugging where the 1408 /// user can reconstruct the "state" by simply re-running the debugger on 1409 /// the core file. 1410 /// 1411 /// \return 1412 /// Returns \b true if the user should be warned about detaching from 1413 /// this process. 1414 virtual bool WarnBeforeDetach() const { return true; } 1415 1416 /// Read of memory from a process. 1417 /// 1418 /// This function will read memory from the current process's address space 1419 /// and remove any traps that may have been inserted into the memory. 1420 /// 1421 /// This function is not meant to be overridden by Process subclasses, the 1422 /// subclasses should implement Process::DoReadMemory (lldb::addr_t, size_t, 1423 /// void *). 1424 /// 1425 /// \param[in] vm_addr 1426 /// A virtual load address that indicates where to start reading 1427 /// memory from. 1428 /// 1429 /// \param[out] buf 1430 /// A byte buffer that is at least \a size bytes long that 1431 /// will receive the memory bytes. 1432 /// 1433 /// \param[in] size 1434 /// The number of bytes to read. 1435 /// 1436 /// \param[out] error 1437 /// An error that indicates the success or failure of this 1438 /// operation. If error indicates success (error.Success()), 1439 /// then the value returned can be trusted, otherwise zero 1440 /// will be returned. 1441 /// 1442 /// \return 1443 /// The number of bytes that were actually read into \a buf. If 1444 /// the returned number is greater than zero, yet less than \a 1445 /// size, then this function will get called again with \a 1446 /// vm_addr, \a buf, and \a size updated appropriately. Zero is 1447 /// returned in the case of an error. 1448 virtual size_t ReadMemory(lldb::addr_t vm_addr, void *buf, size_t size, 1449 Status &error); 1450 1451 /// Read of memory from a process. 1452 /// 1453 /// This function has the same semantics of ReadMemory except that it 1454 /// bypasses caching. 1455 /// 1456 /// \param[in] vm_addr 1457 /// A virtual load address that indicates where to start reading 1458 /// memory from. 1459 /// 1460 /// \param[out] buf 1461 /// A byte buffer that is at least \a size bytes long that 1462 /// will receive the memory bytes. 1463 /// 1464 /// \param[in] size 1465 /// The number of bytes to read. 1466 /// 1467 /// \param[out] error 1468 /// An error that indicates the success or failure of this 1469 /// operation. If error indicates success (error.Success()), 1470 /// then the value returned can be trusted, otherwise zero 1471 /// will be returned. 1472 /// 1473 /// \return 1474 /// The number of bytes that were actually read into \a buf. If 1475 /// the returned number is greater than zero, yet less than \a 1476 /// size, then this function will get called again with \a 1477 /// vm_addr, \a buf, and \a size updated appropriately. Zero is 1478 /// returned in the case of an error. 1479 size_t ReadMemoryFromInferior(lldb::addr_t vm_addr, void *buf, size_t size, 1480 Status &error); 1481 1482 /// Read a NULL terminated C string from memory 1483 /// 1484 /// This function will read a cache page at a time until the NULL 1485 /// C string terminator is found. It will stop reading if the NULL 1486 /// termination byte isn't found before reading \a cstr_max_len bytes, and 1487 /// the results are always guaranteed to be NULL terminated (at most 1488 /// cstr_max_len - 1 bytes will be read). 1489 size_t ReadCStringFromMemory(lldb::addr_t vm_addr, char *cstr, 1490 size_t cstr_max_len, Status &error); 1491 1492 size_t ReadCStringFromMemory(lldb::addr_t vm_addr, std::string &out_str, 1493 Status &error); 1494 1495 /// Reads an unsigned integer of the specified byte size from process 1496 /// memory. 1497 /// 1498 /// \param[in] load_addr 1499 /// A load address of the integer to read. 1500 /// 1501 /// \param[in] byte_size 1502 /// The size in byte of the integer to read. 1503 /// 1504 /// \param[in] fail_value 1505 /// The value to return if we fail to read an integer. 1506 /// 1507 /// \param[out] error 1508 /// An error that indicates the success or failure of this 1509 /// operation. If error indicates success (error.Success()), 1510 /// then the value returned can be trusted, otherwise zero 1511 /// will be returned. 1512 /// 1513 /// \return 1514 /// The unsigned integer that was read from the process memory 1515 /// space. If the integer was smaller than a uint64_t, any 1516 /// unused upper bytes will be zero filled. If the process 1517 /// byte order differs from the host byte order, the integer 1518 /// value will be appropriately byte swapped into host byte 1519 /// order. 1520 uint64_t ReadUnsignedIntegerFromMemory(lldb::addr_t load_addr, 1521 size_t byte_size, uint64_t fail_value, 1522 Status &error); 1523 1524 int64_t ReadSignedIntegerFromMemory(lldb::addr_t load_addr, size_t byte_size, 1525 int64_t fail_value, Status &error); 1526 1527 lldb::addr_t ReadPointerFromMemory(lldb::addr_t vm_addr, Status &error); 1528 1529 bool WritePointerToMemory(lldb::addr_t vm_addr, lldb::addr_t ptr_value, 1530 Status &error); 1531 1532 /// Actually do the writing of memory to a process. 1533 /// 1534 /// \param[in] vm_addr 1535 /// A virtual load address that indicates where to start writing 1536 /// memory to. 1537 /// 1538 /// \param[in] buf 1539 /// A byte buffer that is at least \a size bytes long that 1540 /// contains the data to write. 1541 /// 1542 /// \param[in] size 1543 /// The number of bytes to write. 1544 /// 1545 /// \param[out] error 1546 /// An error value in case the memory write fails. 1547 /// 1548 /// \return 1549 /// The number of bytes that were actually written. 1550 virtual size_t DoWriteMemory(lldb::addr_t vm_addr, const void *buf, 1551 size_t size, Status &error) { 1552 error.SetErrorStringWithFormatv( 1553 "error: {0} does not support writing to processes", GetPluginName()); 1554 return 0; 1555 } 1556 1557 /// Write all or part of a scalar value to memory. 1558 /// 1559 /// The value contained in \a scalar will be swapped to match the byte order 1560 /// of the process that is being debugged. If \a size is less than the size 1561 /// of scalar, the least significant \a size bytes from scalar will be 1562 /// written. If \a size is larger than the byte size of scalar, then the 1563 /// extra space will be padded with zeros and the scalar value will be 1564 /// placed in the least significant bytes in memory. 1565 /// 1566 /// \param[in] vm_addr 1567 /// A virtual load address that indicates where to start writing 1568 /// memory to. 1569 /// 1570 /// \param[in] scalar 1571 /// The scalar to write to the debugged process. 1572 /// 1573 /// \param[in] size 1574 /// This value can be smaller or larger than the scalar value 1575 /// itself. If \a size is smaller than the size of \a scalar, 1576 /// the least significant bytes in \a scalar will be used. If 1577 /// \a size is larger than the byte size of \a scalar, then 1578 /// the extra space will be padded with zeros. If \a size is 1579 /// set to UINT32_MAX, then the size of \a scalar will be used. 1580 /// 1581 /// \param[out] error 1582 /// An error value in case the memory write fails. 1583 /// 1584 /// \return 1585 /// The number of bytes that were actually written. 1586 size_t WriteScalarToMemory(lldb::addr_t vm_addr, const Scalar &scalar, 1587 size_t size, Status &error); 1588 1589 size_t ReadScalarIntegerFromMemory(lldb::addr_t addr, uint32_t byte_size, 1590 bool is_signed, Scalar &scalar, 1591 Status &error); 1592 1593 /// Write memory to a process. 1594 /// 1595 /// This function will write memory to the current process's address space 1596 /// and maintain any traps that might be present due to software 1597 /// breakpoints. 1598 /// 1599 /// This function is not meant to be overridden by Process subclasses, the 1600 /// subclasses should implement Process::DoWriteMemory (lldb::addr_t, 1601 /// size_t, void *). 1602 /// 1603 /// \param[in] vm_addr 1604 /// A virtual load address that indicates where to start writing 1605 /// memory to. 1606 /// 1607 /// \param[in] buf 1608 /// A byte buffer that is at least \a size bytes long that 1609 /// contains the data to write. 1610 /// 1611 /// \param[in] size 1612 /// The number of bytes to write. 1613 /// 1614 /// \return 1615 /// The number of bytes that were actually written. 1616 // TODO: change this to take an ArrayRef<uint8_t> 1617 size_t WriteMemory(lldb::addr_t vm_addr, const void *buf, size_t size, 1618 Status &error); 1619 1620 /// Actually allocate memory in the process. 1621 /// 1622 /// This function will allocate memory in the process's address space. This 1623 /// can't rely on the generic function calling mechanism, since that 1624 /// requires this function. 1625 /// 1626 /// \param[in] size 1627 /// The size of the allocation requested. 1628 /// 1629 /// \return 1630 /// The address of the allocated buffer in the process, or 1631 /// LLDB_INVALID_ADDRESS if the allocation failed. 1632 1633 virtual lldb::addr_t DoAllocateMemory(size_t size, uint32_t permissions, 1634 Status &error) { 1635 error.SetErrorStringWithFormatv( 1636 "error: {0} does not support allocating in the debug process", 1637 GetPluginName()); 1638 return LLDB_INVALID_ADDRESS; 1639 } 1640 1641 virtual Status WriteObjectFile(std::vector<ObjectFile::LoadableData> entries); 1642 1643 /// The public interface to allocating memory in the process. 1644 /// 1645 /// This function will allocate memory in the process's address space. This 1646 /// can't rely on the generic function calling mechanism, since that 1647 /// requires this function. 1648 /// 1649 /// \param[in] size 1650 /// The size of the allocation requested. 1651 /// 1652 /// \param[in] permissions 1653 /// Or together any of the lldb::Permissions bits. The permissions on 1654 /// a given memory allocation can't be changed after allocation. Note 1655 /// that a block that isn't set writable can still be written on from 1656 /// lldb, 1657 /// just not by the process itself. 1658 /// 1659 /// \param[in,out] error 1660 /// An error object to fill in if things go wrong. 1661 /// \return 1662 /// The address of the allocated buffer in the process, or 1663 /// LLDB_INVALID_ADDRESS if the allocation failed. 1664 lldb::addr_t AllocateMemory(size_t size, uint32_t permissions, Status &error); 1665 1666 /// The public interface to allocating memory in the process, this also 1667 /// clears the allocated memory. 1668 /// 1669 /// This function will allocate memory in the process's address space. This 1670 /// can't rely on the generic function calling mechanism, since that 1671 /// requires this function. 1672 /// 1673 /// \param[in] size 1674 /// The size of the allocation requested. 1675 /// 1676 /// \param[in] permissions 1677 /// Or together any of the lldb::Permissions bits. The permissions on 1678 /// a given memory allocation can't be changed after allocation. Note 1679 /// that a block that isn't set writable can still be written on from 1680 /// lldb, 1681 /// just not by the process itself. 1682 /// 1683 /// \param[in,out] error 1684 /// An error object to fill in if things go wrong. 1685 /// 1686 /// \return 1687 /// The address of the allocated buffer in the process, or 1688 /// LLDB_INVALID_ADDRESS if the allocation failed. 1689 1690 lldb::addr_t CallocateMemory(size_t size, uint32_t permissions, 1691 Status &error); 1692 1693 /// If this architecture and process supports memory tagging, return a tag 1694 /// manager that can be used to maniupulate those memory tags. 1695 /// 1696 /// \return 1697 /// Either a valid pointer to a tag manager or an error describing why one 1698 /// could not be provided. 1699 llvm::Expected<const MemoryTagManager *> GetMemoryTagManager(); 1700 1701 /// Read memory tags for the range addr to addr+len. It is assumed 1702 /// that this range has already been granule aligned. 1703 /// (see MemoryTagManager::MakeTaggedRange) 1704 /// 1705 /// This calls DoReadMemoryTags to do the target specific operations. 1706 /// 1707 /// \param[in] addr 1708 /// Start of memory range to read tags for. 1709 /// 1710 /// \param[in] len 1711 /// Length of memory range to read tags for (in bytes). 1712 /// 1713 /// \return 1714 /// If this architecture or process does not support memory tagging, 1715 /// an error saying so. 1716 /// If it does, either the memory tags or an error describing a 1717 /// failure to read or unpack them. 1718 virtual llvm::Expected<std::vector<lldb::addr_t>> 1719 ReadMemoryTags(lldb::addr_t addr, size_t len); 1720 1721 /// Write memory tags for a range of memory. 1722 /// (calls DoWriteMemoryTags to do the target specific work) 1723 /// 1724 /// \param[in] addr 1725 /// The address to start writing tags from. It is assumed that this 1726 /// address is granule aligned. 1727 /// 1728 /// \param[in] len 1729 /// The size of the range to write tags for. It is assumed that this 1730 /// is some multiple of the granule size. This len can be different 1731 /// from (number of tags * granule size) in the case where you want 1732 /// lldb-server to repeat tags across the range. 1733 /// 1734 /// \param[in] tags 1735 /// Allocation tags to be written. Since lldb-server can repeat tags for a 1736 /// range, the number of tags doesn't have to match the number of granules 1737 /// in the range. (though most of the time it will) 1738 /// 1739 /// \return 1740 /// A Status telling you if the write succeeded or not. 1741 Status WriteMemoryTags(lldb::addr_t addr, size_t len, 1742 const std::vector<lldb::addr_t> &tags); 1743 1744 /// Resolve dynamically loaded indirect functions. 1745 /// 1746 /// \param[in] address 1747 /// The load address of the indirect function to resolve. 1748 /// 1749 /// \param[out] error 1750 /// An error value in case the resolve fails. 1751 /// 1752 /// \return 1753 /// The address of the resolved function. 1754 /// LLDB_INVALID_ADDRESS if the resolution failed. 1755 virtual lldb::addr_t ResolveIndirectFunction(const Address *address, 1756 Status &error); 1757 1758 /// Locate the memory region that contains load_addr. 1759 /// 1760 /// If load_addr is within the address space the process has mapped 1761 /// range_info will be filled in with the start and end of that range as 1762 /// well as the permissions for that range and range_info. GetMapped will 1763 /// return true. 1764 /// 1765 /// If load_addr is outside any mapped region then range_info will have its 1766 /// start address set to load_addr and the end of the range will indicate 1767 /// the start of the next mapped range or be set to LLDB_INVALID_ADDRESS if 1768 /// there are no valid mapped ranges between load_addr and the end of the 1769 /// process address space. 1770 /// 1771 /// GetMemoryRegionInfo calls DoGetMemoryRegionInfo. Override that function in 1772 /// process subclasses. 1773 /// 1774 /// \param[in] load_addr 1775 /// The load address to query the range_info for. May include non 1776 /// address bits, these will be removed by the the ABI plugin if there is 1777 /// one. 1778 /// 1779 /// \param[out] range_info 1780 /// An range_info value containing the details of the range. 1781 /// 1782 /// \return 1783 /// An error value. 1784 Status GetMemoryRegionInfo(lldb::addr_t load_addr, 1785 MemoryRegionInfo &range_info); 1786 1787 /// Obtain all the mapped memory regions within this process. 1788 /// 1789 /// \param[out] region_list 1790 /// A vector to contain MemoryRegionInfo objects for all mapped 1791 /// ranges. 1792 /// 1793 /// \return 1794 /// An error value. 1795 virtual Status 1796 GetMemoryRegions(lldb_private::MemoryRegionInfos ®ion_list); 1797 1798 virtual Status GetWatchpointSupportInfo(uint32_t &num) { 1799 Status error; 1800 num = 0; 1801 error.SetErrorString("Process::GetWatchpointSupportInfo() not supported"); 1802 return error; 1803 } 1804 1805 virtual Status GetWatchpointSupportInfo(uint32_t &num, bool &after) { 1806 Status error; 1807 num = 0; 1808 after = true; 1809 error.SetErrorString("Process::GetWatchpointSupportInfo() not supported"); 1810 return error; 1811 } 1812 1813 lldb::ModuleSP ReadModuleFromMemory(const FileSpec &file_spec, 1814 lldb::addr_t header_addr, 1815 size_t size_to_read = 512); 1816 1817 /// Attempt to get the attributes for a region of memory in the process. 1818 /// 1819 /// It may be possible for the remote debug server to inspect attributes for 1820 /// a region of memory in the process, such as whether there is a valid page 1821 /// of memory at a given address or whether that page is 1822 /// readable/writable/executable by the process. 1823 /// 1824 /// \param[in] load_addr 1825 /// The address of interest in the process. 1826 /// 1827 /// \param[out] permissions 1828 /// If this call returns successfully, this bitmask will have 1829 /// its Permissions bits set to indicate whether the region is 1830 /// readable/writable/executable. If this call fails, the 1831 /// bitmask values are undefined. 1832 /// 1833 /// \return 1834 /// Returns true if it was able to determine the attributes of the 1835 /// memory region. False if not. 1836 virtual bool GetLoadAddressPermissions(lldb::addr_t load_addr, 1837 uint32_t &permissions); 1838 1839 /// Determines whether executing JIT-compiled code in this process is 1840 /// possible. 1841 /// 1842 /// \return 1843 /// True if execution of JIT code is possible; false otherwise. 1844 bool CanJIT(); 1845 1846 /// Sets whether executing JIT-compiled code in this process is possible. 1847 /// 1848 /// \param[in] can_jit 1849 /// True if execution of JIT code is possible; false otherwise. 1850 void SetCanJIT(bool can_jit); 1851 1852 /// Determines whether executing function calls using the interpreter is 1853 /// possible for this process. 1854 /// 1855 /// \return 1856 /// True if possible; false otherwise. 1857 bool CanInterpretFunctionCalls() { return m_can_interpret_function_calls; } 1858 1859 /// Sets whether executing function calls using the interpreter is possible 1860 /// for this process. 1861 /// 1862 /// \param[in] can_interpret_function_calls 1863 /// True if possible; false otherwise. 1864 void SetCanInterpretFunctionCalls(bool can_interpret_function_calls) { 1865 m_can_interpret_function_calls = can_interpret_function_calls; 1866 } 1867 1868 /// Sets whether executing code in this process is possible. This could be 1869 /// either through JIT or interpreting. 1870 /// 1871 /// \param[in] can_run_code 1872 /// True if execution of code is possible; false otherwise. 1873 void SetCanRunCode(bool can_run_code); 1874 1875 /// Actually deallocate memory in the process. 1876 /// 1877 /// This function will deallocate memory in the process's address space that 1878 /// was allocated with AllocateMemory. 1879 /// 1880 /// \param[in] ptr 1881 /// A return value from AllocateMemory, pointing to the memory you 1882 /// want to deallocate. 1883 /// 1884 /// \return 1885 /// \b true if the memory was deallocated, \b false otherwise. 1886 virtual Status DoDeallocateMemory(lldb::addr_t ptr) { 1887 Status error; 1888 error.SetErrorStringWithFormatv( 1889 "error: {0} does not support deallocating in the debug process", 1890 GetPluginName()); 1891 return error; 1892 } 1893 1894 /// The public interface to deallocating memory in the process. 1895 /// 1896 /// This function will deallocate memory in the process's address space that 1897 /// was allocated with AllocateMemory. 1898 /// 1899 /// \param[in] ptr 1900 /// A return value from AllocateMemory, pointing to the memory you 1901 /// want to deallocate. 1902 /// 1903 /// \return 1904 /// \b true if the memory was deallocated, \b false otherwise. 1905 Status DeallocateMemory(lldb::addr_t ptr); 1906 1907 /// Get any available STDOUT. 1908 /// 1909 /// Calling this method is a valid operation only if all of the following 1910 /// conditions are true: 1) The process was launched, and not attached to. 1911 /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The 1912 /// process was launched without supplying a valid file path 1913 /// for STDOUT. 1914 /// 1915 /// Note that the implementation will probably need to start a read thread 1916 /// in the background to make sure that the pipe is drained and the STDOUT 1917 /// buffered appropriately, to prevent the process from deadlocking trying 1918 /// to write to a full buffer. 1919 /// 1920 /// Events will be queued indicating that there is STDOUT available that can 1921 /// be retrieved using this function. 1922 /// 1923 /// \param[out] buf 1924 /// A buffer that will receive any STDOUT bytes that are 1925 /// currently available. 1926 /// 1927 /// \param[in] buf_size 1928 /// The size in bytes for the buffer \a buf. 1929 /// 1930 /// \return 1931 /// The number of bytes written into \a buf. If this value is 1932 /// equal to \a buf_size, another call to this function should 1933 /// be made to retrieve more STDOUT data. 1934 virtual size_t GetSTDOUT(char *buf, size_t buf_size, Status &error); 1935 1936 /// Get any available STDERR. 1937 /// 1938 /// Calling this method is a valid operation only if all of the following 1939 /// conditions are true: 1) The process was launched, and not attached to. 1940 /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The 1941 /// process was launched without supplying a valid file path 1942 /// for STDERR. 1943 /// 1944 /// Note that the implementation will probably need to start a read thread 1945 /// in the background to make sure that the pipe is drained and the STDERR 1946 /// buffered appropriately, to prevent the process from deadlocking trying 1947 /// to write to a full buffer. 1948 /// 1949 /// Events will be queued indicating that there is STDERR available that can 1950 /// be retrieved using this function. 1951 /// 1952 /// \param[in] buf 1953 /// A buffer that will receive any STDERR bytes that are 1954 /// currently available. 1955 /// 1956 /// \param[out] buf_size 1957 /// The size in bytes for the buffer \a buf. 1958 /// 1959 /// \return 1960 /// The number of bytes written into \a buf. If this value is 1961 /// equal to \a buf_size, another call to this function should 1962 /// be made to retrieve more STDERR data. 1963 virtual size_t GetSTDERR(char *buf, size_t buf_size, Status &error); 1964 1965 /// Puts data into this process's STDIN. 1966 /// 1967 /// Calling this method is a valid operation only if all of the following 1968 /// conditions are true: 1) The process was launched, and not attached to. 1969 /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The 1970 /// process was launched without supplying a valid file path 1971 /// for STDIN. 1972 /// 1973 /// \param[in] buf 1974 /// A buffer that contains the data to write to the process's STDIN. 1975 /// 1976 /// \param[in] buf_size 1977 /// The size in bytes for the buffer \a buf. 1978 /// 1979 /// \return 1980 /// The number of bytes written into \a buf. If this value is 1981 /// less than \a buf_size, another call to this function should 1982 /// be made to write the rest of the data. 1983 virtual size_t PutSTDIN(const char *buf, size_t buf_size, Status &error) { 1984 error.SetErrorString("stdin unsupported"); 1985 return 0; 1986 } 1987 1988 /// Get any available profile data. 1989 /// 1990 /// \param[out] buf 1991 /// A buffer that will receive any profile data bytes that are 1992 /// currently available. 1993 /// 1994 /// \param[out] buf_size 1995 /// The size in bytes for the buffer \a buf. 1996 /// 1997 /// \return 1998 /// The number of bytes written into \a buf. If this value is 1999 /// equal to \a buf_size, another call to this function should 2000 /// be made to retrieve more profile data. 2001 virtual size_t GetAsyncProfileData(char *buf, size_t buf_size, Status &error); 2002 2003 // Process Breakpoints 2004 size_t GetSoftwareBreakpointTrapOpcode(BreakpointSite *bp_site); 2005 2006 virtual Status EnableBreakpointSite(BreakpointSite *bp_site) { 2007 Status error; 2008 error.SetErrorStringWithFormatv( 2009 "error: {0} does not support enabling breakpoints", GetPluginName()); 2010 return error; 2011 } 2012 2013 virtual Status DisableBreakpointSite(BreakpointSite *bp_site) { 2014 Status error; 2015 error.SetErrorStringWithFormatv( 2016 "error: {0} does not support disabling breakpoints", GetPluginName()); 2017 return error; 2018 } 2019 2020 // This is implemented completely using the lldb::Process API. Subclasses 2021 // don't need to implement this function unless the standard flow of read 2022 // existing opcode, write breakpoint opcode, verify breakpoint opcode doesn't 2023 // work for a specific process plug-in. 2024 virtual Status EnableSoftwareBreakpoint(BreakpointSite *bp_site); 2025 2026 // This is implemented completely using the lldb::Process API. Subclasses 2027 // don't need to implement this function unless the standard flow of 2028 // restoring original opcode in memory and verifying the restored opcode 2029 // doesn't work for a specific process plug-in. 2030 virtual Status DisableSoftwareBreakpoint(BreakpointSite *bp_site); 2031 2032 BreakpointSiteList &GetBreakpointSiteList(); 2033 2034 const BreakpointSiteList &GetBreakpointSiteList() const; 2035 2036 void DisableAllBreakpointSites(); 2037 2038 Status ClearBreakpointSiteByID(lldb::user_id_t break_id); 2039 2040 lldb::break_id_t CreateBreakpointSite(const lldb::BreakpointLocationSP &owner, 2041 bool use_hardware); 2042 2043 Status DisableBreakpointSiteByID(lldb::user_id_t break_id); 2044 2045 Status EnableBreakpointSiteByID(lldb::user_id_t break_id); 2046 2047 // BreakpointLocations use RemoveOwnerFromBreakpointSite to remove themselves 2048 // from the owner's list of this breakpoint sites. 2049 void RemoveOwnerFromBreakpointSite(lldb::user_id_t owner_id, 2050 lldb::user_id_t owner_loc_id, 2051 lldb::BreakpointSiteSP &bp_site_sp); 2052 2053 // Process Watchpoints (optional) 2054 virtual Status EnableWatchpoint(Watchpoint *wp, bool notify = true); 2055 2056 virtual Status DisableWatchpoint(Watchpoint *wp, bool notify = true); 2057 2058 // Thread Queries 2059 2060 /// Update the thread list. 2061 /// 2062 /// This method performs some general clean up before invoking 2063 /// \a DoUpdateThreadList, which should be implemented by each 2064 /// process plugin. 2065 /// 2066 /// \return 2067 /// \b true if the new thread list could be generated, \b false otherwise. 2068 bool UpdateThreadList(ThreadList &old_thread_list, 2069 ThreadList &new_thread_list); 2070 2071 void UpdateThreadListIfNeeded(); 2072 2073 ThreadList &GetThreadList() { return m_thread_list; } 2074 2075 // When ExtendedBacktraces are requested, the HistoryThreads that are created 2076 // need an owner -- they're saved here in the Process. The threads in this 2077 // list are not iterated over - driver programs need to request the extended 2078 // backtrace calls starting from a root concrete thread one by one. 2079 ThreadList &GetExtendedThreadList() { return m_extended_thread_list; } 2080 2081 ThreadList::ThreadIterable Threads() { return m_thread_list.Threads(); } 2082 2083 uint32_t GetNextThreadIndexID(uint64_t thread_id); 2084 2085 lldb::ThreadSP CreateOSPluginThread(lldb::tid_t tid, lldb::addr_t context); 2086 2087 // Returns true if an index id has been assigned to a thread. 2088 bool HasAssignedIndexIDToThread(uint64_t sb_thread_id); 2089 2090 // Given a thread_id, it will assign a more reasonable index id for display 2091 // to the user. If the thread_id has previously been assigned, the same index 2092 // id will be used. 2093 uint32_t AssignIndexIDToThread(uint64_t thread_id); 2094 2095 // Queue Queries 2096 2097 void UpdateQueueListIfNeeded(); 2098 2099 QueueList &GetQueueList() { 2100 UpdateQueueListIfNeeded(); 2101 return m_queue_list; 2102 } 2103 2104 QueueList::QueueIterable Queues() { 2105 UpdateQueueListIfNeeded(); 2106 return m_queue_list.Queues(); 2107 } 2108 2109 // Event Handling 2110 lldb::StateType GetNextEvent(lldb::EventSP &event_sp); 2111 2112 // Returns the process state when it is stopped. If specified, event_sp_ptr 2113 // is set to the event which triggered the stop. If wait_always = false, and 2114 // the process is already stopped, this function returns immediately. If the 2115 // process is hijacked and use_run_lock is true (the default), then this 2116 // function releases the run lock after the stop. Setting use_run_lock to 2117 // false will avoid this behavior. 2118 lldb::StateType 2119 WaitForProcessToStop(const Timeout<std::micro> &timeout, 2120 lldb::EventSP *event_sp_ptr = nullptr, 2121 bool wait_always = true, 2122 lldb::ListenerSP hijack_listener = lldb::ListenerSP(), 2123 Stream *stream = nullptr, bool use_run_lock = true); 2124 2125 uint32_t GetIOHandlerID() const { return m_iohandler_sync.GetValue(); } 2126 2127 /// Waits for the process state to be running within a given msec timeout. 2128 /// 2129 /// The main purpose of this is to implement an interlock waiting for 2130 /// HandlePrivateEvent to push an IOHandler. 2131 /// 2132 /// \param[in] timeout 2133 /// The maximum time length to wait for the process to transition to the 2134 /// eStateRunning state. 2135 void SyncIOHandler(uint32_t iohandler_id, const Timeout<std::micro> &timeout); 2136 2137 lldb::StateType GetStateChangedEvents( 2138 lldb::EventSP &event_sp, const Timeout<std::micro> &timeout, 2139 lldb::ListenerSP 2140 hijack_listener); // Pass an empty ListenerSP to use builtin listener 2141 2142 /// Centralize the code that handles and prints descriptions for process 2143 /// state changes. 2144 /// 2145 /// \param[in] event_sp 2146 /// The process state changed event 2147 /// 2148 /// \param[in] stream 2149 /// The output stream to get the state change description 2150 /// 2151 /// \param[in,out] pop_process_io_handler 2152 /// If this value comes in set to \b true, then pop the Process IOHandler 2153 /// if needed. 2154 /// Else this variable will be set to \b true or \b false to indicate if 2155 /// the process 2156 /// needs to have its process IOHandler popped. 2157 /// 2158 /// \return 2159 /// \b true if the event describes a process state changed event, \b false 2160 /// otherwise. 2161 static bool HandleProcessStateChangedEvent(const lldb::EventSP &event_sp, 2162 Stream *stream, 2163 bool &pop_process_io_handler); 2164 2165 Event *PeekAtStateChangedEvents(); 2166 2167 class ProcessEventHijacker { 2168 public: 2169 ProcessEventHijacker(Process &process, lldb::ListenerSP listener_sp) 2170 : m_process(process) { 2171 m_process.HijackProcessEvents(std::move(listener_sp)); 2172 } 2173 2174 ~ProcessEventHijacker() { m_process.RestoreProcessEvents(); } 2175 2176 private: 2177 Process &m_process; 2178 }; 2179 2180 friend class ProcessEventHijacker; 2181 friend class ProcessProperties; 2182 /// If you need to ensure that you and only you will hear about some public 2183 /// event, then make a new listener, set to listen to process events, and 2184 /// then call this with that listener. Then you will have to wait on that 2185 /// listener explicitly for events (rather than using the GetNextEvent & 2186 /// WaitFor* calls above. Be sure to call RestoreProcessEvents when you are 2187 /// done. 2188 /// 2189 /// \param[in] listener_sp 2190 /// This is the new listener to whom all process events will be delivered. 2191 /// 2192 /// \return 2193 /// Returns \b true if the new listener could be installed, 2194 /// \b false otherwise. 2195 bool HijackProcessEvents(lldb::ListenerSP listener_sp); 2196 2197 /// Restores the process event broadcasting to its normal state. 2198 /// 2199 void RestoreProcessEvents(); 2200 2201 bool StateChangedIsHijackedForSynchronousResume(); 2202 2203 bool StateChangedIsExternallyHijacked(); 2204 2205 const lldb::ABISP &GetABI(); 2206 2207 OperatingSystem *GetOperatingSystem() { return m_os_up.get(); } 2208 2209 std::vector<LanguageRuntime *> GetLanguageRuntimes(); 2210 2211 LanguageRuntime *GetLanguageRuntime(lldb::LanguageType language); 2212 2213 bool IsPossibleDynamicValue(ValueObject &in_value); 2214 2215 bool IsRunning() const; 2216 2217 DynamicCheckerFunctions *GetDynamicCheckers() { 2218 return m_dynamic_checkers_up.get(); 2219 } 2220 2221 void SetDynamicCheckers(DynamicCheckerFunctions *dynamic_checkers); 2222 2223 /// Prune ThreadPlanStacks for unreported threads. 2224 /// 2225 /// \param[in] tid 2226 /// The tid whose Plan Stack we are seeking to prune. 2227 /// 2228 /// \return 2229 /// \b true if the TID is found or \b false if not. 2230 bool PruneThreadPlansForTID(lldb::tid_t tid); 2231 2232 /// Prune ThreadPlanStacks for all unreported threads. 2233 void PruneThreadPlans(); 2234 2235 /// Find the thread plan stack associated with thread with \a tid. 2236 /// 2237 /// \param[in] tid 2238 /// The tid whose Plan Stack we are seeking. 2239 /// 2240 /// \return 2241 /// Returns a ThreadPlan if the TID is found or nullptr if not. 2242 ThreadPlanStack *FindThreadPlans(lldb::tid_t tid); 2243 2244 /// Dump the thread plans associated with thread with \a tid. 2245 /// 2246 /// \param[in,out] strm 2247 /// The stream to which to dump the output 2248 /// 2249 /// \param[in] tid 2250 /// The tid whose Plan Stack we are dumping 2251 /// 2252 /// \param[in] desc_level 2253 /// How much detail to dump 2254 /// 2255 /// \param[in] internal 2256 /// If \b true dump all plans, if false only user initiated plans 2257 /// 2258 /// \param[in] condense_trivial 2259 /// If true, only dump a header if the plan stack is just the base plan. 2260 /// 2261 /// \param[in] skip_unreported_plans 2262 /// If true, only dump a plan if it is currently backed by an 2263 /// lldb_private::Thread *. 2264 /// 2265 /// \return 2266 /// Returns \b true if TID was found, \b false otherwise 2267 bool DumpThreadPlansForTID(Stream &strm, lldb::tid_t tid, 2268 lldb::DescriptionLevel desc_level, bool internal, 2269 bool condense_trivial, bool skip_unreported_plans); 2270 2271 /// Dump all the thread plans for this process. 2272 /// 2273 /// \param[in,out] strm 2274 /// The stream to which to dump the output 2275 /// 2276 /// \param[in] desc_level 2277 /// How much detail to dump 2278 /// 2279 /// \param[in] internal 2280 /// If \b true dump all plans, if false only user initiated plans 2281 /// 2282 /// \param[in] condense_trivial 2283 /// If true, only dump a header if the plan stack is just the base plan. 2284 /// 2285 /// \param[in] skip_unreported_plans 2286 /// If true, skip printing all thread plan stacks that don't currently 2287 /// have a backing lldb_private::Thread *. 2288 void DumpThreadPlans(Stream &strm, lldb::DescriptionLevel desc_level, 2289 bool internal, bool condense_trivial, 2290 bool skip_unreported_plans); 2291 2292 /// Call this to set the lldb in the mode where it breaks on new thread 2293 /// creations, and then auto-restarts. This is useful when you are trying 2294 /// to run only one thread, but either that thread or the kernel is creating 2295 /// new threads in the process. If you stop when the thread is created, you 2296 /// can immediately suspend it, and keep executing only the one thread you 2297 /// intend. 2298 /// 2299 /// \return 2300 /// Returns \b true if we were able to start up the notification 2301 /// \b false otherwise. 2302 virtual bool StartNoticingNewThreads() { return true; } 2303 2304 /// Call this to turn off the stop & notice new threads mode. 2305 /// 2306 /// \return 2307 /// Returns \b true if we were able to start up the notification 2308 /// \b false otherwise. 2309 virtual bool StopNoticingNewThreads() { return true; } 2310 2311 void SetRunningUserExpression(bool on); 2312 void SetRunningUtilityFunction(bool on); 2313 2314 // lldb::ExecutionContextScope pure virtual functions 2315 lldb::TargetSP CalculateTarget() override; 2316 2317 lldb::ProcessSP CalculateProcess() override { return shared_from_this(); } 2318 2319 lldb::ThreadSP CalculateThread() override { return lldb::ThreadSP(); } 2320 2321 lldb::StackFrameSP CalculateStackFrame() override { 2322 return lldb::StackFrameSP(); 2323 } 2324 2325 void CalculateExecutionContext(ExecutionContext &exe_ctx) override; 2326 2327 void SetSTDIOFileDescriptor(int file_descriptor); 2328 2329 // Add a permanent region of memory that should never be read or written to. 2330 // This can be used to ensure that memory reads or writes to certain areas of 2331 // memory never end up being sent to the DoReadMemory or DoWriteMemory 2332 // functions which can improve performance. 2333 void AddInvalidMemoryRegion(const LoadRange ®ion); 2334 2335 // Remove a permanent region of memory that should never be read or written 2336 // to that was previously added with AddInvalidMemoryRegion. 2337 bool RemoveInvalidMemoryRange(const LoadRange ®ion); 2338 2339 // If the setup code of a thread plan needs to do work that might involve 2340 // calling a function in the target, it should not do that work directly in 2341 // one of the thread plan functions (DidPush/WillResume) because such work 2342 // needs to be handled carefully. Instead, put that work in a 2343 // PreResumeAction callback, and register it with the process. It will get 2344 // done before the actual "DoResume" gets called. 2345 2346 typedef bool(PreResumeActionCallback)(void *); 2347 2348 void AddPreResumeAction(PreResumeActionCallback callback, void *baton); 2349 2350 bool RunPreResumeActions(); 2351 2352 void ClearPreResumeActions(); 2353 2354 void ClearPreResumeAction(PreResumeActionCallback callback, void *baton); 2355 2356 ProcessRunLock &GetRunLock(); 2357 2358 bool CurrentThreadIsPrivateStateThread(); 2359 2360 virtual Status SendEventData(const char *data) { 2361 Status return_error("Sending an event is not supported for this process."); 2362 return return_error; 2363 } 2364 2365 lldb::ThreadCollectionSP GetHistoryThreads(lldb::addr_t addr); 2366 2367 lldb::InstrumentationRuntimeSP 2368 GetInstrumentationRuntime(lldb::InstrumentationRuntimeType type); 2369 2370 /// Try to fetch the module specification for a module with the given file 2371 /// name and architecture. Process sub-classes have to override this method 2372 /// if they support platforms where the Platform object can't get the module 2373 /// spec for all module. 2374 /// 2375 /// \param[in] module_file_spec 2376 /// The file name of the module to get specification for. 2377 /// 2378 /// \param[in] arch 2379 /// The architecture of the module to get specification for. 2380 /// 2381 /// \param[out] module_spec 2382 /// The fetched module specification if the return value is 2383 /// \b true, unchanged otherwise. 2384 /// 2385 /// \return 2386 /// Returns \b true if the module spec fetched successfully, 2387 /// \b false otherwise. 2388 virtual bool GetModuleSpec(const FileSpec &module_file_spec, 2389 const ArchSpec &arch, ModuleSpec &module_spec); 2390 2391 virtual void PrefetchModuleSpecs(llvm::ArrayRef<FileSpec> module_file_specs, 2392 const llvm::Triple &triple) {} 2393 2394 /// Try to find the load address of a file. 2395 /// The load address is defined as the address of the first memory region 2396 /// what contains data mapped from the specified file. 2397 /// 2398 /// \param[in] file 2399 /// The name of the file whose load address we are looking for 2400 /// 2401 /// \param[out] is_loaded 2402 /// \b True if the file is loaded into the memory and false 2403 /// otherwise. 2404 /// 2405 /// \param[out] load_addr 2406 /// The load address of the file if it is loaded into the 2407 /// processes address space, LLDB_INVALID_ADDRESS otherwise. 2408 virtual Status GetFileLoadAddress(const FileSpec &file, bool &is_loaded, 2409 lldb::addr_t &load_addr) { 2410 return Status("Not supported"); 2411 } 2412 2413 size_t AddImageToken(lldb::addr_t image_ptr); 2414 2415 lldb::addr_t GetImagePtrFromToken(size_t token) const; 2416 2417 void ResetImageToken(size_t token); 2418 2419 /// Find the next branch instruction to set a breakpoint on 2420 /// 2421 /// When instruction stepping through a source line, instead of stepping 2422 /// through each instruction, we can put a breakpoint on the next branch 2423 /// instruction (within the range of instructions we are stepping through) 2424 /// and continue the process to there, yielding significant performance 2425 /// benefits over instruction stepping. 2426 /// 2427 /// \param[in] default_stop_addr 2428 /// The address of the instruction where lldb would put a 2429 /// breakpoint normally. 2430 /// 2431 /// \param[in] range_bounds 2432 /// The range which the breakpoint must be contained within. 2433 /// Typically a source line. 2434 /// 2435 /// \return 2436 /// The address of the next branch instruction, or the end of 2437 /// the range provided in range_bounds. If there are any 2438 /// problems with the disassembly or getting the instructions, 2439 /// the original default_stop_addr will be returned. 2440 Address AdvanceAddressToNextBranchInstruction(Address default_stop_addr, 2441 AddressRange range_bounds); 2442 2443 /// Configure asynchronous structured data feature. 2444 /// 2445 /// Each Process type that supports using an asynchronous StructuredData 2446 /// feature should implement this to enable/disable/configure the feature. 2447 /// The default implementation here will always return an error indiciating 2448 /// the feature is unsupported. 2449 /// 2450 /// StructuredDataPlugin implementations will call this to configure a 2451 /// feature that has been reported as being supported. 2452 /// 2453 /// \param[in] type_name 2454 /// The StructuredData type name as previously discovered by 2455 /// the Process-derived instance. 2456 /// 2457 /// \param[in] config_sp 2458 /// Configuration data for the feature being enabled. This config 2459 /// data, which may be null, will be passed along to the feature 2460 /// to process. The feature will dictate whether this is a dictionary, 2461 /// an array or some other object. If the feature needs to be 2462 /// set up properly before it can be enabled, then the config should 2463 /// also take an enable/disable flag. 2464 /// 2465 /// \return 2466 /// Returns the result of attempting to configure the feature. 2467 virtual Status 2468 ConfigureStructuredData(ConstString type_name, 2469 const StructuredData::ObjectSP &config_sp); 2470 2471 /// Broadcasts the given structured data object from the given plugin. 2472 /// 2473 /// StructuredDataPlugin instances can use this to optionally broadcast any 2474 /// of their data if they want to make it available for clients. The data 2475 /// will come in on the structured data event bit 2476 /// (eBroadcastBitStructuredData). 2477 /// 2478 /// \param[in] object_sp 2479 /// The structured data object to broadcast. 2480 /// 2481 /// \param[in] plugin_sp 2482 /// The plugin that will be reported in the event's plugin 2483 /// parameter. 2484 void BroadcastStructuredData(const StructuredData::ObjectSP &object_sp, 2485 const lldb::StructuredDataPluginSP &plugin_sp); 2486 2487 /// Returns the StructuredDataPlugin associated with a given type name, if 2488 /// there is one. 2489 /// 2490 /// There will only be a plugin for a given StructuredDataType if the 2491 /// debugged process monitor claims that the feature is supported. This is 2492 /// one way to tell whether a feature is available. 2493 /// 2494 /// \return 2495 /// The plugin if one is available for the specified feature; 2496 /// otherwise, returns an empty shared pointer. 2497 lldb::StructuredDataPluginSP 2498 GetStructuredDataPlugin(ConstString type_name) const; 2499 2500 protected: 2501 friend class Trace; 2502 /// Get the processor tracing type supported for this process. 2503 /// Responses might be different depending on the architecture and 2504 /// capabilities of the underlying OS. 2505 /// 2506 /// \return 2507 /// The supported trace type or an \a llvm::Error if tracing is 2508 /// not supported for the inferior. 2509 virtual llvm::Expected<TraceSupportedResponse> TraceSupported(); 2510 2511 /// Start tracing a process or its threads. 2512 /// 2513 /// \param[in] request 2514 /// JSON object with the information necessary to start tracing. In the 2515 /// case of gdb-remote processes, this JSON object should conform to the 2516 /// jLLDBTraceStart packet. 2517 /// 2518 /// \return 2519 /// \a llvm::Error::success if the operation was successful, or 2520 /// \a llvm::Error otherwise. 2521 virtual llvm::Error TraceStart(const llvm::json::Value &request) { 2522 return llvm::make_error<UnimplementedError>(); 2523 } 2524 2525 /// Stop tracing a live process or its threads. 2526 /// 2527 /// \param[in] request 2528 /// The information determining which threads or process to stop tracing. 2529 /// 2530 /// \return 2531 /// \a llvm::Error::success if the operation was successful, or 2532 /// \a llvm::Error otherwise. 2533 virtual llvm::Error TraceStop(const TraceStopRequest &request) { 2534 return llvm::make_error<UnimplementedError>(); 2535 } 2536 2537 /// Get the current tracing state of the process and its threads. 2538 /// 2539 /// \param[in] type 2540 /// Tracing technology type to consider. 2541 /// 2542 /// \return 2543 /// A JSON object string with custom data depending on the trace 2544 /// technology, or an \a llvm::Error in case of errors. 2545 virtual llvm::Expected<std::string> TraceGetState(llvm::StringRef type) { 2546 return llvm::make_error<UnimplementedError>(); 2547 } 2548 2549 /// Get binary data given a trace technology and a data identifier. 2550 /// 2551 /// \param[in] request 2552 /// Object with the params of the requested data. 2553 /// 2554 /// \return 2555 /// A vector of bytes with the requested data, or an \a llvm::Error in 2556 /// case of failures. 2557 virtual llvm::Expected<std::vector<uint8_t>> 2558 TraceGetBinaryData(const TraceGetBinaryDataRequest &request) { 2559 return llvm::make_error<UnimplementedError>(); 2560 } 2561 2562 // This calls a function of the form "void * (*)(void)". 2563 bool CallVoidArgVoidPtrReturn(const Address *address, 2564 lldb::addr_t &returned_func, 2565 bool trap_exceptions = false); 2566 2567 /// Update the thread list following process plug-in's specific logic. 2568 /// 2569 /// This method should only be invoked by \a UpdateThreadList. 2570 /// 2571 /// \return 2572 /// \b true if the new thread list could be generated, \b false otherwise. 2573 virtual bool DoUpdateThreadList(ThreadList &old_thread_list, 2574 ThreadList &new_thread_list) = 0; 2575 2576 /// Actually do the reading of memory from a process. 2577 /// 2578 /// Subclasses must override this function and can return fewer bytes than 2579 /// requested when memory requests are too large. This class will break up 2580 /// the memory requests and keep advancing the arguments along as needed. 2581 /// 2582 /// \param[in] vm_addr 2583 /// A virtual load address that indicates where to start reading 2584 /// memory from. 2585 /// 2586 /// \param[in] size 2587 /// The number of bytes to read. 2588 /// 2589 /// \param[out] buf 2590 /// A byte buffer that is at least \a size bytes long that 2591 /// will receive the memory bytes. 2592 /// 2593 /// \param[out] error 2594 /// An error that indicates the success or failure of this 2595 /// operation. If error indicates success (error.Success()), 2596 /// then the value returned can be trusted, otherwise zero 2597 /// will be returned. 2598 /// 2599 /// \return 2600 /// The number of bytes that were actually read into \a buf. 2601 /// Zero is returned in the case of an error. 2602 virtual size_t DoReadMemory(lldb::addr_t vm_addr, void *buf, size_t size, 2603 Status &error) = 0; 2604 2605 /// DoGetMemoryRegionInfo is called by GetMemoryRegionInfo after it has 2606 /// removed non address bits from load_addr. Override this method in 2607 /// subclasses of Process. 2608 /// 2609 /// See GetMemoryRegionInfo for details of the logic. 2610 /// 2611 /// \param[in] load_addr 2612 /// The load address to query the range_info for. (non address bits 2613 /// removed) 2614 /// 2615 /// \param[out] range_info 2616 /// An range_info value containing the details of the range. 2617 /// 2618 /// \return 2619 /// An error value. 2620 virtual Status DoGetMemoryRegionInfo(lldb::addr_t load_addr, 2621 MemoryRegionInfo &range_info) { 2622 return Status("Process::DoGetMemoryRegionInfo() not supported"); 2623 } 2624 2625 lldb::StateType GetPrivateState(); 2626 2627 /// The "private" side of resuming a process. This doesn't alter the state 2628 /// of m_run_lock, but just causes the process to resume. 2629 /// 2630 /// \return 2631 /// An Status object describing the success or failure of the resume. 2632 Status PrivateResume(); 2633 2634 // Called internally 2635 void CompleteAttach(); 2636 2637 // NextEventAction provides a way to register an action on the next event 2638 // that is delivered to this process. There is currently only one next event 2639 // action allowed in the process at one time. If a new "NextEventAction" is 2640 // added while one is already present, the old action will be discarded (with 2641 // HandleBeingUnshipped called after it is discarded.) 2642 // 2643 // If you want to resume the process as a result of a resume action, call 2644 // RequestResume, don't call Resume directly. 2645 class NextEventAction { 2646 public: 2647 enum EventActionResult { 2648 eEventActionSuccess, 2649 eEventActionRetry, 2650 eEventActionExit 2651 }; 2652 2653 NextEventAction(Process *process) : m_process(process) {} 2654 2655 virtual ~NextEventAction() = default; 2656 2657 virtual EventActionResult PerformAction(lldb::EventSP &event_sp) = 0; 2658 virtual void HandleBeingUnshipped() {} 2659 virtual EventActionResult HandleBeingInterrupted() = 0; 2660 virtual const char *GetExitString() = 0; 2661 void RequestResume() { m_process->m_resume_requested = true; } 2662 2663 protected: 2664 Process *m_process; 2665 }; 2666 2667 void SetNextEventAction(Process::NextEventAction *next_event_action) { 2668 if (m_next_event_action_up.get()) 2669 m_next_event_action_up->HandleBeingUnshipped(); 2670 2671 m_next_event_action_up.reset(next_event_action); 2672 } 2673 2674 // This is the completer for Attaching: 2675 class AttachCompletionHandler : public NextEventAction { 2676 public: 2677 AttachCompletionHandler(Process *process, uint32_t exec_count); 2678 2679 ~AttachCompletionHandler() override = default; 2680 2681 EventActionResult PerformAction(lldb::EventSP &event_sp) override; 2682 EventActionResult HandleBeingInterrupted() override; 2683 const char *GetExitString() override; 2684 2685 private: 2686 uint32_t m_exec_count; 2687 std::string m_exit_string; 2688 }; 2689 2690 bool PrivateStateThreadIsValid() const { 2691 lldb::StateType state = m_private_state.GetValue(); 2692 return state != lldb::eStateInvalid && state != lldb::eStateDetached && 2693 state != lldb::eStateExited && m_private_state_thread.IsJoinable(); 2694 } 2695 2696 void ForceNextEventDelivery() { m_force_next_event_delivery = true; } 2697 2698 /// Loads any plugins associated with asynchronous structured data and maps 2699 /// the relevant supported type name to the plugin. 2700 /// 2701 /// Processes can receive asynchronous structured data from the process 2702 /// monitor. This method will load and map any structured data plugins that 2703 /// support the given set of supported type names. Later, if any of these 2704 /// features are enabled, the process monitor is free to generate 2705 /// asynchronous structured data. The data must come in as a single \b 2706 /// StructuredData::Dictionary. That dictionary must have a string field 2707 /// named 'type', with a value that equals the relevant type name string 2708 /// (one of the values in \b supported_type_names). 2709 /// 2710 /// \param[in] supported_type_names 2711 /// An array of zero or more type names. Each must be unique. 2712 /// For each entry in the list, a StructuredDataPlugin will be 2713 /// searched for that supports the structured data type name. 2714 void MapSupportedStructuredDataPlugins( 2715 const StructuredData::Array &supported_type_names); 2716 2717 /// Route the incoming structured data dictionary to the right plugin. 2718 /// 2719 /// The incoming structured data must be a dictionary, and it must have a 2720 /// key named 'type' that stores a string value. The string value must be 2721 /// the name of the structured data feature that knows how to handle it. 2722 /// 2723 /// \param[in] object_sp 2724 /// When non-null and pointing to a dictionary, the 'type' 2725 /// key's string value is used to look up the plugin that 2726 /// was registered for that structured data type. It then 2727 /// calls the following method on the StructuredDataPlugin 2728 /// instance: 2729 /// 2730 /// virtual void 2731 /// HandleArrivalOfStructuredData(Process &process, 2732 /// ConstString type_name, 2733 /// const StructuredData::ObjectSP 2734 /// &object_sp) 2735 /// 2736 /// \return 2737 /// True if the structured data was routed to a plugin; otherwise, 2738 /// false. 2739 bool RouteAsyncStructuredData(const StructuredData::ObjectSP object_sp); 2740 2741 /// Check whether the process supports memory tagging. 2742 /// 2743 /// \return 2744 /// true if the process supports memory tagging, 2745 /// false otherwise. 2746 virtual bool SupportsMemoryTagging() { return false; } 2747 2748 /// Does the final operation to read memory tags. E.g. sending a GDB packet. 2749 /// It assumes that ReadMemoryTags has checked that memory tagging is enabled 2750 /// and has expanded the memory range as needed. 2751 /// 2752 /// \param[in] addr 2753 /// Start of address range to read memory tags for. 2754 /// 2755 /// \param[in] len 2756 /// Length of the memory range to read tags for (in bytes). 2757 /// 2758 /// \param[in] type 2759 /// Type of tags to read (get this from a MemoryTagManager) 2760 /// 2761 /// \return 2762 /// The packed tag data received from the remote or an error 2763 /// if the read failed. 2764 virtual llvm::Expected<std::vector<uint8_t>> 2765 DoReadMemoryTags(lldb::addr_t addr, size_t len, int32_t type) { 2766 return llvm::createStringError( 2767 llvm::inconvertibleErrorCode(), 2768 llvm::formatv("{0} does not support reading memory tags", 2769 GetPluginName())); 2770 } 2771 2772 /// Does the final operation to write memory tags. E.g. sending a GDB packet. 2773 /// It assumes that WriteMemoryTags has checked that memory tagging is enabled 2774 /// and has packed the tag data. 2775 /// 2776 /// \param[in] addr 2777 /// Start of address range to write memory tags for. 2778 /// 2779 /// \param[in] len 2780 /// Length of the memory range to write tags for (in bytes). 2781 /// 2782 /// \param[in] type 2783 /// Type of tags to read (get this from a MemoryTagManager) 2784 /// 2785 /// \param[in] tags 2786 /// Packed tags to be written. 2787 /// 2788 /// \return 2789 /// Status telling you whether the write succeeded. 2790 virtual Status DoWriteMemoryTags(lldb::addr_t addr, size_t len, int32_t type, 2791 const std::vector<uint8_t> &tags) { 2792 Status status; 2793 status.SetErrorStringWithFormatv("{0} does not support writing memory tags", 2794 GetPluginName()); 2795 return status; 2796 } 2797 2798 // Type definitions 2799 typedef std::map<lldb::LanguageType, lldb::LanguageRuntimeSP> 2800 LanguageRuntimeCollection; 2801 2802 struct PreResumeCallbackAndBaton { 2803 bool (*callback)(void *); 2804 void *baton; 2805 PreResumeCallbackAndBaton(PreResumeActionCallback in_callback, 2806 void *in_baton) 2807 : callback(in_callback), baton(in_baton) {} 2808 bool operator== (const PreResumeCallbackAndBaton &rhs) { 2809 return callback == rhs.callback && baton == rhs.baton; 2810 } 2811 }; 2812 2813 using StructuredDataPluginMap = 2814 std::map<ConstString, lldb::StructuredDataPluginSP>; 2815 2816 // Member variables 2817 std::weak_ptr<Target> m_target_wp; ///< The target that owns this process. 2818 lldb::pid_t m_pid = LLDB_INVALID_PROCESS_ID; 2819 ThreadSafeValue<lldb::StateType> m_public_state; 2820 ThreadSafeValue<lldb::StateType> 2821 m_private_state; // The actual state of our process 2822 Broadcaster m_private_state_broadcaster; // This broadcaster feeds state 2823 // changed events into the private 2824 // state thread's listener. 2825 Broadcaster m_private_state_control_broadcaster; // This is the control 2826 // broadcaster, used to 2827 // pause, resume & stop the 2828 // private state thread. 2829 lldb::ListenerSP m_private_state_listener_sp; // This is the listener for the 2830 // private state thread. 2831 HostThread m_private_state_thread; ///< Thread ID for the thread that watches 2832 ///internal state events 2833 ProcessModID m_mod_id; ///< Tracks the state of the process over stops and 2834 ///other alterations. 2835 uint32_t m_process_unique_id; ///< Each lldb_private::Process class that is 2836 ///created gets a unique integer ID that 2837 ///increments with each new instance 2838 uint32_t m_thread_index_id; ///< Each thread is created with a 1 based index 2839 ///that won't get re-used. 2840 std::map<uint64_t, uint32_t> m_thread_id_to_index_id_map; 2841 int m_exit_status; ///< The exit status of the process, or -1 if not set. 2842 std::string m_exit_string; ///< A textual description of why a process exited. 2843 std::mutex m_exit_status_mutex; ///< Mutex so m_exit_status m_exit_string can 2844 ///be safely accessed from multiple threads 2845 std::recursive_mutex m_thread_mutex; 2846 ThreadList m_thread_list_real; ///< The threads for this process as are known 2847 ///to the protocol we are debugging with 2848 ThreadList m_thread_list; ///< The threads for this process as the user will 2849 ///see them. This is usually the same as 2850 ///< m_thread_list_real, but might be different if there is an OS plug-in 2851 ///creating memory threads 2852 ThreadPlanStackMap m_thread_plans; ///< This is the list of thread plans for 2853 /// threads in m_thread_list, as well as 2854 /// threads we knew existed, but haven't 2855 /// determined that they have died yet. 2856 ThreadList m_extended_thread_list; ///< Owner for extended threads that may be 2857 ///generated, cleared on natural stops 2858 uint32_t m_extended_thread_stop_id; ///< The natural stop id when 2859 ///extended_thread_list was last updated 2860 QueueList 2861 m_queue_list; ///< The list of libdispatch queues at a given stop point 2862 uint32_t m_queue_list_stop_id; ///< The natural stop id when queue list was 2863 ///last fetched 2864 std::vector<Notifications> m_notifications; ///< The list of notifications 2865 ///that this process can deliver. 2866 std::vector<lldb::addr_t> m_image_tokens; 2867 lldb::ListenerSP m_listener_sp; ///< Shared pointer to the listener used for 2868 ///public events. Can not be empty. 2869 BreakpointSiteList m_breakpoint_site_list; ///< This is the list of breakpoint 2870 ///locations we intend to insert in 2871 ///the target. 2872 lldb::DynamicLoaderUP m_dyld_up; 2873 lldb::JITLoaderListUP m_jit_loaders_up; 2874 lldb::DynamicCheckerFunctionsUP m_dynamic_checkers_up; ///< The functions used 2875 /// by the expression 2876 /// parser to validate 2877 /// data that 2878 /// expressions use. 2879 lldb::OperatingSystemUP m_os_up; 2880 lldb::SystemRuntimeUP m_system_runtime_up; 2881 lldb::UnixSignalsSP 2882 m_unix_signals_sp; /// This is the current signal set for this process. 2883 lldb::ABISP m_abi_sp; 2884 lldb::IOHandlerSP m_process_input_reader; 2885 Communication m_stdio_communication; 2886 std::recursive_mutex m_stdio_communication_mutex; 2887 bool m_stdin_forward; /// Remember if stdin must be forwarded to remote debug 2888 /// server 2889 std::string m_stdout_data; 2890 std::string m_stderr_data; 2891 std::recursive_mutex m_profile_data_comm_mutex; 2892 std::vector<std::string> m_profile_data; 2893 Predicate<uint32_t> m_iohandler_sync; 2894 MemoryCache m_memory_cache; 2895 AllocatedMemoryCache m_allocated_memory_cache; 2896 bool m_should_detach; /// Should we detach if the process object goes away 2897 /// with an explicit call to Kill or Detach? 2898 LanguageRuntimeCollection m_language_runtimes; 2899 std::recursive_mutex m_language_runtimes_mutex; 2900 InstrumentationRuntimeCollection m_instrumentation_runtimes; 2901 std::unique_ptr<NextEventAction> m_next_event_action_up; 2902 std::vector<PreResumeCallbackAndBaton> m_pre_resume_actions; 2903 ProcessRunLock m_public_run_lock; 2904 ProcessRunLock m_private_run_lock; 2905 bool m_currently_handling_do_on_removals; 2906 bool m_resume_requested; // If m_currently_handling_event or 2907 // m_currently_handling_do_on_removals are true, 2908 // Resume will only request a resume, using this 2909 // flag to check. 2910 2911 /// This is set at the beginning of Process::Finalize() to stop functions 2912 /// from looking up or creating things during or after a finalize call. 2913 std::atomic<bool> m_finalizing; 2914 2915 /// Mask for code an data addresses. The default value (0) means no mask is 2916 /// set. The bits set to 1 indicate bits that are NOT significant for 2917 /// addressing. 2918 /// @{ 2919 lldb::addr_t m_code_address_mask = 0; 2920 lldb::addr_t m_data_address_mask = 0; 2921 /// @} 2922 2923 bool m_clear_thread_plans_on_stop; 2924 bool m_force_next_event_delivery; 2925 lldb::StateType m_last_broadcast_state; /// This helps with the Public event 2926 /// coalescing in 2927 /// ShouldBroadcastEvent. 2928 std::map<lldb::addr_t, lldb::addr_t> m_resolved_indirect_addresses; 2929 bool m_destroy_in_process; 2930 bool m_can_interpret_function_calls; // Some targets, e.g the OSX kernel, 2931 // don't support the ability to modify 2932 // the stack. 2933 std::mutex m_run_thread_plan_lock; 2934 StructuredDataPluginMap m_structured_data_plugin_map; 2935 2936 enum { eCanJITDontKnow = 0, eCanJITYes, eCanJITNo } m_can_jit; 2937 2938 std::unique_ptr<UtilityFunction> m_dlopen_utility_func_up; 2939 llvm::once_flag m_dlopen_utility_func_flag_once; 2940 2941 size_t RemoveBreakpointOpcodesFromBuffer(lldb::addr_t addr, size_t size, 2942 uint8_t *buf) const; 2943 2944 void SynchronouslyNotifyStateChanged(lldb::StateType state); 2945 2946 void SetPublicState(lldb::StateType new_state, bool restarted); 2947 2948 void SetPrivateState(lldb::StateType state); 2949 2950 bool StartPrivateStateThread(bool is_secondary_thread = false); 2951 2952 void StopPrivateStateThread(); 2953 2954 void PausePrivateStateThread(); 2955 2956 void ResumePrivateStateThread(); 2957 2958 private: 2959 // The starts up the private state thread that will watch for events from the 2960 // debugee. Pass true for is_secondary_thread in the case where you have to 2961 // temporarily spin up a secondary state thread to handle events from a hand- 2962 // called function on the primary private state thread. 2963 2964 lldb::thread_result_t RunPrivateStateThread(bool is_secondary_thread); 2965 2966 protected: 2967 void HandlePrivateEvent(lldb::EventSP &event_sp); 2968 2969 Status HaltPrivate(); 2970 2971 lldb::StateType WaitForProcessStopPrivate(lldb::EventSP &event_sp, 2972 const Timeout<std::micro> &timeout); 2973 2974 // This waits for both the state change broadcaster, and the control 2975 // broadcaster. If control_only, it only waits for the control broadcaster. 2976 2977 bool GetEventsPrivate(lldb::EventSP &event_sp, 2978 const Timeout<std::micro> &timeout, bool control_only); 2979 2980 lldb::StateType 2981 GetStateChangedEventsPrivate(lldb::EventSP &event_sp, 2982 const Timeout<std::micro> &timeout); 2983 2984 size_t WriteMemoryPrivate(lldb::addr_t addr, const void *buf, size_t size, 2985 Status &error); 2986 2987 void AppendSTDOUT(const char *s, size_t len); 2988 2989 void AppendSTDERR(const char *s, size_t len); 2990 2991 void BroadcastAsyncProfileData(const std::string &one_profile_data); 2992 2993 static void STDIOReadThreadBytesReceived(void *baton, const void *src, 2994 size_t src_len); 2995 2996 bool PushProcessIOHandler(); 2997 2998 bool PopProcessIOHandler(); 2999 3000 bool ProcessIOHandlerIsActive(); 3001 3002 bool ProcessIOHandlerExists() const { 3003 return static_cast<bool>(m_process_input_reader); 3004 } 3005 3006 Status StopForDestroyOrDetach(lldb::EventSP &exit_event_sp); 3007 3008 virtual Status UpdateAutomaticSignalFiltering(); 3009 3010 void LoadOperatingSystemPlugin(bool flush); 3011 3012 private: 3013 Status DestroyImpl(bool force_kill); 3014 3015 /// This is the part of the event handling that for a process event. It 3016 /// decides what to do with the event and returns true if the event needs to 3017 /// be propagated to the user, and false otherwise. If the event is not 3018 /// propagated, this call will most likely set the target to executing 3019 /// again. There is only one place where this call should be called, 3020 /// HandlePrivateEvent. Don't call it from anywhere else... 3021 /// 3022 /// \param[in] event_ptr 3023 /// This is the event we are handling. 3024 /// 3025 /// \return 3026 /// Returns \b true if the event should be reported to the 3027 /// user, \b false otherwise. 3028 bool ShouldBroadcastEvent(Event *event_ptr); 3029 3030 void ControlPrivateStateThread(uint32_t signal); 3031 3032 Status LaunchPrivate(ProcessLaunchInfo &launch_info, lldb::StateType &state, 3033 lldb::EventSP &event_sp); 3034 3035 Process(const Process &) = delete; 3036 const Process &operator=(const Process &) = delete; 3037 }; 3038 3039 /// RAII guard that should be acquired when an utility function is called within 3040 /// a given process. 3041 class UtilityFunctionScope { 3042 Process *m_process; 3043 3044 public: 3045 UtilityFunctionScope(Process *p) : m_process(p) { 3046 if (m_process) 3047 m_process->SetRunningUtilityFunction(true); 3048 } 3049 ~UtilityFunctionScope() { 3050 if (m_process) 3051 m_process->SetRunningUtilityFunction(false); 3052 } 3053 }; 3054 3055 } // namespace lldb_private 3056 3057 #endif // LLDB_TARGET_PROCESS_H 3058