LLVM API Documentation
00001 //===- InferiorProcess.h - Represent the program being debugged -*- C++ -*-===// 00002 // 00003 // The LLVM Compiler Infrastructure 00004 // 00005 // This file was developed by the LLVM research group and is distributed under 00006 // the University of Illinois Open Source License. See LICENSE.TXT for details. 00007 // 00008 //===----------------------------------------------------------------------===// 00009 // 00010 // This file defines the InferiorProcess class, which is used to represent, 00011 // inspect, and manipulate a process under the control of the LLVM debugger. 00012 // 00013 // This is an abstract class which should allow various different types of 00014 // implementations. Initially we implement a unix specific debugger backend 00015 // that does not require code generator support, but we could eventually use 00016 // code generator support with ptrace, support windows based targets, supported 00017 // remote targets, etc. 00018 // 00019 // If the inferior process unexpectedly dies, an attempt to communicate with it 00020 // will cause an InferiorProcessDead exception to be thrown, indicating the exit 00021 // code of the process. When this occurs, no methods on the InferiorProcess 00022 // class should be called except for the destructor. 00023 // 00024 //===----------------------------------------------------------------------===// 00025 00026 #ifndef LLVM_DEBUGGER_INFERIORPROCESS_H 00027 #define LLVM_DEBUGGER_INFERIORPROCESS_H 00028 00029 #include <string> 00030 #include <vector> 00031 00032 namespace llvm { 00033 class Module; 00034 class GlobalVariable; 00035 00036 /// InferiorProcessDead exception - This class is thrown by methods that 00037 /// communicate with the interior process if the process unexpectedly exits or 00038 /// dies. The instance variable indicates what the exit code of the process 00039 /// was, or -1 if unknown. 00040 class InferiorProcessDead { 00041 int ExitCode; 00042 public: 00043 InferiorProcessDead(int EC) : ExitCode(EC) {} 00044 int getExitCode() const { return ExitCode; } 00045 }; 00046 00047 /// InferiorProcess class - This class represents the process being debugged 00048 /// by the debugger. Objects of this class should not be stack allocated, 00049 /// because the destructor can throw exceptions. 00050 /// 00051 class InferiorProcess { 00052 Module *M; 00053 protected: 00054 InferiorProcess(Module *m) : M(m) {} 00055 public: 00056 /// create - Create an inferior process of the specified module, and 00057 /// stop it at the first opportunity. If there is a problem starting the 00058 /// program (for example, it has no main), throw an exception. 00059 static InferiorProcess *create(Module *M, 00060 const std::vector<std::string> &Arguments, 00061 const char * const *envp); 00062 00063 // InferiorProcess destructor - Kill the current process. If something 00064 // terrible happens, we throw an exception from the destructor. 00065 virtual ~InferiorProcess() {} 00066 00067 //===------------------------------------------------------------------===// 00068 // Status methods - These methods return information about the currently 00069 // stopped process. 00070 // 00071 00072 /// getStatus - Return a status message that is specific to the current type 00073 /// of inferior process that is created. This can return things like the 00074 /// PID of the inferior or other potentially interesting things. 00075 virtual std::string getStatus() const { 00076 return ""; 00077 } 00078 00079 //===------------------------------------------------------------------===// 00080 // Methods for inspecting the call stack. 00081 // 00082 00083 /// getPreviousFrame - Given the descriptor for the current stack frame, 00084 /// return the descriptor for the caller frame. This returns null when it 00085 /// runs out of frames. If Frame is null, the initial frame should be 00086 /// returned. 00087 virtual void *getPreviousFrame(void *Frame) const = 0; 00088 00089 /// getSubprogramDesc - Return the subprogram descriptor for the current 00090 /// stack frame. 00091 virtual const GlobalVariable *getSubprogramDesc(void *Frame) const = 0; 00092 00093 /// getFrameLocation - This method returns the source location where each 00094 /// stack frame is stopped. 00095 virtual void getFrameLocation(void *Frame, unsigned &LineNo, 00096 unsigned &ColNo, 00097 const GlobalVariable *&SourceDesc) const = 0; 00098 00099 //===------------------------------------------------------------------===// 00100 // Methods for manipulating breakpoints. 00101 // 00102 00103 /// addBreakpoint - This method adds a breakpoint at the specified line, 00104 /// column, and source file, and returns a unique identifier for it. 00105 /// 00106 /// It is up to the debugger to determine whether or not there is actually a 00107 /// stop-point that corresponds with the specified location. 00108 virtual unsigned addBreakpoint(unsigned LineNo, unsigned ColNo, 00109 const GlobalVariable *SourceDesc) = 0; 00110 00111 /// removeBreakpoint - This deletes the breakpoint with the specified ID 00112 /// number. 00113 virtual void removeBreakpoint(unsigned ID) = 0; 00114 00115 00116 //===------------------------------------------------------------------===// 00117 // Execution methods - These methods cause the program to continue execution 00118 // by some amount. If the program successfully stops, this returns. 00119 // Otherwise, if the program unexpectedly terminates, an InferiorProcessDead 00120 // exception is thrown. 00121 // 00122 00123 /// stepProgram - Implement the 'step' command, continuing execution until 00124 /// the next possible stop point. 00125 virtual void stepProgram() = 0; 00126 00127 /// finishProgram - Implement the 'finish' command, continuing execution 00128 /// until the current function returns. 00129 virtual void finishProgram(void *Frame) = 0; 00130 00131 /// contProgram - Implement the 'cont' command, continuing execution until 00132 /// a breakpoint is encountered. 00133 virtual void contProgram() = 0; 00134 }; 00135 } // end namespace llvm 00136 00137 #endif 00138