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