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