LLVM API Documentation
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