LLVM API Documentation

InferiorProcess.h

Go to the documentation of this file.
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