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
22namespace lldb_private
23{
24class Error;
25class Module;
26class Scalar;
27} // End lldb_private namespace.
28
29class ProcessLinux;
30class 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/// ProcessLinux instance by calling ProcessLinux::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.
44class ProcessMonitor
45{
46public:
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                   lldb_private::Error &error);
59
60    ProcessMonitor(ProcessPOSIX *process,
61                   lldb::pid_t pid,
62                   lldb_private::Error &error);
63
64    ~ProcessMonitor();
65
66    enum ResumeSignals
67    {
68        eResumeSignalNone = 0
69    };
70
71    /// Provides the process number of debugee.
72    lldb::pid_t
73    GetPID() const { return m_pid; }
74
75    /// Returns the process associated with this ProcessMonitor.
76    ProcessLinux &
77    GetProcess() { return *m_process; }
78
79    /// Returns a file descriptor to the controlling terminal of the inferior
80    /// process.
81    ///
82    /// Reads from this file descriptor yield both the standard output and
83    /// standard error of this debugee.  Even if stderr and stdout were
84    /// redirected on launch it may still happen that data is available on this
85    /// descriptor (if the inferior process opens /dev/tty, for example).
86    ///
87    /// If this monitor was attached to an existing process this method returns
88    /// -1.
89    int
90    GetTerminalFD() const { return m_terminal_fd; }
91
92    /// Reads @p size bytes from address @vm_adder in the inferior process
93    /// address space.
94    ///
95    /// This method is provided to implement Process::DoReadMemory.
96    size_t
97    ReadMemory(lldb::addr_t vm_addr, void *buf, size_t size,
98               lldb_private::Error &error);
99
100    /// Writes @p size bytes from address @p vm_adder in the inferior process
101    /// address space.
102    ///
103    /// This method is provided to implement Process::DoWriteMemory.
104    size_t
105    WriteMemory(lldb::addr_t vm_addr, const void *buf, size_t size,
106                lldb_private::Error &error);
107
108    /// Reads the contents from the register identified by the given (architecture
109    /// dependent) offset.
110    ///
111    /// This method is provided for use by RegisterContextLinux derivatives.
112    bool
113    ReadRegisterValue(lldb::tid_t tid, unsigned offset, const char *reg_name,
114                      unsigned size, lldb_private::RegisterValue &value);
115
116    /// Writes the given value to the register identified by the given
117    /// (architecture dependent) offset.
118    ///
119    /// This method is provided for use by RegisterContextLinux derivatives.
120    bool
121    WriteRegisterValue(lldb::tid_t tid, unsigned offset, const char *reg_name,
122                       const lldb_private::RegisterValue &value);
123
124    /// Reads all general purpose registers into the specified buffer.
125    bool
126    ReadGPR(lldb::tid_t tid, void *buf, size_t buf_size);
127
128    /// Reads generic floating point registers into the specified buffer.
129    bool
130    ReadFPR(lldb::tid_t tid, void *buf, size_t buf_size);
131
132    /// Reads the specified register set into the specified buffer.
133    /// For instance, the extended floating-point register set.
134    bool
135    ReadRegisterSet(lldb::tid_t tid, void *buf, size_t buf_size, unsigned int regset);
136
137    /// Writes all general purpose registers into the specified buffer.
138    bool
139    WriteGPR(lldb::tid_t tid, void *buf, size_t buf_size);
140
141    /// Writes generic floating point registers into the specified buffer.
142    bool
143    WriteFPR(lldb::tid_t tid, void *buf, size_t buf_size);
144
145    /// Writes the specified register set into the specified buffer.
146    /// For instance, the extended floating-point register set.
147    bool
148    WriteRegisterSet(lldb::tid_t tid, void *buf, size_t buf_size, unsigned int regset);
149
150    /// Writes a siginfo_t structure corresponding to the given thread ID to the
151    /// memory region pointed to by @p siginfo.
152    bool
153    GetSignalInfo(lldb::tid_t tid, void *siginfo, int &ptrace_err);
154
155    /// Writes the raw event message code (vis-a-vis PTRACE_GETEVENTMSG)
156    /// corresponding to the given thread IDto the memory pointed to by @p
157    /// message.
158    bool
159    GetEventMessage(lldb::tid_t tid, unsigned long *message);
160
161    /// Resumes the given thread.  If @p signo is anything but
162    /// LLDB_INVALID_SIGNAL_NUMBER, deliver that signal to the thread.
163    bool
164    Resume(lldb::tid_t tid, uint32_t signo);
165
166    /// Single steps the given thread.  If @p signo is anything but
167    /// LLDB_INVALID_SIGNAL_NUMBER, deliver that signal to the thread.
168    bool
169    SingleStep(lldb::tid_t tid, uint32_t signo);
170
171    /// Sends the inferior process a PTRACE_KILL signal.  The inferior will
172    /// still exists and can be interrogated.  Once resumed it will exit as
173    /// though it received a SIGKILL.
174    bool
175    BringProcessIntoLimbo();
176
177    lldb_private::Error
178    Detach(lldb::tid_t tid);
179
180    /// Stops the monitoring the child process thread.
181    void
182    StopMonitor();
183
184    /// Stops the requested thread and waits for the stop signal.
185    bool
186    StopThread(lldb::tid_t tid);
187
188private:
189    ProcessLinux *m_process;
190
191    lldb::thread_t m_operation_thread;
192    lldb::thread_t m_monitor_thread;
193    lldb::pid_t m_pid;
194    int m_terminal_fd;
195
196
197    lldb_private::Mutex m_server_mutex;
198    int m_client_fd;
199    int m_server_fd;
200
201    struct OperationArgs
202    {
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::Error m_error;    // Set if process operation failed.
210    };
211
212    /// @class LauchArgs
213    ///
214    /// @brief Simple structure to pass data to the thread responsible for
215    /// launching a child process.
216    struct LaunchArgs : OperationArgs
217    {
218        LaunchArgs(ProcessMonitor *monitor,
219                   lldb_private::Module *module,
220                   char const **argv,
221                   char const **envp,
222                   const char *stdin_path,
223                   const char *stdout_path,
224                   const char *stderr_path,
225                   const char *working_dir);
226
227        ~LaunchArgs();
228
229        lldb_private::Module *m_module; // The executable image to launch.
230        char const **m_argv;            // Process arguments.
231        char const **m_envp;            // Process environment.
232        const char *m_stdin_path;       // Redirect stdin or NULL.
233        const char *m_stdout_path;      // Redirect stdout or NULL.
234        const char *m_stderr_path;      // Redirect stderr or NULL.
235        const char *m_working_dir;      // Working directory or NULL.
236    };
237
238    void
239    StartLaunchOpThread(LaunchArgs *args, lldb_private::Error &error);
240
241    static void *
242    LaunchOpThread(void *arg);
243
244    static bool
245    Launch(LaunchArgs *args);
246
247    bool
248    EnableIPC();
249
250    struct AttachArgs : OperationArgs
251    {
252        AttachArgs(ProcessMonitor *monitor,
253                   lldb::pid_t pid);
254
255        ~AttachArgs();
256
257        lldb::pid_t m_pid;              // pid of the process to be attached.
258    };
259
260    void
261    StartAttachOpThread(AttachArgs *args, lldb_private::Error &error);
262
263    static void *
264    AttachOpThread(void *args);
265
266    static bool
267    Attach(AttachArgs *args);
268
269    static bool
270    SetDefaultPtraceOpts(const lldb::pid_t);
271
272    static void
273    ServeOperation(OperationArgs *args);
274
275    static bool
276    DupDescriptor(const char *path, int fd, int flags);
277
278    static bool
279    MonitorCallback(void *callback_baton,
280                    lldb::pid_t pid, bool exited, int signal, int status);
281
282    static ProcessMessage
283    MonitorSIGTRAP(ProcessMonitor *monitor,
284                   const siginfo_t *info, lldb::pid_t pid);
285
286    static ProcessMessage
287    MonitorSignal(ProcessMonitor *monitor,
288                  const siginfo_t *info, lldb::pid_t pid);
289
290    static ProcessMessage::CrashReason
291    GetCrashReasonForSIGSEGV(const siginfo_t *info);
292
293    static ProcessMessage::CrashReason
294    GetCrashReasonForSIGILL(const siginfo_t *info);
295
296    static ProcessMessage::CrashReason
297    GetCrashReasonForSIGFPE(const siginfo_t *info);
298
299    static ProcessMessage::CrashReason
300    GetCrashReasonForSIGBUS(const siginfo_t *info);
301
302    void
303    DoOperation(Operation *op);
304
305    /// Stops the child monitor thread.
306    void
307    StopMonitoringChildProcess();
308
309    /// Stops the operation thread used to attach/launch a process.
310    void
311    StopOpThread();
312
313    void
314    CloseFD(int &fd);
315};
316
317#endif // #ifndef liblldb_ProcessMonitor_H_
318