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 "NativeBreakpointList.h"
  14 #include "NativeThreadProtocol.h"
  15 #include "NativeWatchpointList.h"
  16 #include "lldb/Host/Host.h"
  17 #include "lldb/Host/MainLoop.h"
  18 #include "lldb/Utility/ArchSpec.h"
  19 #include "lldb/Utility/Status.h"
  20 #include "lldb/Utility/TraceOptions.h"
  21 #include "lldb/lldb-private-forward.h"
  22 #include "lldb/lldb-types.h"
  23 #include "llvm/ADT/ArrayRef.h"
  24 #include "llvm/ADT/DenseSet.h"
  25 #include "llvm/ADT/StringRef.h"
  26 #include "llvm/Support/Error.h"
  27 #include "llvm/Support/MemoryBuffer.h"
  28 #include <vector>
  29
  30 namespace lldb_private {
  31 class MemoryRegionInfo;
  32 class ResumeActionList;
  33
  34 //------------------------------------------------------------------
  35 // NativeProcessProtocol
  36 //------------------------------------------------------------------
  37 class NativeProcessProtocol {
  38   friend class SoftwareBreakpoint;
  39
  40 public:
  41   virtual ~NativeProcessProtocol() {}
  42
  43   virtual Status Resume(const ResumeActionList &resume_actions) = 0;
  44
  45   virtual Status Halt() = 0;
  46
  47   virtual Status Detach() = 0;
  48
  49   //------------------------------------------------------------------
  50   /// Sends a process a UNIX signal \a signal.
  51   ///
  52   /// @return
  53   ///     Returns an error object.
  54   //------------------------------------------------------------------
  55   virtual Status Signal(int signo) = 0;
  56
  57   //------------------------------------------------------------------
  58   /// Tells a process to interrupt all operations as if by a Ctrl-C.
  59   ///
  60   /// The default implementation will send a local host's equivalent of
  61   /// a SIGSTOP to the process via the NativeProcessProtocol::Signal()
  62   /// operation.
  63   ///
  64   /// @return
  65   ///     Returns an error object.
  66   //------------------------------------------------------------------
  67   virtual Status Interrupt();
  68
  69   virtual Status Kill() = 0;
  70
  71   //------------------------------------------------------------------
  72   // Tells a process not to stop the inferior on given signals
  73   // and just reinject them back.
  74   //------------------------------------------------------------------
  75   virtual Status IgnoreSignals(llvm::ArrayRef<int> signals);
  76
  77   //----------------------------------------------------------------------
  78   // Memory and memory region functions
  79   //----------------------------------------------------------------------
  80
  81   virtual Status GetMemoryRegionInfo(lldb::addr_t load_addr,
  82                                      MemoryRegionInfo &range_info);
  83
  84   virtual Status ReadMemory(lldb::addr_t addr, void *buf, size_t size,
  85                             size_t &bytes_read) = 0;
  86
  87   virtual Status ReadMemoryWithoutTrap(lldb::addr_t addr, void *buf,
  88                                        size_t size, size_t &bytes_read) = 0;
  89
  90   virtual Status WriteMemory(lldb::addr_t addr, const void *buf, size_t size,
  91                              size_t &bytes_written) = 0;
  92
  93   virtual Status AllocateMemory(size_t size, uint32_t permissions,
  94                                 lldb::addr_t &addr) = 0;
  95
  96   virtual Status DeallocateMemory(lldb::addr_t addr) = 0;
  97
  98   virtual lldb::addr_t GetSharedLibraryInfoAddress() = 0;
  99
 100   virtual bool IsAlive() const;
 101
 102   virtual size_t UpdateThreads() = 0;
 103
 104   virtual const ArchSpec &GetArchitecture() const = 0;
 105
 106   //----------------------------------------------------------------------
 107   // Breakpoint functions
 108   //----------------------------------------------------------------------
 109   virtual Status SetBreakpoint(lldb::addr_t addr, uint32_t size,
 110                                bool hardware) = 0;
 111
 112   virtual Status RemoveBreakpoint(lldb::addr_t addr, bool hardware = false);
 113
 114   virtual Status EnableBreakpoint(lldb::addr_t addr);
 115
 116   virtual Status DisableBreakpoint(lldb::addr_t addr);
 117
 118   //----------------------------------------------------------------------
 119   // Hardware Breakpoint functions
 120   //----------------------------------------------------------------------
 121   virtual const HardwareBreakpointMap &GetHardwareBreakpointMap() const;
 122
 123   virtual Status SetHardwareBreakpoint(lldb::addr_t addr, size_t size);
 124
 125   virtual Status RemoveHardwareBreakpoint(lldb::addr_t addr);
 126
 127   //----------------------------------------------------------------------
 128   // Watchpoint functions
 129   //----------------------------------------------------------------------
 130   virtual const NativeWatchpointList::WatchpointMap &GetWatchpointMap() const;
 131
 132   virtual llvm::Optional<std::pair<uint32_t, uint32_t>>
 133   GetHardwareDebugSupportInfo() const;
 134
 135   virtual Status SetWatchpoint(lldb::addr_t addr, size_t size,
 136                                uint32_t watch_flags, bool hardware);
 137
 138   virtual Status RemoveWatchpoint(lldb::addr_t addr);
 139
 140   //----------------------------------------------------------------------
 141   // Accessors
 142   //----------------------------------------------------------------------
 143   lldb::pid_t GetID() const { return m_pid; }
 144
 145   lldb::StateType GetState() const;
 146
 147   bool IsRunning() const {
 148     return m_state == lldb::eStateRunning || IsStepping();
 149   }
 150
 151   bool IsStepping() const { return m_state == lldb::eStateStepping; }
 152
 153   bool CanResume() const { return m_state == lldb::eStateStopped; }
 154
 155   lldb::ByteOrder GetByteOrder() const {
 156     return GetArchitecture().GetByteOrder();
 157   }
 158
 159   virtual llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
 160   GetAuxvData() const = 0;
 161
 162   //----------------------------------------------------------------------
 163   // Exit Status
 164   //----------------------------------------------------------------------
 165   virtual llvm::Optional<WaitStatus> GetExitStatus();
 166
 167   virtual bool SetExitStatus(WaitStatus status, bool bNotifyStateChange);
 168
 169   //----------------------------------------------------------------------
 170   // Access to threads
 171   //----------------------------------------------------------------------
 172   NativeThreadProtocol *GetThreadAtIndex(uint32_t idx);
 173
 174   NativeThreadProtocol *GetThreadByID(lldb::tid_t tid);
 175
 176   void SetCurrentThreadID(lldb::tid_t tid) { m_current_thread_id = tid; }
 177
 178   lldb::tid_t GetCurrentThreadID() { return m_current_thread_id; }
 179
 180   NativeThreadProtocol *GetCurrentThread() {
 181     return GetThreadByID(m_current_thread_id);
 182   }
 183
 184   //----------------------------------------------------------------------
 185   // Access to inferior stdio
 186   //----------------------------------------------------------------------
 187   virtual int GetTerminalFileDescriptor() { return m_terminal_fd; }
 188
 189   //----------------------------------------------------------------------
 190   // Stop id interface
 191   //----------------------------------------------------------------------
 192
 193   uint32_t GetStopID() const;
 194
 195   // ---------------------------------------------------------------------
 196   // Callbacks for low-level process state changes
 197   // ---------------------------------------------------------------------
 198   class NativeDelegate {
 199   public:
 200     virtual ~NativeDelegate() {}
 201
 202     virtual void InitializeDelegate(NativeProcessProtocol *process) = 0;
 203
 204     virtual void ProcessStateChanged(NativeProcessProtocol *process,
 205                                      lldb::StateType state) = 0;
 206
 207     virtual void DidExec(NativeProcessProtocol *process) = 0;
 208   };
 209
 210   //------------------------------------------------------------------
 211   /// Register a native delegate.
 212   ///
 213   /// Clients can register nofication callbacks by passing in a
 214   /// NativeDelegate impl and passing it into this function.
 215   ///
 216   /// Note: it is required that the lifetime of the
 217   /// native_delegate outlive the NativeProcessProtocol.
 218   ///
 219   /// @param[in] native_delegate
 220   ///     A NativeDelegate impl to be called when certain events
 221   ///     happen within the NativeProcessProtocol or related threads.
 222   ///
 223   /// @return
 224   ///     true if the delegate was registered successfully;
 225   ///     false if the delegate was already registered.
 226   ///
 227   /// @see NativeProcessProtocol::NativeDelegate.
 228   //------------------------------------------------------------------
 229   bool RegisterNativeDelegate(NativeDelegate &native_delegate);
 230
 231   //------------------------------------------------------------------
 232   /// Unregister a native delegate previously registered.
 233   ///
 234   /// @param[in] native_delegate
 235   ///     A NativeDelegate impl previously registered with this process.
 236   ///
 237   /// @return Returns \b true if the NativeDelegate was
 238   /// successfully removed from the process, \b false otherwise.
 239   ///
 240   /// @see NativeProcessProtocol::NativeDelegate
 241   //------------------------------------------------------------------
 242   bool UnregisterNativeDelegate(NativeDelegate &native_delegate);
 243
 244   virtual Status GetLoadedModuleFileSpec(const char *module_path,
 245                                          FileSpec &file_spec) = 0;
 246
 247   virtual Status GetFileLoadAddress(const llvm::StringRef &file_name,
 248                                     lldb::addr_t &load_addr) = 0;
 249
 250   class Factory {
 251   public:
 252     virtual ~Factory();
 253     //------------------------------------------------------------------
 254     /// Launch a process for debugging.
 255     ///
 256     /// @param[in] launch_info
 257     ///     Information required to launch the process.
 258     ///
 259     /// @param[in] native_delegate
 260     ///     The delegate that will receive messages regarding the
 261     ///     inferior.  Must outlive the NativeProcessProtocol
 262     ///     instance.
 263     ///
 264     /// @param[in] mainloop
 265     ///     The mainloop instance with which the process can register
 266     ///     callbacks. Must outlive the NativeProcessProtocol
 267     ///     instance.
 268     ///
 269     /// @return
 270     ///     A NativeProcessProtocol shared pointer if the operation succeeded or
 271     ///     an error object if it failed.
 272     //------------------------------------------------------------------
 273     virtual llvm::Expected<std::unique_ptr<NativeProcessProtocol>>
 274     Launch(ProcessLaunchInfo &launch_info, NativeDelegate &native_delegate,
 275            MainLoop &mainloop) const = 0;
 276
 277     //------------------------------------------------------------------
 278     /// Attach to an existing process.
 279     ///
 280     /// @param[in] pid
 281     ///     pid of the process locatable
 282     ///
 283     /// @param[in] native_delegate
 284     ///     The delegate that will receive messages regarding the
 285     ///     inferior.  Must outlive the NativeProcessProtocol
 286     ///     instance.
 287     ///
 288     /// @param[in] mainloop
 289     ///     The mainloop instance with which the process can register
 290     ///     callbacks. Must outlive the NativeProcessProtocol
 291     ///     instance.
 292     ///
 293     /// @return
 294     ///     A NativeProcessProtocol shared pointer if the operation succeeded or
 295     ///     an error object if it failed.
 296     //------------------------------------------------------------------
 297     virtual llvm::Expected<std::unique_ptr<NativeProcessProtocol>>
 298     Attach(lldb::pid_t pid, NativeDelegate &native_delegate,
 299            MainLoop &mainloop) const = 0;
 300   };
 301
 302   //------------------------------------------------------------------
 303   /// StartTracing API for starting a tracing instance with the
 304   /// TraceOptions on a specific thread or process.
 305   ///
 306   /// @param[in] config
 307   ///     The configuration to use when starting tracing.
 308   ///
 309   /// @param[out] error
 310   ///     Status indicates what went wrong.
 311   ///
 312   /// @return
 313   ///     The API returns a user_id which can be used to get trace
 314   ///     data, trace configuration or stopping the trace instance.
 315   ///     The user_id is a key to identify and operate with a tracing
 316   ///     instance. It may refer to the complete process or a single
 317   ///     thread.
 318   //------------------------------------------------------------------
 319   virtual lldb::user_id_t StartTrace(const TraceOptions &config,
 320                                      Status &error) {
 321     error.SetErrorString("Not implemented");
 322     return LLDB_INVALID_UID;
 323   }
 324
 325   //------------------------------------------------------------------
 326   /// StopTracing API as the name suggests stops a tracing instance.
 327   ///
 328   /// @param[in] traceid
 329   ///     The user id of the trace intended to be stopped. Now a
 330   ///     user_id may map to multiple threads in which case this API
 331   ///     could be used to stop the tracing for a specific thread by
 332   ///     supplying its thread id.
 333   ///
 334   /// @param[in] thread
 335   ///     Thread is needed when the complete process is being traced
 336   ///     and the user wishes to stop tracing on a particular thread.
 337   ///
 338   /// @return
 339   ///     Status indicating what went wrong.
 340   //------------------------------------------------------------------
 341   virtual Status StopTrace(lldb::user_id_t traceid,
 342                            lldb::tid_t thread = LLDB_INVALID_THREAD_ID) {
 343     return Status("Not implemented");
 344   }
 345
 346   //------------------------------------------------------------------
 347   /// This API provides the trace data collected in the form of raw
 348   /// data.
 349   ///
 350   /// @param[in] traceid thread
 351   ///     The traceid and thread provide the context for the trace
 352   ///     instance.
 353   ///
 354   /// @param[in] buffer
 355   ///     The buffer provides the destination buffer where the trace
 356   ///     data would be read to. The buffer should be truncated to the
 357   ///     filled length by this function.
 358   ///
 359   /// @param[in] offset
 360   ///     There is possibility to read partially the trace data from
 361   ///     a specified offset where in such cases the buffer provided
 362   ///     may be smaller than the internal trace collection container.
 363   ///
 364   /// @return
 365   ///     The size of the data actually read.
 366   //------------------------------------------------------------------
 367   virtual Status GetData(lldb::user_id_t traceid, lldb::tid_t thread,
 368                          llvm::MutableArrayRef<uint8_t> &buffer,
 369                          size_t offset = 0) {
 370     return Status("Not implemented");
 371   }
 372
 373   //------------------------------------------------------------------
 374   /// Similar API as above except it aims to provide any extra data
 375   /// useful for decoding the actual trace data.
 376   //------------------------------------------------------------------
 377   virtual Status GetMetaData(lldb::user_id_t traceid, lldb::tid_t thread,
 378                              llvm::MutableArrayRef<uint8_t> &buffer,
 379                              size_t offset = 0) {
 380     return Status("Not implemented");
 381   }
 382
 383   //------------------------------------------------------------------
 384   /// API to query the TraceOptions for a given user id
 385   ///
 386   /// @param[in] traceid
 387   ///     The user id of the tracing instance.
 388   ///
 389   /// @param[in] config
 390   ///     The thread id of the tracing instance, in case configuration
 391   ///     for a specific thread is needed should be specified in the
 392   ///     config.
 393   ///
 394   /// @param[out] error
 395   ///     Status indicates what went wrong.
 396   ///
 397   /// @param[out] config
 398   ///     The actual configuration being used for tracing.
 399   //------------------------------------------------------------------
 400   virtual Status GetTraceConfig(lldb::user_id_t traceid, TraceOptions &config) {
 401     return Status("Not implemented");
 402   }
 403
 404 protected:
 405   lldb::pid_t m_pid;
 406
 407   std::vector<std::unique_ptr<NativeThreadProtocol>> m_threads;
 408   lldb::tid_t m_current_thread_id = LLDB_INVALID_THREAD_ID;
 409   mutable std::recursive_mutex m_threads_mutex;
 410
 411   lldb::StateType m_state = lldb::eStateInvalid;
 412   mutable std::recursive_mutex m_state_mutex;
 413
 414   llvm::Optional<WaitStatus> m_exit_status;
 415
 416   std::recursive_mutex m_delegates_mutex;
 417   std::vector<NativeDelegate *> m_delegates;
 418   NativeBreakpointList m_breakpoint_list;
 419   NativeWatchpointList m_watchpoint_list;
 420   HardwareBreakpointMap m_hw_breakpoints_map;
 421   int m_terminal_fd;
 422   uint32_t m_stop_id = 0;
 423
 424   // Set of signal numbers that LLDB directly injects back to inferior
 425   // without stopping it.
 426   llvm::DenseSet<int> m_signals_to_ignore;
 427
 428   // lldb_private::Host calls should be used to launch a process for debugging,
 429   // and
 430   // then the process should be attached to. When attaching to a process
 431   // lldb_private::Host calls should be used to locate the process to attach to,
 432   // and then this function should be called.
 433   NativeProcessProtocol(lldb::pid_t pid, int terminal_fd,
 434                         NativeDelegate &delegate);
 435
 436   // -----------------------------------------------------------
 437   // Internal interface for state handling
 438   // -----------------------------------------------------------
 439   void SetState(lldb::StateType state, bool notify_delegates = true);
 440
 441   // Derived classes need not implement this.  It can be used as a
 442   // hook to clear internal caches that should be invalidated when
 443   // stop ids change.
 444   //
 445   // Note this function is called with the state mutex obtained
 446   // by the caller.
 447   virtual void DoStopIDBumped(uint32_t newBumpId);
 448
 449   // -----------------------------------------------------------
 450   // Internal interface for software breakpoints
 451   // -----------------------------------------------------------
 452   Status SetSoftwareBreakpoint(lldb::addr_t addr, uint32_t size_hint);
 453
 454   virtual Status
 455   GetSoftwareBreakpointTrapOpcode(size_t trap_opcode_size_hint,
 456                                   size_t &actual_opcode_size,
 457                                   const uint8_t *&trap_opcode_bytes) = 0;
 458
 459   // -----------------------------------------------------------
 460   /// Notify the delegate that an exec occurred.
 461   ///
 462   /// Provide a mechanism for a delegate to clear out any exec-
 463   /// sensitive data.
 464   // -----------------------------------------------------------
 465   void NotifyDidExec();
 466
 467   NativeThreadProtocol *GetThreadByIDUnlocked(lldb::tid_t tid);
 468
 469   // -----------------------------------------------------------
 470   // Static helper methods for derived classes.
 471   // -----------------------------------------------------------
 472   static Status ResolveProcessArchitecture(lldb::pid_t pid, ArchSpec &arch);
 473
 474 private:
 475   void SynchronouslyNotifyProcessStateChanged(lldb::StateType state);
 476 };
 477 } // namespace lldb_private
 478
 479 #endif // #ifndef liblldb_NativeProcessProtocol_h_