//===-- Process.h -----------------------------------------------*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

#ifndef LLDB_TARGET_PROCESS_H

#define LLDB_TARGET_PROCESS_H

#include "lldb/Host/Config.h"

#include <climits>

#include <chrono>

#include <list>

#include <memory>

#include <mutex>

#include <optional>

#include <string>

#include <unordered_set>

#include <vector>

#include "lldb/Breakpoint/BreakpointSiteList.h"

#include "lldb/Core/LoadedModuleInfoList.h"

#include "lldb/Core/PluginInterface.h"

#include "lldb/Core/SourceManager.h"

#include "lldb/Core/ThreadSafeValue.h"

#include "lldb/Core/ThreadedCommunication.h"

#include "lldb/Core/UserSettingsController.h"

#include "lldb/Host/HostThread.h"

#include "lldb/Host/ProcessLaunchInfo.h"

#include "lldb/Host/ProcessRunLock.h"

#include "lldb/Symbol/ObjectFile.h"

#include "lldb/Target/ExecutionContextScope.h"

#include "lldb/Target/InstrumentationRuntime.h"

#include "lldb/Target/Memory.h"

#include "lldb/Target/MemoryTagManager.h"

#include "lldb/Target/QueueList.h"

#include "lldb/Target/ThreadList.h"

#include "lldb/Target/ThreadPlanStack.h"

#include "lldb/Target/Trace.h"

#include "lldb/Utility/ArchSpec.h"

#include "lldb/Utility/Broadcaster.h"

#include "lldb/Utility/Event.h"

#include "lldb/Utility/Listener.h"

#include "lldb/Utility/NameMatches.h"

#include "lldb/Utility/ProcessInfo.h"

#include "lldb/Utility/Status.h"

#include "lldb/Utility/StructuredData.h"

#include "lldb/Utility/TraceGDBRemotePackets.h"

#include "lldb/Utility/UnimplementedError.h"

#include "lldb/Utility/UserIDResolver.h"

#include "lldb/lldb-private.h"

#include "llvm/ADT/ArrayRef.h"

#include "llvm/Support/Threading.h"

#include "llvm/Support/VersionTuple.h"

namespace lldb_private {

template <typename B, typename S> struct Range;

class ProcessExperimentalProperties : public Properties {

public:

  ProcessExperimentalProperties();

};

class ProcessProperties : public Properties {

public:

  // Pass nullptr for "process" if the ProcessProperties are to be the global

  // copy

  ProcessProperties(lldb_private::Process *process);

  ~ProcessProperties() override;

  bool GetDisableMemoryCache() const;

  uint64_t GetMemoryCacheLineSize() const;

  Args GetExtraStartupCommands() const;

  void SetExtraStartupCommands(const Args &args);

  FileSpec GetPythonOSPluginPath() const;

  uint32_t GetVirtualAddressableBits() const;

  void SetVirtualAddressableBits(uint32_t bits);

  uint32_t GetHighmemVirtualAddressableBits() const;

  void SetHighmemVirtualAddressableBits(uint32_t bits);

  void SetPythonOSPluginPath(const FileSpec &file);

  bool GetIgnoreBreakpointsInExpressions() const;

  void SetIgnoreBreakpointsInExpressions(bool ignore);

  bool GetUnwindOnErrorInExpressions() const;

  void SetUnwindOnErrorInExpressions(bool ignore);

  bool GetStopOnSharedLibraryEvents() const;

  void SetStopOnSharedLibraryEvents(bool stop);

  bool GetDisableLangRuntimeUnwindPlans() const;

  void SetDisableLangRuntimeUnwindPlans(bool disable);

  bool GetDetachKeepsStopped() const;

  void SetDetachKeepsStopped(bool keep_stopped);

  bool GetWarningsOptimization() const;

  bool GetWarningsUnsupportedLanguage() const;

  bool GetStopOnExec() const;

  std::chrono::seconds GetUtilityExpressionTimeout() const;

  std::chrono::seconds GetInterruptTimeout() const;

  bool GetOSPluginReportsAllThreads() const;

  void SetOSPluginReportsAllThreads(bool does_report);

  bool GetSteppingRunsAllThreads() const;

  FollowForkMode GetFollowForkMode() const;

protected:

  Process *m_process; // Can be nullptr for global ProcessProperties

  std::unique_ptr<ProcessExperimentalProperties> m_experimental_properties_up;

};

// ProcessAttachInfo

//

// Describes any information that is required to attach to a process.

class ProcessAttachInfo : public ProcessInstanceInfo {

public:

  ProcessAttachInfo() = default;

  ProcessAttachInfo(const ProcessLaunchInfo &launch_info)

      : m_resume_count(0), m_wait_for_launch(false), m_ignore_existing(true),

        m_continue_once_attached(false), m_detach_on_error(true),

        m_async(false) {

    ProcessInfo::operator=(launch_info);

    SetProcessPluginName(launch_info.GetProcessPluginName());

    SetResumeCount(launch_info.GetResumeCount());

    m_detach_on_error = launch_info.GetDetachOnError();

  }

  bool GetWaitForLaunch() const { return m_wait_for_launch; }

  void SetWaitForLaunch(bool b) { m_wait_for_launch = b; }

  bool GetAsync() const { return m_async; }

  void SetAsync(bool b) { m_async = b; }

  bool GetIgnoreExisting() const { return m_ignore_existing; }

  void SetIgnoreExisting(bool b) { m_ignore_existing = b; }

  bool GetContinueOnceAttached() const { return m_continue_once_attached; }

  void SetContinueOnceAttached(bool b) { m_continue_once_attached = b; }

  uint32_t GetResumeCount() const { return m_resume_count; }

  void SetResumeCount(uint32_t c) { m_resume_count = c; }

  llvm::StringRef GetProcessPluginName() const {

    return llvm::StringRef(m_plugin_name);

  }

  void SetProcessPluginName(llvm::StringRef plugin) {

    m_plugin_name = std::string(plugin);

  }

  void Clear() {

    ProcessInstanceInfo::Clear();

    m_plugin_name.clear();

    m_resume_count = 0;

    m_wait_for_launch = false;

    m_ignore_existing = true;

    m_continue_once_attached = false;

  }

  bool ProcessInfoSpecified() const {

    if (GetExecutableFile())

      return true;

    if (GetProcessID() != LLDB_INVALID_PROCESS_ID)

      return true;

    if (GetParentProcessID() != LLDB_INVALID_PROCESS_ID)

      return true;

    return false;

  }

  bool GetDetachOnError() const { return m_detach_on_error; }

  void SetDetachOnError(bool enable) { m_detach_on_error = enable; }

  lldb::ListenerSP GetListenerForProcess(Debugger &debugger);

protected:

  std::string m_plugin_name;

  uint32_t m_resume_count = 0; // How many times do we resume after launching

  bool m_wait_for_launch = false;

  bool m_ignore_existing = true;

  bool m_continue_once_attached = false; // Supports the use-case scenario of

                                         // immediately continuing the process

                                         // once attached.

  bool m_detach_on_error =

      true; // If we are debugging remotely, instruct the stub to

            // detach rather than killing the target on error.

  bool m_async =

      false; // Use an async attach where we start the attach and return

             // immediately (used by GUI programs with --waitfor so they can

             // call SBProcess::Stop() to cancel attach)

};

// This class tracks the Modification state of the process.  Things that can

// currently modify the program are running the program (which will up the

// StopID) and writing memory (which will up the MemoryID.)

// FIXME: Should we also include modification of register states?

class ProcessModID {

  friend bool operator==(const ProcessModID &lhs, const ProcessModID &rhs);

public:

  ProcessModID() = default;

  ProcessModID(const ProcessModID &rhs)

      : m_stop_id(rhs.m_stop_id), m_memory_id(rhs.m_memory_id) {}

  const ProcessModID &operator=(const ProcessModID &rhs) {

    if (this != &rhs) {

      m_stop_id = rhs.m_stop_id;

      m_memory_id = rhs.m_memory_id;

    }

    return *this;

  }

  ~ProcessModID() = default;

  uint32_t BumpStopID() {

    const uint32_t prev_stop_id = m_stop_id++;

    if (!IsLastResumeForUserExpression())

      m_last_natural_stop_id++;

    return prev_stop_id;

  }

  void BumpMemoryID() { m_memory_id++; }

  void BumpResumeID() {

    m_resume_id++;

    if (m_running_user_expression > 0)

      m_last_user_expression_resume = m_resume_id;

  }

  bool IsRunningUtilityFunction() const {

    return m_running_utility_function > 0;

  }

  uint32_t GetStopID() const { return m_stop_id; }

  uint32_t GetLastNaturalStopID() const { return m_last_natural_stop_id; }

  uint32_t GetMemoryID() const { return m_memory_id; }

  uint32_t GetResumeID() const { return m_resume_id; }

  uint32_t GetLastUserExpressionResumeID() const {

    return m_last_user_expression_resume;

  }

  bool MemoryIDEqual(const ProcessModID &compare) const {

    return m_memory_id == compare.m_memory_id;

  }

  bool StopIDEqual(const ProcessModID &compare) const {

    return m_stop_id == compare.m_stop_id;

  }

  void SetInvalid() { m_stop_id = UINT32_MAX; }

  bool IsValid() const { return m_stop_id != UINT32_MAX; }

  bool IsLastResumeForUserExpression() const {

    // If we haven't yet resumed the target, then it can't be for a user

    // expression...

    if (m_resume_id == 0)

      return false;

    return m_resume_id == m_last_user_expression_resume;

  }

  bool IsRunningExpression() const {

    // Don't return true if we are no longer running an expression:

    if (m_running_user_expression || 
m_running_utility_function2.59k
)

      return true;

    return false;

  }

  void SetRunningUserExpression(bool on) {

    if (on)

      m_running_user_expression++;

    else

      m_running_user_expression--;

  }

  void SetRunningUtilityFunction(bool on) {

    if (on)

      m_running_utility_function++;

    else {

      assert(m_running_utility_function > 0 &&

             "Called SetRunningUtilityFunction(false) without calling "

             "SetRunningUtilityFunction(true) before?");

      m_running_utility_function--;

    }

  }

  void SetStopEventForLastNaturalStopID(lldb::EventSP event_sp) {

    m_last_natural_stop_event = std::move(event_sp);

  }

  lldb::EventSP GetStopEventForStopID(uint32_t stop_id) const {

    if (stop_id == m_last_natural_stop_id)

      return m_last_natural_stop_event;

    return lldb::EventSP();

  }

private:

  uint32_t m_stop_id = 0;

  uint32_t m_last_natural_stop_id = 0;

  uint32_t m_resume_id = 0;

  uint32_t m_memory_id = 0;

  uint32_t m_last_user_expression_resume = 0;

  uint32_t m_running_user_expression = false;

  uint32_t m_running_utility_function = 0;

  lldb::EventSP m_last_natural_stop_event;

};

inline bool operator==(const ProcessModID &lhs, const ProcessModID &rhs) {

  if (lhs.StopIDEqual(rhs) && 
lhs.MemoryIDEqual(rhs)569k
)

    return true;

  else

    return false;

}

inline bool operator!=(const ProcessModID &lhs, const ProcessModID &rhs) {

  return (!lhs.StopIDEqual(rhs) || !lhs.MemoryIDEqual(rhs));

}

/// \class Process Process.h "lldb/Target/Process.h"

/// A plug-in interface definition class for debugging a process.

class Process : public std::enable_shared_from_this<Process>,

                public ProcessProperties,

                public Broadcaster,

                public ExecutionContextScope,

                public PluginInterface {

  friend class FunctionCaller; // For WaitForStateChangeEventsPrivate

  friend class Debugger; // For PopProcessIOHandler and ProcessIOHandlerIsActive

  friend class DynamicLoader; // For LoadOperatingSystemPlugin

  friend class ProcessEventData;

  friend class StopInfo;

  friend class Target;

  friend class ThreadList;

public:

  /// Broadcaster event bits definitions.

  enum {

    eBroadcastBitStateChanged = (1 << 0),

    eBroadcastBitInterrupt = (1 << 1),

    eBroadcastBitSTDOUT = (1 << 2),

    eBroadcastBitSTDERR = (1 << 3),

    eBroadcastBitProfileData = (1 << 4),

    eBroadcastBitStructuredData = (1 << 5),

  };

  // This is all the event bits the public process broadcaster broadcasts.

  // The process shadow listener signs up for all these bits...

  static constexpr int g_all_event_bits = eBroadcastBitStateChanged 

                                        | eBroadcastBitInterrupt

                                        | eBroadcastBitSTDOUT 

                                        | eBroadcastBitSTDERR

                                        | eBroadcastBitProfileData 

                                        | eBroadcastBitStructuredData;

  enum {

    eBroadcastInternalStateControlStop = (1 << 0),

    eBroadcastInternalStateControlPause = (1 << 1),

    eBroadcastInternalStateControlResume = (1 << 2)

  };

  typedef Range<lldb::addr_t, lldb::addr_t> LoadRange;

  // We use a read/write lock to allow on or more clients to access the process

  // state while the process is stopped (reader). We lock the write lock to

  // control access to the process while it is running (readers, or clients

  // that want the process stopped can block waiting for the process to stop,

  // or just try to lock it to see if they can immediately access the stopped

  // process. If the try read lock fails, then the process is running.

  typedef ProcessRunLock::ProcessRunLocker StopLocker;

  // These two functions fill out the Broadcaster interface:

  static ConstString &GetStaticBroadcasterClass();

  static constexpr llvm::StringRef AttachSynchronousHijackListenerName =

      "lldb.internal.Process.AttachSynchronous.hijack";

  static constexpr llvm::StringRef LaunchSynchronousHijackListenerName =

      "lldb.internal.Process.LaunchSynchronous.hijack";

  static constexpr llvm::StringRef ResumeSynchronousHijackListenerName =

      "lldb.internal.Process.ResumeSynchronous.hijack";

  ConstString &GetBroadcasterClass() const override {

    return GetStaticBroadcasterClass();

  }

/// A notification structure that can be used by clients to listen

/// for changes in a process's lifetime.

///

/// \see RegisterNotificationCallbacks (const Notifications&) @see

/// UnregisterNotificationCallbacks (const Notifications&)

  typedef struct {

    void *baton;

    void (*initialize)(void *baton, Process *process);

    void (*process_state_changed)(void *baton, Process *process,

                                  lldb::StateType state);

  } Notifications;

  class ProcessEventData : public EventData {

    friend class Process;

  public:

    ProcessEventData();

    ProcessEventData(const lldb::ProcessSP &process, lldb::StateType state);

    ~ProcessEventData() override;

    static llvm::StringRef GetFlavorString();

    llvm::StringRef GetFlavor() const override;

    lldb::ProcessSP GetProcessSP() const { return m_process_wp.lock(); }

    lldb::StateType GetState() const { return m_state; }

    bool GetRestarted() const { return m_restarted; }

    size_t GetNumRestartedReasons() { return m_restarted_reasons.size(); }

    const char *GetRestartedReasonAtIndex(size_t idx) {

      return ((idx < m_restarted_reasons.size())

                  ? m_restarted_reasons[idx].c_str()

                  : 
nullptr0
);

    }

    bool GetInterrupted() const { return m_interrupted; }

    void Dump(Stream *s) const override;

    virtual bool ShouldStop(Event *event_ptr, bool &found_valid_stopinfo);

    void DoOnRemoval(Event *event_ptr) override;

    static const Process::ProcessEventData *

    GetEventDataFromEvent(const Event *event_ptr);

    static lldb::ProcessSP GetProcessFromEvent(const Event *event_ptr);

    static lldb::StateType GetStateFromEvent(const Event *event_ptr);

    static bool GetRestartedFromEvent(const Event *event_ptr);

    static size_t GetNumRestartedReasons(const Event *event_ptr);

    static const char *GetRestartedReasonAtIndex(const Event *event_ptr,

                                                 size_t idx);

    static void AddRestartedReason(Event *event_ptr, const char *reason);

    static void SetRestartedInEvent(Event *event_ptr, bool new_value);

    static bool GetInterruptedFromEvent(const Event *event_ptr);

    static void SetInterruptedInEvent(Event *event_ptr, bool new_value);

    static bool SetUpdateStateOnRemoval(Event *event_ptr);

  private:

    void SetUpdateStateOnRemoval() { m_update_state++; }

    void SetRestarted(bool new_value) { m_restarted = new_value; }

    void SetInterrupted(bool new_value) { m_interrupted = new_value; }

    void AddRestartedReason(const char *reason) {

      m_restarted_reasons.push_back(reason);

    }

    lldb::ProcessWP m_process_wp;

    lldb::StateType m_state = lldb::eStateInvalid;

    std::vector<std::string> m_restarted_reasons;

    bool m_restarted = false; // For "eStateStopped" events, this is true if the

                              // target was automatically restarted.

    int m_update_state = 0;

    bool m_interrupted = false;

    ProcessEventData(const ProcessEventData &) = delete;

    const ProcessEventData &operator=(const ProcessEventData &) = delete;

  };

  /// Destructor.

  ///

  /// The destructor is virtual since this class is designed to be inherited

  /// from by the plug-in instance.

  ~Process() override;

  static void SettingsInitialize();

  static void SettingsTerminate();

  static ProcessProperties &GetGlobalProperties();

  /// Find a Process plug-in that can debug \a module using the currently

  /// selected architecture.

  ///

  /// Scans all loaded plug-in interfaces that implement versions of the

  /// Process plug-in interface and returns the first instance that can debug

  /// the file.

  ///

  /// \see Process::CanDebug ()

  static lldb::ProcessSP FindPlugin(lldb::TargetSP target_sp,

                                    llvm::StringRef plugin_name,

                                    lldb::ListenerSP listener_sp,

                                    const FileSpec *crash_file_path,

                                    bool can_connect);

  /// Static function that can be used with the \b host function

  /// Host::StartMonitoringChildProcess ().

  ///

  /// This function can be used by lldb_private::Process subclasses when they

  /// want to watch for a local process and have its exit status automatically

  /// set when the host child process exits. Subclasses should call

  /// Host::StartMonitoringChildProcess () with:

  ///     callback = Process::SetHostProcessExitStatus

  ///     pid = Process::GetID()

  ///     monitor_signals = false

  static bool

  SetProcessExitStatus(lldb::pid_t pid, // The process ID we want to monitor

                       bool exited,

                       int signo,   // Zero for no signal

                       int status); // Exit value of process if signal is zero

  lldb::ByteOrder GetByteOrder() const;

  uint32_t GetAddressByteSize() const;

  /// Returns the pid of the process or LLDB_INVALID_PROCESS_ID if there is

  /// no known pid.

  lldb::pid_t GetID() const { return m_pid; }

  /// Sets the stored pid.

  ///

  /// This does not change the pid of underlying process.

  void SetID(lldb::pid_t new_pid) { m_pid = new_pid; }

  uint32_t GetUniqueID() const { return m_process_unique_id; }

  /// Check if a plug-in instance can debug the file in \a module.

  ///

  /// Each plug-in is given a chance to say whether it can debug the file in

  /// \a module. If the Process plug-in instance can debug a file on the

  /// current system, it should return \b true.

  ///

  /// \return

  ///     Returns \b true if this Process plug-in instance can

  ///     debug the executable, \b false otherwise.

  virtual bool CanDebug(lldb::TargetSP target,

                        bool plugin_specified_by_name) = 0;

  /// This object is about to be destroyed, do any necessary cleanup.

  ///

  /// Subclasses that override this method should always call this superclass

  /// method.

  virtual void Finalize();

  /// Return whether this object is valid (i.e. has not been finalized.)

  ///

  /// \return

  ///     Returns \b true if this Process has not been finalized

  ///     and \b false otherwise.

  bool IsValid() const { return !m_finalizing; }

  /// Return a multi-word command object that can be used to expose plug-in

  /// specific commands.

  ///

  /// This object will be used to resolve plug-in commands and can be

  /// triggered by a call to:

  ///

  ///     (lldb) process command <args>

  ///

  /// \return

  ///     A CommandObject which can be one of the concrete subclasses

  ///     of CommandObject like CommandObjectRaw, CommandObjectParsed,

  ///     or CommandObjectMultiword.

  virtual CommandObject *GetPluginCommandObject() { return nullptr; }

  /// The underlying plugin might store the low-level communication history for

  /// this session.  Dump it into the provided stream.

  virtual void DumpPluginHistory(Stream &s) { return; }

  /// Launch a new process.

  ///

  /// Launch a new process by spawning a new process using the target object's

  /// executable module's file as the file to launch.

  ///

  /// This function is not meant to be overridden by Process subclasses. It

  /// will first call Process::WillLaunch (Module *) and if that returns \b

  /// true, Process::DoLaunch (Module*, char const *[],char const *[],const

  /// char *,const char *, const char *) will be called to actually do the

  /// launching. If DoLaunch returns \b true, then Process::DidLaunch() will

  /// be called.

  ///

  /// \param[in] launch_info

  ///     Details regarding the environment, STDIN/STDOUT/STDERR

  ///     redirection, working path, etc. related to the requested launch.

  ///

  /// \return

  ///     An error object. Call GetID() to get the process ID if

  ///     the error object is success.

  virtual Status Launch(ProcessLaunchInfo &launch_info);

  virtual Status LoadCore();

  virtual Status DoLoadCore() {

    Status error;

    error.SetErrorStringWithFormatv(

        "error: {0} does not support loading core files.", GetPluginName());

    return error;

  }

  /// The "ShadowListener" for a process is just an ordinary Listener that 

  /// listens for all the Process event bits.  It's convenient because you can

  /// specify it in the LaunchInfo or AttachInfo, so it will get events from

  /// the very start of the process.

  void SetShadowListener(lldb::ListenerSP shadow_listener_sp) {

    if (shadow_listener_sp)

      AddListener(shadow_listener_sp, g_all_event_bits);

  }

  // FUTURE WORK: GetLoadImageUtilityFunction are the first use we've

  // had of having other plugins cache data in the Process.  This is handy for

  // long-living plugins - like the Platform - which manage interactions whose

  // lifetime is governed by the Process lifetime.  If we find we need to do

  // this more often, we should construct a general solution to the problem.

  // The consensus suggestion was that we have a token based registry in the

  // Process. Some undecided questions are  (1) who manages the tokens.  It's

  // probably best that you add the element  and get back a token that

  // represents it.  That will avoid collisions.  But there may be some utility

  // in the registerer controlling the token? (2) whether the thing added

  // should be simply owned by Process, and just go away when it does (3)

  // whether the registree should be notified of the Process' demise.

  //

  // We are postponing designing this till we have at least a second use case.

  /// Get the cached UtilityFunction that assists in loading binary images

  /// into the process.

  ///

  /// \param[in] platform

  ///     The platform fetching the UtilityFunction.

  /// \param[in] factory

  ///     A function that will be called only once per-process in a

  ///     thread-safe way to create the UtilityFunction if it has not

  ///     been initialized yet.

  ///

  /// \return

  ///     The cached utility function or null if the platform is not the

  ///     same as the target's platform.

  UtilityFunction *GetLoadImageUtilityFunction(

      Platform *platform,

      llvm::function_ref<std::unique_ptr<UtilityFunction>()> factory);

  /// Get the dynamic loader plug-in for this process.

  ///

  /// The default action is to let the DynamicLoader plug-ins check the main

  /// executable and the DynamicLoader will select itself automatically.

  /// Subclasses can override this if inspecting the executable is not

  /// desired, or if Process subclasses can only use a specific DynamicLoader

  /// plug-in.

  virtual DynamicLoader *GetDynamicLoader();

  void SetDynamicLoader(lldb::DynamicLoaderUP dyld);

  // Returns AUXV structure found in many ELF-based environments.

  //

  // The default action is to return an empty data buffer.

  //

  // \return

  //    A data extractor containing the contents of the AUXV data.

  virtual DataExtractor GetAuxvData();

  /// Sometimes processes know how to retrieve and load shared libraries. This

  /// is normally done by DynamicLoader plug-ins, but sometimes the connection

  /// to the process allows retrieving this information. The dynamic loader

  /// plug-ins can use this function if they can't determine the current

  /// shared library load state.

  ///

  /// \return

  ///    A status object indicating if the operation was sucessful or not.

  virtual llvm::Error LoadModules() {

    return llvm::make_error<llvm::StringError>("Not implemented.",

                                               llvm::inconvertibleErrorCode());

  }

  /// Query remote GDBServer for a detailed loaded library list

  /// \return

  ///    The list of modules currently loaded by the process, or an error.

  virtual llvm::Expected<LoadedModuleInfoList> GetLoadedModuleList() {

    return llvm::createStringError(llvm::inconvertibleErrorCode(),

                                   "Not implemented");

  }

  /// Save core dump into the specified file.

  ///

  /// \param[in] outfile

  ///     Path to store core dump in.

  ///

  /// \return

  ///     true if saved successfully, false if saving the core dump

  ///     is not supported by the plugin, error otherwise.

  virtual llvm::Expected<bool> SaveCore(llvm::StringRef outfile);

protected:

  virtual JITLoaderList &GetJITLoaders();

public:

  /// Get the system architecture for this process.

  virtual ArchSpec GetSystemArchitecture() { return {}; }

  /// Get the system runtime plug-in for this process.

  ///

  /// \return

  ///   Returns a pointer to the SystemRuntime plugin for this Process

  ///   if one is available.  Else returns nullptr.

  virtual SystemRuntime *GetSystemRuntime();

  /// Attach to an existing process using the process attach info.

  ///

  /// This function is not meant to be overridden by Process subclasses. It

  /// will first call WillAttach (lldb::pid_t) or WillAttach (const char *),

  /// and if that returns \b true, DoAttach (lldb::pid_t) or DoAttach (const

  /// char *) will be called to actually do the attach. If DoAttach returns \b

  /// true, then Process::DidAttach() will be called.

  ///

  /// \param[in] attach_info

  ///     The process attach info.

  ///

  /// \return

  ///     Returns \a pid if attaching was successful, or

  ///     LLDB_INVALID_PROCESS_ID if attaching fails.

  virtual Status Attach(ProcessAttachInfo &attach_info);

  /// Attach to a remote system via a URL

  ///

  /// \param[in] remote_url

  ///     The URL format that we are connecting to.

  ///

  /// \return

  ///     Returns an error object.

  virtual Status ConnectRemote(llvm::StringRef remote_url);

  bool GetShouldDetach() const { return m_should_detach; }

  void SetShouldDetach(bool b) { m_should_detach = b; }

  /// Get the image vector for the current process.

  ///

  /// \return

  ///     The constant reference to the member m_image_tokens.

  const std::vector<lldb::addr_t>& GetImageTokens() { return m_image_tokens; }

  /// Get the image information address for the current process.

  ///

  /// Some runtimes have system functions that can help dynamic loaders locate

  /// the dynamic loader information needed to observe shared libraries being

  /// loaded or unloaded. This function is in the Process interface (as

  /// opposed to the DynamicLoader interface) to ensure that remote debugging

  /// can take advantage of this functionality.

  ///

  /// \return

  ///     The address of the dynamic loader information, or

  ///     LLDB_INVALID_ADDRESS if this is not supported by this

  ///     interface.

  virtual lldb::addr_t GetImageInfoAddress();

  /// Called when the process is about to broadcast a public stop.

  ///

  /// There are public and private stops. Private stops are when the process

  /// is doing things like stepping and the client doesn't need to know about

  /// starts and stop that implement a thread plan. Single stepping over a

  /// source line in code might end up being implemented by one or more

  /// process starts and stops. Public stops are when clients will be notified

  /// that the process is stopped. These events typically trigger UI updates

  /// (thread stack frames to be displayed, variables to be displayed, and

  /// more). This function can be overriden and allows process subclasses to

  /// do something before the eBroadcastBitStateChanged event is sent to

  /// public clients.

  virtual void WillPublicStop() {}

/// Register for process and thread notifications.

///

/// Clients can register notification callbacks by filling out a

/// Process::Notifications structure and calling this function.

///

/// \param[in] callbacks

///     A structure that contains the notification baton and

///     callback functions.

///

/// \see Process::Notifications

  void RegisterNotificationCallbacks(const Process::Notifications &callbacks);

/// Unregister for process and thread notifications.

///

/// Clients can unregister notification callbacks by passing a copy of the

/// original baton and callbacks in \a callbacks.

///

/// \param[in] callbacks

///     A structure that contains the notification baton and

///     callback functions.

///

/// \return

///     Returns \b true if the notification callbacks were

///     successfully removed from the process, \b false otherwise.

///

/// \see Process::Notifications

  bool UnregisterNotificationCallbacks(const Process::Notifications &callbacks);

  //==================================================================

  // Built in Process Control functions

  //==================================================================

  /// Resumes all of a process's threads as configured using the Thread run

  /// control functions.

  ///

  /// Threads for a process should be updated with one of the run control

  /// actions (resume, step, or suspend) that they should take when the

  /// process is resumed. If no run control action is given to a thread it

  /// will be resumed by default.

  ///

  /// This function is not meant to be overridden by Process subclasses. This

  /// function will take care of disabling any breakpoints that threads may be

  /// stopped at, single stepping, and re-enabling breakpoints, and enabling

  /// the basic flow control that the plug-in instances need not worry about.

  ///

  /// N.B. This function also sets the Write side of the Run Lock, which is

  /// unset when the corresponding stop event is pulled off the Public Event

  /// Queue.  If you need to resume the process without setting the Run Lock,

  /// use PrivateResume (though you should only do that from inside the

  /// Process class.

  ///

  /// \return

  ///     Returns an error object.

  ///

  /// \see Thread:Resume()

  /// \see Thread:Step()

  /// \see Thread:Suspend()

  Status Resume();

  /// Resume a process, and wait for it to stop.

  Status ResumeSynchronous(Stream *stream);

  /// Halts a running process.

  ///

  /// This function is not meant to be overridden by Process subclasses. If

  /// the process is successfully halted, a eStateStopped process event with

  /// GetInterrupted will be broadcast.  If false, we will halt the process

  /// with no events generated by the halt.

  ///

  /// \param[in] clear_thread_plans

  ///     If true, when the process stops, clear all thread plans.

  ///

  /// \param[in] use_run_lock

  ///     Whether to release the run lock after the stop.

  ///

  /// \return

  ///     Returns an error object.  If the error is empty, the process is

  ///     halted.

  ///     otherwise the halt has failed.

  Status Halt(bool clear_thread_plans = false, bool use_run_lock = true);

  /// Detaches from a running or stopped process.

  ///

  /// This function is not meant to be overridden by Process subclasses.

  ///

  /// \param[in] keep_stopped

  ///     If true, don't resume the process on detach.

  ///

  /// \return

  ///     Returns an error object.

  Status Detach(bool keep_stopped);

  /// Kills the process and shuts down all threads that were spawned to track

  /// and monitor the process.

  ///

  /// This function is not meant to be overridden by Process subclasses.

  ///

  /// \param[in] force_kill

  ///     Whether lldb should force a kill (instead of a detach) from

  ///     the inferior process.  Normally if lldb launched a binary and

  ///     Destory is called, lldb kills it.  If lldb attached to a

  ///     running process and Destory is called, lldb detaches.  If

  ///     this behavior needs to be over-ridden, this is the bool that

  ///     can be used.

  ///

  /// \return

  ///     Returns an error object.

  Status Destroy(bool force_kill);

  /// Sends a process a UNIX signal \a signal.

  ///

  /// This function is not meant to be overridden by Process subclasses.

  ///

  /// \return

  ///     Returns an error object.

  Status Signal(int signal);

  void SetUnixSignals(lldb::UnixSignalsSP &&signals_sp);

  const lldb::UnixSignalsSP &GetUnixSignals();

  //==================================================================

  // Plug-in Process Control Overrides

  //==================================================================

  /// Called before attaching to a process.

  ///

  /// \return

  ///     Returns an error object.

  Status WillAttachToProcessWithID(lldb::pid_t pid);

  /// Called before attaching to a process.

  ///

  /// Allow Process plug-ins to execute some code before attaching a process.

  ///

  /// \return

  ///     Returns an error object.

  virtual Status DoWillAttachToProcessWithID(lldb::pid_t pid) {

    return Status();

  }

  /// Called before attaching to a process.

  ///

  /// \return

  ///     Returns an error object.

  Status WillAttachToProcessWithName(const char *process_name,

                                     bool wait_for_launch);

  /// Called before attaching to a process.

  ///

  /// Allow Process plug-ins to execute some code before attaching a process.

  ///

  /// \return

  ///     Returns an error object.

  virtual Status DoWillAttachToProcessWithName(const char *process_name,

                                               bool wait_for_launch) {

    return Status();

  }

  /// Attach to a remote system via a URL

  ///

  /// \param[in] remote_url

  ///     The URL format that we are connecting to.

  ///

  /// \return

  ///     Returns an error object.

  virtual Status DoConnectRemote(llvm::StringRef remote_url) {

    Status error;

    error.SetErrorString("remote connections are not supported");

    return error;

  }

  /// Attach to an existing process using a process ID.

  ///

  /// \param[in] pid

  ///     The process ID that we should attempt to attach to.

  ///

  /// \param[in] attach_info

  ///     Information on how to do the attach. For example, GetUserID()

  ///     will return the uid to attach as.

  ///

  /// \return

  ///     Returns a successful Status attaching was successful, or

  ///     an appropriate (possibly platform-specific) error code if

  ///     attaching fails.

  /// hanming : need flag

  virtual Status DoAttachToProcessWithID(lldb::pid_t pid,

                                         const ProcessAttachInfo &attach_info) {

    Status error;

    error.SetErrorStringWithFormatv(

        "error: {0} does not support attaching to a process by pid",

        GetPluginName());

    return error;

  }

  /// Attach to an existing process using a partial process name.

  ///

  /// \param[in] process_name

  ///     The name of the process to attach to.

  ///

  /// \param[in] attach_info

  ///     Information on how to do the attach. For example, GetUserID()

  ///     will return the uid to attach as.

  ///

  /// \return

  ///     Returns a successful Status attaching was successful, or

  ///     an appropriate (possibly platform-specific) error code if

  ///     attaching fails.

  virtual Status

  DoAttachToProcessWithName(const char *process_name,

                            const ProcessAttachInfo &attach_info) {

    Status error;

    error.SetErrorString("attach by name is not supported");

    return error;

  }

  /// Called after attaching a process.

  ///

  /// \param[in] process_arch

  ///     If you can figure out the process architecture after attach, fill it

  ///     in here.

  ///

  /// Allow Process plug-ins to execute some code after attaching to a

  /// process.

  virtual void DidAttach(ArchSpec &process_arch) { process_arch.Clear(); }

  /// Called after a process re-execs itself.

  ///

  /// Allow Process plug-ins to execute some code after a process has exec'ed

  /// itself. Subclasses typically should override DoDidExec() as the

  /// lldb_private::Process class needs to remove its dynamic loader, runtime,

  /// ABI and other plug-ins, as well as unload all shared libraries.

  virtual void DidExec();

  /// Subclasses of Process should implement this function if they need to do

  /// anything after a process exec's itself.

  virtual void DoDidExec() {}

  /// Called after a reported fork.

  virtual void DidFork(lldb::pid_t child_pid, lldb::tid_t child_tid) {}

  /// Called after a reported vfork.

  virtual void DidVFork(lldb::pid_t child_pid, lldb::tid_t child_tid) {}

  /// Called after reported vfork completion.

  virtual void DidVForkDone() {}

  /// Called before launching to a process.

  /// \return

  ///     Returns an error object.

  Status WillLaunch(Module *module);

  /// Called before launching to a process.

  ///

  /// Allow Process plug-ins to execute some code before launching a process.

  ///

  /// \return

  ///     Returns an error object.

  virtual Status DoWillLaunch(Module *module) { return Status(); }

  /// Launch a new process.

  ///

  /// Launch a new process by spawning a new process using \a exe_module's

  /// file as the file to launch. Launch details are provided in \a

  /// launch_info.

  ///

  /// \param[in] exe_module

  ///     The module from which to extract the file specification and

  ///     launch.

  ///

  /// \param[in] launch_info

  ///     Details (e.g. arguments, stdio redirection, etc.) for the

  ///     requested launch.

  ///

  /// \return

  ///     An Status instance indicating success or failure of the

  ///     operation.

  virtual Status DoLaunch(Module *exe_module, ProcessLaunchInfo &launch_info) {

    Status error;

    error.SetErrorStringWithFormatv(

        "error: {0} does not support launching processes", GetPluginName());

    return error;

  }

  /// Called after launching a process.

  ///

  /// Allow Process plug-ins to execute some code after launching a process.

  virtual void DidLaunch() {}

  /// Called before resuming to a process.

  ///

  /// Allow Process plug-ins to execute some code before resuming a process.

  ///

  /// \return

  ///     Returns an error object.

  virtual Status WillResume() { return Status(); }

  /// Resumes all of a process's threads as configured using the Thread run

  /// control functions.

  ///

  /// Threads for a process should be updated with one of the run control

  /// actions (resume, step, or suspend) that they should take when the

  /// process is resumed. If no run control action is given to a thread it

  /// will be resumed by default.

  ///

  /// \return

  ///     Returns \b true if the process successfully resumes using

  ///     the thread run control actions, \b false otherwise.

  ///

  /// \see Thread:Resume()

  /// \see Thread:Step()

  /// \see Thread:Suspend()

  virtual Status DoResume() {

    Status error;

    error.SetErrorStringWithFormatv(

        "error: {0} does not support resuming processes", GetPluginName());