1 //===-- Address.h -----------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_Address_h_
11 #define liblldb_Address_h_
17 // Other libraries and framework includes
19 #include "lldb/lldb-private.h"
20 #include "lldb/Symbol/SymbolContextScope.h"
22 namespace lldb_private {
24 //----------------------------------------------------------------------
25 /// @class Address Address.h "lldb/Core/Address.h"
26 /// @brief A section + offset based address class.
28 /// The Address class allows addresses to be relative to a section
29 /// that can move during runtime due to images (executables, shared
30 /// libraries, bundles, frameworks) being loaded at different
31 /// addresses than the addresses found in the object file that
32 /// represents them on disk. There are currently two types of addresses
34 /// @li file addresses
35 /// @li load addresses
37 /// File addresses represent the virtual addresses that are in the "on
38 /// disk" object files. These virtual addresses are converted to be
39 /// relative to unique sections scoped to the object file so that
40 /// when/if the addresses slide when the images are loaded/unloaded
41 /// in memory, we can easily track these changes without having to
42 /// update every object (compile unit ranges, line tables, function
43 /// address ranges, lexical block and inlined subroutine address
44 /// ranges, global and static variables) each time an image is loaded or
47 /// Load addresses represent the virtual addresses where each section
48 /// ends up getting loaded at runtime. Before executing a program, it
49 /// is common for all of the load addresses to be unresolved. When a
50 /// DynamicLoader plug-in receives notification that shared libraries
51 /// have been loaded/unloaded, the load addresses of the main executable
52 /// and any images (shared libraries) will be resolved/unresolved. When
53 /// this happens, breakpoints that are in one of these sections can be
55 //----------------------------------------------------------------------
59 //------------------------------------------------------------------
60 /// Dump styles allow the Address::Dump(Stream *,DumpStyle) const
61 /// function to display Address contents in a variety of ways.
62 //------------------------------------------------------------------
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
70 DumpStyleSectionPointerOffset, ///< Display as the section pointer + offset (debug output).
72 /// // address for printf in libSystem.B.dylib as a section pointer + offset
73 /// (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 module name prepended (if any).
80 /// // address for printf in libSystem.B.dylib as a file address
81 /// libSystem.B.dylib[0x000000000005dcff] \endcode
82 DumpStyleLoadAddress, ///< Display as the load address (if resolved).
84 /// // address for printf in libSystem.B.dylib as a load address
85 /// 0x00007fff8306bcff \endcode
86 DumpStyleResolvedDescription, ///< Display the details about what an address resolves to. This can
87 ///< be anything from a symbol context summary (module, function/symbol,
88 ///< and file and line), to information about what the pointer points to
89 ///< if the address is in a section (section of pointers, c strings, etc).
90 DumpStyleResolvedDescriptionNoModule,
91 DumpStyleResolvedDescriptionNoFunctionArguments,
92 DumpStyleNoFunctionName, ///< Elide the function name; display an offset into the current function.
93 ///< Used primarily in disassembly symbolication
94 DumpStyleDetailedSymbolContext, ///< Detailed symbol context information for an address for all symbol
96 DumpStyleResolvedPointerDescription ///< Dereference a pointer at the current address and then lookup the
97 ///< dereferenced address using DumpStyleResolvedDescription
100 //------------------------------------------------------------------
101 /// Default constructor.
103 /// Initialize with a invalid section (NULL) and an invalid
104 /// offset (LLDB_INVALID_ADDRESS).
105 //------------------------------------------------------------------
108 m_offset (LLDB_INVALID_ADDRESS)
112 //------------------------------------------------------------------
115 /// Makes a copy of the another Address object \a rhs.
118 /// A const Address object reference to copy.
119 //------------------------------------------------------------------
120 Address (const Address& rhs) :
121 m_section_wp (rhs.m_section_wp),
122 m_offset(rhs.m_offset.load())
126 //------------------------------------------------------------------
127 /// Construct with a section pointer and offset.
129 /// Initialize the address with the supplied \a section and \a
132 /// @param[in] section
133 /// A section pointer to a valid lldb::Section, or NULL if the
134 /// address doesn't have a section or will get resolved later.
136 /// @param[in] offset
137 /// The offset in bytes into \a section.
138 //------------------------------------------------------------------
139 Address (const lldb::SectionSP §ion_sp, lldb::addr_t offset) :
140 m_section_wp (), // Don't init with section_sp in case section_sp is invalid (the weak_ptr will throw)
144 m_section_wp = section_sp;
147 //------------------------------------------------------------------
148 /// Construct with a virtual address and section list.
150 /// Initialize and resolve the address with the supplied virtual
151 /// address \a file_addr.
153 /// @param[in] file_addr
154 /// A virtual file address.
156 /// @param[in] section_list
157 /// A list of sections, one of which may contain the \a file_addr.
158 //------------------------------------------------------------------
159 Address (lldb::addr_t file_addr, const SectionList * section_list);
161 Address (lldb::addr_t abs_addr);
163 //------------------------------------------------------------------
164 /// Assignment operator.
166 /// Copies the address value from another Address object \a rhs
167 /// into \a this object.
170 /// A const Address object reference to copy.
173 /// A const Address object reference to \a this.
174 //------------------------------------------------------------------
177 operator= (const Address& rhs);
180 //------------------------------------------------------------------
181 /// Clear the object's state.
183 /// Sets the section to an invalid value (NULL) and an invalid
184 /// offset (LLDB_INVALID_ADDRESS).
185 //------------------------------------------------------------------
189 m_section_wp.reset();
190 m_offset = LLDB_INVALID_ADDRESS;
193 //------------------------------------------------------------------
194 /// Compare two Address objects.
197 /// The Left Hand Side const Address object reference.
200 /// The Right Hand Side const Address object reference.
203 /// @li -1 if lhs < rhs
204 /// @li 0 if lhs == rhs
205 /// @li 1 if lhs > rhs
206 //------------------------------------------------------------------
208 CompareFileAddress (const Address& lhs, const Address& rhs);
211 CompareLoadAddress (const Address& lhs, const Address& rhs, Target *target);
214 CompareModulePointerAndOffset (const Address& lhs, const Address& rhs);
216 // For use with std::map, std::multi_map
217 class ModulePointerAndOffsetLessThanFunctionObject
220 ModulePointerAndOffsetLessThanFunctionObject() = default;
223 operator() (const Address& a, const Address& b) const
225 return Address::CompareModulePointerAndOffset(a, b) < 0;
229 //------------------------------------------------------------------
230 /// Dump a description of this object to a Stream.
232 /// Dump a description of the contents of this object to the
233 /// supplied stream \a s. There are many ways to display a section
234 /// offset based address, and \a style lets the user choose.
237 /// The stream to which to dump the object description.
240 /// The display style for the address.
242 /// @param[in] fallback_style
243 /// The display style for the address.
246 /// Returns \b true if the address was able to be displayed.
247 /// File and load addresses may be unresolved and it may not be
248 /// possible to display a valid value, \b false will be returned
251 /// @see Address::DumpStyle
252 //------------------------------------------------------------------
255 ExecutionContextScope *exe_scope,
257 DumpStyle fallback_style = DumpStyleInvalid,
258 uint32_t addr_byte_size = UINT32_MAX) const;
261 GetAddressClass () const;
263 //------------------------------------------------------------------
264 /// Get the file address.
266 /// If an address comes from a file on disk that has section
267 /// relative addresses, then it has a virtual address that is
268 /// relative to unique section in the object file.
271 /// The valid file virtual address, or LLDB_INVALID_ADDRESS if
272 /// the address doesn't have a file virtual address (image is
273 /// from memory only with no representation on disk).
274 //------------------------------------------------------------------
276 GetFileAddress () const;
278 //------------------------------------------------------------------
279 /// Get the load address.
281 /// If an address comes from a file on disk that has section
282 /// relative addresses, then it has a virtual address that is
283 /// relative to unique section in the object file. Sections get
284 /// resolved at runtime by DynamicLoader plug-ins as images
285 /// (executables and shared libraries) get loaded/unloaded. If a
286 /// section is loaded, then the load address can be resolved.
289 /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
290 /// the address is currently not loaded.
291 //------------------------------------------------------------------
293 GetLoadAddress (Target *target) const;
295 //------------------------------------------------------------------
296 /// Get the load address as a callable code load address.
298 /// This function will first resolve its address to a load address.
299 /// Then, if the address turns out to be in code address, return the
300 /// load address that would be required to call or return to. The
301 /// address might have extra bits set (bit zero will be set to Thumb
302 /// functions for an ARM target) that are required when changing the
303 /// program counter to setting a return address.
306 /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
307 /// the address is currently not loaded.
308 //------------------------------------------------------------------
310 GetCallableLoadAddress (Target *target, bool is_indirect = false) const;
312 //------------------------------------------------------------------
313 /// Get the load address as an opcode load address.
315 /// This function will first resolve its address to a load address.
316 /// Then, if the address turns out to be in code address, return the
317 /// load address for an opcode. This address object might have
318 /// extra bits set (bit zero will be set to Thumb functions for an
319 /// ARM target) that are required for changing the program counter
320 /// and this function will remove any bits that are intended for
321 /// these special purposes. The result of this function can be used
322 /// to safely write a software breakpoint trap to memory.
325 /// The valid load virtual address with extra callable bits
326 /// removed, or LLDB_INVALID_ADDRESS if the address is currently
328 //------------------------------------------------------------------
330 GetOpcodeLoadAddress (Target *target,
331 lldb::AddressClass addr_class = lldb::eAddressClassInvalid) const;
333 //------------------------------------------------------------------
334 /// Get the section relative offset value.
337 /// The current offset, or LLDB_INVALID_ADDRESS if this address
338 /// doesn't contain a valid offset.
339 //------------------------------------------------------------------
341 GetOffset () const { return m_offset; }
343 //------------------------------------------------------------------
344 /// Check if an address is section offset.
346 /// When converting a virtual file or load address into a section
347 /// offset based address, we often need to know if, given a section
348 /// list, if the address was able to be converted to section offset.
349 /// This function returns true if the current value contained in
350 /// this object is section offset based.
353 /// Returns \b true if the address has a valid section and
354 /// offset, \b false otherwise.
355 //------------------------------------------------------------------
357 IsSectionOffset() const
359 return IsValid() && (GetSection().get() != nullptr);
362 //------------------------------------------------------------------
363 /// Check if the object state is valid.
365 /// A valid Address object contains either a section pointer and
366 /// and offset (for section offset based addresses), or just a valid
367 /// offset (for absolute addresses that have no section).
370 /// Returns \b true if the offset is valid, \b false
372 //------------------------------------------------------------------
376 return m_offset != LLDB_INVALID_ADDRESS;
379 //------------------------------------------------------------------
380 /// Get the memory cost of this object.
383 /// The number of bytes that this object occupies in memory.
384 //------------------------------------------------------------------
388 //------------------------------------------------------------------
389 /// Resolve a file virtual address using a section list.
391 /// Given a list of sections, attempt to resolve \a addr as a
392 /// an offset into one of the file sections.
395 /// Returns \b true if \a addr was able to be resolved, \b false
397 //------------------------------------------------------------------
399 ResolveAddressUsingFileSections (lldb::addr_t addr, const SectionList *sections);
401 //------------------------------------------------------------------
402 /// Set the address to represent \a load_addr.
404 /// The address will attempt to find a loaded section within
405 /// \a target that contains \a load_addr. If successful, this
406 /// address object will have a valid section and offset. Else this
407 /// address object will have no section (NULL) and the offset will
410 /// @param[in] load_addr
411 /// A load address from a current process.
413 /// @param[in] target
414 /// The target to use when trying resolve the address into
415 /// a section + offset. The Target's SectionLoadList object
416 /// is used to resolve the address.
419 /// Returns \b true if the load address was resolved to be
420 /// section/offset, \b false otherwise. It is often ok for an
421 /// address no not resolve to a section in a module, this often
422 /// happens for JIT'ed code, or any load addresses on the stack
424 //------------------------------------------------------------------
426 SetLoadAddress (lldb::addr_t load_addr, Target *target);
429 SetOpcodeLoadAddress (lldb::addr_t load_addr,
431 lldb::AddressClass addr_class = lldb::eAddressClassInvalid);
434 SetCallableLoadAddress (lldb::addr_t load_addr, Target *target);
436 //------------------------------------------------------------------
437 /// Get accessor for the module for this address.
440 /// Returns the Module pointer that this address is an offset
441 /// in, or NULL if this address doesn't belong in a module, or
442 /// isn't resolved yet.
443 //------------------------------------------------------------------
447 //------------------------------------------------------------------
448 /// Get const accessor for the section.
451 /// Returns the const lldb::Section pointer that this address is an
452 /// offset in, or NULL if this address is absolute.
453 //------------------------------------------------------------------
455 GetSection () const { return m_section_wp.lock(); }
457 //------------------------------------------------------------------
458 /// Set accessor for the offset.
460 /// @param[in] offset
461 /// A new offset value for this object.
464 /// Returns \b true if the offset changed, \b false otherwise.
465 //------------------------------------------------------------------
467 SetOffset (lldb::addr_t offset)
469 bool changed = m_offset != offset;
475 SetRawAddress (lldb::addr_t addr)
477 m_section_wp.reset();
482 Slide (int64_t offset)
484 if (m_offset != LLDB_INVALID_ADDRESS)
492 //------------------------------------------------------------------
493 /// Set accessor for the section.
495 /// @param[in] section
496 /// A new lldb::Section pointer to use as the section base. Can
497 /// be NULL for absolute addresses that are not relative to
499 //------------------------------------------------------------------
501 SetSection (const lldb::SectionSP §ion_sp)
503 m_section_wp = section_sp;
509 m_section_wp.reset();
512 //------------------------------------------------------------------
513 /// Reconstruct a symbol context from an address.
515 /// This class doesn't inherit from SymbolContextScope because many
516 /// address objects have short lifespans. Address objects that are
517 /// section offset can reconstruct their symbol context by looking
518 /// up the address in the module found in the section.
520 /// @see SymbolContextScope::CalculateSymbolContext(SymbolContext*)
521 //------------------------------------------------------------------
523 CalculateSymbolContext (SymbolContext *sc,
524 uint32_t resolve_scope = lldb::eSymbolContextEverything) const;
527 CalculateSymbolContextModule () const;
530 CalculateSymbolContextCompileUnit () const;
533 CalculateSymbolContextFunction () const;
536 CalculateSymbolContextBlock () const;
539 CalculateSymbolContextSymbol () const;
542 CalculateSymbolContextLineEntry (LineEntry &line_entry) const;
544 //------------------------------------------------------------------
545 // Returns true if the section should be valid, but isn't because
546 // the shared pointer to the section can't be reconstructed from
547 // a weak pointer that contains a valid weak reference to a section.
548 // Returns false if the section weak pointer has no reference to
549 // a section, or if the section is still valid
550 //------------------------------------------------------------------
552 SectionWasDeleted() const;
555 //------------------------------------------------------------------
557 //------------------------------------------------------------------
558 lldb::SectionWP m_section_wp; ///< The section for the address, can be NULL.
559 std::atomic<lldb::addr_t> m_offset; ///< Offset into section if \a m_section_wp is valid...
561 //------------------------------------------------------------------
562 // Returns true if the m_section_wp once had a reference to a valid
563 // section shared pointer, but no longer does. This can happen if
564 // we have an address from a module that gets unloaded and deleted.
565 // This function should only be called if GetSection() returns an
566 // empty shared pointer and you want to know if this address used to
567 // have a valid section.
568 //------------------------------------------------------------------
570 SectionWasDeletedPrivate() const;
573 //----------------------------------------------------------------------
574 // NOTE: Be careful using this operator. It can correctly compare two
575 // addresses from the same Module correctly. It can't compare two
576 // addresses from different modules in any meaningful way, but it will
577 // compare the module pointers.
580 // - works great for addresses within the same module
581 // - it works for addresses across multiple modules, but don't expect the
582 // address results to make much sense
584 // This basically lets Address objects be used in ordered collection
586 //----------------------------------------------------------------------
587 bool operator< (const Address& lhs, const Address& rhs);
588 bool operator> (const Address& lhs, const Address& rhs);
589 bool operator== (const Address& lhs, const Address& rhs);
590 bool operator!= (const Address& lhs, const Address& rhs);
592 } // namespace lldb_private
594 #endif // liblldb_Address_h_