CompileUnit.h revision 0be1edd34ff46e017b1b973c5a57e3de9f613baf
1//===-- CompileUnit.h -------------------------------------------*- 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#ifndef liblldb_CompUnit_h_ 11#define liblldb_CompUnit_h_ 12 13#include "lldb/Symbol/Function.h" 14#include "lldb/Core/FileSpecList.h" 15#include "lldb/Core/Language.h" 16#include "lldb/Core/ModuleChild.h" 17#include "lldb/Core/Stream.h" 18#include "lldb/Core/UserID.h" 19 20namespace lldb_private { 21//---------------------------------------------------------------------- 22/// @class CompileUnit CompileUnit.h "lldb/Symbol/CompileUnit.h" 23/// @brief A class that describes a compilation unit. 24/// 25/// A representation of a compilation unit, or compiled source file. 26/// The UserID of the compile unit is specified by the SymbolFile 27/// plug-in and can have any value as long as the value is unique 28/// within the Module that owns this compile units. 29/// 30/// Each compile unit has a list of functions, global and static 31/// variables, support file list (include files and inlined source 32/// files), and a line table. 33//---------------------------------------------------------------------- 34class CompileUnit : 35 public STD_ENABLE_SHARED_FROM_THIS(CompileUnit), 36 public ModuleChild, 37 public FileSpec, 38 public UserID, 39 public Language, 40 public SymbolContextScope 41{ 42public: 43 //------------------------------------------------------------------ 44 /// Construct with a module, path, UID and language. 45 /// 46 /// Initialize the compile unit given the owning \a module, a path 47 /// to convert into a FileSpec, the SymbolFile plug-in supplied 48 /// \a uid, and the source language type. 49 /// 50 /// @param[in] module 51 /// The parent module that owns this compile unit. This value 52 /// must be a valid pointer value. 53 /// 54 /// @param[in] user_data 55 /// User data where the SymbolFile parser can store data. 56 /// 57 /// @param[in] pathname 58 /// The path to the source file for this compile unit. 59 /// 60 /// @param[in] uid 61 /// The user ID of the compile unit. This value is supplied by 62 /// the SymbolFile plug-in and should be a value that allows 63 /// the SymbolFile plug-in to easily locate and parse additional 64 /// information for the compile unit. 65 /// 66 /// @param[in] language 67 /// A language enumeration type that describes the main language 68 /// of this compile unit. 69 /// 70 /// @see lldb::LanguageType 71 //------------------------------------------------------------------ 72 CompileUnit(const lldb::ModuleSP &module_sp, void *user_data, const char *pathname, lldb::user_id_t uid, lldb::LanguageType language); 73 74 //------------------------------------------------------------------ 75 /// Construct with a module, file spec, UID and language. 76 /// 77 /// Initialize the compile unit given the owning \a module, a path 78 /// to convert into a FileSpec, the SymbolFile plug-in supplied 79 /// \a uid, and the source language type. 80 /// 81 /// @param[in] module 82 /// The parent module that owns this compile unit. This value 83 /// must be a valid pointer value. 84 /// 85 /// @param[in] user_data 86 /// User data where the SymbolFile parser can store data. 87 /// 88 /// @param[in] file_spec 89 /// The file specification for the source file of this compile 90 /// unit. 91 /// 92 /// @param[in] uid 93 /// The user ID of the compile unit. This value is supplied by 94 /// the SymbolFile plug-in and should be a value that allows 95 /// the plug-in to easily locate and parse 96 /// additional information for the compile unit. 97 /// 98 /// @param[in] language 99 /// A language enumeration type that describes the main language 100 /// of this compile unit. 101 /// 102 /// @see lldb::LanguageType 103 //------------------------------------------------------------------ 104 CompileUnit(const lldb::ModuleSP &module_sp, void *user_data, const FileSpec &file_spec, lldb::user_id_t uid, lldb::LanguageType language); 105 106 //------------------------------------------------------------------ 107 /// Destructor 108 //------------------------------------------------------------------ 109 virtual 110 ~CompileUnit(); 111 112 //------------------------------------------------------------------ 113 /// Add a function to this compile unit. 114 /// 115 /// Typically called by the SymbolFile plug-ins as they partially 116 /// parse the debug information. 117 /// 118 /// @param[in] function_sp 119 /// A shared pointer to the a Function object. 120 //------------------------------------------------------------------ 121 void 122 AddFunction(lldb::FunctionSP& function_sp); 123 124 //------------------------------------------------------------------ 125 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*) 126 /// 127 /// @see SymbolContextScope 128 //------------------------------------------------------------------ 129 virtual void 130 CalculateSymbolContext(SymbolContext* sc); 131 132 virtual lldb::ModuleSP 133 CalculateSymbolContextModule (); 134 135 virtual CompileUnit * 136 CalculateSymbolContextCompileUnit (); 137 138 //------------------------------------------------------------------ 139 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*) 140 /// 141 /// @see SymbolContextScope 142 //------------------------------------------------------------------ 143 virtual void 144 DumpSymbolContext(Stream *s); 145 146 147 void 148 GetDescription(Stream *s, lldb::DescriptionLevel level) const; 149 150 //------------------------------------------------------------------ 151 /// Get a shared pointer to a function in this compile unit by 152 /// index. 153 /// 154 /// Typically called when iterating though all functions in a 155 /// compile unit after all functions have been parsed. This provides 156 /// raw access to the function shared pointer list and will not 157 /// cause the SymbolFile plug-in to parse any unparsed functions. 158 /// 159 /// @param[in] idx 160 /// An index into the function list. 161 /// 162 /// @return 163 /// A shared pointer to a function that might contain a NULL 164 /// Function class pointer. 165 //------------------------------------------------------------------ 166 lldb::FunctionSP 167 GetFunctionAtIndex (size_t idx); 168 169 //------------------------------------------------------------------ 170 /// Dump the compile unit contents to the stream \a s. 171 /// 172 /// @param[in] s 173 /// The stream to which to dump the object descripton. 174 /// 175 /// @param[in] show_context 176 /// If \b true, variables will dump their symbol context 177 /// information. 178 //------------------------------------------------------------------ 179 void 180 Dump (Stream *s, bool show_context) const; 181 182 //------------------------------------------------------------------ 183 /// Find the line entry by line and optional inlined file spec. 184 /// 185 /// Finds the first line entry that has an index greater than 186 /// \a start_idx that matches \a line. If \a file_spec_ptr 187 /// is NULL, then the search matches line entries whose file matches 188 /// the file for the compile unit. If \a file_spec_ptr is 189 /// not NULL, line entries must match the specified file spec (for 190 /// inlined line table entries). 191 /// 192 /// Multiple calls to this function can find all entries that match 193 /// a given file and line by starting with \a start_idx equal to zero, 194 /// and calling this function back with the return valeu + 1. 195 /// 196 /// @param[in] start_idx 197 /// The zero based index at which to start looking for matches. 198 /// 199 /// @param[in] line 200 /// The line number to search for. 201 /// 202 /// @param[in] file_spec_ptr 203 /// If non-NULL search for entries that match this file spec, 204 /// else if NULL, search for line entries that match the compile 205 /// unit file. 206 /// 207 /// @param[in] exact 208 /// If \btrue match only if there is a line table entry for this line number. 209 /// If \bfalse, find the line table entry equal to or after this line number. 210 /// 211 /// @param[out] line_entry 212 /// If non-NULL, a copy of the line entry that was found. 213 /// 214 /// @return 215 /// The zero based index of a matching line entry, or UINT32_MAX 216 /// if no matching line entry is found. 217 //------------------------------------------------------------------ 218 uint32_t 219 FindLineEntry (uint32_t start_idx, 220 uint32_t line, 221 const FileSpec* file_spec_ptr, 222 bool exact, 223 LineEntry *line_entry); 224 225 //------------------------------------------------------------------ 226 /// Get the line table for the compile unit. 227 /// 228 /// Called by clients and the SymbolFile plug-in. The SymbolFile 229 /// plug-ins use this function to determine if the line table has 230 /// be parsed yet. Clients use this function to get the line table 231 /// from a compile unit. 232 /// 233 /// @return 234 /// The line table object pointer, or NULL if this line table 235 /// hasn't been parsed yet. 236 //------------------------------------------------------------------ 237 LineTable* 238 GetLineTable (); 239 240 //------------------------------------------------------------------ 241 /// Get the compile unit's support file list. 242 /// 243 /// The support file list is used by the line table, and any objects 244 /// that have valid Declaration objects. 245 /// 246 /// @return 247 /// A support file list object. 248 //------------------------------------------------------------------ 249 FileSpecList& 250 GetSupportFiles (); 251 252 //------------------------------------------------------------------ 253 /// Get the SymbolFile plug-in user data. 254 /// 255 /// SymbolFile plug-ins can store user data to internal state or 256 /// objects to quickly allow them to parse more information for a 257 /// given object. 258 /// 259 /// @return 260 /// The user data stored with the CompileUnit when it was 261 /// constructed. 262 //------------------------------------------------------------------ 263 void * 264 GetUserData () const; 265 266 //------------------------------------------------------------------ 267 /// Get the variable list for a compile unit. 268 /// 269 /// Called by clients to get the variable list for a compile unit. 270 /// The variable list will contain all global and static variables 271 /// that were defined at the compile unit level. 272 /// 273 /// @param[in] can_create 274 /// If \b true, the variable list will be parsed on demand. If 275 /// \b false, the current variable list will be returned even 276 /// if it contains a NULL VariableList object (typically 277 /// called by dumping routines that want to display only what 278 /// has currently been parsed). 279 /// 280 /// @return 281 /// A shared pointer to a variable list, that can contain NULL 282 /// VariableList pointer if there are no global or static 283 /// variables. 284 //------------------------------------------------------------------ 285 lldb::VariableListSP 286 GetVariableList (bool can_create); 287 288 //------------------------------------------------------------------ 289 /// Finds a function by user ID. 290 /// 291 /// Typically used by SymbolFile plug-ins when partially parsing 292 /// the debug information to see if the function has been parsed 293 /// yet. 294 /// 295 /// @param[in] uid 296 /// The user ID of the function to find. This value is supplied 297 /// by the SymbolFile plug-in and should be a value that 298 /// allows the plug-in to easily locate and parse additional 299 /// information in the function. 300 /// 301 /// @return 302 /// A shared pointer to the function object that might contain 303 /// a NULL Function pointer. 304 //------------------------------------------------------------------ 305 lldb::FunctionSP 306 FindFunctionByUID (lldb::user_id_t uid); 307 308 //------------------------------------------------------------------ 309 /// Set the line table for the compile unit. 310 /// 311 /// Called by the SymbolFile plug-in when if first parses the line 312 /// table and hands ownership of the line table to this object. The 313 /// compile unit owns the line table object and will delete the 314 /// object when it is deleted. 315 /// 316 /// @param[in] line_table 317 /// A line table object pointer that this object now owns. 318 //------------------------------------------------------------------ 319 void 320 SetLineTable(LineTable* line_table); 321 322 //------------------------------------------------------------------ 323 /// Set accessor for the variable list. 324 /// 325 /// Called by the SymbolFile plug-ins after they have parsed the 326 /// variable lists and are ready to hand ownership of the list over 327 /// to this object. 328 /// 329 /// @param[in] variable_list_sp 330 /// A shared pointer to a VariableList. 331 //------------------------------------------------------------------ 332 void 333 SetVariableList (lldb::VariableListSP& variable_list_sp); 334 335 //------------------------------------------------------------------ 336 /// Resolve symbol contexts by file and line. 337 /// 338 /// Given a file in \a file_spec, and a line number, find all 339 /// instances and append them to the supplied symbol context list 340 /// \a sc_list. 341 /// 342 /// @param[in] file_spec 343 /// A file specification. If \a file_spec contains no directory 344 /// information, only the basename will be used when matching 345 /// contexts. If the directory in \a file_spec is valid, a 346 /// complete file specification match will be performed. 347 /// 348 /// @param[in] line 349 /// The line number to match against the compile unit's line 350 /// tables. 351 /// 352 /// @param[in] check_inlines 353 /// If \b true this function will also match any inline 354 /// file and line matches. If \b false, the compile unit's 355 /// file specification must match \a file_spec for any matches 356 /// to be returned. 357 /// 358 /// @param[in] exact 359 /// If true, only resolve the context if \a line exists in the line table. 360 /// If false, resolve the context to the closest line greater than \a line 361 /// in the line table. 362 /// 363 /// @param[in] resolve_scope 364 /// For each matching line entry, this bitfield indicates what 365 /// values within each SymbolContext that gets added to \a 366 /// sc_list will be resolved. See the SymbolContext::Scope 367 /// enumeration for a list of all available bits that can be 368 /// resolved. Only SymbolContext entries that can be resolved 369 /// using a LineEntry base address will be able to be resolved. 370 /// 371 /// @param[out] sc_list 372 /// A SymbolContext list class that willl get any matching 373 /// entries appended to. 374 /// 375 /// @return 376 /// The number of new matches that were added to \a sc_list. 377 /// 378 /// @see enum SymbolContext::Scope 379 //------------------------------------------------------------------ 380 uint32_t 381 ResolveSymbolContext (const FileSpec& file_spec, 382 uint32_t line, 383 bool check_inlines, 384 bool exact, 385 uint32_t resolve_scope, 386 SymbolContextList &sc_list); 387 388 389protected: 390 void *m_user_data; ///< User data for the SymbolFile parser to store information into. 391 Flags m_flags; ///< Compile unit flags that help with partial parsing. 392 std::vector<lldb::FunctionSP> m_functions; ///< The sparsely populated list of shared pointers to functions 393 ///< that gets populated as functions get partially parsed. 394 FileSpecList m_support_files; ///< Files associated with this compile unit's line table and declarations. 395 std::auto_ptr<LineTable> m_line_table_ap; ///< Line table that will get parsed on demand. 396 lldb::VariableListSP m_variables; ///< Global and static variable list that will get parsed on demand. 397 398private: 399 enum 400 { 401 flagsParsedAllFunctions = (1 << 0), ///< Have we already parsed all our functions 402 flagsParsedVariables = (1 << 1), ///< Have we already parsed globals and statics? 403 flagsParsedSupportFiles = (1 << 2), ///< Have we already parsed the support files for this compile unit? 404 flagsParsedLineTable = (1 << 3) ///< Have we parsed the line table already? 405 }; 406 407 DISALLOW_COPY_AND_ASSIGN (CompileUnit); 408}; 409 410} // namespace lldb_private 411 412#endif // liblldb_CompUnit_h_ 413