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_
13 #include "lldb/Host/MainLoop.h"
14 #include "lldb/Utility/Error.h"
15 #include "lldb/lldb-private-forward.h"
16 #include "lldb/lldb-types.h"
17 #include "llvm/ADT/ArrayRef.h"
18 #include "llvm/ADT/DenseSet.h"
19 #include "llvm/ADT/StringRef.h"
20 #include "llvm/Support/MemoryBuffer.h"
23 #include "NativeBreakpointList.h"
24 #include "NativeWatchpointList.h"
26 namespace lldb_private {
27 class MemoryRegionInfo;
28 class ResumeActionList;
30 //------------------------------------------------------------------
31 // NativeProcessProtocol
32 //------------------------------------------------------------------
33 class NativeProcessProtocol
34 : public std::enable_shared_from_this<NativeProcessProtocol> {
35 friend class SoftwareBreakpoint;
38 virtual ~NativeProcessProtocol() {}
40 virtual Error Resume(const ResumeActionList &resume_actions) = 0;
42 virtual Error Halt() = 0;
44 virtual Error Detach() = 0;
46 //------------------------------------------------------------------
47 /// Sends a process a UNIX signal \a signal.
50 /// Returns an error object.
51 //------------------------------------------------------------------
52 virtual Error Signal(int signo) = 0;
54 //------------------------------------------------------------------
55 /// Tells a process to interrupt all operations as if by a Ctrl-C.
57 /// The default implementation will send a local host's equivalent of
58 /// a SIGSTOP to the process via the NativeProcessProtocol::Signal()
62 /// Returns an error object.
63 //------------------------------------------------------------------
64 virtual Error Interrupt();
66 virtual Error Kill() = 0;
68 //------------------------------------------------------------------
69 // Tells a process not to stop the inferior on given signals
70 // and just reinject them back.
71 //------------------------------------------------------------------
72 virtual Error IgnoreSignals(llvm::ArrayRef<int> signals);
74 //----------------------------------------------------------------------
75 // Memory and memory region functions
76 //----------------------------------------------------------------------
78 virtual Error GetMemoryRegionInfo(lldb::addr_t load_addr,
79 MemoryRegionInfo &range_info);
81 virtual Error ReadMemory(lldb::addr_t addr, void *buf, size_t size,
82 size_t &bytes_read) = 0;
84 virtual Error ReadMemoryWithoutTrap(lldb::addr_t addr, void *buf, size_t size,
85 size_t &bytes_read) = 0;
87 virtual Error WriteMemory(lldb::addr_t addr, const void *buf, size_t size,
88 size_t &bytes_written) = 0;
90 virtual Error AllocateMemory(size_t size, uint32_t permissions,
91 lldb::addr_t &addr) = 0;
93 virtual Error DeallocateMemory(lldb::addr_t addr) = 0;
95 virtual lldb::addr_t GetSharedLibraryInfoAddress() = 0;
97 virtual bool IsAlive() const;
99 virtual size_t UpdateThreads() = 0;
101 virtual bool GetArchitecture(ArchSpec &arch) const = 0;
103 //----------------------------------------------------------------------
104 // Breakpoint functions
105 //----------------------------------------------------------------------
106 virtual Error SetBreakpoint(lldb::addr_t addr, uint32_t size,
109 virtual Error RemoveBreakpoint(lldb::addr_t addr, bool hardware = false);
111 virtual Error EnableBreakpoint(lldb::addr_t addr);
113 virtual Error DisableBreakpoint(lldb::addr_t addr);
115 //----------------------------------------------------------------------
116 // Hardware Breakpoint functions
117 //----------------------------------------------------------------------
118 virtual const HardwareBreakpointMap &GetHardwareBreakpointMap() const;
120 virtual Error SetHardwareBreakpoint(lldb::addr_t addr, size_t size);
122 virtual Error RemoveHardwareBreakpoint(lldb::addr_t addr);
124 //----------------------------------------------------------------------
125 // Watchpoint functions
126 //----------------------------------------------------------------------
127 virtual const NativeWatchpointList::WatchpointMap &GetWatchpointMap() const;
129 virtual llvm::Optional<std::pair<uint32_t, uint32_t>>
130 GetHardwareDebugSupportInfo() const;
132 virtual Error SetWatchpoint(lldb::addr_t addr, size_t size,
133 uint32_t watch_flags, bool hardware);
135 virtual Error RemoveWatchpoint(lldb::addr_t addr);
137 //----------------------------------------------------------------------
139 //----------------------------------------------------------------------
140 lldb::pid_t GetID() const { return m_pid; }
142 lldb::StateType GetState() const;
144 bool IsRunning() const {
145 return m_state == lldb::eStateRunning || IsStepping();
148 bool IsStepping() const { return m_state == lldb::eStateStepping; }
150 bool CanResume() const { return m_state == lldb::eStateStopped; }
152 bool GetByteOrder(lldb::ByteOrder &byte_order) const;
154 virtual llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
155 GetAuxvData() const = 0;
157 //----------------------------------------------------------------------
159 //----------------------------------------------------------------------
160 virtual bool GetExitStatus(lldb_private::ExitType *exit_type, int *status,
161 std::string &exit_description);
163 virtual bool SetExitStatus(lldb_private::ExitType exit_type, int status,
164 const char *exit_description,
165 bool bNotifyStateChange);
167 //----------------------------------------------------------------------
169 //----------------------------------------------------------------------
170 NativeThreadProtocolSP GetThreadAtIndex(uint32_t idx);
172 NativeThreadProtocolSP GetThreadByID(lldb::tid_t tid);
174 void SetCurrentThreadID(lldb::tid_t tid) { m_current_thread_id = tid; }
176 lldb::tid_t GetCurrentThreadID() { return m_current_thread_id; }
178 NativeThreadProtocolSP GetCurrentThread() {
179 return GetThreadByID(m_current_thread_id);
182 //----------------------------------------------------------------------
183 // Access to inferior stdio
184 //----------------------------------------------------------------------
185 virtual int GetTerminalFileDescriptor() { return m_terminal_fd; }
187 //----------------------------------------------------------------------
189 //----------------------------------------------------------------------
191 uint32_t GetStopID() const;
193 // ---------------------------------------------------------------------
194 // Callbacks for low-level process state changes
195 // ---------------------------------------------------------------------
196 class NativeDelegate {
198 virtual ~NativeDelegate() {}
200 virtual void InitializeDelegate(NativeProcessProtocol *process) = 0;
202 virtual void ProcessStateChanged(NativeProcessProtocol *process,
203 lldb::StateType state) = 0;
205 virtual void DidExec(NativeProcessProtocol *process) = 0;
208 //------------------------------------------------------------------
209 /// Register a native delegate.
211 /// Clients can register nofication callbacks by passing in a
212 /// NativeDelegate impl and passing it into this function.
214 /// Note: it is required that the lifetime of the
215 /// native_delegate outlive the NativeProcessProtocol.
217 /// @param[in] native_delegate
218 /// A NativeDelegate impl to be called when certain events
219 /// happen within the NativeProcessProtocol or related threads.
222 /// true if the delegate was registered successfully;
223 /// false if the delegate was already registered.
225 /// @see NativeProcessProtocol::NativeDelegate.
226 //------------------------------------------------------------------
227 bool RegisterNativeDelegate(NativeDelegate &native_delegate);
229 //------------------------------------------------------------------
230 /// Unregister a native delegate previously registered.
232 /// @param[in] native_delegate
233 /// A NativeDelegate impl previously registered with this process.
235 /// @return Returns \b true if the NativeDelegate was
236 /// successfully removed from the process, \b false otherwise.
238 /// @see NativeProcessProtocol::NativeDelegate
239 //------------------------------------------------------------------
240 bool UnregisterNativeDelegate(NativeDelegate &native_delegate);
242 virtual Error GetLoadedModuleFileSpec(const char *module_path,
243 FileSpec &file_spec) = 0;
245 virtual Error GetFileLoadAddress(const llvm::StringRef &file_name,
246 lldb::addr_t &load_addr) = 0;
248 //------------------------------------------------------------------
249 /// Launch a process for debugging. This method will create an concrete
250 /// instance of NativeProcessProtocol, based on the host platform.
251 /// (e.g. NativeProcessLinux on linux, etc.)
253 /// @param[in] launch_info
254 /// Information required to launch the process.
256 /// @param[in] native_delegate
257 /// The delegate that will receive messages regarding the
258 /// inferior. Must outlive the NativeProcessProtocol
261 /// @param[in] mainloop
262 /// The mainloop instance with which the process can register
263 /// callbacks. Must outlive the NativeProcessProtocol
266 /// @param[out] process_sp
267 /// On successful return from the method, this parameter
268 /// contains the shared pointer to the
269 /// NativeProcessProtocol that can be used to manipulate
270 /// the native process.
273 /// An error object indicating if the operation succeeded,
274 /// and if not, what error occurred.
275 //------------------------------------------------------------------
276 static Error Launch(ProcessLaunchInfo &launch_info,
277 NativeDelegate &native_delegate, MainLoop &mainloop,
278 NativeProcessProtocolSP &process_sp);
280 //------------------------------------------------------------------
281 /// Attach to an existing process. This method will create an concrete
282 /// instance of NativeProcessProtocol, based on the host platform.
283 /// (e.g. NativeProcessLinux on linux, etc.)
286 /// pid of the process locatable
288 /// @param[in] native_delegate
289 /// The delegate that will receive messages regarding the
290 /// inferior. Must outlive the NativeProcessProtocol
293 /// @param[in] mainloop
294 /// The mainloop instance with which the process can register
295 /// callbacks. Must outlive the NativeProcessProtocol
298 /// @param[out] process_sp
299 /// On successful return from the method, this parameter
300 /// contains the shared pointer to the
301 /// NativeProcessProtocol that can be used to manipulate
302 /// the native process.
305 /// An error object indicating if the operation succeeded,
306 /// and if not, what error occurred.
307 //------------------------------------------------------------------
308 static Error Attach(lldb::pid_t pid, NativeDelegate &native_delegate,
309 MainLoop &mainloop, NativeProcessProtocolSP &process_sp);
314 std::vector<NativeThreadProtocolSP> m_threads;
315 lldb::tid_t m_current_thread_id;
316 mutable std::recursive_mutex m_threads_mutex;
318 lldb::StateType m_state;
319 mutable std::recursive_mutex m_state_mutex;
321 lldb_private::ExitType m_exit_type;
323 std::string m_exit_description;
324 std::recursive_mutex m_delegates_mutex;
325 std::vector<NativeDelegate *> m_delegates;
326 NativeBreakpointList m_breakpoint_list;
327 NativeWatchpointList m_watchpoint_list;
328 HardwareBreakpointMap m_hw_breakpoints_map;
332 // Set of signal numbers that LLDB directly injects back to inferior
333 // without stopping it.
334 llvm::DenseSet<int> m_signals_to_ignore;
336 // lldb_private::Host calls should be used to launch a process for debugging,
338 // then the process should be attached to. When attaching to a process
339 // lldb_private::Host calls should be used to locate the process to attach to,
340 // and then this function should be called.
341 NativeProcessProtocol(lldb::pid_t pid);
343 // -----------------------------------------------------------
344 // Internal interface for state handling
345 // -----------------------------------------------------------
346 void SetState(lldb::StateType state, bool notify_delegates = true);
348 // Derived classes need not implement this. It can be used as a
349 // hook to clear internal caches that should be invalidated when
352 // Note this function is called with the state mutex obtained
354 virtual void DoStopIDBumped(uint32_t newBumpId);
356 // -----------------------------------------------------------
357 // Internal interface for software breakpoints
358 // -----------------------------------------------------------
359 Error SetSoftwareBreakpoint(lldb::addr_t addr, uint32_t size_hint);
362 GetSoftwareBreakpointTrapOpcode(size_t trap_opcode_size_hint,
363 size_t &actual_opcode_size,
364 const uint8_t *&trap_opcode_bytes) = 0;
366 // -----------------------------------------------------------
367 /// Notify the delegate that an exec occurred.
369 /// Provide a mechanism for a delegate to clear out any exec-
371 // -----------------------------------------------------------
372 void NotifyDidExec();
374 NativeThreadProtocolSP GetThreadByIDUnlocked(lldb::tid_t tid);
376 // -----------------------------------------------------------
377 // Static helper methods for derived classes.
378 // -----------------------------------------------------------
379 static Error ResolveProcessArchitecture(lldb::pid_t pid, ArchSpec &arch);
382 void SynchronouslyNotifyProcessStateChanged(lldb::StateType state);
386 #endif // #ifndef liblldb_NativeProcessProtocol_h_