contrib/llvm/tools/lldb/include/lldb/Symbol/CompileUnit.h

   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
 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_