1 //===-- Address.h -----------------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef liblldb_Address_h_
10 #define liblldb_Address_h_
12 #include "lldb/lldb-defines.h"
13 #include "lldb/lldb-forward.h"
14 #include "lldb/lldb-private-enumerations.h"
15 #include "lldb/lldb-types.h"
20 namespace lldb_private {
23 class ExecutionContextScope;
32 /// \class Address Address.h "lldb/Core/Address.h"
33 /// A section + offset based address class.
35 /// The Address class allows addresses to be relative to a section that can
36 /// move during runtime due to images (executables, shared libraries, bundles,
37 /// frameworks) being loaded at different addresses than the addresses found
38 /// in the object file that represents them on disk. There are currently two
39 /// types of addresses for a section:
40 /// \li file addresses
41 /// \li load addresses
43 /// File addresses represent the virtual addresses that are in the "on disk"
44 /// object files. These virtual addresses are converted to be relative to
45 /// unique sections scoped to the object file so that when/if the addresses
46 /// slide when the images are loaded/unloaded in memory, we can easily track
47 /// these changes without having to update every object (compile unit ranges,
48 /// line tables, function address ranges, lexical block and inlined subroutine
49 /// address ranges, global and static variables) each time an image is loaded
52 /// Load addresses represent the virtual addresses where each section ends up
53 /// getting loaded at runtime. Before executing a program, it is common for
54 /// all of the load addresses to be unresolved. When a DynamicLoader plug-in
55 /// receives notification that shared libraries have been loaded/unloaded, the
56 /// load addresses of the main executable and any images (shared libraries)
57 /// will be resolved/unresolved. When this happens, breakpoints that are in
58 /// one of these sections can be set/cleared.
61 /// Dump styles allow the Address::Dump(Stream *,DumpStyle) const function
62 /// to display Address contents in a variety of ways.
64 DumpStyleInvalid, ///< Invalid dump style
65 DumpStyleSectionNameOffset, ///< Display as the section name + offset.
67 /// // address for printf in libSystem.B.dylib as a section name + offset
68 /// libSystem.B.dylib.__TEXT.__text + 0x0005cfdf \endcode
69 DumpStyleSectionPointerOffset, ///< Display as the section pointer + offset
72 /// // address for printf in libSystem.B.dylib as a section pointer +
73 /// offset (lldb::Section *)0x35cc50 + 0x000000000005cfdf \endcode
74 DumpStyleFileAddress, ///< Display as the file address (if any).
76 /// // address for printf in libSystem.B.dylib as a file address
77 /// 0x000000000005dcff \endcode
78 DumpStyleModuleWithFileAddress, ///< Display as the file address with the
79 /// module name prepended (if any).
81 /// // address for printf in libSystem.B.dylib as a file address
82 /// libSystem.B.dylib[0x000000000005dcff] \endcode
83 DumpStyleLoadAddress, ///< Display as the load address (if resolved).
85 /// // address for printf in libSystem.B.dylib as a load address
86 /// 0x00007fff8306bcff \endcode
87 DumpStyleResolvedDescription, ///< Display the details about what an address
88 /// resolves to. This can
89 ///< be anything from a symbol context summary (module, function/symbol,
90 ///< and file and line), to information about what the pointer points to
91 ///< if the address is in a section (section of pointers, c strings, etc).
92 DumpStyleResolvedDescriptionNoModule,
93 DumpStyleResolvedDescriptionNoFunctionArguments,
94 DumpStyleNoFunctionName, ///< Elide the function name; display an offset
95 /// into the current function.
96 ///< Used primarily in disassembly symbolication
97 DumpStyleDetailedSymbolContext, ///< Detailed symbol context information for
98 /// an address for all symbol
100 DumpStyleResolvedPointerDescription ///< Dereference a pointer at the
101 /// current address and then lookup the
102 ///< dereferenced address using DumpStyleResolvedDescription
105 /// Default constructor.
107 /// Initialize with a invalid section (NULL) and an invalid offset
108 /// (LLDB_INVALID_ADDRESS).
109 Address() : m_section_wp(), m_offset(LLDB_INVALID_ADDRESS) {}
113 /// Makes a copy of the another Address object \a rhs.
116 /// A const Address object reference to copy.
117 Address(const Address &rhs)
118 : m_section_wp(rhs.m_section_wp), m_offset(rhs.m_offset) {}
120 /// Construct with a section pointer and offset.
122 /// Initialize the address with the supplied \a section and \a offset.
124 /// \param[in] section
125 /// A section pointer to a valid lldb::Section, or NULL if the
126 /// address doesn't have a section or will get resolved later.
128 /// \param[in] offset
129 /// The offset in bytes into \a section.
130 Address(const lldb::SectionSP §ion_sp, lldb::addr_t offset)
131 : m_section_wp(), // Don't init with section_sp in case section_sp is
132 // invalid (the weak_ptr will throw)
135 m_section_wp = section_sp;
138 /// Construct with a virtual address and section list.
140 /// Initialize and resolve the address with the supplied virtual address \a
143 /// \param[in] file_addr
144 /// A virtual file address.
146 /// \param[in] section_list
147 /// A list of sections, one of which may contain the \a file_addr.
148 Address(lldb::addr_t file_addr, const SectionList *section_list);
150 Address(lldb::addr_t abs_addr);
152 /// Assignment operator.
154 /// Copies the address value from another Address object \a rhs into \a this
158 /// A const Address object reference to copy.
161 /// A const Address object reference to \a this.
162 const Address &operator=(const Address &rhs);
164 /// Clear the object's state.
166 /// Sets the section to an invalid value (NULL) and an invalid offset
167 /// (LLDB_INVALID_ADDRESS).
169 m_section_wp.reset();
170 m_offset = LLDB_INVALID_ADDRESS;
173 /// Compare two Address objects.
176 /// The Left Hand Side const Address object reference.
179 /// The Right Hand Side const Address object reference.
182 /// \li -1 if lhs < rhs
183 /// \li 0 if lhs == rhs
184 /// \li 1 if lhs > rhs
185 static int CompareFileAddress(const Address &lhs, const Address &rhs);
187 static int CompareLoadAddress(const Address &lhs, const Address &rhs,
190 static int CompareModulePointerAndOffset(const Address &lhs,
193 // For use with std::map, std::multi_map
194 class ModulePointerAndOffsetLessThanFunctionObject {
196 ModulePointerAndOffsetLessThanFunctionObject() = default;
198 bool operator()(const Address &a, const Address &b) const {
199 return Address::CompareModulePointerAndOffset(a, b) < 0;
203 /// Dump a description of this object to a Stream.
205 /// Dump a description of the contents of this object to the supplied stream
206 /// \a s. There are many ways to display a section offset based address, and
207 /// \a style lets the user choose.
210 /// The stream to which to dump the object description.
213 /// The display style for the address.
215 /// \param[in] fallback_style
216 /// The display style for the address.
219 /// Returns \b true if the address was able to be displayed.
220 /// File and load addresses may be unresolved and it may not be
221 /// possible to display a valid value, \b false will be returned
224 /// \see Address::DumpStyle
225 bool Dump(Stream *s, ExecutionContextScope *exe_scope, DumpStyle style,
226 DumpStyle fallback_style = DumpStyleInvalid,
227 uint32_t addr_byte_size = UINT32_MAX) const;
229 AddressClass GetAddressClass() const;
231 /// Get the file address.
233 /// If an address comes from a file on disk that has section relative
234 /// addresses, then it has a virtual address that is relative to unique
235 /// section in the object file.
238 /// The valid file virtual address, or LLDB_INVALID_ADDRESS if
239 /// the address doesn't have a file virtual address (image is
240 /// from memory only with no representation on disk).
241 lldb::addr_t GetFileAddress() const;
243 /// Get the load address.
245 /// If an address comes from a file on disk that has section relative
246 /// addresses, then it has a virtual address that is relative to unique
247 /// section in the object file. Sections get resolved at runtime by
248 /// DynamicLoader plug-ins as images (executables and shared libraries) get
249 /// loaded/unloaded. If a section is loaded, then the load address can be
253 /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
254 /// the address is currently not loaded.
255 lldb::addr_t GetLoadAddress(Target *target) const;
257 /// Get the load address as a callable code load address.
259 /// This function will first resolve its address to a load address. Then, if
260 /// the address turns out to be in code address, return the load address
261 /// that would be required to call or return to. The address might have
262 /// extra bits set (bit zero will be set to Thumb functions for an ARM
263 /// target) that are required when changing the program counter to setting a
267 /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
268 /// the address is currently not loaded.
269 lldb::addr_t GetCallableLoadAddress(Target *target,
270 bool is_indirect = false) const;
272 /// Get the load address as an opcode load address.
274 /// This function will first resolve its address to a load address. Then, if
275 /// the address turns out to be in code address, return the load address for
276 /// an opcode. This address object might have extra bits set (bit zero will
277 /// be set to Thumb functions for an
278 /// ARM target) that are required for changing the program counter
279 /// and this function will remove any bits that are intended for these
280 /// special purposes. The result of this function can be used to safely
281 /// write a software breakpoint trap to memory.
284 /// The valid load virtual address with extra callable bits
285 /// removed, or LLDB_INVALID_ADDRESS if the address is currently
287 lldb::addr_t GetOpcodeLoadAddress(
289 AddressClass addr_class = AddressClass::eInvalid) const;
291 /// Get the section relative offset value.
294 /// The current offset, or LLDB_INVALID_ADDRESS if this address
295 /// doesn't contain a valid offset.
296 lldb::addr_t GetOffset() const { return m_offset; }
298 /// Check if an address is section offset.
300 /// When converting a virtual file or load address into a section offset
301 /// based address, we often need to know if, given a section list, if the
302 /// address was able to be converted to section offset. This function
303 /// returns true if the current value contained in this object is section
307 /// Returns \b true if the address has a valid section and
308 /// offset, \b false otherwise.
309 bool IsSectionOffset() const {
310 return IsValid() && (GetSection().get() != nullptr);
313 /// Check if the object state is valid.
315 /// A valid Address object contains either a section pointer and
316 /// offset (for section offset based addresses), or just a valid offset
317 /// (for absolute addresses that have no section).
320 /// Returns \b true if the offset is valid, \b false
322 bool IsValid() const { return m_offset != LLDB_INVALID_ADDRESS; }
324 /// Get the memory cost of this object.
327 /// The number of bytes that this object occupies in memory.
328 size_t MemorySize() const;
330 /// Resolve a file virtual address using a section list.
332 /// Given a list of sections, attempt to resolve \a addr as an offset into
333 /// one of the file sections.
336 /// Returns \b true if \a addr was able to be resolved, \b false
338 bool ResolveAddressUsingFileSections(lldb::addr_t addr,
339 const SectionList *sections);
341 /// Resolve this address to its containing function and optionally get
342 /// that function's address range.
344 /// \param[out] sym_ctx
345 /// The symbol context describing the function in which this address lies
347 /// \parm[out] addr_range_ptr
348 /// Pointer to the AddressRange to fill in with the function's address
349 /// range. Caller may pass null if they don't need the address range.
352 /// Returns \b false if the function/symbol could not be resolved
353 /// or if the address range was requested and could not be resolved;
354 /// returns \b true otherwise.
355 bool ResolveFunctionScope(lldb_private::SymbolContext &sym_ctx,
356 lldb_private::AddressRange *addr_range_ptr = nullptr);
358 /// Set the address to represent \a load_addr.
360 /// The address will attempt to find a loaded section within \a target that
361 /// contains \a load_addr. If successful, this address object will have a
362 /// valid section and offset. Else this address object will have no section
363 /// (NULL) and the offset will be \a load_addr.
365 /// \param[in] load_addr
366 /// A load address from a current process.
368 /// \param[in] target
369 /// The target to use when trying resolve the address into
370 /// a section + offset. The Target's SectionLoadList object
371 /// is used to resolve the address.
373 /// \param[in] allow_section_end
374 /// If true, treat an address pointing to the end of the module as
375 /// belonging to that module.
378 /// Returns \b true if the load address was resolved to be
379 /// section/offset, \b false otherwise. It is often ok for an
380 /// address to not resolve to a section in a module, this often
381 /// happens for JIT'ed code, or any load addresses on the stack
383 bool SetLoadAddress(lldb::addr_t load_addr, Target *target,
384 bool allow_section_end = false);
386 bool SetOpcodeLoadAddress(
387 lldb::addr_t load_addr, Target *target,
388 AddressClass addr_class = AddressClass::eInvalid,
389 bool allow_section_end = false);
391 bool SetCallableLoadAddress(lldb::addr_t load_addr, Target *target);
393 /// Get accessor for the module for this address.
396 /// Returns the Module pointer that this address is an offset
397 /// in, or NULL if this address doesn't belong in a module, or
398 /// isn't resolved yet.
399 lldb::ModuleSP GetModule() const;
401 /// Get const accessor for the section.
404 /// Returns the const lldb::Section pointer that this address is an
405 /// offset in, or NULL if this address is absolute.
406 lldb::SectionSP GetSection() const { return m_section_wp.lock(); }
408 /// Set accessor for the offset.
410 /// \param[in] offset
411 /// A new offset value for this object.
414 /// Returns \b true if the offset changed, \b false otherwise.
415 bool SetOffset(lldb::addr_t offset) {
416 bool changed = m_offset != offset;
421 void SetRawAddress(lldb::addr_t addr) {
422 m_section_wp.reset();
426 bool Slide(int64_t offset) {
427 if (m_offset != LLDB_INVALID_ADDRESS) {
434 /// Set accessor for the section.
436 /// \param[in] section
437 /// A new lldb::Section pointer to use as the section base. Can
438 /// be NULL for absolute addresses that are not relative to
440 void SetSection(const lldb::SectionSP §ion_sp) {
441 m_section_wp = section_sp;
444 void ClearSection() { m_section_wp.reset(); }
446 /// Reconstruct a symbol context from an address.
448 /// This class doesn't inherit from SymbolContextScope because many address
449 /// objects have short lifespans. Address objects that are section offset
450 /// can reconstruct their symbol context by looking up the address in the
451 /// module found in the section.
453 /// \see SymbolContextScope::CalculateSymbolContext(SymbolContext*)
454 uint32_t CalculateSymbolContext(SymbolContext *sc,
455 lldb::SymbolContextItem resolve_scope =
456 lldb::eSymbolContextEverything) const;
458 lldb::ModuleSP CalculateSymbolContextModule() const;
460 CompileUnit *CalculateSymbolContextCompileUnit() const;
462 Function *CalculateSymbolContextFunction() const;
464 Block *CalculateSymbolContextBlock() const;
466 Symbol *CalculateSymbolContextSymbol() const;
468 bool CalculateSymbolContextLineEntry(LineEntry &line_entry) const;
470 // Returns true if the section should be valid, but isn't because the shared
471 // pointer to the section can't be reconstructed from a weak pointer that
472 // contains a valid weak reference to a section. Returns false if the section
473 // weak pointer has no reference to a section, or if the section is still
475 bool SectionWasDeleted() const;
479 lldb::SectionWP m_section_wp; ///< The section for the address, can be NULL.
480 lldb::addr_t m_offset; ///< Offset into section if \a m_section_wp is valid...
482 // Returns true if the m_section_wp once had a reference to a valid section
483 // shared pointer, but no longer does. This can happen if we have an address
484 // from a module that gets unloaded and deleted. This function should only be
485 // called if GetSection() returns an empty shared pointer and you want to
486 // know if this address used to have a valid section.
487 bool SectionWasDeletedPrivate() const;
490 // NOTE: Be careful using this operator. It can correctly compare two
491 // addresses from the same Module correctly. It can't compare two addresses
492 // from different modules in any meaningful way, but it will compare the module
496 // - works great for addresses within the same module - it works for addresses
497 // across multiple modules, but don't expect the
498 // address results to make much sense
500 // This basically lets Address objects be used in ordered collection classes.
501 bool operator<(const Address &lhs, const Address &rhs);
502 bool operator>(const Address &lhs, const Address &rhs);
503 bool operator==(const Address &lhs, const Address &rhs);
504 bool operator!=(const Address &lhs, const Address &rhs);
506 } // namespace lldb_private
508 #endif // liblldb_Address_h_