LLDB mainline
Block.h
Go to the documentation of this file.
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
18#include "lldb/Utility/Stream.h"
19#include "lldb/Utility/UserID.h"
20#include "lldb/lldb-private.h"
21#include <vector>
22
23namespace 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.
41class Block : public UserID, public SymbolContextScope {
42public:
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.
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
74
76
78
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.
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.
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 *
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.
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.
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.
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.
275
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
322
323 void SetBlockInfoHasBeenParsed(bool b, bool set_children);
324
326
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
345
346 bool GetStartAddress(Address &addr);
347
348 void SetDidParseVariables(bool b, bool set_children);
349
350protected:
351 typedef std::vector<lldb::BlockSP> collection;
352 // Member variables.
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
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
368private:
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
A section + offset based address range class.
Definition: AddressRange.h:25
A section + offset based address class.
Definition: Address.h:62
A class that describes a single lexical block.
Definition: Block.h:41
bool BlockInfoHasBeenParsed() const
Definition: Block.h:321
RangeList::Entry Range
Definition: Block.h:44
Block * GetFirstChild() const
Get the first child block.
Definition: Block.h:192
lldb::VariableListSP m_variable_list_sp
The variable list for all local, static and parameter variables scoped to this block.
Definition: Block.h:357
lldb::VariableListSP GetBlockVariableList(bool can_create)
Get the variable list for this block only.
Definition: Block.cpp:407
Block * GetContainingInlinedBlockWithCallSite(const Declaration &find_call_site)
Get the inlined block at the given call site that contains this block.
Definition: Block.cpp:218
void CalculateSymbolContext(SymbolContext *sc) override
Reconstruct the object's symbol context into sc.
Definition: Block.cpp:138
Block * FindInnermostBlockByOffset(const lldb::addr_t offset)
Definition: Block.cpp:128
const Block & operator=(const Block &)=delete
lldb::ModuleSP CalculateSymbolContextModule() override
Definition: Block.cpp:143
Block * GetContainingInlinedBlock()
Get the inlined block that contains this block.
Definition: Block.cpp:201
void SetBlockInfoHasBeenParsed(bool b, bool set_children)
Definition: Block.cpp:494
bool GetRangeAtIndex(uint32_t range_idx, AddressRange &range)
Definition: Block.cpp:297
const InlineFunctionInfo * GetInlinedFunctionInfo() const
Get const accessor for any inlined function information.
Definition: Block.h:266
AddressRanges GetRanges()
Definition: Block.cpp:311
bool m_parsed_child_blocks
Definition: Block.h:362
lldb::InlineFunctionInfoSP m_inlineInfoSP
Inlined function information.
Definition: Block.h:356
void DumpSymbolContext(Stream *s) override
Dump the object's symbol context to the stream s.
Definition: Block.cpp:157
bool GetRangeContainingAddress(const Address &addr, AddressRange &range)
Definition: Block.cpp:243
lldb::BlockSP CreateChild(lldb::user_id_t uid)
Creates a block with the specified UID uid.
Definition: Block.cpp:395
Block * FindBlockByID(lldb::user_id_t block_id)
Definition: Block.cpp:114
bool m_parsed_block_info
Set to true if this block and it's children have all been parsed.
Definition: Block.h:361
Block * GetSibling() const
Get the sibling block for this block.
Definition: Block.cpp:513
CompileUnit * CalculateSymbolContextCompileUnit() override
Definition: Block.cpp:147
Block * GetSiblingForChild(const Block *child_block) const
Definition: Block.cpp:521
Function * CalculateSymbolContextFunction() override
Definition: Block.cpp:151
void SetVariableList(lldb::VariableListSP &variable_list_sp)
Set accessor for the variable list.
Definition: Block.h:317
bool GetRangeContainingLoadAddress(lldb::addr_t load_addr, Target &target, AddressRange &range)
Definition: Block.cpp:272
CompilerDeclContext GetDeclContext()
Definition: Block.cpp:488
collection m_children
Definition: Block.h:354
bool m_parsed_block_variables
Definition: Block.h:362
Block * GetParent() const
Get the parent block.
Definition: Block.cpp:197
uint32_t AppendVariables(bool can_create, bool get_parent_variables, bool stop_if_block_is_inlined_function, const std::function< bool(Variable *)> &filter, VariableList *variable_list)
Appends the variables from this block, and optionally from all parent blocks, to variable_list.
Definition: Block.cpp:451
size_t GetNumRanges() const
Definition: Block.h:329
bool GetStartAddress(Address &addr)
Definition: Block.cpp:327
SymbolFile * GetSymbolFile()
Get the symbol file which contains debug info for this block's symbol context module.
Definition: Block.cpp:482
void Dump(Stream *s, lldb::addr_t base_addr, int32_t depth, bool show_context) const
Dump the block contents.
Definition: Block.cpp:61
void SetDidParseVariables(bool b, bool set_children)
Definition: Block.cpp:504
bool GetRangeContainingOffset(const lldb::addr_t offset, Range &range)
Definition: Block.cpp:233
void AddRange(const Range &range)
Add a new offset range to this block.
Definition: Block.cpp:345
Block * CalculateSymbolContextBlock() override
Definition: Block.cpp:155
void DumpAddressRanges(Stream *s, lldb::addr_t base_addr)
Definition: Block.cpp:164
Block * GetInlinedParent()
Get the inlined parent block for this block.
Definition: Block.cpp:207
void FinalizeRanges()
Definition: Block.cpp:340
std::vector< lldb::BlockSP > collection
Definition: Block.h:351
SymbolContextScope & m_parent_scope
Definition: Block.h:353
RangeVector< uint32_t, uint32_t, 1 > RangeList
Definition: Block.h:43
uint32_t GetRangeIndexContainingAddress(const Address &addr)
Definition: Block.cpp:280
void SetInlinedFunctionInfo(const char *name, const char *mangled, const Declaration *decl_ptr, const Declaration *call_decl_ptr)
Set accessor for any inlined function information.
Definition: Block.cpp:400
size_t MemorySize() const
Get the memory cost of this object.
Definition: Block.cpp:386
uint32_t AppendBlockVariables(bool can_create, bool get_child_block_variables, bool stop_if_child_block_is_inlined_function, const std::function< bool(Variable *)> &filter, VariableList *variable_list)
Get the variable list for this block and optionally all child blocks if get_child_variables is true.
Definition: Block.cpp:421
Block(const Block &)=delete
void GetDescription(Stream *s, Function *function, lldb::DescriptionLevel level, Target *target) const
Definition: Block.cpp:33
RangeList m_ranges
Definition: Block.h:355
A class that describes a compilation unit.
Definition: CompileUnit.h:43
Represents a generic declaration context in a program.
A class that describes the declaration location of a lldb object.
Definition: Declaration.h:24
A class that describes a function.
Definition: Function.h:399
A class that describes information for an inlined function.
Definition: Function.h:125
size_t GetSize() const
Definition: RangeMap.h:295
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
"lldb/Symbol/SymbolContextScope.h" Inherit from this if your object is part of a symbol context and c...
Defines a symbol context baton that can be handed other debug core functions.
Definition: SymbolContext.h:34
Provides public interface for all SymbolFiles.
Definition: SymbolFile.h:50
A class that represents a running process on the host machine.
std::shared_ptr< lldb_private::InlineFunctionInfo > InlineFunctionInfoSP
Definition: lldb-forward.h:357
DescriptionLevel
Description levels for "void GetDescription(Stream *, DescriptionLevel)" calls.
std::shared_ptr< lldb_private::Block > BlockSP
Definition: lldb-forward.h:320
std::shared_ptr< lldb_private::VariableList > VariableListSP
Definition: lldb-forward.h:487
uint64_t user_id_t
Definition: lldb-types.h:82
uint64_t addr_t
Definition: lldb-types.h:80
std::shared_ptr< lldb_private::Module > ModuleSP
Definition: lldb-forward.h:373
A mix in class that contains a generic user ID.
Definition: UserID.h:31