LLDB  mainline
Address.h
Go to the documentation of this file.
1 //===-- Address.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 liblldb_Address_h_
10 #define liblldb_Address_h_
11 
12 #include "lldb/lldb-defines.h"
13 #include "lldb/lldb-forward.h"
15 #include "lldb/lldb-types.h"
16 
17 #include <stddef.h>
18 #include <stdint.h>
19 
20 namespace lldb_private {
21 class Block;
22 }
23 namespace lldb_private {
24 class CompileUnit;
25 }
26 namespace lldb_private {
27 class ExecutionContextScope;
28 }
29 namespace lldb_private {
30 class Function;
31 }
32 namespace lldb_private {
33 class SectionList;
34 }
35 namespace lldb_private {
36 class Stream;
37 }
38 namespace lldb_private {
39 class Symbol;
40 }
41 namespace lldb_private {
42 class SymbolContext;
43 }
44 namespace lldb_private {
45 class Target;
46 }
47 namespace lldb_private {
48 struct LineEntry;
49 }
50 
51 namespace lldb_private {
52 
53 /// \class Address Address.h "lldb/Core/Address.h"
54 /// A section + offset based address class.
55 ///
56 /// The Address class allows addresses to be relative to a section that can
57 /// move during runtime due to images (executables, shared libraries, bundles,
58 /// frameworks) being loaded at different addresses than the addresses found
59 /// in the object file that represents them on disk. There are currently two
60 /// types of addresses for a section:
61 /// \li file addresses
62 /// \li load addresses
63 ///
64 /// File addresses represent the virtual addresses that are in the "on disk"
65 /// object files. These virtual addresses are converted to be relative to
66 /// unique sections scoped to the object file so that when/if the addresses
67 /// slide when the images are loaded/unloaded in memory, we can easily track
68 /// these changes without having to update every object (compile unit ranges,
69 /// line tables, function address ranges, lexical block and inlined subroutine
70 /// address ranges, global and static variables) each time an image is loaded
71 /// or unloaded.
72 ///
73 /// Load addresses represent the virtual addresses where each section ends up
74 /// getting loaded at runtime. Before executing a program, it is common for
75 /// all of the load addresses to be unresolved. When a DynamicLoader plug-in
76 /// receives notification that shared libraries have been loaded/unloaded, the
77 /// load addresses of the main executable and any images (shared libraries)
78 /// will be resolved/unresolved. When this happens, breakpoints that are in
79 /// one of these sections can be set/cleared.
80 class Address {
81 public:
82  /// Dump styles allow the Address::Dump(Stream *,DumpStyle) const function
83  /// to display Address contents in a variety of ways.
84  typedef enum {
85  DumpStyleInvalid, ///< Invalid dump style
86  DumpStyleSectionNameOffset, ///< Display as the section name + offset.
87  ///< \code
88  /// // address for printf in libSystem.B.dylib as a section name + offset
89  /// libSystem.B.dylib.__TEXT.__text + 0x0005cfdf \endcode
90  DumpStyleSectionPointerOffset, ///< Display as the section pointer + offset
91  ///(debug output).
92  ///< \code
93  /// // address for printf in libSystem.B.dylib as a section pointer +
94  /// offset (lldb::Section *)0x35cc50 + 0x000000000005cfdf \endcode
95  DumpStyleFileAddress, ///< Display as the file address (if any).
96  ///< \code
97  /// // address for printf in libSystem.B.dylib as a file address
98  /// 0x000000000005dcff \endcode
99  DumpStyleModuleWithFileAddress, ///< Display as the file address with the
100  ///module name prepended (if any).
101  ///< \code
102  /// // address for printf in libSystem.B.dylib as a file address
103  /// libSystem.B.dylib[0x000000000005dcff] \endcode
104  DumpStyleLoadAddress, ///< Display as the load address (if resolved).
105  ///< \code
106  /// // address for printf in libSystem.B.dylib as a load address
107  /// 0x00007fff8306bcff \endcode
108  DumpStyleResolvedDescription, ///< Display the details about what an address
109  ///resolves to. This can
110  ///< be anything from a symbol context summary (module, function/symbol,
111  ///< and file and line), to information about what the pointer points to
112  ///< if the address is in a section (section of pointers, c strings, etc).
115  DumpStyleNoFunctionName, ///< Elide the function name; display an offset
116  ///into the current function.
117  ///< Used primarily in disassembly symbolication
118  DumpStyleDetailedSymbolContext, ///< Detailed symbol context information for
119  ///an address for all symbol
120  ///< context members.
121  DumpStyleResolvedPointerDescription ///< Dereference a pointer at the
122  ///current address and then lookup the
123  ///< dereferenced address using DumpStyleResolvedDescription
124  } DumpStyle;
125 
126  /// Default constructor.
127  ///
128  /// Initialize with a invalid section (NULL) and an invalid offset
129  /// (LLDB_INVALID_ADDRESS).
131 
132  /// Copy constructor
133  ///
134  /// Makes a copy of the another Address object \a rhs.
135  ///
136  /// \param[in] rhs
137  /// A const Address object reference to copy.
138  Address(const Address &rhs)
140 
141  /// Construct with a section pointer and offset.
142  ///
143  /// Initialize the address with the supplied \a section and \a offset.
144  ///
145  /// \param[in] section
146  /// A section pointer to a valid lldb::Section, or NULL if the
147  /// address doesn't have a section or will get resolved later.
148  ///
149  /// \param[in] offset
150  /// The offset in bytes into \a section.
151  Address(const lldb::SectionSP &section_sp, lldb::addr_t offset)
152  : m_section_wp(), // Don't init with section_sp in case section_sp is
153  // invalid (the weak_ptr will throw)
154  m_offset(offset) {
155  if (section_sp)
156  m_section_wp = section_sp;
157  }
158 
159  /// Construct with a virtual address and section list.
160  ///
161  /// Initialize and resolve the address with the supplied virtual address \a
162  /// file_addr.
163  ///
164  /// \param[in] file_addr
165  /// A virtual file address.
166  ///
167  /// \param[in] section_list
168  /// A list of sections, one of which may contain the \a file_addr.
169  Address(lldb::addr_t file_addr, const SectionList *section_list);
170 
171  Address(lldb::addr_t abs_addr);
172 
173 /// Assignment operator.
174 ///
175 /// Copies the address value from another Address object \a rhs into \a this
176 /// object.
177 ///
178 /// \param[in] rhs
179 /// A const Address object reference to copy.
180 ///
181 /// \return
182 /// A const Address object reference to \a this.
183  const Address &operator=(const Address &rhs);
184 
185  /// Clear the object's state.
186  ///
187  /// Sets the section to an invalid value (NULL) and an invalid offset
188  /// (LLDB_INVALID_ADDRESS).
189  void Clear() {
190  m_section_wp.reset();
192  }
193 
194  /// Compare two Address objects.
195  ///
196  /// \param[in] lhs
197  /// The Left Hand Side const Address object reference.
198  ///
199  /// \param[in] rhs
200  /// The Right Hand Side const Address object reference.
201  ///
202  /// \return
203  /// \li -1 if lhs < rhs
204  /// \li 0 if lhs == rhs
205  /// \li 1 if lhs > rhs
206  static int CompareFileAddress(const Address &lhs, const Address &rhs);
207 
208  static int CompareLoadAddress(const Address &lhs, const Address &rhs,
209  Target *target);
210 
211  static int CompareModulePointerAndOffset(const Address &lhs,
212  const Address &rhs);
213 
214  // For use with std::map, std::multi_map
216  public:
218 
219  bool operator()(const Address &a, const Address &b) const {
221  }
222  };
223 
224  /// Dump a description of this object to a Stream.
225  ///
226  /// Dump a description of the contents of this object to the supplied stream
227  /// \a s. There are many ways to display a section offset based address, and
228  /// \a style lets the user choose.
229  ///
230  /// \param[in] s
231  /// The stream to which to dump the object description.
232  ///
233  /// \param[in] style
234  /// The display style for the address.
235  ///
236  /// \param[in] fallback_style
237  /// The display style for the address.
238  ///
239  /// \return
240  /// Returns \b true if the address was able to be displayed.
241  /// File and load addresses may be unresolved and it may not be
242  /// possible to display a valid value, \b false will be returned
243  /// in such cases.
244  ///
245  /// \see Address::DumpStyle
246  bool Dump(Stream *s, ExecutionContextScope *exe_scope, DumpStyle style,
247  DumpStyle fallback_style = DumpStyleInvalid,
248  uint32_t addr_byte_size = UINT32_MAX) const;
249 
251 
252  /// Get the file address.
253  ///
254  /// If an address comes from a file on disk that has section relative
255  /// addresses, then it has a virtual address that is relative to unique
256  /// section in the object file.
257  ///
258  /// \return
259  /// The valid file virtual address, or LLDB_INVALID_ADDRESS if
260  /// the address doesn't have a file virtual address (image is
261  /// from memory only with no representation on disk).
263 
264  /// Get the load address.
265  ///
266  /// If an address comes from a file on disk that has section relative
267  /// addresses, then it has a virtual address that is relative to unique
268  /// section in the object file. Sections get resolved at runtime by
269  /// DynamicLoader plug-ins as images (executables and shared libraries) get
270  /// loaded/unloaded. If a section is loaded, then the load address can be
271  /// resolved.
272  ///
273  /// \return
274  /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
275  /// the address is currently not loaded.
276  lldb::addr_t GetLoadAddress(Target *target) const;
277 
278  /// Get the load address as a callable code load address.
279  ///
280  /// This function will first resolve its address to a load address. Then, if
281  /// the address turns out to be in code address, return the load address
282  /// that would be required to call or return to. The address might have
283  /// extra bits set (bit zero will be set to Thumb functions for an ARM
284  /// target) that are required when changing the program counter to setting a
285  /// return address.
286  ///
287  /// \return
288  /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
289  /// the address is currently not loaded.
291  bool is_indirect = false) const;
292 
293  /// Get the load address as an opcode load address.
294  ///
295  /// This function will first resolve its address to a load address. Then, if
296  /// the address turns out to be in code address, return the load address for
297  /// an opcode. This address object might have extra bits set (bit zero will
298  /// be set to Thumb functions for an
299  /// ARM target) that are required for changing the program counter
300  /// and this function will remove any bits that are intended for these
301  /// special purposes. The result of this function can be used to safely
302  /// write a software breakpoint trap to memory.
303  ///
304  /// \return
305  /// The valid load virtual address with extra callable bits
306  /// removed, or LLDB_INVALID_ADDRESS if the address is currently
307  /// not loaded.
309  Target *target,
310  AddressClass addr_class = AddressClass::eInvalid) const;
311 
312  /// Get the section relative offset value.
313  ///
314  /// \return
315  /// The current offset, or LLDB_INVALID_ADDRESS if this address
316  /// doesn't contain a valid offset.
317  lldb::addr_t GetOffset() const { return m_offset; }
318 
319  /// Check if an address is section offset.
320  ///
321  /// When converting a virtual file or load address into a section offset
322  /// based address, we often need to know if, given a section list, if the
323  /// address was able to be converted to section offset. This function
324  /// returns true if the current value contained in this object is section
325  /// offset based.
326  ///
327  /// \return
328  /// Returns \b true if the address has a valid section and
329  /// offset, \b false otherwise.
330  bool IsSectionOffset() const {
331  return IsValid() && (GetSection().get() != nullptr);
332  }
333 
334  /// Check if the object state is valid.
335  ///
336  /// A valid Address object contains either a section pointer and
337  /// offset (for section offset based addresses), or just a valid offset
338  /// (for absolute addresses that have no section).
339  ///
340  /// \return
341  /// Returns \b true if the offset is valid, \b false
342  /// otherwise.
343  bool IsValid() const { return m_offset != LLDB_INVALID_ADDRESS; }
344 
345  /// Get the memory cost of this object.
346  ///
347  /// \return
348  /// The number of bytes that this object occupies in memory.
349  size_t MemorySize() const;
350 
351  /// Resolve a file virtual address using a section list.
352  ///
353  /// Given a list of sections, attempt to resolve \a addr as an offset into
354  /// one of the file sections.
355  ///
356  /// \return
357  /// Returns \b true if \a addr was able to be resolved, \b false
358  /// otherwise.
360  const SectionList *sections);
361 
362  /// Set the address to represent \a load_addr.
363  ///
364  /// The address will attempt to find a loaded section within \a target that
365  /// contains \a load_addr. If successful, this address object will have a
366  /// valid section and offset. Else this address object will have no section
367  /// (NULL) and the offset will be \a load_addr.
368  ///
369  /// \param[in] load_addr
370  /// A load address from a current process.
371  ///
372  /// \param[in] target
373  /// The target to use when trying resolve the address into
374  /// a section + offset. The Target's SectionLoadList object
375  /// is used to resolve the address.
376  ///
377  /// \param[in] allow_section_end
378  /// If true, treat an address pointing to the end of the module as
379  /// belonging to that module.
380  ///
381  /// \return
382  /// Returns \b true if the load address was resolved to be
383  /// section/offset, \b false otherwise. It is often ok for an
384  /// address to not resolve to a section in a module, this often
385  /// happens for JIT'ed code, or any load addresses on the stack
386  /// or heap.
387  bool SetLoadAddress(lldb::addr_t load_addr, Target *target,
388  bool allow_section_end = false);
389 
391  lldb::addr_t load_addr, Target *target,
393  bool allow_section_end = false);
394 
395  bool SetCallableLoadAddress(lldb::addr_t load_addr, Target *target);
396 
397  /// Get accessor for the module for this address.
398  ///
399  /// \return
400  /// Returns the Module pointer that this address is an offset
401  /// in, or NULL if this address doesn't belong in a module, or
402  /// isn't resolved yet.
403  lldb::ModuleSP GetModule() const;
404 
405  /// Get const accessor for the section.
406  ///
407  /// \return
408  /// Returns the const lldb::Section pointer that this address is an
409  /// offset in, or NULL if this address is absolute.
410  lldb::SectionSP GetSection() const { return m_section_wp.lock(); }
411 
412  /// Set accessor for the offset.
413  ///
414  /// \param[in] offset
415  /// A new offset value for this object.
416  ///
417  /// \return
418  /// Returns \b true if the offset changed, \b false otherwise.
419  bool SetOffset(lldb::addr_t offset) {
420  bool changed = m_offset != offset;
421  m_offset = offset;
422  return changed;
423  }
424 
426  m_section_wp.reset();
427  m_offset = addr;
428  }
429 
430  bool Slide(int64_t offset) {
432  m_offset += offset;
433  return true;
434  }
435  return false;
436  }
437 
438  /// Set accessor for the section.
439  ///
440  /// \param[in] section
441  /// A new lldb::Section pointer to use as the section base. Can
442  /// be NULL for absolute addresses that are not relative to
443  /// any section.
444  void SetSection(const lldb::SectionSP &section_sp) {
445  m_section_wp = section_sp;
446  }
447 
448  void ClearSection() { m_section_wp.reset(); }
449 
450  /// Reconstruct a symbol context from an address.
451  ///
452  /// This class doesn't inherit from SymbolContextScope because many address
453  /// objects have short lifespans. Address objects that are section offset
454  /// can reconstruct their symbol context by looking up the address in the
455  /// module found in the section.
456  ///
457  /// \see SymbolContextScope::CalculateSymbolContext(SymbolContext*)
459  lldb::SymbolContextItem resolve_scope =
460  lldb::eSymbolContextEverything) const;
461 
462  lldb::ModuleSP CalculateSymbolContextModule() const;
463 
465 
467 
469 
471 
472  bool CalculateSymbolContextLineEntry(LineEntry &line_entry) const;
473 
474  // Returns true if the section should be valid, but isn't because the shared
475  // pointer to the section can't be reconstructed from a weak pointer that
476  // contains a valid weak reference to a section. Returns false if the section
477  // weak pointer has no reference to a section, or if the section is still
478  // valid
479  bool SectionWasDeleted() const;
480 
481 protected:
482  // Member variables.
483  lldb::SectionWP m_section_wp; ///< The section for the address, can be NULL.
484  lldb::addr_t m_offset; ///< Offset into section if \a m_section_wp is valid...
485 
486  // Returns true if the m_section_wp once had a reference to a valid section
487  // shared pointer, but no longer does. This can happen if we have an address
488  // from a module that gets unloaded and deleted. This function should only be
489  // called if GetSection() returns an empty shared pointer and you want to
490  // know if this address used to have a valid section.
491  bool SectionWasDeletedPrivate() const;
492 };
493 
494 // NOTE: Be careful using this operator. It can correctly compare two
495 // addresses from the same Module correctly. It can't compare two addresses
496 // from different modules in any meaningful way, but it will compare the module
497 // pointers.
498 //
499 // To sum things up:
500 // - works great for addresses within the same module - it works for addresses
501 // across multiple modules, but don't expect the
502 // address results to make much sense
503 //
504 // This basically lets Address objects be used in ordered collection classes.
505 bool operator<(const Address &lhs, const Address &rhs);
506 bool operator>(const Address &lhs, const Address &rhs);
507 bool operator==(const Address &lhs, const Address &rhs);
508 bool operator!=(const Address &lhs, const Address &rhs);
509 
510 } // namespace lldb_private
511 
512 #endif // liblldb_Address_h_
bool SetOpcodeLoadAddress(lldb::addr_t load_addr, Target *target, AddressClass addr_class=AddressClass::eInvalid, bool allow_section_end=false)
Definition: Address.cpp:360
lldb::addr_t GetCallableLoadAddress(Target *target, bool is_indirect=false) const
Get the load address as a callable code load address.
Definition: Address.cpp:317
A line table entry class.
Definition: LineEntry.h:20
bool IsSectionOffset() const
Check if an address is section offset.
Definition: Address.h:330
Function * CalculateSymbolContextFunction() const
Definition: Address.cpp:822
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
uint32_t CalculateSymbolContext(SymbolContext *sc, lldb::SymbolContextItem resolve_scope=lldb::eSymbolContextEverything) const
Reconstruct a symbol context from an address.
Definition: Address.cpp:782
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
bool SetCallableLoadAddress(lldb::addr_t load_addr, Target *target)
Definition: Address.cpp:340
CompileUnit * CalculateSymbolContextCompileUnit() const
Definition: Address.cpp:808
Defines a symbol context baton that can be handed other debug core functions.
Definition: SymbolContext.h:33
lldb::addr_t GetLoadAddress(Target *target) const
Get the load address.
Definition: Address.cpp:292
void SetSection(const lldb::SectionSP &section_sp)
Set accessor for the section.
Definition: Address.h:444
bool Dump(Stream *s, ExecutionContextScope *exe_scope, DumpStyle style, DumpStyle fallback_style=DumpStyleInvalid, uint32_t addr_byte_size=UINT32_MAX) const
Dump a description of this object to a Stream.
Definition: Address.cpp:374
static int CompareModulePointerAndOffset(const Address &lhs, const Address &rhs)
Definition: Address.cpp:904
A class that describes a function.
Definition: Function.h:323
lldb::addr_t GetFileAddress() const
Get the file address.
Definition: Address.cpp:272
static int CompareLoadAddress(const Address &lhs, const Address &rhs, Target *target)
Definition: Address.cpp:892
Address(const lldb::SectionSP &section_sp, lldb::addr_t offset)
Construct with a section pointer and offset.
Definition: Address.h:151
Address(const Address &rhs)
Copy constructor.
Definition: Address.h:138
A class that describes a single lexical block.
Definition: Block.h:41
bool SetLoadAddress(lldb::addr_t load_addr, Target *target, bool allow_section_end=false)
Set the address to represent load_addr.
Definition: Address.cpp:998
bool SectionWasDeleted() const
Definition: Address.cpp:762
lldb::ModuleSP CalculateSymbolContextModule() const
Definition: Address.cpp:801
Display as the section pointer + offset (debug output).
Definition: Address.h:90
bool SetOffset(lldb::addr_t offset)
Set accessor for the offset.
Definition: Address.h:419
DumpStyle
Dump styles allow the Address::Dump(Stream *,DumpStyle) const function to display Address contents in...
Definition: Address.h:84
lldb::SectionWP m_section_wp
The section for the address, can be NULL.
Definition: Address.h:483
A class that describes a compilation unit.
Definition: CompileUnit.h:35
static int CompareFileAddress(const Address &lhs, const Address &rhs)
Compare two Address objects.
Definition: Address.cpp:882
lldb::addr_t GetOffset() const
Get the section relative offset value.
Definition: Address.h:317
bool operator==(const Address &lhs, const Address &rhs)
Definition: Address.cpp:973
lldb::addr_t m_offset
Offset into section if m_section_wp is valid...
Definition: Address.h:484
#define UINT32_MAX
Definition: lldb-defines.h:31
bool Slide(int64_t offset)
Definition: Address.h:430
AddressClass GetAddressClass() const
Definition: Address.cpp:983
#define LLDB_INVALID_ADDRESS
Invalid value definitions.
Definition: lldb-defines.h:85
Address()
Default constructor.
Definition: Address.h:130
const Address & operator=(const Address &rhs)
Assignment operator.
Definition: Address.cpp:239
lldb::addr_t GetOpcodeLoadAddress(Target *target, AddressClass addr_class=AddressClass::eInvalid) const
Get the load address as an opcode load address.
Definition: Address.cpp:349
"lldb/Target/ExecutionContextScope.h" Inherit from this if your object can reconstruct its execution ...
Display as the section name + offset.
Definition: Address.h:86
Detailed symbol context information for an address for all symbol context members.
Definition: Address.h:118
void SetRawAddress(lldb::addr_t addr)
Definition: Address.h:425
bool IsValid() const
Check if the object state is valid.
Definition: Address.h:343
A section + offset based address class.
Definition: Address.h:80
bool operator!=(const Address &lhs, const Address &rhs)
Definition: Address.cpp:979
Dereference a pointer at the current address and then lookup the.
Definition: Address.h:121
bool CalculateSymbolContextLineEntry(LineEntry &line_entry) const
Definition: Address.cpp:864
size_t MemorySize() const
Get the memory cost of this object.
Definition: Address.cpp:924
Block * CalculateSymbolContextBlock() const
Definition: Address.cpp:836
bool operator>(const Address &lhs, const Address &rhs)
Definition: Address.cpp:957
bool operator()(const Address &a, const Address &b) const
Definition: Address.h:219
Display the details about what an address resolves to.
Definition: Address.h:108
uint64_t addr_t
Definition: lldb-types.h:83
Display as the load address (if resolved).
Definition: Address.h:104
lldb::ModuleSP GetModule() const
Get accessor for the module for this address.
Definition: Address.cpp:264
bool SectionWasDeletedPrivate() const
Definition: Address.cpp:768
Display as the file address with the module name prepended (if any).
Definition: Address.h:99
Elide the function name; display an offset into the current function.
Definition: Address.h:115
bool ResolveAddressUsingFileSections(lldb::addr_t addr, const SectionList *sections)
Resolve a file virtual address using a section list.
Definition: Address.cpp:247
Symbol * CalculateSymbolContextSymbol() const
Definition: Address.cpp:850
lldb::SectionSP GetSection() const
Get const accessor for the section.
Definition: Address.h:410
bool operator<(const Address &lhs, const Address &rhs)
Definition: Address.cpp:942
void Clear()
Clear the object&#39;s state.
Definition: Address.h:189
Display as the file address (if any).
Definition: Address.h:95