blob: 34e34e5514df37c6852b606e477fd8d81ce4b62b [file] [log] [blame]
//===-- CompileUnit.h -------------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
#ifndef LLDB_SYMBOL_COMPILEUNIT_H
#define LLDB_SYMBOL_COMPILEUNIT_H
#include "lldb/Core/FileSpecList.h"
#include "lldb/Core/ModuleChild.h"
#include "lldb/Core/SourceLocationSpec.h"
#include "lldb/Symbol/DebugMacros.h"
#include "lldb/Symbol/Function.h"
#include "lldb/Symbol/LineTable.h"
#include "lldb/Symbol/SourceModule.h"
#include "lldb/Utility/Stream.h"
#include "lldb/Utility/UserID.h"
#include "lldb/lldb-enumerations.h"
#include "llvm/ADT/DenseMap.h"
#include "llvm/ADT/DenseSet.h"
namespace lldb_private {
/// \class CompileUnit CompileUnit.h "lldb/Symbol/CompileUnit.h"
/// A class that describes a compilation unit.
///
/// A representation of a compilation unit, or compiled source file.
/// The UserID of the compile unit is specified by the SymbolFile plug-in and
/// can have any value as long as the value is unique within the Module that
/// owns this compile units.
///
/// Each compile unit has a list of functions, global and static variables,
/// support file list (include files and inlined source files), and a line
/// table.
class CompileUnit : public std::enable_shared_from_this<CompileUnit>,
public ModuleChild,
public UserID,
public SymbolContextScope {
public:
/// Construct with a module, path, UID and language.
///
/// Initialize the compile unit given the owning \a module, a path to
/// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the
/// source language type.
///
/// \param[in] module_sp
/// The parent module that owns this compile unit. This value
/// must be a valid pointer value.
///
/// \param[in] user_data
/// User data where the SymbolFile parser can store data.
///
/// \param[in] pathname
/// The path to the source file for this compile unit.
///
/// \param[in] uid
/// The user ID of the compile unit. This value is supplied by
/// the SymbolFile plug-in and should be a value that allows
/// the SymbolFile plug-in to easily locate and parse additional
/// information for the compile unit.
///
/// \param[in] language
/// A language enumeration type that describes the main language
/// of this compile unit.
///
/// \param[in] is_optimized
/// A value that can initialized with eLazyBoolYes, eLazyBoolNo
/// or eLazyBoolCalculate. If set to eLazyBoolCalculate, then
/// an extra call into SymbolVendor will be made to calculate if
/// the compile unit is optimized will be made when
/// CompileUnit::GetIsOptimized() is called.
///
/// \see lldb::LanguageType
CompileUnit(const lldb::ModuleSP &module_sp, void *user_data,
const char *pathname, lldb::user_id_t uid,
lldb::LanguageType language, lldb_private::LazyBool is_optimized);
/// Construct with a module, file spec, UID and language.
///
/// Initialize the compile unit given the owning \a module, a path to
/// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the
/// source language type.
///
/// \param[in] module_sp
/// The parent module that owns this compile unit. This value
/// must be a valid pointer value.
///
/// \param[in] user_data
/// User data where the SymbolFile parser can store data.
///
/// \param[in] file_spec
/// The file specification for the source file of this compile
/// unit.
///
/// \param[in] uid
/// The user ID of the compile unit. This value is supplied by
/// the SymbolFile plug-in and should be a value that allows
/// the plug-in to easily locate and parse
/// additional information for the compile unit.
///
/// \param[in] language
/// A language enumeration type that describes the main language
/// of this compile unit.
///
/// \param[in] is_optimized
/// A value that can initialized with eLazyBoolYes, eLazyBoolNo
/// or eLazyBoolCalculate. If set to eLazyBoolCalculate, then
/// an extra call into SymbolVendor will be made to calculate if
/// the compile unit is optimized will be made when
/// CompileUnit::GetIsOptimized() is called.
///
/// \see lldb::LanguageType
CompileUnit(const lldb::ModuleSP &module_sp, void *user_data,
const FileSpec &file_spec, lldb::user_id_t uid,
lldb::LanguageType language, lldb_private::LazyBool is_optimized);
/// Add a function to this compile unit.
///
/// Typically called by the SymbolFile plug-ins as they partially parse the
/// debug information.
///
/// \param[in] function_sp
/// A shared pointer to the Function object.
void AddFunction(lldb::FunctionSP &function_sp);
/// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
///
/// \see SymbolContextScope
void CalculateSymbolContext(SymbolContext *sc) override;
lldb::ModuleSP CalculateSymbolContextModule() override;
CompileUnit *CalculateSymbolContextCompileUnit() override;
/// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
///
/// \see SymbolContextScope
void DumpSymbolContext(Stream *s) override;
lldb::LanguageType GetLanguage();
void SetLanguage(lldb::LanguageType language) {
m_flags.Set(flagsParsedLanguage);
m_language = language;
}
void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
/// Apply a lambda to each function in this compile unit.
///
/// This provides raw access to the function shared pointer list and will not
/// cause the SymbolFile plug-in to parse any unparsed functions.
///
/// \note Prefer using FindFunctionByUID over this if possible.
///
/// \param[in] lambda
/// The lambda that should be applied to every function. The lambda can
/// return true if the iteration should be aborted earlier.
void ForeachFunction(
llvm::function_ref<bool(const lldb::FunctionSP &)> lambda) const;
/// Find a function in the compile unit based on the predicate matching_lambda
///
/// \param[in] matching_lambda
/// A predicate that will be used within FindFunction to evaluate each
/// FunctionSP in m_functions_by_uid. When the predicate returns true
/// FindFunction will return the corresponding FunctionSP.
///
/// \return
/// The first FunctionSP that the matching_lambda prediate returns true for.
lldb::FunctionSP FindFunction(
llvm::function_ref<bool(const lldb::FunctionSP &)> matching_lambda);
/// Dump the compile unit contents to the stream \a s.
///
/// \param[in] s
/// The stream to which to dump the object description.
///
/// \param[in] show_context
/// If \b true, variables will dump their symbol context
/// information.
void Dump(Stream *s, bool show_context) const;
/// Find the line entry by line and optional inlined file spec.
///
/// Finds the first line entry that has an index greater than \a start_idx
/// that matches \a line. If \a file_spec_ptr is NULL, then the search
/// matches line entries whose file matches the file for the compile unit.
/// If \a file_spec_ptr is not NULL, line entries must match the specified
/// file spec (for inlined line table entries).
///
/// Multiple calls to this function can find all entries that match a given
/// file and line by starting with \a start_idx equal to zero, and calling
/// this function back with the return value + 1.
///
/// \param[in] start_idx
/// The zero based index at which to start looking for matches.
///
/// \param[in] line
/// The line number to search for.
///
/// \param[in] file_spec_ptr
/// If non-NULL search for entries that match this file spec,
/// else if NULL, search for line entries that match the compile
/// unit file.
///
/// \param[in] exact
/// If \btrue match only if there is a line table entry for this line
/// number.
/// If \bfalse, find the line table entry equal to or after this line
/// number.
///
/// \param[out] line_entry
/// If non-NULL, a copy of the line entry that was found.
///
/// \return
/// The zero based index of a matching line entry, or UINT32_MAX
/// if no matching line entry is found.
uint32_t FindLineEntry(uint32_t start_idx, uint32_t line,
const FileSpec *file_spec_ptr, bool exact,
LineEntry *line_entry);
/// Return the primary source file associated with this compile unit.
const FileSpec &GetPrimaryFile() const { return m_file_spec; }
/// Get the line table for the compile unit.
///
/// Called by clients and the SymbolFile plug-in. The SymbolFile plug-ins
/// use this function to determine if the line table has be parsed yet.
/// Clients use this function to get the line table from a compile unit.
///
/// \return
/// The line table object pointer, or NULL if this line table
/// hasn't been parsed yet.
LineTable *GetLineTable();
DebugMacros *GetDebugMacros();
/// Apply a lambda to each external lldb::Module referenced by this
/// compilation unit. Recursively also descends into the referenced external
/// modules of any encountered compilation unit.
///
/// \param visited_symbol_files
/// A set of SymbolFiles that were already visited to avoid
/// visiting one file more than once.
///
/// \param[in] lambda
/// The lambda that should be applied to every function. The lambda can
/// return true if the iteration should be aborted earlier.
///
/// \return
/// If the lambda early-exited, this function returns true to
/// propagate the early exit.
virtual bool ForEachExternalModule(
llvm::DenseSet<lldb_private::SymbolFile *> &visited_symbol_files,
llvm::function_ref<bool(Module &)> lambda);
/// Get the compile unit's support file list.
///
/// The support file list is used by the line table, and any objects that
/// have valid Declaration objects.
///
/// \return
/// A support file list object.
const FileSpecList &GetSupportFiles();
/// Get the compile unit's imported module list.
///
/// This reports all the imports that the compile unit made, including the
/// current module.
///
/// \return
/// A list of imported modules.
const std::vector<SourceModule> &GetImportedModules();
/// Get the SymbolFile plug-in user data.
///
/// SymbolFile plug-ins can store user data to internal state or objects to
/// quickly allow them to parse more information for a given object.
///
/// \return
/// The user data stored with the CompileUnit when it was
/// constructed.
void *GetUserData() const;
/// Get the variable list for a compile unit.
///
/// Called by clients to get the variable list for a compile unit. The
/// variable list will contain all global and static variables that were
/// defined at the compile unit level.
///
/// \param[in] can_create
/// If \b true, the variable list will be parsed on demand. If
/// \b false, the current variable list will be returned even
/// if it contains a NULL VariableList object (typically
/// called by dumping routines that want to display only what
/// has currently been parsed).
///
/// \return
/// A shared pointer to a variable list, that can contain NULL
/// VariableList pointer if there are no global or static
/// variables.
lldb::VariableListSP GetVariableList(bool can_create);
/// Finds a function by user ID.
///
/// Typically used by SymbolFile plug-ins when partially parsing the debug
/// information to see if the function has been parsed yet.
///
/// \param[in] uid
/// The user ID of the function to find. This value is supplied
/// by the SymbolFile plug-in and should be a value that
/// allows the plug-in to easily locate and parse additional
/// information in the function.
///
/// \return
/// A shared pointer to the function object that might contain
/// a NULL Function pointer.
lldb::FunctionSP FindFunctionByUID(lldb::user_id_t uid);
/// Set the line table for the compile unit.
///
/// Called by the SymbolFile plug-in when if first parses the line table and
/// hands ownership of the line table to this object. The compile unit owns
/// the line table object and will delete the object when it is deleted.
///
/// \param[in] line_table
/// A line table object pointer that this object now owns.
void SetLineTable(LineTable *line_table);
void SetSupportFiles(const FileSpecList &support_files);
void SetSupportFiles(FileSpecList &&support_files);
void SetDebugMacros(const DebugMacrosSP &debug_macros);
/// Set accessor for the variable list.
///
/// Called by the SymbolFile plug-ins after they have parsed the variable
/// lists and are ready to hand ownership of the list over to this object.
///
/// \param[in] variable_list_sp
/// A shared pointer to a VariableList.
void SetVariableList(lldb::VariableListSP &variable_list_sp);
/// Resolve symbol contexts by file and line.
///
/// Given a file in \a src_location_spec, find all instances and
/// append them to the supplied symbol context list \a sc_list.
///
/// \param[in] src_location_spec
/// The \a src_location_spec containing the \a file_spec, the line and the
/// column of the symbol to look for. Also hold the inlines and
/// exact_match flags.
///
/// If check_inlines is \b true, this function will also match any inline
/// file and line matches. If \b false, the compile unit's
/// file specification must match \a file_spec for any matches
/// to be returned.
///
/// If exact_match is \b true, only resolve the context if \a line and \a
/// column exists in the line table. If \b false, resolve the context to
/// the closest line greater than \a line in the line table.
///
/// \param[in] resolve_scope
/// For each matching line entry, this bitfield indicates what
/// values within each SymbolContext that gets added to \a
/// sc_list will be resolved. See the SymbolContext::Scope
/// enumeration for a list of all available bits that can be
/// resolved. Only SymbolContext entries that can be resolved
/// using a LineEntry base address will be able to be resolved.
///
/// \param[out] sc_list
/// A SymbolContext list class that will get any matching
/// entries appended to.
///
/// \see enum SymbolContext::Scope
void ResolveSymbolContext(const SourceLocationSpec &src_location_spec,
lldb::SymbolContextItem resolve_scope,
SymbolContextList &sc_list);
/// Get whether compiler optimizations were enabled for this compile unit
///
/// "optimized" means that the debug experience may be difficult for the
/// user to understand. Variables may not be available when the developer
/// would expect them, stepping through the source lines in the function may
/// appear strange, etc.
///
/// \return
/// Returns 'true' if this compile unit was compiled with
/// optimization. 'false' indicates that either the optimization
/// is unknown, or this compile unit was built without optimization.
bool GetIsOptimized();
/// Returns the number of functions in this compile unit
size_t GetNumFunctions() const { return m_functions_by_uid.size(); }
protected:
/// User data for the SymbolFile parser to store information into.
void *m_user_data;
/// The programming language enumeration value.
lldb::LanguageType m_language;
/// Compile unit flags that help with partial parsing.
Flags m_flags;
/// Maps UIDs to functions.
llvm::DenseMap<lldb::user_id_t, lldb::FunctionSP> m_functions_by_uid;
/// All modules, including the current module, imported by this
/// compile unit.
std::vector<SourceModule> m_imported_modules;
/// The primary file associated with this compile unit.
FileSpec m_file_spec;
/// Files associated with this compile unit's line table and
/// declarations.
FileSpecList m_support_files;
/// Line table that will get parsed on demand.
std::unique_ptr<LineTable> m_line_table_up;
/// Debug macros that will get parsed on demand.
DebugMacrosSP m_debug_macros_sp;
/// Global and static variable list that will get parsed on demand.
lldb::VariableListSP m_variables;
/// eLazyBoolYes if this compile unit was compiled with
/// optimization.
lldb_private::LazyBool m_is_optimized;
private:
enum {
flagsParsedAllFunctions =
(1u << 0), ///< Have we already parsed all our functions
flagsParsedVariables =
(1u << 1), ///< Have we already parsed globals and statics?
flagsParsedSupportFiles = (1u << 2), ///< Have we already parsed the support
///files for this compile unit?
flagsParsedLineTable =
(1u << 3), ///< Have we parsed the line table already?
flagsParsedLanguage = (1u << 4), ///< Have we parsed the language already?
flagsParsedImportedModules =
(1u << 5), ///< Have we parsed the imported modules already?
flagsParsedDebugMacros =
(1u << 6) ///< Have we parsed the debug macros already?
};
CompileUnit(const CompileUnit &) = delete;
const CompileUnit &operator=(const CompileUnit &) = delete;
const char *GetCachedLanguage() const;
};
} // namespace lldb_private
#endif // LLDB_SYMBOL_COMPILEUNIT_H