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