include/llvm/Debugger/Debugger.h

   1 //===- Debugger.h - LLVM debugger library interface -------------*- 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 LLVM source-level debugger library interface.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_DEBUGGER_DEBUGGER_H
  15 #define LLVM_DEBUGGER_DEBUGGER_H
  16
  17 #include <string>
  18 #include <vector>
  19
  20 namespace llvm {
  21   class Module;
  22   class InferiorProcess;
  23   class LLVMContext;
  24
  25   /// Debugger class - This class implements the LLVM source-level debugger.
  26   /// This allows clients to handle the user IO processing without having to
  27   /// worry about how the debugger itself works.
  28   ///
  29   class Debugger {
  30     // State the debugger needs when starting and stopping the program.
  31     std::vector<std::string> ProgramArguments;
  32
  33     // The environment to run the program with.  This should eventually be
  34     // changed to vector of strings when we allow the user to edit the
  35     // environment.
  36     const char * const *Environment;
  37
  38     // Program - The currently loaded program, or null if none is loaded.
  39     Module *Program;
  40
  41     // Process - The currently executing inferior process.
  42     InferiorProcess *Process;
  43
  44     Debugger(const Debugger &);         // DO NOT IMPLEMENT
  45     void operator=(const Debugger &);   // DO NOT IMPLEMENT
  46   public:
  47     Debugger();
  48     ~Debugger();
  49
  50     //===------------------------------------------------------------------===//
  51     // Methods for manipulating and inspecting the execution environment.
  52     //
  53
  54     /// initializeEnvironment - Specify the environment the program should run
  55     /// with.  This is used to initialize the environment of the program to the
  56     /// environment of the debugger.
  57     void initializeEnvironment(const char *const *envp) {
  58       Environment = envp;
  59     }
  60
  61     /// setWorkingDirectory - Specify the working directory for the program to
  62     /// be started from.
  63     void setWorkingDirectory(const std::string &Dir) {
  64       // FIXME: implement
  65     }
  66
  67     template<typename It>
  68     void setProgramArguments(It I, It E) {
  69       ProgramArguments.assign(I, E);
  70     }
  71     unsigned getNumProgramArguments() const {
  72       return static_cast<unsigned>(ProgramArguments.size());
  73     }
  74     const std::string &getProgramArgument(unsigned i) const {
  75       return ProgramArguments[i];
  76     }
  77
  78
  79     //===------------------------------------------------------------------===//
  80     // Methods for manipulating and inspecting the program currently loaded.
  81     //
  82
  83     /// isProgramLoaded - Return true if there is a program currently loaded.
  84     ///
  85     bool isProgramLoaded() const { return Program != 0; }
  86
  87     /// getProgram - Return the LLVM module corresponding to the program.
  88     ///
  89     Module *getProgram() const { return Program; }
  90
  91     /// getProgramPath - Get the path of the currently loaded program, or an
  92     /// empty string if none is loaded.
  93     std::string getProgramPath() const;
  94
  95     /// loadProgram - If a program is currently loaded, unload it.  Then search
  96     /// the PATH for the specified program, loading it when found.  If the
  97     /// specified program cannot be found, an exception is thrown to indicate
  98     /// the error.
  99     void loadProgram(const std::string &Path, LLVMContext* Context);
 100
 101     /// unloadProgram - If a program is running, kill it, then unload all traces
 102     /// of the current program.  If no program is loaded, this method silently
 103     /// succeeds.
 104     void unloadProgram();
 105
 106     //===------------------------------------------------------------------===//
 107     // Methods for manipulating and inspecting the program currently running.
 108     //
 109     // If the program is running, and the debugger is active, then we know that
 110     // the program has stopped.  This being the case, we can inspect the
 111     // program, ask it for its source location, set breakpoints, etc.
 112     //
 113
 114     /// isProgramRunning - Return true if a program is loaded and has a
 115     /// currently active instance.
 116     bool isProgramRunning() const { return Process != 0; }
 117
 118     /// getRunningProcess - If there is no program running, throw an exception.
 119     /// Otherwise return the running process so that it can be inspected by the
 120     /// debugger.
 121     const InferiorProcess &getRunningProcess() const {
 122       if (Process == 0) throw "No process running.";
 123       return *Process;
 124     }
 125
 126     /// createProgram - Create an instance of the currently loaded program,
 127     /// killing off any existing one.  This creates the program and stops it at
 128     /// the first possible moment.  If there is no program loaded or if there is
 129     /// a problem starting the program, this method throws an exception.
 130     void createProgram();
 131
 132     /// killProgram - If the program is currently executing, kill off the
 133     /// process and free up any state related to the currently running program.
 134     /// If there is no program currently running, this just silently succeeds.
 135     /// If something horrible happens when killing the program, an exception
 136     /// gets thrown.
 137     void killProgram();
 138
 139
 140     //===------------------------------------------------------------------===//
 141     // Methods for continuing execution.  These methods continue the execution
 142     // of the program by some amount.  If the program is successfully stopped,
 143     // execution returns, otherwise an exception is thrown.
 144     //
 145     // NOTE: These methods should always be used in preference to directly
 146     // accessing the Dbg object, because these will delete the Process object if
 147     // the process unexpectedly dies.
 148     //
 149
 150     /// stepProgram - Implement the 'step' command, continuing execution until
 151     /// the next possible stop point.
 152     void stepProgram();
 153
 154     /// nextProgram - Implement the 'next' command, continuing execution until
 155     /// the next possible stop point that is in the current function.
 156     void nextProgram();
 157
 158     /// finishProgram - Implement the 'finish' command, continuing execution
 159     /// until the specified frame ID returns.
 160     void finishProgram(void *Frame);
 161
 162     /// contProgram - Implement the 'cont' command, continuing execution until
 163     /// the next breakpoint is encountered.
 164     void contProgram();
 165   };
 166
 167   class NonErrorException {
 168     std::string Message;
 169   public:
 170     NonErrorException(const std::string &M) : Message(M) {}
 171     const std::string &getMessage() const { return Message; }
 172   };
 173
 174 } // end namespace llvm
 175
 176 #endif