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