contrib/llvm/tools/lldb/include/lldb/Host/common/NativeProcessProtocol.h

   1 //===-- NativeProcessProtocol.h ---------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_NativeProcessProtocol_h_
  11 #define liblldb_NativeProcessProtocol_h_
  12
  13 #include "lldb/Host/MainLoop.h"
  14 #include "lldb/Utility/Error.h"
  15 #include "lldb/lldb-private-forward.h"
  16 #include "lldb/lldb-types.h"
  17 #include "llvm/ADT/ArrayRef.h"
  18 #include "llvm/ADT/DenseSet.h"
  19 #include "llvm/ADT/StringRef.h"
  20 #include "llvm/Support/MemoryBuffer.h"
  21 #include <vector>
  22
  23 #include "NativeBreakpointList.h"
  24 #include "NativeWatchpointList.h"
  25
  26 namespace lldb_private {
  27 class MemoryRegionInfo;
  28 class ResumeActionList;
  29
  30 //------------------------------------------------------------------
  31 // NativeProcessProtocol
  32 //------------------------------------------------------------------
  33 class NativeProcessProtocol
  34     : public std::enable_shared_from_this<NativeProcessProtocol> {
  35   friend class SoftwareBreakpoint;
  36
  37 public:
  38   virtual ~NativeProcessProtocol() {}
  39
  40   virtual Error Resume(const ResumeActionList &resume_actions) = 0;
  41
  42   virtual Error Halt() = 0;
  43
  44   virtual Error Detach() = 0;
  45
  46   //------------------------------------------------------------------
  47   /// Sends a process a UNIX signal \a signal.
  48   ///
  49   /// @return
  50   ///     Returns an error object.
  51   //------------------------------------------------------------------
  52   virtual Error Signal(int signo) = 0;
  53
  54   //------------------------------------------------------------------
  55   /// Tells a process to interrupt all operations as if by a Ctrl-C.
  56   ///
  57   /// The default implementation will send a local host's equivalent of
  58   /// a SIGSTOP to the process via the NativeProcessProtocol::Signal()
  59   /// operation.
  60   ///
  61   /// @return
  62   ///     Returns an error object.
  63   //------------------------------------------------------------------
  64   virtual Error Interrupt();
  65
  66   virtual Error Kill() = 0;
  67
  68   //------------------------------------------------------------------
  69   // Tells a process not to stop the inferior on given signals
  70   // and just reinject them back.
  71   //------------------------------------------------------------------
  72   virtual Error IgnoreSignals(llvm::ArrayRef<int> signals);
  73
  74   //----------------------------------------------------------------------
  75   // Memory and memory region functions
  76   //----------------------------------------------------------------------
  77
  78   virtual Error GetMemoryRegionInfo(lldb::addr_t load_addr,
  79                                     MemoryRegionInfo &range_info);
  80
  81   virtual Error ReadMemory(lldb::addr_t addr, void *buf, size_t size,
  82                            size_t &bytes_read) = 0;
  83
  84   virtual Error ReadMemoryWithoutTrap(lldb::addr_t addr, void *buf, size_t size,
  85                                       size_t &bytes_read) = 0;
  86
  87   virtual Error WriteMemory(lldb::addr_t addr, const void *buf, size_t size,
  88                             size_t &bytes_written) = 0;
  89
  90   virtual Error AllocateMemory(size_t size, uint32_t permissions,
  91                                lldb::addr_t &addr) = 0;
  92
  93   virtual Error DeallocateMemory(lldb::addr_t addr) = 0;
  94
  95   virtual lldb::addr_t GetSharedLibraryInfoAddress() = 0;
  96
  97   virtual bool IsAlive() const;
  98
  99   virtual size_t UpdateThreads() = 0;
 100
 101   virtual bool GetArchitecture(ArchSpec &arch) const = 0;
 102
 103   //----------------------------------------------------------------------
 104   // Breakpoint functions
 105   //----------------------------------------------------------------------
 106   virtual Error SetBreakpoint(lldb::addr_t addr, uint32_t size,
 107                               bool hardware) = 0;
 108
 109   virtual Error RemoveBreakpoint(lldb::addr_t addr, bool hardware = false);
 110
 111   virtual Error EnableBreakpoint(lldb::addr_t addr);
 112
 113   virtual Error DisableBreakpoint(lldb::addr_t addr);
 114
 115   //----------------------------------------------------------------------
 116   // Hardware Breakpoint functions
 117   //----------------------------------------------------------------------
 118   virtual const HardwareBreakpointMap &GetHardwareBreakpointMap() const;
 119
 120   virtual Error SetHardwareBreakpoint(lldb::addr_t addr, size_t size);
 121
 122   virtual Error RemoveHardwareBreakpoint(lldb::addr_t addr);
 123
 124   //----------------------------------------------------------------------
 125   // Watchpoint functions
 126   //----------------------------------------------------------------------
 127   virtual const NativeWatchpointList::WatchpointMap &GetWatchpointMap() const;
 128
 129   virtual llvm::Optional<std::pair<uint32_t, uint32_t>>
 130   GetHardwareDebugSupportInfo() const;
 131
 132   virtual Error SetWatchpoint(lldb::addr_t addr, size_t size,
 133                               uint32_t watch_flags, bool hardware);
 134
 135   virtual Error RemoveWatchpoint(lldb::addr_t addr);
 136
 137   //----------------------------------------------------------------------
 138   // Accessors
 139   //----------------------------------------------------------------------
 140   lldb::pid_t GetID() const { return m_pid; }
 141
 142   lldb::StateType GetState() const;
 143
 144   bool IsRunning() const {
 145     return m_state == lldb::eStateRunning || IsStepping();
 146   }
 147
 148   bool IsStepping() const { return m_state == lldb::eStateStepping; }
 149
 150   bool CanResume() const { return m_state == lldb::eStateStopped; }
 151
 152   bool GetByteOrder(lldb::ByteOrder &byte_order) const;
 153
 154   virtual llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
 155   GetAuxvData() const = 0;
 156
 157   //----------------------------------------------------------------------
 158   // Exit Status
 159   //----------------------------------------------------------------------
 160   virtual bool GetExitStatus(lldb_private::ExitType *exit_type, int *status,
 161                              std::string &exit_description);
 162
 163   virtual bool SetExitStatus(lldb_private::ExitType exit_type, int status,
 164                              const char *exit_description,
 165                              bool bNotifyStateChange);
 166
 167   //----------------------------------------------------------------------
 168   // Access to threads
 169   //----------------------------------------------------------------------
 170   NativeThreadProtocolSP GetThreadAtIndex(uint32_t idx);
 171
 172   NativeThreadProtocolSP GetThreadByID(lldb::tid_t tid);
 173
 174   void SetCurrentThreadID(lldb::tid_t tid) { m_current_thread_id = tid; }
 175
 176   lldb::tid_t GetCurrentThreadID() { return m_current_thread_id; }
 177
 178   NativeThreadProtocolSP GetCurrentThread() {
 179     return GetThreadByID(m_current_thread_id);
 180   }
 181
 182   //----------------------------------------------------------------------
 183   // Access to inferior stdio
 184   //----------------------------------------------------------------------
 185   virtual int GetTerminalFileDescriptor() { return m_terminal_fd; }
 186
 187   //----------------------------------------------------------------------
 188   // Stop id interface
 189   //----------------------------------------------------------------------
 190
 191   uint32_t GetStopID() const;
 192
 193   // ---------------------------------------------------------------------
 194   // Callbacks for low-level process state changes
 195   // ---------------------------------------------------------------------
 196   class NativeDelegate {
 197   public:
 198     virtual ~NativeDelegate() {}
 199
 200     virtual void InitializeDelegate(NativeProcessProtocol *process) = 0;
 201
 202     virtual void ProcessStateChanged(NativeProcessProtocol *process,
 203                                      lldb::StateType state) = 0;
 204
 205     virtual void DidExec(NativeProcessProtocol *process) = 0;
 206   };
 207
 208   //------------------------------------------------------------------
 209   /// Register a native delegate.
 210   ///
 211   /// Clients can register nofication callbacks by passing in a
 212   /// NativeDelegate impl and passing it into this function.
 213   ///
 214   /// Note: it is required that the lifetime of the
 215   /// native_delegate outlive the NativeProcessProtocol.
 216   ///
 217   /// @param[in] native_delegate
 218   ///     A NativeDelegate impl to be called when certain events
 219   ///     happen within the NativeProcessProtocol or related threads.
 220   ///
 221   /// @return
 222   ///     true if the delegate was registered successfully;
 223   ///     false if the delegate was already registered.
 224   ///
 225   /// @see NativeProcessProtocol::NativeDelegate.
 226   //------------------------------------------------------------------
 227   bool RegisterNativeDelegate(NativeDelegate &native_delegate);
 228
 229   //------------------------------------------------------------------
 230   /// Unregister a native delegate previously registered.
 231   ///
 232   /// @param[in] native_delegate
 233   ///     A NativeDelegate impl previously registered with this process.
 234   ///
 235   /// @return Returns \b true if the NativeDelegate was
 236   /// successfully removed from the process, \b false otherwise.
 237   ///
 238   /// @see NativeProcessProtocol::NativeDelegate
 239   //------------------------------------------------------------------
 240   bool UnregisterNativeDelegate(NativeDelegate &native_delegate);
 241
 242   virtual Error GetLoadedModuleFileSpec(const char *module_path,
 243                                         FileSpec &file_spec) = 0;
 244
 245   virtual Error GetFileLoadAddress(const llvm::StringRef &file_name,
 246                                    lldb::addr_t &load_addr) = 0;
 247
 248   //------------------------------------------------------------------
 249   /// Launch a process for debugging. This method will create an concrete
 250   /// instance of NativeProcessProtocol, based on the host platform.
 251   /// (e.g. NativeProcessLinux on linux, etc.)
 252   ///
 253   /// @param[in] launch_info
 254   ///     Information required to launch the process.
 255   ///
 256   /// @param[in] native_delegate
 257   ///     The delegate that will receive messages regarding the
 258   ///     inferior.  Must outlive the NativeProcessProtocol
 259   ///     instance.
 260   ///
 261   /// @param[in] mainloop
 262   ///     The mainloop instance with which the process can register
 263   ///     callbacks. Must outlive the NativeProcessProtocol
 264   ///     instance.
 265   ///
 266   /// @param[out] process_sp
 267   ///     On successful return from the method, this parameter
 268   ///     contains the shared pointer to the
 269   ///     NativeProcessProtocol that can be used to manipulate
 270   ///     the native process.
 271   ///
 272   /// @return
 273   ///     An error object indicating if the operation succeeded,
 274   ///     and if not, what error occurred.
 275   //------------------------------------------------------------------
 276   static Error Launch(ProcessLaunchInfo &launch_info,
 277                       NativeDelegate &native_delegate, MainLoop &mainloop,
 278                       NativeProcessProtocolSP &process_sp);
 279
 280   //------------------------------------------------------------------
 281   /// Attach to an existing process. This method will create an concrete
 282   /// instance of NativeProcessProtocol, based on the host platform.
 283   /// (e.g. NativeProcessLinux on linux, etc.)
 284   ///
 285   /// @param[in] pid
 286   ///     pid of the process locatable
 287   ///
 288   /// @param[in] native_delegate
 289   ///     The delegate that will receive messages regarding the
 290   ///     inferior.  Must outlive the NativeProcessProtocol
 291   ///     instance.
 292   ///
 293   /// @param[in] mainloop
 294   ///     The mainloop instance with which the process can register
 295   ///     callbacks. Must outlive the NativeProcessProtocol
 296   ///     instance.
 297   ///
 298   /// @param[out] process_sp
 299   ///     On successful return from the method, this parameter
 300   ///     contains the shared pointer to the
 301   ///     NativeProcessProtocol that can be used to manipulate
 302   ///     the native process.
 303   ///
 304   /// @return
 305   ///     An error object indicating if the operation succeeded,
 306   ///     and if not, what error occurred.
 307   //------------------------------------------------------------------
 308   static Error Attach(lldb::pid_t pid, NativeDelegate &native_delegate,
 309                       MainLoop &mainloop, NativeProcessProtocolSP &process_sp);
 310
 311 protected:
 312   lldb::pid_t m_pid;
 313
 314   std::vector<NativeThreadProtocolSP> m_threads;
 315   lldb::tid_t m_current_thread_id;
 316   mutable std::recursive_mutex m_threads_mutex;
 317
 318   lldb::StateType m_state;
 319   mutable std::recursive_mutex m_state_mutex;
 320
 321   lldb_private::ExitType m_exit_type;
 322   int m_exit_status;
 323   std::string m_exit_description;
 324   std::recursive_mutex m_delegates_mutex;
 325   std::vector<NativeDelegate *> m_delegates;
 326   NativeBreakpointList m_breakpoint_list;
 327   NativeWatchpointList m_watchpoint_list;
 328   HardwareBreakpointMap m_hw_breakpoints_map;
 329   int m_terminal_fd;
 330   uint32_t m_stop_id;
 331
 332   // Set of signal numbers that LLDB directly injects back to inferior
 333   // without stopping it.
 334   llvm::DenseSet<int> m_signals_to_ignore;
 335
 336   // lldb_private::Host calls should be used to launch a process for debugging,
 337   // and
 338   // then the process should be attached to. When attaching to a process
 339   // lldb_private::Host calls should be used to locate the process to attach to,
 340   // and then this function should be called.
 341   NativeProcessProtocol(lldb::pid_t pid);
 342
 343   // -----------------------------------------------------------
 344   // Internal interface for state handling
 345   // -----------------------------------------------------------
 346   void SetState(lldb::StateType state, bool notify_delegates = true);
 347
 348   // Derived classes need not implement this.  It can be used as a
 349   // hook to clear internal caches that should be invalidated when
 350   // stop ids change.
 351   //
 352   // Note this function is called with the state mutex obtained
 353   // by the caller.
 354   virtual void DoStopIDBumped(uint32_t newBumpId);
 355
 356   // -----------------------------------------------------------
 357   // Internal interface for software breakpoints
 358   // -----------------------------------------------------------
 359   Error SetSoftwareBreakpoint(lldb::addr_t addr, uint32_t size_hint);
 360
 361   virtual Error
 362   GetSoftwareBreakpointTrapOpcode(size_t trap_opcode_size_hint,
 363                                   size_t &actual_opcode_size,
 364                                   const uint8_t *&trap_opcode_bytes) = 0;
 365
 366   // -----------------------------------------------------------
 367   /// Notify the delegate that an exec occurred.
 368   ///
 369   /// Provide a mechanism for a delegate to clear out any exec-
 370   /// sensitive data.
 371   // -----------------------------------------------------------
 372   void NotifyDidExec();
 373
 374   NativeThreadProtocolSP GetThreadByIDUnlocked(lldb::tid_t tid);
 375
 376   // -----------------------------------------------------------
 377   // Static helper methods for derived classes.
 378   // -----------------------------------------------------------
 379   static Error ResolveProcessArchitecture(lldb::pid_t pid, ArchSpec &arch);
 380
 381 private:
 382   void SynchronouslyNotifyProcessStateChanged(lldb::StateType state);
 383 };
 384 }
 385
 386 #endif // #ifndef liblldb_NativeProcessProtocol_h_