lldb/Symbol/Block.h

//===-- Block.h -------------------------------------------------*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//

#ifndef liblldb_Block_h_
#define liblldb_Block_h_

#include "lldb/lldb-private.h"
#include "lldb/Core/AddressRange.h"
#include "lldb/Core/Stream.h"
#include "lldb/Core/UserID.h"
#include "lldb/Core/VMRange.h"
#include "lldb/Symbol/LineEntry.h"
#include "lldb/Symbol/SymbolContext.h"

namespace lldb_private {

//----------------------------------------------------------------------
/// @class Block Block.h "lldb/Symbol/Block.h"
/// @brief A class that describes a single lexical block.
///
/// A Function object owns a BlockList object which owns one or more
/// Block objects. The BlockList object contains a section offset
/// address range, and Block objects contain one or more ranges
/// which are offsets into that range. Blocks are can have discontiguous
/// ranges within the BlockList adress range, and each block can
/// contain child blocks each with their own sets of ranges.
///
/// Each block has a variable list that represents local, argument, and
/// static variables that are scoped to the block.
///
/// Inlined functions are representated by attaching a
/// InlineFunctionInfo shared pointer object to a block. Inlined
/// functions are represented as named blocks.
//----------------------------------------------------------------------
class Block :
    public UserID,
    public SymbolContextScope
{
public:

    //------------------------------------------------------------------
    /// Construct with a User ID \a uid, \a depth.
    ///
    /// Initialize this block with the specified UID \a uid. The
    /// \a depth in the \a block_list is used to represent the parent,
    /// sibling, and child block information and also allows for partial
    /// parsing at the block level.
    ///
    /// @param[in] uid
    ///     The UID for a given block. This value is given by the
    ///     SymbolFile plug-in and can be any value that helps the
    ///     SymbolFile plug-in to match this block back to the debug
    ///     information data that it parses for further or more in
    ///     depth parsing. Common values would be the index into a
    ///     table, or an offset into the debug information.
    ///
    /// @param[in] depth
    ///     The integer depth of this block in the block list hierarchy.
    ///
    /// @param[in] block_list
    ///     The block list that this object belongs to.
    ///
    /// @see BlockList
    //------------------------------------------------------------------
    Block (lldb::user_id_t uid);

    //------------------------------------------------------------------
    /// Destructor.
    //------------------------------------------------------------------
    ~Block ();

    //------------------------------------------------------------------
    /// Add a child to this object.
    ///
    /// @param[in] child_block_sp
    ///     A shared pointer to a child block that will get added to
    ///     this block.
    //------------------------------------------------------------------
    void
    AddChild (const lldb::BlockSP &child_block_sp);

    //------------------------------------------------------------------
    /// Add a new offset range to this block.
    ///
    /// @param[in] start_offset
    ///     An offset into this Function's address range that
    ///     describes the start address of a range for this block.
    ///
    /// @param[in] end_offset
    ///     An offset into this Function's address range that
    ///     describes the end address of a range for this block.
    //------------------------------------------------------------------
    void
    AddRange(lldb::addr_t start_offset, lldb::addr_t end_offset);

    //------------------------------------------------------------------
    /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
    ///
    /// @see SymbolContextScope
    //------------------------------------------------------------------
    virtual void
    CalculateSymbolContext(SymbolContext* sc);

    //------------------------------------------------------------------
    /// Check if an offset is in one of the block offset ranges.
    ///
    /// @param[in] range_offset
    ///     An offset into the Function's address range.
    ///
    /// @return
    ///     Returns \b true if \a range_offset falls in one of this
    ///     block's ranges, \b false otherwise.
    //------------------------------------------------------------------
    bool
    Contains (lldb::addr_t range_offset) const;

    //------------------------------------------------------------------
    /// Check if a offset range is in one of the block offset ranges.
    ///
    /// @param[in] range
    ///     An offset range into the Function's address range.
    ///
    /// @return
    ///     Returns \b true if \a range falls in one of this
    ///     block's ranges, \b false otherwise.
    //------------------------------------------------------------------
    bool
    Contains (const VMRange& range) const;

    //------------------------------------------------------------------
    /// Dump the block contents.
    ///
    /// @param[in] s
    ///     The stream to which to dump the object descripton.
    ///
    /// @param[in] base_addr
    ///     The resolved start address of the Function's address
    ///     range. This should be resolved as the file or load address
    ///     prior to passing the value into this function for dumping.
    ///
    /// @param[in] depth
    ///     Limit the number of levels deep that this function should
    ///     print as this block can contain child blocks. Specify
    ///     INT_MAX to dump all child blocks.
    ///
    /// @param[in] show_context
    ///     If \b true, variables will dump their context information.
    //------------------------------------------------------------------
    void
    Dump (Stream *s, lldb::addr_t base_addr, int32_t depth, bool show_context) const;

    void
    DumpStopContext (Stream *s, const SymbolContext *sc);

    //------------------------------------------------------------------
    /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
    ///
    /// @see SymbolContextScope
    //------------------------------------------------------------------
    virtual void
    DumpSymbolContext(Stream *s);

    void
    GetDescription (Stream *s,
                    Function *function,
                    lldb::DescriptionLevel level,
                    Process *process) const;

    //------------------------------------------------------------------
    /// Get the parent block.
    ///
    /// @return
    ///     The parent block pointer, or NULL if this block has no
    ///     parent.
    //------------------------------------------------------------------
    Block *
    GetParent () const;

    //------------------------------------------------------------------
    /// Get the sibling block for this block.
    ///
    /// @return
    ///     The sibling block pointer, or NULL if this block has no
    ///     sibling.
    //------------------------------------------------------------------
    Block *
    GetSibling () const
    {
        return m_sibling;
    }

    //------------------------------------------------------------------
    /// Get the first child block.
    ///
    /// @return
    ///     The first child block pointer, or NULL if this block has no
    ///     children.
    //------------------------------------------------------------------
    Block *
    GetFirstChild () const;

    //------------------------------------------------------------------
    /// Get the variable list for this block and optionally all child
    /// blocks if \a get_child_variables is \b true.
    ///
    /// @param[in] get_child_variables
    ///     If \b true, all variables from all child blocks will be
    ///     added to the variable list.
    ///
    /// @param[in] can_create
    ///     If \b true, the variables can be parsed if they already
    ///     haven't been, else the current state of the block will be
    ///     returned. Passing \b true for this parameter can be used
    ///     to see the current state of what has been parsed up to this
    ///     point.
    ///
    /// @return
    ///     A variable list shared pointer that contains all variables
    ///     for this block.
    //------------------------------------------------------------------
    lldb::VariableListSP
    GetVariableList (bool get_child_variables, bool can_create);


    //------------------------------------------------------------------
    /// Appends the variables from this block, and optionally from all
    /// parent blocks, to \a variable_list.
    ///
    /// @param[in] can_create
    ///     If \b true, the variables can be parsed if they already
    ///     haven't been, else the current state of the block will be
    ///     returned. Passing \b true for this parameter can be used
    ///     to see the current state of what has been parsed up to this
    ///     point.
    ///
    /// @param[in] get_parent_variables
    ///     If \b true, all variables from all parent blocks will be
    ///     added to the variable list.
    ///
    /// @param[in/out] variable_list
    ///     All variables in this block, and optionally all parent
    ///     blocks will be added to this list.
    ///
    /// @return
    ///     The number of variable that were appended to \a
    ///     variable_list.
    //------------------------------------------------------------------
    uint32_t
    AppendVariables(bool can_create, bool get_parent_variables, VariableList *variable_list);

    //------------------------------------------------------------------
    /// Get accessor for any inlined function information.
    ///
    /// @return
    ///     A pointer to any inlined function information, or NULL if
    ///     this is a regular block.
    //------------------------------------------------------------------
    InlineFunctionInfo*
    InlinedFunctionInfo ();

    //------------------------------------------------------------------
    /// Get const accessor for any inlined function information.
    ///
    /// @return
    ///     A cpmst pointer to any inlined function information, or NULL
    ///     if this is a regular block.
    //------------------------------------------------------------------
    const InlineFunctionInfo*
    InlinedFunctionInfo () const;

    //------------------------------------------------------------------
    /// Get the memory cost of this object.
    ///
    /// Returns the cost of this object plus any owned objects from the
    /// ranges, variables, and inline function information.
    ///
    /// @return
    ///     The number of bytes that this object occupies in memory.
    //------------------------------------------------------------------
    size_t
    MemorySize() const;

    //------------------------------------------------------------------
    /// Set accessor for any inlined function information.
    ///
    /// @param[in] name
    ///     The method name for the inlined function. This value should
    ///     not be NULL.
    ///
    /// @param[in] mangled
    ///     The mangled method name for the inlined function. This can
    ///     be NULL if there is no mangled name for an inlined function
    ///     or if the name is the same as \a name.
    ///
    /// @param[in] decl_ptr
    ///     A optional pointer to declaration information for the
    ///     inlined function information. This value can be NULL to
    ///     indicate that no declaration information is available.
    ///
    /// @param[in] call_decl_ptr
    ///     Optional calling location declaration information that
    ///     describes from where this inlined function was called.
    //------------------------------------------------------------------
    void
    SetInlinedFunctionInfo (const char *name,
                            const char *mangled,
                            const Declaration *decl_ptr,
                            const Declaration *call_decl_ptr);


    void
    SetParentScope (SymbolContextScope *parent_scope)
    {
        m_parent_scope = parent_scope;
    }

    void
    SetSibling (Block *block)
    {
        m_sibling = block;
    }

    //------------------------------------------------------------------
    /// 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);


    bool
    BlockInfoHasBeenParsed() const
    {
        return m_parsed_block_info;
    }

    void
    SetBlockInfoHasBeenParsed (bool b, bool set_children);

    Block *
    FindBlockByID (lldb::user_id_t block_id);

protected:
    typedef std::vector<lldb::BlockSP> collection;
    //------------------------------------------------------------------
    // Member variables.
    //------------------------------------------------------------------
    SymbolContextScope *m_parent_scope;
    Block *m_sibling;
    collection m_children;
    VMRange::collection m_ranges; ///< A list of address offset ranges relative to the function's section/offset address.
    lldb::InlineFunctionInfoSP m_inlineInfoSP; ///< Inlined function information.
    lldb::VariableListSP m_variables; ///< The variable list for all local, static and paramter variables scoped to this block.
    bool m_parsed_block_info:1,         ///< Set to true if this block and it's children have all been parsed
         m_parsed_block_variables:1,
         m_parsed_child_blocks:1;

private:
    DISALLOW_COPY_AND_ASSIGN (Block);
};


} // namespace lldb_private

#endif  // liblldb_Block_h_