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