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