include/llvm/Debugger/InferiorProcess.h

   1 //===- InferiorProcess.h - Represent the program being debugged -*- 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 // This file defines the InferiorProcess class, which is used to represent,
  11 // inspect, and manipulate a process under the control of the LLVM debugger.
  12 //
  13 // This is an abstract class which should allow various different types of
  14 // implementations.  Initially we implement a unix specific debugger backend
  15 // that does not require code generator support, but we could eventually use
  16 // code generator support with ptrace, support windows based targets, supported
  17 // remote targets, etc.
  18 //
  19 // If the inferior process unexpectedly dies, an attempt to communicate with it
  20 // will cause an InferiorProcessDead exception to be thrown, indicating the exit
  21 // code of the process.  When this occurs, no methods on the InferiorProcess
  22 // class should be called except for the destructor.
  23 //
  24 //===----------------------------------------------------------------------===//
  25
  26 #ifndef LLVM_DEBUGGER_INFERIORPROCESS_H
  27 #define LLVM_DEBUGGER_INFERIORPROCESS_H
  28
  29 #include <string>
  30 #include <vector>
  31
  32 namespace llvm {
  33   class Module;
  34   class GlobalVariable;
  35
  36   /// InferiorProcessDead exception - This class is thrown by methods that
  37   /// communicate with the interior process if the process unexpectedly exits or
  38   /// dies.  The instance variable indicates what the exit code of the process
  39   /// was, or -1 if unknown.
  40   class InferiorProcessDead {
  41     int ExitCode;
  42   public:
  43     InferiorProcessDead(int EC) : ExitCode(EC) {}
  44     int getExitCode() const { return ExitCode; }
  45   };
  46
  47   /// InferiorProcess class - This class represents the process being debugged
  48   /// by the debugger.  Objects of this class should not be stack allocated,
  49   /// because the destructor can throw exceptions.
  50   ///
  51   class InferiorProcess {
  52     Module *M;
  53   protected:
  54     InferiorProcess(Module *m) : M(m) {}
  55   public:
  56     /// create - Create an inferior process of the specified module, and
  57     /// stop it at the first opportunity.  If there is a problem starting the
  58     /// program (for example, it has no main), throw an exception.
  59     static InferiorProcess *create(Module *M,
  60                                    const std::vector<std::string> &Arguments,
  61                                    const char * const *envp);
  62
  63     // InferiorProcess destructor - Kill the current process.  If something
  64     // terrible happens, we throw an exception from the destructor.
  65     virtual ~InferiorProcess() {}
  66
  67     //===------------------------------------------------------------------===//
  68     // Status methods - These methods return information about the currently
  69     // stopped process.
  70     //
  71
  72     /// getStatus - Return a status message that is specific to the current type
  73     /// of inferior process that is created.  This can return things like the
  74     /// PID of the inferior or other potentially interesting things.
  75     virtual std::string getStatus() const {
  76       return "";
  77     }
  78
  79     //===------------------------------------------------------------------===//
  80     // Methods for inspecting the call stack.
  81     //
  82
  83     /// getPreviousFrame - Given the descriptor for the current stack frame,
  84     /// return the descriptor for the caller frame.  This returns null when it
  85     /// runs out of frames.  If Frame is null, the initial frame should be
  86     /// returned.
  87     virtual void *getPreviousFrame(void *Frame) const = 0;
  88
  89     /// getSubprogramDesc - Return the subprogram descriptor for the current
  90     /// stack frame.
  91     virtual const GlobalVariable *getSubprogramDesc(void *Frame) const = 0;
  92
  93     /// getFrameLocation - This method returns the source location where each
  94     /// stack frame is stopped.
  95     virtual void getFrameLocation(void *Frame, unsigned &LineNo,
  96                                   unsigned &ColNo,
  97                                   const GlobalVariable *&SourceDesc) const = 0;
  98
  99     //===------------------------------------------------------------------===//
 100     // Methods for manipulating breakpoints.
 101     //
 102
 103     /// addBreakpoint - This method adds a breakpoint at the specified line,
 104     /// column, and source file, and returns a unique identifier for it.
 105     ///
 106     /// It is up to the debugger to determine whether or not there is actually a
 107     /// stop-point that corresponds with the specified location.
 108     virtual unsigned addBreakpoint(unsigned LineNo, unsigned ColNo,
 109                                    const GlobalVariable *SourceDesc) = 0;
 110
 111     /// removeBreakpoint - This deletes the breakpoint with the specified ID
 112     /// number.
 113     virtual void removeBreakpoint(unsigned ID) = 0;
 114
 115
 116     //===------------------------------------------------------------------===//
 117     // Execution methods - These methods cause the program to continue execution
 118     // by some amount.  If the program successfully stops, this returns.
 119     // Otherwise, if the program unexpectedly terminates, an InferiorProcessDead
 120     // exception is thrown.
 121     //
 122
 123     /// stepProgram - Implement the 'step' command, continuing execution until
 124     /// the next possible stop point.
 125     virtual void stepProgram() = 0;
 126
 127     /// finishProgram - Implement the 'finish' command, continuing execution
 128     /// until the current function returns.
 129     virtual void finishProgram(void *Frame) = 0;
 130
 131     /// contProgram - Implement the 'cont' command, continuing execution until
 132     /// a breakpoint is encountered.
 133     virtual void contProgram() = 0;
 134   };
 135 }  // end namespace llvm
 136
 137 #endif