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