1 //===-- CompileUnit.h -------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_CompUnit_h_
11 #define liblldb_CompUnit_h_
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"
20 namespace lldb_private {
21 //----------------------------------------------------------------------
22 /// @class CompileUnit CompileUnit.h "lldb/Symbol/CompileUnit.h"
23 /// @brief A class that describes a compilation unit.
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.
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 //----------------------------------------------------------------------
35 public std::enable_shared_from_this<CompileUnit>,
39 public SymbolContextScope
42 //------------------------------------------------------------------
43 /// Construct with a module, path, UID and language.
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.
50 /// The parent module that owns this compile unit. This value
51 /// must be a valid pointer value.
53 /// @param[in] user_data
54 /// User data where the SymbolFile parser can store data.
56 /// @param[in] pathname
57 /// The path to the source file for this compile unit.
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.
65 /// @param[in] language
66 /// A language enumeration type that describes the main language
67 /// of this compile unit.
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);
73 //------------------------------------------------------------------
74 /// Construct with a module, file spec, UID and language.
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.
81 /// The parent module that owns this compile unit. This value
82 /// must be a valid pointer value.
84 /// @param[in] user_data
85 /// User data where the SymbolFile parser can store data.
87 /// @param[in] file_spec
88 /// The file specification for the source file of this compile
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.
97 /// @param[in] language
98 /// A language enumeration type that describes the main language
99 /// of this compile unit.
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);
105 //------------------------------------------------------------------
107 //------------------------------------------------------------------
111 //------------------------------------------------------------------
112 /// Add a function to this compile unit.
114 /// Typically called by the SymbolFile plug-ins as they partially
115 /// parse the debug information.
117 /// @param[in] function_sp
118 /// A shared pointer to the a Function object.
119 //------------------------------------------------------------------
121 AddFunction(lldb::FunctionSP& function_sp);
123 //------------------------------------------------------------------
124 /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
126 /// @see SymbolContextScope
127 //------------------------------------------------------------------
129 CalculateSymbolContext(SymbolContext* sc);
131 virtual lldb::ModuleSP
132 CalculateSymbolContextModule ();
134 virtual CompileUnit *
135 CalculateSymbolContextCompileUnit ();
137 //------------------------------------------------------------------
138 /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
140 /// @see SymbolContextScope
141 //------------------------------------------------------------------
143 DumpSymbolContext(Stream *s);
149 SetLanguage(lldb::LanguageType language)
151 m_flags.Set(flagsParsedLanguage);
152 m_language = language;
156 GetDescription(Stream *s, lldb::DescriptionLevel level) const;
158 //------------------------------------------------------------------
159 /// Get a shared pointer to a function in this compile unit by
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.
168 /// An index into the function list.
171 /// A shared pointer to a function that might contain a NULL
172 /// Function class pointer.
173 //------------------------------------------------------------------
175 GetFunctionAtIndex (size_t idx);
177 //------------------------------------------------------------------
178 /// Dump the compile unit contents to the stream \a s.
181 /// The stream to which to dump the object descripton.
183 /// @param[in] show_context
184 /// If \b true, variables will dump their symbol context
186 //------------------------------------------------------------------
188 Dump (Stream *s, bool show_context) const;
190 //------------------------------------------------------------------
191 /// Find the line entry by line and optional inlined file spec.
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).
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.
204 /// @param[in] start_idx
205 /// The zero based index at which to start looking for matches.
208 /// The line number to search for.
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
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.
219 /// @param[out] line_entry
220 /// If non-NULL, a copy of the line entry that was found.
223 /// The zero based index of a matching line entry, or UINT32_MAX
224 /// if no matching line entry is found.
225 //------------------------------------------------------------------
227 FindLineEntry (uint32_t start_idx,
229 const FileSpec* file_spec_ptr,
231 LineEntry *line_entry);
233 //------------------------------------------------------------------
234 /// Get the line table for the compile unit.
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.
242 /// The line table object pointer, or NULL if this line table
243 /// hasn't been parsed yet.
244 //------------------------------------------------------------------
248 //------------------------------------------------------------------
249 /// Get the compile unit's support file list.
251 /// The support file list is used by the line table, and any objects
252 /// that have valid Declaration objects.
255 /// A support file list object.
256 //------------------------------------------------------------------
260 //------------------------------------------------------------------
261 /// Get the SymbolFile plug-in user data.
263 /// SymbolFile plug-ins can store user data to internal state or
264 /// objects to quickly allow them to parse more information for a
268 /// The user data stored with the CompileUnit when it was
270 //------------------------------------------------------------------
272 GetUserData () const;
274 //------------------------------------------------------------------
275 /// Get the variable list for a compile unit.
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.
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).
289 /// A shared pointer to a variable list, that can contain NULL
290 /// VariableList pointer if there are no global or static
292 //------------------------------------------------------------------
294 GetVariableList (bool can_create);
296 //------------------------------------------------------------------
297 /// Finds a function by user ID.
299 /// Typically used by SymbolFile plug-ins when partially parsing
300 /// the debug information to see if the function has been parsed
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.
310 /// A shared pointer to the function object that might contain
311 /// a NULL Function pointer.
312 //------------------------------------------------------------------
314 FindFunctionByUID (lldb::user_id_t uid);
316 //------------------------------------------------------------------
317 /// Set the line table for the compile unit.
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.
324 /// @param[in] line_table
325 /// A line table object pointer that this object now owns.
326 //------------------------------------------------------------------
328 SetLineTable(LineTable* line_table);
330 //------------------------------------------------------------------
331 /// Set accessor for the variable list.
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
337 /// @param[in] variable_list_sp
338 /// A shared pointer to a VariableList.
339 //------------------------------------------------------------------
341 SetVariableList (lldb::VariableListSP& variable_list_sp);
343 //------------------------------------------------------------------
344 /// Resolve symbol contexts by file and line.
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
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.
357 /// The line number to match against the compile unit's line
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
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.
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.
379 /// @param[out] sc_list
380 /// A SymbolContext list class that willl get any matching
381 /// entries appended to.
384 /// The number of new matches that were added to \a sc_list.
386 /// @see enum SymbolContext::Scope
387 //------------------------------------------------------------------
389 ResolveSymbolContext (const FileSpec& file_spec,
393 uint32_t resolve_scope,
394 SymbolContextList &sc_list);
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.
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?
417 DISALLOW_COPY_AND_ASSIGN (CompileUnit);
420 } // namespace lldb_private
422 #endif // liblldb_CompUnit_h_