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