1 //===-- NativeProcessProtocol.h ---------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_NativeProcessProtocol_h_
11 #define liblldb_NativeProcessProtocol_h_
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"
22 #include "NativeBreakpointList.h"
23 #include "NativeWatchpointList.h"
25 namespace lldb_private {
26 class MemoryRegionInfo;
27 class ResumeActionList;
29 //------------------------------------------------------------------
30 // NativeProcessProtocol
31 //------------------------------------------------------------------
32 class NativeProcessProtocol
33 : public std::enable_shared_from_this<NativeProcessProtocol> {
34 friend class SoftwareBreakpoint;
37 virtual ~NativeProcessProtocol() {}
39 virtual Error Resume(const ResumeActionList &resume_actions) = 0;
41 virtual Error Halt() = 0;
43 virtual Error Detach() = 0;
45 //------------------------------------------------------------------
46 /// Sends a process a UNIX signal \a signal.
49 /// Returns an error object.
50 //------------------------------------------------------------------
51 virtual Error Signal(int signo) = 0;
53 //------------------------------------------------------------------
54 /// Tells a process to interrupt all operations as if by a Ctrl-C.
56 /// The default implementation will send a local host's equivalent of
57 /// a SIGSTOP to the process via the NativeProcessProtocol::Signal()
61 /// Returns an error object.
62 //------------------------------------------------------------------
63 virtual Error Interrupt();
65 virtual Error Kill() = 0;
67 //----------------------------------------------------------------------
68 // Memory and memory region functions
69 //----------------------------------------------------------------------
71 virtual Error GetMemoryRegionInfo(lldb::addr_t load_addr,
72 MemoryRegionInfo &range_info);
74 virtual Error ReadMemory(lldb::addr_t addr, void *buf, size_t size,
75 size_t &bytes_read) = 0;
77 virtual Error ReadMemoryWithoutTrap(lldb::addr_t addr, void *buf, size_t size,
78 size_t &bytes_read) = 0;
80 virtual Error WriteMemory(lldb::addr_t addr, const void *buf, size_t size,
81 size_t &bytes_written) = 0;
83 virtual Error AllocateMemory(size_t size, uint32_t permissions,
84 lldb::addr_t &addr) = 0;
86 virtual Error DeallocateMemory(lldb::addr_t addr) = 0;
88 virtual lldb::addr_t GetSharedLibraryInfoAddress() = 0;
90 virtual bool IsAlive() const;
92 virtual size_t UpdateThreads() = 0;
94 virtual bool GetArchitecture(ArchSpec &arch) const = 0;
96 //----------------------------------------------------------------------
97 // Breakpoint functions
98 //----------------------------------------------------------------------
99 virtual Error SetBreakpoint(lldb::addr_t addr, uint32_t size,
102 virtual Error RemoveBreakpoint(lldb::addr_t addr);
104 virtual Error EnableBreakpoint(lldb::addr_t addr);
106 virtual Error DisableBreakpoint(lldb::addr_t addr);
108 //----------------------------------------------------------------------
109 // Watchpoint functions
110 //----------------------------------------------------------------------
111 virtual const NativeWatchpointList::WatchpointMap &GetWatchpointMap() const;
113 virtual uint32_t GetMaxWatchpoints() const;
115 virtual Error SetWatchpoint(lldb::addr_t addr, size_t size,
116 uint32_t watch_flags, bool hardware);
118 virtual Error RemoveWatchpoint(lldb::addr_t addr);
120 //----------------------------------------------------------------------
122 //----------------------------------------------------------------------
123 lldb::pid_t GetID() const { return m_pid; }
125 lldb::StateType GetState() const;
127 bool IsRunning() const {
128 return m_state == lldb::eStateRunning || IsStepping();
131 bool IsStepping() const { return m_state == lldb::eStateStepping; }
133 bool CanResume() const { return m_state == lldb::eStateStopped; }
135 bool GetByteOrder(lldb::ByteOrder &byte_order) const;
137 //----------------------------------------------------------------------
139 //----------------------------------------------------------------------
140 virtual bool GetExitStatus(lldb_private::ExitType *exit_type, int *status,
141 std::string &exit_description);
143 virtual bool SetExitStatus(lldb_private::ExitType exit_type, int status,
144 const char *exit_description,
145 bool bNotifyStateChange);
147 //----------------------------------------------------------------------
149 //----------------------------------------------------------------------
150 NativeThreadProtocolSP GetThreadAtIndex(uint32_t idx);
152 NativeThreadProtocolSP GetThreadByID(lldb::tid_t tid);
154 void SetCurrentThreadID(lldb::tid_t tid) { m_current_thread_id = tid; }
156 lldb::tid_t GetCurrentThreadID() { return m_current_thread_id; }
158 NativeThreadProtocolSP GetCurrentThread() {
159 return GetThreadByID(m_current_thread_id);
162 //----------------------------------------------------------------------
163 // Access to inferior stdio
164 //----------------------------------------------------------------------
165 virtual int GetTerminalFileDescriptor() { return m_terminal_fd; }
167 //----------------------------------------------------------------------
169 //----------------------------------------------------------------------
171 uint32_t GetStopID() const;
173 // ---------------------------------------------------------------------
174 // Callbacks for low-level process state changes
175 // ---------------------------------------------------------------------
176 class NativeDelegate {
178 virtual ~NativeDelegate() {}
180 virtual void InitializeDelegate(NativeProcessProtocol *process) = 0;
182 virtual void ProcessStateChanged(NativeProcessProtocol *process,
183 lldb::StateType state) = 0;
185 virtual void DidExec(NativeProcessProtocol *process) = 0;
188 //------------------------------------------------------------------
189 /// Register a native delegate.
191 /// Clients can register nofication callbacks by passing in a
192 /// NativeDelegate impl and passing it into this function.
194 /// Note: it is required that the lifetime of the
195 /// native_delegate outlive the NativeProcessProtocol.
197 /// @param[in] native_delegate
198 /// A NativeDelegate impl to be called when certain events
199 /// happen within the NativeProcessProtocol or related threads.
202 /// true if the delegate was registered successfully;
203 /// false if the delegate was already registered.
205 /// @see NativeProcessProtocol::NativeDelegate.
206 //------------------------------------------------------------------
207 bool RegisterNativeDelegate(NativeDelegate &native_delegate);
209 //------------------------------------------------------------------
210 /// Unregister a native delegate previously registered.
212 /// @param[in] native_delegate
213 /// A NativeDelegate impl previously registered with this process.
215 /// @return Returns \b true if the NativeDelegate was
216 /// successfully removed from the process, \b false otherwise.
218 /// @see NativeProcessProtocol::NativeDelegate
219 //------------------------------------------------------------------
220 bool UnregisterNativeDelegate(NativeDelegate &native_delegate);
222 virtual Error GetLoadedModuleFileSpec(const char *module_path,
223 FileSpec &file_spec) = 0;
225 virtual Error GetFileLoadAddress(const llvm::StringRef &file_name,
226 lldb::addr_t &load_addr) = 0;
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.)
233 /// @param[in] launch_info
234 /// Information required to launch the process.
236 /// @param[in] native_delegate
237 /// The delegate that will receive messages regarding the
238 /// inferior. Must outlive the NativeProcessProtocol
241 /// @param[in] mainloop
242 /// The mainloop instance with which the process can register
243 /// callbacks. Must outlive the NativeProcessProtocol
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.
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);
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.)
266 /// pid of the process locatable
268 /// @param[in] native_delegate
269 /// The delegate that will receive messages regarding the
270 /// inferior. Must outlive the NativeProcessProtocol
273 /// @param[in] mainloop
274 /// The mainloop instance with which the process can register
275 /// callbacks. Must outlive the NativeProcessProtocol
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.
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);
294 std::vector<NativeThreadProtocolSP> m_threads;
295 lldb::tid_t m_current_thread_id;
296 mutable std::recursive_mutex m_threads_mutex;
298 lldb::StateType m_state;
299 mutable std::recursive_mutex m_state_mutex;
301 lldb_private::ExitType m_exit_type;
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;
311 // lldb_private::Host calls should be used to launch a process for debugging,
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);
318 // -----------------------------------------------------------
319 // Internal interface for state handling
320 // -----------------------------------------------------------
321 void SetState(lldb::StateType state, bool notify_delegates = true);
323 // Derived classes need not implement this. It can be used as a
324 // hook to clear internal caches that should be invalidated when
327 // Note this function is called with the state mutex obtained
329 virtual void DoStopIDBumped(uint32_t newBumpId);
331 // -----------------------------------------------------------
332 // Internal interface for software breakpoints
333 // -----------------------------------------------------------
334 Error SetSoftwareBreakpoint(lldb::addr_t addr, uint32_t size_hint);
337 GetSoftwareBreakpointTrapOpcode(size_t trap_opcode_size_hint,
338 size_t &actual_opcode_size,
339 const uint8_t *&trap_opcode_bytes) = 0;
341 // -----------------------------------------------------------
342 /// Notify the delegate that an exec occurred.
344 /// Provide a mechanism for a delegate to clear out any exec-
346 // -----------------------------------------------------------
347 void NotifyDidExec();
349 NativeThreadProtocolSP GetThreadByIDUnlocked(lldb::tid_t tid);
351 // -----------------------------------------------------------
352 // Static helper methods for derived classes.
353 // -----------------------------------------------------------
354 static Error ResolveProcessArchitecture(lldb::pid_t pid, ArchSpec &arch);
357 void SynchronouslyNotifyProcessStateChanged(lldb::StateType state);
361 #endif // #ifndef liblldb_NativeProcessProtocol_h_