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