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