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