LLVM API Documentation
00001 //===- ProgramInfo.h - Information about the loaded program -----*- 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 various pieces of information about the currently loaded 00011 // program. One instance of this object is created every time a program is 00012 // loaded, and destroyed every time it is unloaded. 00013 // 00014 // The various pieces of information gathered about the source program are all 00015 // designed to be extended by various SourceLanguage implementations. This 00016 // allows source languages to keep any extended information that they support in 00017 // the derived class portions of the class. 00018 // 00019 //===----------------------------------------------------------------------===// 00020 00021 #ifndef LLVM_DEBUGGER_PROGRAMINFO_H 00022 #define LLVM_DEBUGGER_PROGRAMINFO_H 00023 00024 #include <string> 00025 #include <map> 00026 #include <vector> 00027 00028 namespace llvm { 00029 class GlobalVariable; 00030 class Module; 00031 class SourceFile; 00032 class SourceLanguage; 00033 class ProgramInfo; 00034 00035 /// SourceLanguageCache - SourceLanguage implementations are allowed to cache 00036 /// stuff in the ProgramInfo object. The only requirement we have on these 00037 /// instances is that they are destroyable. 00038 struct SourceLanguageCache { 00039 virtual ~SourceLanguageCache() {} 00040 }; 00041 00042 /// SourceFileInfo - One instance of this structure is created for each 00043 /// source file in the program. 00044 /// 00045 class SourceFileInfo { 00046 /// BaseName - The filename of the source file. 00047 std::string BaseName; 00048 00049 /// Directory - The working directory of this source file when it was 00050 /// compiled. 00051 std::string Directory; 00052 00053 /// Version - The version of the LLVM debug information that this file was 00054 /// compiled with. 00055 unsigned Version; 00056 00057 /// Language - The source language that the file was compiled with. This 00058 /// pointer is never null. 00059 /// 00060 const SourceLanguage *Language; 00061 00062 /// Descriptor - The LLVM Global Variable which describes the source file. 00063 /// 00064 const GlobalVariable *Descriptor; 00065 00066 /// SourceText - The body of this source file, or null if it has not yet 00067 /// been loaded. 00068 mutable SourceFile *SourceText; 00069 public: 00070 SourceFileInfo(const GlobalVariable *Desc, const SourceLanguage &Lang); 00071 ~SourceFileInfo(); 00072 00073 const std::string &getBaseName() const { return BaseName; } 00074 const std::string &getDirectory() const { return Directory; } 00075 unsigned getDebugVersion() const { return Version; } 00076 const GlobalVariable *getDescriptor() const { return Descriptor; } 00077 SourceFile &getSourceText() const; 00078 00079 const SourceLanguage &getLanguage() const { return *Language; } 00080 }; 00081 00082 00083 /// SourceFunctionInfo - An instance of this class is used to represent each 00084 /// source function in the program. 00085 /// 00086 class SourceFunctionInfo { 00087 /// Name - This contains an abstract name that is potentially useful to the 00088 /// end-user. If there is no explicit support for the current language, 00089 /// then this string is used to identify the function. 00090 std::string Name; 00091 00092 /// Descriptor - The descriptor for this function. 00093 /// 00094 const GlobalVariable *Descriptor; 00095 00096 /// SourceFile - The file that this function is defined in. 00097 /// 00098 const SourceFileInfo *SourceFile; 00099 00100 /// LineNo, ColNo - The location of the first stop-point in the function. 00101 /// These are computed on demand. 00102 mutable unsigned LineNo, ColNo; 00103 00104 public: 00105 SourceFunctionInfo(ProgramInfo &PI, const GlobalVariable *Desc); 00106 virtual ~SourceFunctionInfo() {} 00107 00108 /// getSymbolicName - Return a human-readable symbolic name to identify the 00109 /// function (for example, in stack traces). 00110 virtual std::string getSymbolicName() const { return Name; } 00111 00112 /// getDescriptor - This returns the descriptor for the function. 00113 /// 00114 const GlobalVariable *getDescriptor() const { return Descriptor; } 00115 00116 /// getSourceFile - This returns the source file that defines the function. 00117 /// 00118 const SourceFileInfo &getSourceFile() const { return *SourceFile; } 00119 00120 /// getSourceLocation - This method returns the location of the first 00121 /// stopping point in the function. If the body of the function cannot be 00122 /// found, this returns zeros for both values. 00123 void getSourceLocation(unsigned &LineNo, unsigned &ColNo) const; 00124 }; 00125 00126 00127 /// ProgramInfo - This object contains information about the loaded program. 00128 /// When a new program is loaded, an instance of this class is created. When 00129 /// the program is unloaded, the instance is destroyed. This object basically 00130 /// manages the lazy computation of information useful for the debugger. 00131 class ProgramInfo { 00132 Module *M; 00133 00134 /// ProgramTimeStamp - This is the timestamp of the executable file that we 00135 /// currently have loaded into the debugger. 00136 unsigned long long ProgramTimeStamp; 00137 00138 /// SourceFiles - This map is used to transform source file descriptors into 00139 /// their corresponding SourceFileInfo objects. This mapping owns the 00140 /// memory for the SourceFileInfo objects. 00141 /// 00142 bool SourceFilesIsComplete; 00143 std::map<const GlobalVariable*, SourceFileInfo*> SourceFiles; 00144 00145 /// SourceFileIndex - Mapping from source file basenames to the information 00146 /// about the file. Note that there can be filename collisions, so this is 00147 /// a multimap. This map is populated incrementally as the user interacts 00148 /// with the program, through the getSourceFileFromDesc method. If ALL of 00149 /// the source files are needed, the getSourceFiles() method scans the 00150 /// entire program looking for them. 00151 /// 00152 std::multimap<std::string, SourceFileInfo*> SourceFileIndex; 00153 00154 /// SourceFunctions - This map contains entries functions in the source 00155 /// program. If SourceFunctionsIsComplete is true, then this is ALL of the 00156 /// functions in the program are in this map. 00157 bool SourceFunctionsIsComplete; 00158 std::map<const GlobalVariable*, SourceFunctionInfo*> SourceFunctions; 00159 00160 /// LanguageCaches - Each source language is permitted to keep a per-program 00161 /// cache of information specific to whatever it needs. This vector is 00162 /// effectively a small map from the languages that are active in the 00163 /// program to their caches. This can be accessed by the language by the 00164 /// "getLanguageCache" method. 00165 std::vector<std::pair<const SourceLanguage*, 00166 SourceLanguageCache*> > LanguageCaches; 00167 public: 00168 ProgramInfo(Module *m); 00169 ~ProgramInfo(); 00170 00171 /// getProgramTimeStamp - Return the time-stamp of the program when it was 00172 /// loaded. 00173 unsigned long long getProgramTimeStamp() const { return ProgramTimeStamp; } 00174 00175 //===------------------------------------------------------------------===// 00176 // Interfaces to the source code files that make up the program. 00177 // 00178 00179 /// getSourceFile - Return source file information for the specified source 00180 /// file descriptor object, adding it to the collection as needed. This 00181 /// method always succeeds (is unambiguous), and is always efficient. 00182 /// 00183 const SourceFileInfo &getSourceFile(const GlobalVariable *Desc); 00184 00185 /// getSourceFile - Look up the file with the specified name. If there is 00186 /// more than one match for the specified filename, prompt the user to pick 00187 /// one. If there is no source file that matches the specified name, throw 00188 /// an exception indicating that we can't find the file. Otherwise, return 00189 /// the file information for that file. 00190 /// 00191 /// If the source file hasn't been discovered yet in the program, this 00192 /// method might have to index the whole program by calling the 00193 /// getSourceFiles() method. 00194 /// 00195 const SourceFileInfo &getSourceFile(const std::string &Filename); 00196 00197 /// getSourceFiles - Index all of the source files in the program and return 00198 /// them. This information is lazily computed the first time that it is 00199 /// requested. Since this information can take a long time to compute, the 00200 /// user is given a chance to cancel it. If this occurs, an exception is 00201 /// thrown. 00202 const std::map<const GlobalVariable*, SourceFileInfo*> & 00203 getSourceFiles(bool RequiresCompleteMap = true); 00204 00205 //===------------------------------------------------------------------===// 00206 // Interfaces to the functions that make up the program. 00207 // 00208 00209 /// getFunction - Return source function information for the specified 00210 /// function descriptor object, adding it to the collection as needed. This 00211 /// method always succeeds (is unambiguous), and is always efficient. 00212 /// 00213 const SourceFunctionInfo &getFunction(const GlobalVariable *Desc); 00214 00215 /// getSourceFunctions - Index all of the functions in the program and 00216 /// return them. This information is lazily computed the first time that it 00217 /// is requested. Since this information can take a long time to compute, 00218 /// the user is given a chance to cancel it. If this occurs, an exception 00219 /// is thrown. 00220 const std::map<const GlobalVariable*, SourceFunctionInfo*> & 00221 getSourceFunctions(bool RequiresCompleteMap = true); 00222 00223 /// addSourceFunctionsRead - Return true if the source functions map is 00224 /// complete: that is, all functions in the program have been read in. 00225 bool allSourceFunctionsRead() const { return SourceFunctionsIsComplete; } 00226 00227 /// getLanguageCache - This method is used to build per-program caches of 00228 /// information, such as the functions or types visible to the program. 00229 /// This can be used by SourceLanguage implementations because it requires 00230 /// an accessible [sl]::CacheType typedef, where [sl] is the C++ type of the 00231 /// source-language subclass. 00232 template<typename SL> 00233 typename SL::CacheType &getLanguageCache(const SL *L) { 00234 for (unsigned i = 0, e = LanguageCaches.size(); i != e; ++i) 00235 if (LanguageCaches[i].first == L) 00236 return *(typename SL::CacheType*)LanguageCaches[i].second; 00237 typename SL::CacheType *NewCache = L->createSourceLanguageCache(*this); 00238 LanguageCaches.push_back(std::make_pair(L, NewCache)); 00239 return *NewCache; 00240 } 00241 }; 00242 00243 } // end namespace llvm 00244 00245 #endif