LLVM API Documentation

Debugger.h

Go to the documentation of this file.
00001 //===- Debugger.h - LLVM debugger library interface -------------*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file is distributed under the University of Illinois Open Source
00006 // License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file defines the LLVM source-level debugger library interface.
00011 //
00012 //===----------------------------------------------------------------------===//
00013 
00014 #ifndef LLVM_DEBUGGER_DEBUGGER_H
00015 #define LLVM_DEBUGGER_DEBUGGER_H
00016 
00017 #include <string>
00018 #include <vector>
00019 
00020 namespace llvm {
00021   class Module;
00022   class InferiorProcess;
00023   class LLVMContext;
00024 
00025   /// Debugger class - This class implements the LLVM source-level debugger.
00026   /// This allows clients to handle the user IO processing without having to
00027   /// worry about how the debugger itself works.
00028   ///
00029   class Debugger {
00030     // State the debugger needs when starting and stopping the program.
00031     std::vector<std::string> ProgramArguments;
00032 
00033     // The environment to run the program with.  This should eventually be
00034     // changed to vector of strings when we allow the user to edit the
00035     // environment.
00036     const char * const *Environment;
00037 
00038     // Program - The currently loaded program, or null if none is loaded.
00039     Module *Program;
00040 
00041     // Process - The currently executing inferior process.
00042     InferiorProcess *Process;
00043 
00044     Debugger(const Debugger &);         // DO NOT IMPLEMENT
00045     void operator=(const Debugger &);   // DO NOT IMPLEMENT
00046   public:
00047     Debugger();
00048     ~Debugger();
00049 
00050     //===------------------------------------------------------------------===//
00051     // Methods for manipulating and inspecting the execution environment.
00052     //
00053 
00054     /// initializeEnvironment - Specify the environment the program should run
00055     /// with.  This is used to initialize the environment of the program to the
00056     /// environment of the debugger.
00057     void initializeEnvironment(const char *const *envp) {
00058       Environment = envp;
00059     }
00060 
00061     /// setWorkingDirectory - Specify the working directory for the program to
00062     /// be started from.
00063     void setWorkingDirectory(const std::string &Dir) {
00064       // FIXME: implement
00065     }
00066 
00067     template<typename It>
00068     void setProgramArguments(It I, It E) {
00069       ProgramArguments.assign(I, E);
00070     }
00071     unsigned getNumProgramArguments() const {
00072       return static_cast<unsigned>(ProgramArguments.size());
00073     }
00074     const std::string &getProgramArgument(unsigned i) const {
00075       return ProgramArguments[i];
00076     }
00077 
00078 
00079     //===------------------------------------------------------------------===//
00080     // Methods for manipulating and inspecting the program currently loaded.
00081     //
00082 
00083     /// isProgramLoaded - Return true if there is a program currently loaded.
00084     ///
00085     bool isProgramLoaded() const { return Program != 0; }
00086 
00087     /// getProgram - Return the LLVM module corresponding to the program.
00088     ///
00089     Module *getProgram() const { return Program; }
00090 
00091     /// getProgramPath - Get the path of the currently loaded program, or an
00092     /// empty string if none is loaded.
00093     std::string getProgramPath() const;
00094 
00095     /// loadProgram - If a program is currently loaded, unload it.  Then search
00096     /// the PATH for the specified program, loading it when found.  If the
00097     /// specified program cannot be found, an exception is thrown to indicate
00098     /// the error.
00099     void loadProgram(const std::string &Path, LLVMContext& Context);
00100 
00101     /// unloadProgram - If a program is running, kill it, then unload all traces
00102     /// of the current program.  If no program is loaded, this method silently
00103     /// succeeds.
00104     void unloadProgram();
00105 
00106     //===------------------------------------------------------------------===//
00107     // Methods for manipulating and inspecting the program currently running.
00108     //
00109     // If the program is running, and the debugger is active, then we know that
00110     // the program has stopped.  This being the case, we can inspect the
00111     // program, ask it for its source location, set breakpoints, etc.
00112     //
00113 
00114     /// isProgramRunning - Return true if a program is loaded and has a
00115     /// currently active instance.
00116     bool isProgramRunning() const { return Process != 0; }
00117 
00118     /// getRunningProcess - If there is no program running, throw an exception.
00119     /// Otherwise return the running process so that it can be inspected by the
00120     /// debugger.
00121     const InferiorProcess &getRunningProcess() const {
00122       if (Process == 0) throw "No process running.";
00123       return *Process;
00124     }
00125 
00126     /// createProgram - Create an instance of the currently loaded program,
00127     /// killing off any existing one.  This creates the program and stops it at
00128     /// the first possible moment.  If there is no program loaded or if there is
00129     /// a problem starting the program, this method throws an exception.
00130     void createProgram();
00131 
00132     /// killProgram - If the program is currently executing, kill off the
00133     /// process and free up any state related to the currently running program.
00134     /// If there is no program currently running, this just silently succeeds.
00135     /// If something horrible happens when killing the program, an exception
00136     /// gets thrown.
00137     void killProgram();
00138 
00139 
00140     //===------------------------------------------------------------------===//
00141     // Methods for continuing execution.  These methods continue the execution
00142     // of the program by some amount.  If the program is successfully stopped,
00143     // execution returns, otherwise an exception is thrown.
00144     //
00145     // NOTE: These methods should always be used in preference to directly
00146     // accessing the Dbg object, because these will delete the Process object if
00147     // the process unexpectedly dies.
00148     //
00149 
00150     /// stepProgram - Implement the 'step' command, continuing execution until
00151     /// the next possible stop point.
00152     void stepProgram();
00153 
00154     /// nextProgram - Implement the 'next' command, continuing execution until
00155     /// the next possible stop point that is in the current function.
00156     void nextProgram();
00157 
00158     /// finishProgram - Implement the 'finish' command, continuing execution
00159     /// until the specified frame ID returns.
00160     void finishProgram(void *Frame);
00161 
00162     /// contProgram - Implement the 'cont' command, continuing execution until
00163     /// the next breakpoint is encountered.
00164     void contProgram();
00165   };
00166 
00167   class NonErrorException {
00168     std::string Message;
00169   public:
00170     NonErrorException(const std::string &M) : Message(M) {}
00171     const std::string &getMessage() const { return Message; }
00172   };
00173 
00174 } // end namespace llvm
00175 
00176 #endif