EIC code displayed by LXR master/​include/​lldb/​Host/​common/​NativeProcessProtocol.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2026-05-10 08:42:48

 //===-- NativeProcessProtocol.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_HOST_COMMON_NATIVEPROCESSPROTOCOL_H
 #define LLDB_HOST_COMMON_NATIVEPROCESSPROTOCOL_H
 
 #include "NativeBreakpointList.h"
 #include "NativeThreadProtocol.h"
 #include "NativeWatchpointList.h"
 #include "lldb/Host/Host.h"
 #include "lldb/Host/MainLoop.h"
 #include "lldb/Utility/ArchSpec.h"
 #include "lldb/Utility/Iterable.h"
 #include "lldb/Utility/Status.h"
 #include "lldb/Utility/TraceGDBRemotePackets.h"
 #include "lldb/Utility/UnimplementedError.h"
 #include "lldb/lldb-private-forward.h"
 #include "lldb/lldb-types.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/DenseSet.h"
 #include "llvm/ADT/StringRef.h"
 #include "llvm/Support/Error.h"
 #include "llvm/Support/MemoryBuffer.h"
 #include <mutex>
 #include <optional>
 #include <unordered_map>
 #include <vector>
 
 namespace lldb_private {
 LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE();
 
 class MemoryRegionInfo;
 class ResumeActionList;
 
 struct SVR4LibraryInfo {
   std::string name;
   lldb::addr_t link_map;
   lldb::addr_t base_addr;
   lldb::addr_t ld_addr;
   lldb::addr_t next;
 };
 
 // NativeProcessProtocol
 class NativeProcessProtocol {
 public:
   virtual ~NativeProcessProtocol() = default;
 
   typedef std::vector<std::unique_ptr<NativeThreadProtocol>> thread_collection;
   template <typename I>
   static NativeThreadProtocol &thread_list_adapter(I &iter) {
     assert(*iter);
     return **iter;
   }
   typedef LockingAdaptedIterable<thread_collection, NativeThreadProtocol &,
                                  thread_list_adapter, std::recursive_mutex>
       ThreadIterable;
 
   virtual Status Resume(const ResumeActionList &resume_actions) = 0;
 
   virtual Status Halt() = 0;
 
   virtual Status Detach() = 0;
 
   /// Sends a process a UNIX signal \a signal.
   ///
   /// \return
   ///     Returns an error object.
   virtual Status Signal(int signo) = 0;
 
   /// Tells a process to interrupt all operations as if by a Ctrl-C.
   ///
   /// The default implementation will send a local host's equivalent of
   /// a SIGSTOP to the process via the NativeProcessProtocol::Signal()
   /// operation.
   ///
   /// \return
   ///     Returns an error object.
   virtual Status Interrupt();
 
   virtual Status Kill() = 0;
 
   // Tells a process not to stop the inferior on given signals and just
   // reinject them back.
   virtual Status IgnoreSignals(llvm::ArrayRef<int> signals);
 
   // Memory and memory region functions
 
   virtual Status GetMemoryRegionInfo(lldb::addr_t load_addr,
                                      MemoryRegionInfo &range_info);
 
   virtual Status ReadMemory(lldb::addr_t addr, void *buf, size_t size,
                             size_t &bytes_read) = 0;
 
   Status ReadMemoryWithoutTrap(lldb::addr_t addr, void *buf, size_t size,
                                size_t &bytes_read);
 
   virtual Status ReadMemoryTags(int32_t type, lldb::addr_t addr, size_t len,
                                 std::vector<uint8_t> &tags);
 
   virtual Status WriteMemoryTags(int32_t type, lldb::addr_t addr, size_t len,
                                  const std::vector<uint8_t> &tags);
 
   /// Reads a null terminated string from memory.
   ///
   /// Reads up to \p max_size bytes of memory until it finds a '\0'.
   /// If a '\0' is not found then it reads max_size-1 bytes as a string and a
   /// '\0' is added as the last character of the \p buffer.
   ///
   /// \param[in] addr
   ///     The address in memory to read from.
   ///
   /// \param[in] buffer
   ///     An allocated buffer with at least \p max_size size.
   ///
   /// \param[in] max_size
   ///     The maximum number of bytes to read from memory until it reads the
   ///     string.
   ///
   /// \param[out] total_bytes_read
   ///     The number of bytes read from memory into \p buffer.
   ///
   /// \return
   ///     Returns a StringRef backed up by the \p buffer passed in.
   llvm::Expected<llvm::StringRef>
   ReadCStringFromMemory(lldb::addr_t addr, char *buffer, size_t max_size,
                         size_t &total_bytes_read);
 
   virtual Status WriteMemory(lldb::addr_t addr, const void *buf, size_t size,
                              size_t &bytes_written) = 0;
 
   virtual llvm::Expected<lldb::addr_t> AllocateMemory(size_t size,
                                                       uint32_t permissions) {
     return llvm::make_error<UnimplementedError>();
   }
 
   virtual llvm::Error DeallocateMemory(lldb::addr_t addr) {
     return llvm::make_error<UnimplementedError>();
   }
 
   virtual lldb::addr_t GetSharedLibraryInfoAddress() = 0;
 
   virtual llvm::Expected<std::vector<SVR4LibraryInfo>>
   GetLoadedSVR4Libraries() {
     return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                    "Not implemented");
   }
 
   virtual bool IsAlive() const;
 
   virtual size_t UpdateThreads() = 0;
 
   virtual const ArchSpec &GetArchitecture() const = 0;
 
   // Breakpoint functions
   virtual Status SetBreakpoint(lldb::addr_t addr, uint32_t size,
                                bool hardware) = 0;
 
   virtual Status RemoveBreakpoint(lldb::addr_t addr, bool hardware = false);
 
   // Hardware Breakpoint functions
   virtual const HardwareBreakpointMap &GetHardwareBreakpointMap() const;
 
   virtual Status SetHardwareBreakpoint(lldb::addr_t addr, size_t size);
 
   virtual Status RemoveHardwareBreakpoint(lldb::addr_t addr);
 
   // Watchpoint functions
   virtual const NativeWatchpointList::WatchpointMap &GetWatchpointMap() const;
 
   virtual std::optional<std::pair<uint32_t, uint32_t>>
   GetHardwareDebugSupportInfo() const;
 
   virtual Status SetWatchpoint(lldb::addr_t addr, size_t size,
                                uint32_t watch_flags, bool hardware);
 
   virtual Status RemoveWatchpoint(lldb::addr_t addr);
 
   // Accessors
   lldb::pid_t GetID() const { return m_pid; }
 
   lldb::StateType GetState() const;
 
   bool IsRunning() const {
     return m_state == lldb::eStateRunning || IsStepping();
   }
 
   bool IsStepping() const { return m_state == lldb::eStateStepping; }
 
   bool CanResume() const { return m_state == lldb::eStateStopped; }
 
   lldb::ByteOrder GetByteOrder() const {
     return GetArchitecture().GetByteOrder();
   }
 
   uint32_t GetAddressByteSize() const {
     return GetArchitecture().GetAddressByteSize();
   }
 
   virtual llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
   GetAuxvData() const = 0;
 
   // Exit Status
   virtual std::optional<WaitStatus> GetExitStatus();
 
   virtual bool SetExitStatus(WaitStatus status, bool bNotifyStateChange);
 
   // Access to threads
   NativeThreadProtocol *GetThreadAtIndex(uint32_t idx);
 
   NativeThreadProtocol *GetThreadByID(lldb::tid_t tid);
 
   void SetCurrentThreadID(lldb::tid_t tid) { m_current_thread_id = tid; }
 
   lldb::tid_t GetCurrentThreadID() const { return m_current_thread_id; }
 
   NativeThreadProtocol *GetCurrentThread() {
     return GetThreadByID(m_current_thread_id);
   }
 
   ThreadIterable Threads() const {
     return ThreadIterable(m_threads, m_threads_mutex);
   }
 
   // Access to inferior stdio
   virtual int GetTerminalFileDescriptor() { return m_terminal_fd; }
 
   // Stop id interface
 
   uint32_t GetStopID() const;
 
   // Callbacks for low-level process state changes
   class NativeDelegate {
   public:
     virtual ~NativeDelegate() = default;
 
     virtual void InitializeDelegate(NativeProcessProtocol *process) = 0;
 
     virtual void ProcessStateChanged(NativeProcessProtocol *process,
                                      lldb::StateType state) = 0;
 
     virtual void DidExec(NativeProcessProtocol *process) = 0;
 
     virtual void
     NewSubprocess(NativeProcessProtocol *parent_process,
                   std::unique_ptr<NativeProcessProtocol> child_process) = 0;
   };
 
   virtual Status GetLoadedModuleFileSpec(const char *module_path,
                                          FileSpec &file_spec) = 0;
 
   virtual Status GetFileLoadAddress(const llvm::StringRef &file_name,
                                     lldb::addr_t &load_addr) = 0;
 
   /// Extension flag constants, returned by Manager::GetSupportedExtensions()
   /// and passed to SetEnabledExtension()
   enum class Extension {
     multiprocess = (1u << 0),
     fork = (1u << 1),
     vfork = (1u << 2),
     pass_signals = (1u << 3),
     auxv = (1u << 4),
     libraries_svr4 = (1u << 5),
     memory_tagging = (1u << 6),
     savecore = (1u << 7),
     siginfo_read = (1u << 8),
 
     LLVM_MARK_AS_BITMASK_ENUM(siginfo_read)
   };
 
   class Manager {
   public:
     Manager(MainLoop &mainloop) : m_mainloop(mainloop) {}
     Manager(const Manager &) = delete;
     Manager &operator=(const Manager &) = delete;
 
     virtual ~Manager();
 
     /// Launch a process for debugging.
     ///
     /// \param[in] launch_info
     ///     Information required to launch the process.
     ///
     /// \param[in] native_delegate
     ///     The delegate that will receive messages regarding the
     ///     inferior.  Must outlive the NativeProcessProtocol
     ///     instance.
     ///
     /// \param[in] mainloop
     ///     The mainloop instance with which the process can register
     ///     callbacks. Must outlive the NativeProcessProtocol
     ///     instance.
     ///
     /// \return
     ///     A NativeProcessProtocol shared pointer if the operation succeeded or
     ///     an error object if it failed.
     virtual llvm::Expected<std::unique_ptr<NativeProcessProtocol>>
     Launch(ProcessLaunchInfo &launch_info,
            NativeDelegate &native_delegate) = 0;
 
     /// Attach to an existing process.
     ///
     /// \param[in] pid
     ///     pid of the process locatable
     ///
     /// \param[in] native_delegate
     ///     The delegate that will receive messages regarding the
     ///     inferior.  Must outlive the NativeProcessProtocol
     ///     instance.
     ///
     /// \param[in] mainloop
     ///     The mainloop instance with which the process can register
     ///     callbacks. Must outlive the NativeProcessProtocol
     ///     instance.
     ///
     /// \return
     ///     A NativeProcessProtocol shared pointer if the operation succeeded or
     ///     an error object if it failed.
     virtual llvm::Expected<std::unique_ptr<NativeProcessProtocol>>
     Attach(lldb::pid_t pid, NativeDelegate &native_delegate) = 0;
 
     /// Get the bitmask of extensions supported by this process plugin.
     ///
     /// \return
     ///     A NativeProcessProtocol::Extension bitmask.
     virtual Extension GetSupportedExtensions() const { return {}; }
 
   protected:
     MainLoop &m_mainloop;
   };
 
   /// Notify tracers that the target process will resume
   virtual void NotifyTracersProcessWillResume() {}
 
   /// Notify tracers that the target process just stopped
   virtual void NotifyTracersProcessDidStop() {}
 
   /// Start tracing a process or its threads.
   ///
   /// \param[in] json_params
   ///     JSON object with the information of what and how to trace.
   ///     In the case of gdb-remote, this object should conform to the
   ///     jLLDBTraceStart packet.
   ///
   ///     This object should have a string entry called "type", which is the
   ///     tracing technology name.
   ///
   /// \param[in] type
   ///     Tracing technology type, as described in the \a json_params.
   ///
   /// \return
   ///     \a llvm::Error::success if the operation was successful, or an
   ///     \a llvm::Error otherwise.
   virtual llvm::Error TraceStart(llvm::StringRef json_params,
                                  llvm::StringRef type) {
     return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                    "Unsupported tracing type '%s'",
                                    type.data());
   }
 
   /// \copydoc Process::TraceStop(const TraceStopRequest &)
   virtual llvm::Error TraceStop(const TraceStopRequest &request) {
     return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                    "Unsupported tracing type '%s'",
                                    request.type.data());
   }
 
   /// \copydoc Process::TraceGetState(llvm::StringRef type)
   virtual llvm::Expected<llvm::json::Value>
   TraceGetState(llvm::StringRef type) {
     return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                    "Unsupported tracing type '%s'",
                                    type.data());
   }
 
   /// \copydoc Process::TraceGetBinaryData(const TraceGetBinaryDataRequest &)
   virtual llvm::Expected<std::vector<uint8_t>>
   TraceGetBinaryData(const TraceGetBinaryDataRequest &request) {
     return llvm::createStringError(
         llvm::inconvertibleErrorCode(),
         "Unsupported data kind '%s' for the '%s' tracing technology",
         request.kind.c_str(), request.type.c_str());
   }
 
   /// \copydoc Process::TraceSupported()
   virtual llvm::Expected<TraceSupportedResponse> TraceSupported() {
     return llvm::make_error<UnimplementedError>();
   }
 
   /// Method called in order to propagate the bitmap of protocol
   /// extensions supported by the client.
   ///
   /// \param[in] flags
   ///     The bitmap of enabled extensions.
   virtual void SetEnabledExtensions(Extension flags) {
     m_enabled_extensions = flags;
   }
 
   /// Write a core dump (without crashing the program).
   ///
   /// \param[in] path_hint
   ///     Suggested core dump path (optional, can be empty).
   ///
   /// \return
   ///     Path to the core dump if successfully written, an error
   ///     otherwise.
   virtual llvm::Expected<std::string> SaveCore(llvm::StringRef path_hint) {
     return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                    "Not implemented");
   }
 
 protected:
   struct SoftwareBreakpoint {
     uint32_t ref_count;
     llvm::SmallVector<uint8_t, 4> saved_opcodes;
     llvm::ArrayRef<uint8_t> breakpoint_opcodes;
   };
 
   std::unordered_map<lldb::addr_t, SoftwareBreakpoint> m_software_breakpoints;
   lldb::pid_t m_pid;
 
   std::vector<std::unique_ptr<NativeThreadProtocol>> m_threads;
   lldb::tid_t m_current_thread_id = LLDB_INVALID_THREAD_ID;
   mutable std::recursive_mutex m_threads_mutex;
 
   lldb::StateType m_state = lldb::eStateInvalid;
   mutable std::recursive_mutex m_state_mutex;
 
   std::optional<WaitStatus> m_exit_status;
 
   NativeDelegate &m_delegate;
   NativeWatchpointList m_watchpoint_list;
   HardwareBreakpointMap m_hw_breakpoints_map;
   int m_terminal_fd;
   uint32_t m_stop_id = 0;
 
   // Set of signal numbers that LLDB directly injects back to inferior without
   // stopping it.
   llvm::DenseSet<int> m_signals_to_ignore;
 
   // Extensions enabled per the last SetEnabledExtensions() call.
   Extension m_enabled_extensions;
 
   // lldb_private::Host calls should be used to launch a process for debugging,
   // and then the process should be attached to. When attaching to a process
   // lldb_private::Host calls should be used to locate the process to attach
   // to, and then this function should be called.
   NativeProcessProtocol(lldb::pid_t pid, int terminal_fd,
                         NativeDelegate &delegate);
 
   void SetID(lldb::pid_t pid) { m_pid = pid; }
 
   // interface for state handling
   void SetState(lldb::StateType state, bool notify_delegates = true);
 
   // Derived classes need not implement this.  It can be used as a hook to
   // clear internal caches that should be invalidated when stop ids change.
   //
   // Note this function is called with the state mutex obtained by the caller.
   virtual void DoStopIDBumped(uint32_t newBumpId);
 
   // interface for software breakpoints
 
   Status SetSoftwareBreakpoint(lldb::addr_t addr, uint32_t size_hint);
   Status RemoveSoftwareBreakpoint(lldb::addr_t addr);
 
   virtual llvm::Expected<llvm::ArrayRef<uint8_t>>
   GetSoftwareBreakpointTrapOpcode(size_t size_hint);
 
   /// Return the offset of the PC relative to the software breakpoint that was hit. If an
   /// architecture (e.g. arm) reports breakpoint hits before incrementing the PC, this offset
   /// will be 0. If an architecture (e.g. intel) reports breakpoints hits after incrementing the
   /// PC, this offset will be the size of the breakpoint opcode.
   virtual size_t GetSoftwareBreakpointPCOffset();
 
   // Adjust the thread's PC after hitting a software breakpoint. On
   // architectures where the PC points after the breakpoint instruction, this
   // resets it to point to the breakpoint itself.
   void FixupBreakpointPCAsNeeded(NativeThreadProtocol &thread);
 
   /// Notify the delegate that an exec occurred.
   ///
   /// Provide a mechanism for a delegate to clear out any exec-
   /// sensitive data.
   virtual void NotifyDidExec();
 
   NativeThreadProtocol *GetThreadByIDUnlocked(lldb::tid_t tid);
 
 private:
   void SynchronouslyNotifyProcessStateChanged(lldb::StateType state);
   llvm::Expected<SoftwareBreakpoint>
   EnableSoftwareBreakpoint(lldb::addr_t addr, uint32_t size_hint);
 };
 } // namespace lldb_private
 
 #endif // LLDB_HOST_COMMON_NATIVEPROCESSPROTOCOL_H

This page was automatically generated by the 2.3.7 LXR engine. The LXR team