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