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

   1 //===-- Block.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_Block_h_
  11 #define liblldb_Block_h_
  12
  13 #include "lldb/lldb-private.h"
  14 #include "lldb/Core/AddressRange.h"
  15 #include "lldb/Core/RangeMap.h"
  16 #include "lldb/Core/Stream.h"
  17 #include "lldb/Core/UserID.h"
  18 #include "lldb/Symbol/LineEntry.h"
  19 #include "lldb/Symbol/SymbolContext.h"
  20
  21 namespace lldb_private {
  22
  23 //----------------------------------------------------------------------
  24 /// @class Block Block.h "lldb/Symbol/Block.h"
  25 /// @brief A class that describes a single lexical block.
  26 ///
  27 /// A Function object owns a BlockList object which owns one or more
  28 /// Block objects. The BlockList object contains a section offset
  29 /// address range, and Block objects contain one or more ranges
  30 /// which are offsets into that range. Blocks are can have discontiguous
  31 /// ranges within the BlockList adress range, and each block can
  32 /// contain child blocks each with their own sets of ranges.
  33 ///
  34 /// Each block has a variable list that represents local, argument, and
  35 /// static variables that are scoped to the block.
  36 ///
  37 /// Inlined functions are representated by attaching a
  38 /// InlineFunctionInfo shared pointer object to a block. Inlined
  39 /// functions are represented as named blocks.
  40 //----------------------------------------------------------------------
  41 class Block :
  42     public UserID,
  43     public SymbolContextScope
  44 {
  45 public:
  46     typedef RangeArray<uint32_t, uint32_t, 1> RangeList;
  47     typedef RangeList::Entry Range;
  48
  49     //------------------------------------------------------------------
  50     /// Construct with a User ID \a uid, \a depth.
  51     ///
  52     /// Initialize this block with the specified UID \a uid. The
  53     /// \a depth in the \a block_list is used to represent the parent,
  54     /// sibling, and child block information and also allows for partial
  55     /// parsing at the block level.
  56     ///
  57     /// @param[in] uid
  58     ///     The UID for a given block. This value is given by the
  59     ///     SymbolFile plug-in and can be any value that helps the
  60     ///     SymbolFile plug-in to match this block back to the debug
  61     ///     information data that it parses for further or more in
  62     ///     depth parsing. Common values would be the index into a
  63     ///     table, or an offset into the debug information.
  64     ///
  65     /// @param[in] depth
  66     ///     The integer depth of this block in the block list hierarchy.
  67     ///
  68     /// @param[in] block_list
  69     ///     The block list that this object belongs to.
  70     ///
  71     /// @see BlockList
  72     //------------------------------------------------------------------
  73     Block (lldb::user_id_t uid);
  74
  75     //------------------------------------------------------------------
  76     /// Destructor.
  77     //------------------------------------------------------------------
  78     virtual ~Block ();
  79
  80     //------------------------------------------------------------------
  81     /// Add a child to this object.
  82     ///
  83     /// @param[in] child_block_sp
  84     ///     A shared pointer to a child block that will get added to
  85     ///     this block.
  86     //------------------------------------------------------------------
  87     void
  88     AddChild (const lldb::BlockSP &child_block_sp);
  89
  90     //------------------------------------------------------------------
  91     /// Add a new offset range to this block.
  92     ///
  93     /// @param[in] start_offset
  94     ///     An offset into this Function's address range that
  95     ///     describes the start address of a range for this block.
  96     ///
  97     /// @param[in] end_offset
  98     ///     An offset into this Function's address range that
  99     ///     describes the end address of a range for this block.
 100     //------------------------------------------------------------------
 101     void
 102     AddRange (const Range& range);
 103
 104     void
 105     FinalizeRanges ();
 106
 107     //------------------------------------------------------------------
 108     /// @copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
 109     ///
 110     /// @see SymbolContextScope
 111     //------------------------------------------------------------------
 112     virtual void
 113     CalculateSymbolContext(SymbolContext* sc);
 114
 115     virtual lldb::ModuleSP
 116     CalculateSymbolContextModule ();
 117
 118     virtual CompileUnit *
 119     CalculateSymbolContextCompileUnit ();
 120
 121     virtual Function *
 122     CalculateSymbolContextFunction ();
 123
 124     virtual Block *
 125     CalculateSymbolContextBlock ();
 126
 127     //------------------------------------------------------------------
 128     /// Check if an offset is in one of the block offset ranges.
 129     ///
 130     /// @param[in] range_offset
 131     ///     An offset into the Function's address range.
 132     ///
 133     /// @return
 134     ///     Returns \b true if \a range_offset falls in one of this
 135     ///     block's ranges, \b false otherwise.
 136     //------------------------------------------------------------------
 137     bool
 138     Contains (lldb::addr_t range_offset) const;
 139
 140     //------------------------------------------------------------------
 141     /// Check if a offset range is in one of the block offset ranges.
 142     ///
 143     /// @param[in] range
 144     ///     An offset range into the Function's address range.
 145     ///
 146     /// @return
 147     ///     Returns \b true if \a range falls in one of this
 148     ///     block's ranges, \b false otherwise.
 149     //------------------------------------------------------------------
 150     bool
 151     Contains (const Range& range) const;
 152
 153     //------------------------------------------------------------------
 154     /// Check if this object contains "block" as a child block at any
 155     /// depth.
 156     ///
 157     /// @param[in] block
 158     ///     A potential child block.
 159     ///
 160     /// @return
 161     ///     Returns \b true if \a block is a child of this block, \b
 162     ///     false otherwise.
 163     //------------------------------------------------------------------
 164     bool
 165     Contains (const Block *block) const;
 166
 167     //------------------------------------------------------------------
 168     /// Dump the block contents.
 169     ///
 170     /// @param[in] s
 171     ///     The stream to which to dump the object descripton.
 172     ///
 173     /// @param[in] base_addr
 174     ///     The resolved start address of the Function's address
 175     ///     range. This should be resolved as the file or load address
 176     ///     prior to passing the value into this function for dumping.
 177     ///
 178     /// @param[in] depth
 179     ///     Limit the number of levels deep that this function should
 180     ///     print as this block can contain child blocks. Specify
 181     ///     INT_MAX to dump all child blocks.
 182     ///
 183     /// @param[in] show_context
 184     ///     If \b true, variables will dump their context information.
 185     //------------------------------------------------------------------
 186     void
 187     Dump (Stream *s, lldb::addr_t base_addr, int32_t depth, bool show_context) const;
 188
 189     //------------------------------------------------------------------
 190     /// @copydoc SymbolContextScope::DumpSymbolContext(Stream*)
 191     ///
 192     /// @see SymbolContextScope
 193     //------------------------------------------------------------------
 194     virtual void
 195     DumpSymbolContext(Stream *s);
 196
 197     void
 198     DumpAddressRanges (Stream *s,
 199                        lldb::addr_t base_addr);
 200
 201     void
 202     GetDescription (Stream *s,
 203                     Function *function,
 204                     lldb::DescriptionLevel level,
 205                     Target *target) const;
 206
 207     //------------------------------------------------------------------
 208     /// Get the parent block.
 209     ///
 210     /// @return
 211     ///     The parent block pointer, or NULL if this block has no
 212     ///     parent.
 213     //------------------------------------------------------------------
 214     Block *
 215     GetParent () const;
 216
 217
 218     //------------------------------------------------------------------
 219     /// Get the inlined block that contains this block.
 220     ///
 221     /// @return
 222     ///     If this block contains inlined function info, it will return
 223     ///     this block, else parent blocks will be searched to see if
 224     ///     any contain this block. NULL will be returned if this block
 225     ///     nor any parent blocks are inlined function blocks.
 226     //------------------------------------------------------------------
 227     Block *
 228     GetContainingInlinedBlock ();
 229
 230     //------------------------------------------------------------------
 231     /// Get the inlined parent block for this block.
 232     ///
 233     /// @return
 234     ///     The parent block pointer, or NULL if this block has no
 235     ///     parent.
 236     //------------------------------------------------------------------
 237     Block *
 238     GetInlinedParent ();
 239
 240     //------------------------------------------------------------------
 241     /// Get the sibling block for this block.
 242     ///
 243     /// @return
 244     ///     The sibling block pointer, or NULL if this block has no
 245     ///     sibling.
 246     //------------------------------------------------------------------
 247     Block *
 248     GetSibling () const;
 249
 250     //------------------------------------------------------------------
 251     /// Get the first child block.
 252     ///
 253     /// @return
 254     ///     The first child block pointer, or NULL if this block has no
 255     ///     children.
 256     //------------------------------------------------------------------
 257     Block *
 258     GetFirstChild () const
 259     {
 260         if (m_children.empty())
 261             return NULL;
 262         return m_children.front().get();
 263     }
 264
 265     //------------------------------------------------------------------
 266     /// Get the variable list for this block only.
 267     ///
 268     /// @param[in] can_create
 269     ///     If \b true, the variables can be parsed if they already
 270     ///     haven't been, else the current state of the block will be
 271     ///     returned.
 272     ///
 273     /// @return
 274     ///     A variable list shared pointer that contains all variables
 275     ///     for this block.
 276     //------------------------------------------------------------------
 277     lldb::VariableListSP
 278     GetBlockVariableList (bool can_create);
 279
 280
 281     //------------------------------------------------------------------
 282     /// Get the variable list for this block and optionally all child
 283     /// blocks if \a get_child_variables is \b true.
 284     ///
 285     /// @param[in] get_child_variables
 286     ///     If \b true, all variables from all child blocks will be
 287     ///     added to the variable list.
 288     ///
 289     /// @param[in] can_create
 290     ///     If \b true, the variables can be parsed if they already
 291     ///     haven't been, else the current state of the block will be
 292     ///     returned. Passing \b true for this parameter can be used
 293     ///     to see the current state of what has been parsed up to this
 294     ///     point.
 295     ///
 296     /// @param[in] add_inline_child_block_variables
 297     ///     If this is \b false, no child variables of child blocks
 298     ///     that are inlined functions will be gotten. If \b true then
 299     ///     all child variables will be added regardless of whether they
 300     ///     come from inlined functions or not.
 301     ///
 302     /// @return
 303     ///     A variable list shared pointer that contains all variables
 304     ///     for this block.
 305     //------------------------------------------------------------------
 306     uint32_t
 307     AppendBlockVariables (bool can_create,
 308                           bool get_child_block_variables,
 309                           bool stop_if_child_block_is_inlined_function,
 310                           VariableList *variable_list);
 311
 312     //------------------------------------------------------------------
 313     /// Appends the variables from this block, and optionally from all
 314     /// parent blocks, to \a variable_list.
 315     ///
 316     /// @param[in] can_create
 317     ///     If \b true, the variables can be parsed if they already
 318     ///     haven't been, else the current state of the block will be
 319     ///     returned. Passing \b true for this parameter can be used
 320     ///     to see the current state of what has been parsed up to this
 321     ///     point.
 322     ///
 323     /// @param[in] get_parent_variables
 324     ///     If \b true, all variables from all parent blocks will be
 325     ///     added to the variable list.
 326     ///
 327     /// @param[in] stop_if_block_is_inlined_function
 328     ///     If \b true, all variables from all parent blocks will be
 329     ///     added to the variable list until there are no parent blocks
 330     ///     or the parent block has inlined function info.
 331     ///
 332     /// @param[in/out] variable_list
 333     ///     All variables in this block, and optionally all parent
 334     ///     blocks will be added to this list.
 335     ///
 336     /// @return
 337     ///     The number of variable that were appended to \a
 338     ///     variable_list.
 339     //------------------------------------------------------------------
 340     uint32_t
 341     AppendVariables (bool can_create,
 342                      bool get_parent_variables,
 343                      bool stop_if_block_is_inlined_function,
 344                      VariableList *variable_list);
 345
 346     //------------------------------------------------------------------
 347     /// Get const accessor for any inlined function information.
 348     ///
 349     /// @return
 350     ///     A comst pointer to any inlined function information, or NULL
 351     ///     if this is a regular block.
 352     //------------------------------------------------------------------
 353     const InlineFunctionInfo*
 354     GetInlinedFunctionInfo () const
 355     {
 356         return m_inlineInfoSP.get();
 357     }
 358
 359     clang::DeclContext *
 360     GetClangDeclContext();
 361
 362     //------------------------------------------------------------------
 363     /// Get the memory cost of this object.
 364     ///
 365     /// Returns the cost of this object plus any owned objects from the
 366     /// ranges, variables, and inline function information.
 367     ///
 368     /// @return
 369     ///     The number of bytes that this object occupies in memory.
 370     //------------------------------------------------------------------
 371     size_t
 372     MemorySize() const;
 373
 374     //------------------------------------------------------------------
 375     /// Set accessor for any inlined function information.
 376     ///
 377     /// @param[in] name
 378     ///     The method name for the inlined function. This value should
 379     ///     not be NULL.
 380     ///
 381     /// @param[in] mangled
 382     ///     The mangled method name for the inlined function. This can
 383     ///     be NULL if there is no mangled name for an inlined function
 384     ///     or if the name is the same as \a name.
 385     ///
 386     /// @param[in] decl_ptr
 387     ///     A optional pointer to declaration information for the
 388     ///     inlined function information. This value can be NULL to
 389     ///     indicate that no declaration information is available.
 390     ///
 391     /// @param[in] call_decl_ptr
 392     ///     Optional calling location declaration information that
 393     ///     describes from where this inlined function was called.
 394     //------------------------------------------------------------------
 395     void
 396     SetInlinedFunctionInfo (const char *name,
 397                             const char *mangled,
 398                             const Declaration *decl_ptr,
 399                             const Declaration *call_decl_ptr);
 400
 401
 402     void
 403     SetParentScope (SymbolContextScope *parent_scope)
 404     {
 405         m_parent_scope = parent_scope;
 406     }
 407
 408     //------------------------------------------------------------------
 409     /// Set accessor for the variable list.
 410     ///
 411     /// Called by the SymbolFile plug-ins after they have parsed the
 412     /// variable lists and are ready to hand ownership of the list over
 413     /// to this object.
 414     ///
 415     /// @param[in] variable_list_sp
 416     ///     A shared pointer to a VariableList.
 417     //------------------------------------------------------------------
 418     void
 419     SetVariableList (lldb::VariableListSP& variable_list_sp)
 420     {
 421         m_variable_list_sp = variable_list_sp;
 422     }
 423
 424
 425
 426     bool
 427     BlockInfoHasBeenParsed() const
 428     {
 429         return m_parsed_block_info;
 430     }
 431
 432     void
 433     SetBlockInfoHasBeenParsed (bool b, bool set_children);
 434
 435     Block *
 436     FindBlockByID (lldb::user_id_t block_id);
 437
 438     size_t
 439     GetNumRanges () const
 440     {
 441         return m_ranges.GetSize();
 442     }
 443
 444     bool
 445     GetRangeContainingOffset (const lldb::addr_t offset, Range &range);
 446
 447     bool
 448     GetRangeContainingAddress (const Address& addr, AddressRange &range);
 449
 450     bool
 451     GetRangeContainingLoadAddress (lldb::addr_t load_addr, Target &target, AddressRange &range);
 452
 453     uint32_t
 454     GetRangeIndexContainingAddress (const Address& addr);
 455
 456     //------------------------------------------------------------------
 457     // Since blocks might have multiple discontiguous addresss ranges,
 458     // we need to be able to get at any of the address ranges in a block.
 459     //------------------------------------------------------------------
 460     bool
 461     GetRangeAtIndex (uint32_t range_idx,
 462                      AddressRange &range);
 463
 464     bool
 465     GetStartAddress (Address &addr);
 466
 467     void
 468     SetDidParseVariables (bool b, bool set_children);
 469
 470 protected:
 471     typedef std::vector<lldb::BlockSP> collection;
 472     //------------------------------------------------------------------
 473     // Member variables.
 474     //------------------------------------------------------------------
 475     SymbolContextScope *m_parent_scope;
 476     collection m_children;
 477     RangeList m_ranges;
 478     lldb::InlineFunctionInfoSP m_inlineInfoSP; ///< Inlined function information.
 479     lldb::VariableListSP m_variable_list_sp; ///< The variable list for all local, static and paramter variables scoped to this block.
 480     bool m_parsed_block_info:1,         ///< Set to true if this block and it's children have all been parsed
 481          m_parsed_block_variables:1,
 482          m_parsed_child_blocks:1;
 483
 484     // A parent of child blocks can be asked to find a sibling block given
 485     // one of its child blocks
 486     Block *
 487     GetSiblingForChild (const Block *child_block) const;
 488
 489 private:
 490     DISALLOW_COPY_AND_ASSIGN (Block);
 491 };
 492
 493
 494 } // namespace lldb_private
 495
 496 #endif  // liblldb_Block_h_