1 //===-- ProcessMonitor.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_ProcessMonitor_H_
11 #define liblldb_ProcessMonitor_H_
12 
13 #include <semaphore.h>
14 #include <signal.h>
15 
16 #include <mutex>
17 
18 #include "lldb/Host/HostThread.h"
19 #include "lldb/Utility/FileSpec.h"
20 #include "lldb/lldb-types.h"
21 
22 namespace lldb_private {
23 class Status;
24 class Module;
25 class Scalar;
26 } // End lldb_private namespace.
27 
28 class ProcessFreeBSD;
29 class Operation;
30 
31 /// @class ProcessMonitor
32 /// Manages communication with the inferior (debugee) process.
33 ///
34 /// Upon construction, this class prepares and launches an inferior process
35 /// for debugging.
36 ///
37 /// Changes in the inferior process state are propagated to the associated
38 /// ProcessFreeBSD instance by calling ProcessFreeBSD::SendMessage with the
39 /// appropriate ProcessMessage events.
40 ///
41 /// A purposely minimal set of operations are provided to interrogate and change
42 /// the inferior process state.
43 class ProcessMonitor {
44 public:
45   /// Launches an inferior process ready for debugging.  Forms the
46   /// implementation of Process::DoLaunch.
47   ProcessMonitor(ProcessFreeBSD *process, lldb_private::Module *module,
48                  char const *argv[], lldb_private::Environment env,
49                  const lldb_private::FileSpec &stdin_file_spec,
50                  const lldb_private::FileSpec &stdout_file_spec,
51                  const lldb_private::FileSpec &stderr_file_spec,
52                  const lldb_private::FileSpec &working_dir,
53                  const lldb_private::ProcessLaunchInfo &launch_info,
54                  lldb_private::Status &error);
55 
56   ProcessMonitor(ProcessFreeBSD *process, lldb::pid_t pid,
57                  lldb_private::Status &error);
58 
59   ~ProcessMonitor();
60 
61   /// Provides the process number of debugee.
GetPID()62   lldb::pid_t GetPID() const { return m_pid; }
63 
64   /// Returns the process associated with this ProcessMonitor.
GetProcess()65   ProcessFreeBSD &GetProcess() { return *m_process; }
66 
67   /// Returns a file descriptor to the controlling terminal of the inferior
68   /// process.
69   ///
70   /// Reads from this file descriptor yield both the standard output and
71   /// standard error of this debugee.  Even if stderr and stdout were
72   /// redirected on launch it may still happen that data is available on this
73   /// descriptor (if the inferior process opens /dev/tty, for example). This
74   /// descriptor is closed after a call to StopMonitor().
75   ///
76   /// If this monitor was attached to an existing process this method returns
77   /// -1.
GetTerminalFD()78   int GetTerminalFD() const { return m_terminal_fd; }
79 
80   /// Reads @p size bytes from address @vm_adder in the inferior process
81   /// address space.
82   ///
83   /// This method is provided to implement Process::DoReadMemory.
84   size_t ReadMemory(lldb::addr_t vm_addr, void *buf, size_t size,
85                     lldb_private::Status &error);
86 
87   /// Writes @p size bytes from address @p vm_adder in the inferior process
88   /// address space.
89   ///
90   /// This method is provided to implement Process::DoWriteMemory.
91   size_t WriteMemory(lldb::addr_t vm_addr, const void *buf, size_t size,
92                      lldb_private::Status &error);
93 
94   /// Reads the contents from the register identified by the given
95   /// (architecture dependent) offset.
96   ///
97   /// This method is provided for use by RegisterContextFreeBSD derivatives.
98   bool ReadRegisterValue(lldb::tid_t tid, unsigned offset, const char *reg_name,
99                          unsigned size, lldb_private::RegisterValue &value);
100 
101   /// Writes the given value to the register identified by the given
102   /// (architecture dependent) offset.
103   ///
104   /// This method is provided for use by RegisterContextFreeBSD derivatives.
105   bool WriteRegisterValue(lldb::tid_t tid, unsigned offset,
106                           const char *reg_name,
107                           const lldb_private::RegisterValue &value);
108 
109   /// Reads the contents from the debug register identified by the given
110   /// (architecture dependent) offset.
111   ///
112   /// This method is provided for use by RegisterContextFreeBSD derivatives.
113   bool ReadDebugRegisterValue(lldb::tid_t tid, unsigned offset,
114                               const char *reg_name, unsigned size,
115                               lldb_private::RegisterValue &value);
116 
117   /// Writes the given value to the debug register identified by the given
118   /// (architecture dependent) offset.
119   ///
120   /// This method is provided for use by RegisterContextFreeBSD derivatives.
121   bool WriteDebugRegisterValue(lldb::tid_t tid, unsigned offset,
122                                const char *reg_name,
123                                const lldb_private::RegisterValue &value);
124   /// Reads all general purpose registers into the specified buffer.
125   bool ReadGPR(lldb::tid_t tid, void *buf, size_t buf_size);
126 
127   /// Reads all floating point registers into the specified buffer.
128   bool ReadFPR(lldb::tid_t tid, void *buf, size_t buf_size);
129 
130   /// Reads the specified register set into the specified buffer.
131   ///
132   /// This method is provided for use by RegisterContextFreeBSD derivatives.
133   bool ReadRegisterSet(lldb::tid_t tid, void *buf, size_t buf_size,
134                        unsigned int regset);
135 
136   /// Writes all general purpose registers into the specified buffer.
137   bool WriteGPR(lldb::tid_t tid, void *buf, size_t buf_size);
138 
139   /// Writes all floating point registers into the specified buffer.
140   bool WriteFPR(lldb::tid_t tid, void *buf, size_t buf_size);
141 
142   /// Writes the specified register set into the specified buffer.
143   ///
144   /// This method is provided for use by RegisterContextFreeBSD derivatives.
145   bool WriteRegisterSet(lldb::tid_t tid, void *buf, size_t buf_size,
146                         unsigned int regset);
147 
148   /// Reads the value of the thread-specific pointer for a given thread ID.
149   bool ReadThreadPointer(lldb::tid_t tid, lldb::addr_t &value);
150 
151   /// Returns current thread IDs in process
152   size_t GetCurrentThreadIDs(std::vector<lldb::tid_t> &thread_ids);
153 
154   /// Writes a ptrace_lwpinfo structure corresponding to the given thread ID
155   /// to the memory region pointed to by @p lwpinfo.
156   bool GetLwpInfo(lldb::tid_t tid, void *lwpinfo, int &error_no);
157 
158   /// Suspends or unsuspends a thread prior to process resume or step.
159   bool ThreadSuspend(lldb::tid_t tid, bool suspend);
160 
161   /// Writes the raw event message code (vis-a-vis PTRACE_GETEVENTMSG)
162   /// corresponding to the given thread IDto the memory pointed to by @p
163   /// message.
164   bool GetEventMessage(lldb::tid_t tid, unsigned long *message);
165 
166   /// Resumes the process.  If @p signo is anything but
167   /// LLDB_INVALID_SIGNAL_NUMBER, deliver that signal to the process.
168   bool Resume(lldb::tid_t unused, uint32_t signo);
169 
170   /// Single steps the process.  If @p signo is anything but
171   /// LLDB_INVALID_SIGNAL_NUMBER, deliver that signal to the process.
172   bool SingleStep(lldb::tid_t unused, uint32_t signo);
173 
174   /// Terminate the traced process.
175   bool Kill();
176 
177   lldb_private::Status Detach(lldb::tid_t tid);
178 
179   void StopMonitor();
180 
181   // Waits for the initial stop message from a new thread.
182   bool WaitForInitialTIDStop(lldb::tid_t tid);
183 
184 private:
185   ProcessFreeBSD *m_process;
186 
187   lldb_private::HostThread m_operation_thread;
188   lldb_private::HostThread m_monitor_thread;
189   lldb::pid_t m_pid;
190 
191   int m_terminal_fd;
192 
193   // current operation which must be executed on the privileged thread
194   Operation *m_operation;
195   std::mutex m_operation_mutex;
196 
197   // semaphores notified when Operation is ready to be processed and when
198   // the operation is complete.
199   sem_t m_operation_pending;
200   sem_t m_operation_done;
201 
202   struct OperationArgs {
203     OperationArgs(ProcessMonitor *monitor);
204 
205     ~OperationArgs();
206 
207     ProcessMonitor *m_monitor;   // The monitor performing the attach.
208     sem_t m_semaphore;           // Posted to once operation complete.
209     lldb_private::Status m_error; // Set if process operation failed.
210   };
211 
212   /// @class LauchArgs
213   ///
214   /// Simple structure to pass data to the thread responsible for launching a
215   /// child process.
216   struct LaunchArgs : OperationArgs {
217     LaunchArgs(ProcessMonitor *monitor, lldb_private::Module *module,
218                char const **argv, lldb_private::Environment env,
219                const lldb_private::FileSpec &stdin_file_spec,
220                const lldb_private::FileSpec &stdout_file_spec,
221                const lldb_private::FileSpec &stderr_file_spec,
222                const lldb_private::FileSpec &working_dir);
223 
224     ~LaunchArgs();
225 
226     lldb_private::Module *m_module; // The executable image to launch.
227     char const **m_argv;            // Process arguments.
228     lldb_private::Environment m_env;                // Process environment.
229     const lldb_private::FileSpec m_stdin_file_spec; // Redirect stdin or empty.
230     const lldb_private::FileSpec
231         m_stdout_file_spec; // Redirect stdout or empty.
232     const lldb_private::FileSpec
233         m_stderr_file_spec;                     // Redirect stderr or empty.
234     const lldb_private::FileSpec m_working_dir; // Working directory or empty.
235   };
236 
237   void StartLaunchOpThread(LaunchArgs *args, lldb_private::Status &error);
238 
239   static void *LaunchOpThread(void *arg);
240 
241   static bool Launch(LaunchArgs *args);
242 
243   struct AttachArgs : OperationArgs {
244     AttachArgs(ProcessMonitor *monitor, lldb::pid_t pid);
245 
246     ~AttachArgs();
247 
248     lldb::pid_t m_pid; // pid of the process to be attached.
249   };
250 
251   void StartAttachOpThread(AttachArgs *args, lldb_private::Status &error);
252 
253   static void *AttachOpThread(void *args);
254 
255   static void Attach(AttachArgs *args);
256 
257   static void ServeOperation(OperationArgs *args);
258 
259   static bool DupDescriptor(const lldb_private::FileSpec &file_spec, int fd,
260                             int flags);
261 
262   static bool MonitorCallback(ProcessMonitor *monitor, lldb::pid_t pid,
263                               bool exited, int signal, int status);
264 
265   static ProcessMessage MonitorSIGTRAP(ProcessMonitor *monitor,
266                                        const siginfo_t *info, lldb::pid_t pid);
267 
268   static ProcessMessage MonitorSignal(ProcessMonitor *monitor,
269                                       const siginfo_t *info, lldb::pid_t pid);
270 
271   void DoOperation(Operation *op);
272 
273   /// Stops the child monitor thread.
274   void StopMonitoringChildProcess();
275 
276   /// Stops the operation thread used to attach/launch a process.
277   void StopOpThread();
278 };
279 
280 #endif // #ifndef liblldb_ProcessMonitor_H_
281