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