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