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