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_
16 // Other libraries and framework includes
18 #include "lldb/lldb-private.h"
19 #include "lldb/Symbol/SymbolContextScope.h"
21 namespace lldb_private {
23 //----------------------------------------------------------------------
24 /// @class Address Address.h "lldb/Core/Address.h"
25 /// @brief A section + offset based address class.
27 /// The Address class allows addresses to be relative to a section
28 /// that can move during runtime due to images (executables, shared
29 /// libraries, bundles, frameworks) being loaded at different
30 /// addresses than the addresses found in the object file that
31 /// represents them on disk. There are currently two types of addresses
33 /// @li file addresses
34 /// @li load addresses
36 /// File addresses represent the virtual addresses that are in the "on
37 /// disk" object files. These virtual addresses are converted to be
38 /// relative to unique sections scoped to the object file so that
39 /// when/if the addresses slide when the images are loaded/unloaded
40 /// in memory, we can easily track these changes without having to
41 /// update every object (compile unit ranges, line tables, function
42 /// address ranges, lexical block and inlined subroutine address
43 /// ranges, global and static variables) each time an image is loaded or
46 /// Load addresses represent the virtual addresses where each section
47 /// ends up getting loaded at runtime. Before executing a program, it
48 /// is common for all of the load addresses to be unresolved. When a
49 /// DynamicLoader plug-in receives notification that shared libraries
50 /// have been loaded/unloaded, the load addresses of the main executable
51 /// and any images (shared libraries) will be resolved/unresolved. When
52 /// this happens, breakpoints that are in one of these sections can be
54 //----------------------------------------------------------------------
58 //------------------------------------------------------------------
59 /// Dump styles allow the Address::Dump(Stream *,DumpStyle) const
60 /// function to display Address contents in a variety of ways.
61 //------------------------------------------------------------------
63 DumpStyleInvalid, ///< Invalid dump style
64 DumpStyleSectionNameOffset, ///< Display as the section name + offset.
66 /// // address for printf in libSystem.B.dylib as a section name + offset
67 /// libSystem.B.dylib.__TEXT.__text + 0x0005cfdf
69 DumpStyleSectionPointerOffset, ///< Display as the section pointer + offset (debug output).
71 /// // address for printf in libSystem.B.dylib as a section pointer + offset
72 /// (lldb::Section *)0x35cc50 + 0x000000000005cfdf \endcode
73 DumpStyleFileAddress, ///< Display as the file address (if any).
75 /// // address for printf in libSystem.B.dylib as a file address
76 /// 0x000000000005dcff \endcode
77 DumpStyleModuleWithFileAddress, ///< Display as the file address with the module name prepended (if any).
79 /// // address for printf in libSystem.B.dylib as a file address
80 /// libSystem.B.dylib[0x000000000005dcff] \endcode
81 DumpStyleLoadAddress, ///< Display as the load address (if resolved).
83 /// // address for printf in libSystem.B.dylib as a load address
84 /// 0x00007fff8306bcff \endcode
85 DumpStyleResolvedDescription, ///< Display the details about what an address resolves to. This can
86 ///< be anything from a symbol context summary (module, function/symbol,
87 ///< and file and line), to information about what the pointer points to
88 ///< if the address is in a section (section of pointers, c strings, etc).
89 DumpStyleResolvedDescriptionNoModule,
90 DumpStyleDetailedSymbolContext, ///< Detailed symbol context information for an address for all symbol
92 DumpStyleResolvedPointerDescription ///< Dereference a pointer at the current address and then lookup the
93 ///< dereferenced address using DumpStyleResolvedDescription
96 //------------------------------------------------------------------
97 /// Default constructor.
99 /// Initialize with a invalid section (NULL) and an invalid
100 /// offset (LLDB_INVALID_ADDRESS).
101 //------------------------------------------------------------------
104 m_offset (LLDB_INVALID_ADDRESS)
109 //------------------------------------------------------------------
112 /// Makes a copy of the another Address object \a rhs.
115 /// A const Address object reference to copy.
116 //------------------------------------------------------------------
117 Address (const Address& rhs) :
118 m_section_wp (rhs.m_section_wp),
119 m_offset(rhs.m_offset.load())
123 //------------------------------------------------------------------
124 /// Construct with a section pointer and offset.
126 /// Initialize the address with the supplied \a section and \a
129 /// @param[in] section
130 /// A section pointer to a valid lldb::Section, or NULL if the
131 /// address doesn't have a section or will get resolved later.
133 /// @param[in] offset
134 /// The offset in bytes into \a section.
135 //------------------------------------------------------------------
136 Address (const lldb::SectionSP §ion_sp, lldb::addr_t offset) :
137 m_section_wp (), // Don't init with section_sp in case section_sp is invalid (the weak_ptr will throw)
141 m_section_wp = section_sp;
144 //------------------------------------------------------------------
145 /// Construct with a virtual address and section list.
147 /// Initialize and resolve the address with the supplied virtual
148 /// address \a file_addr.
150 /// @param[in] file_addr
151 /// A virtual file address.
153 /// @param[in] section_list
154 /// A list of sections, one of which may contain the \a file_addr.
155 //------------------------------------------------------------------
156 Address (lldb::addr_t file_addr, const SectionList * section_list);
158 Address (lldb::addr_t abs_addr);
160 //------------------------------------------------------------------
161 /// Assignment operator.
163 /// Copies the address value from another Address object \a rhs
164 /// into \a this object.
167 /// A const Address object reference to copy.
170 /// A const Address object reference to \a this.
171 //------------------------------------------------------------------
174 operator= (const Address& rhs);
176 //------------------------------------------------------------------
177 /// Clear the object's state.
179 /// Sets the section to an invalid value (NULL) and an invalid
180 /// offset (LLDB_INVALID_ADDRESS).
181 //------------------------------------------------------------------
185 m_section_wp.reset();
186 m_offset = LLDB_INVALID_ADDRESS;
189 //------------------------------------------------------------------
190 /// Compare two Address objects.
193 /// The Left Hand Side const Address object reference.
196 /// The Right Hand Side const Address object reference.
199 /// @li -1 if lhs < rhs
200 /// @li 0 if lhs == rhs
201 /// @li 1 if lhs > rhs
202 //------------------------------------------------------------------
204 CompareFileAddress (const Address& lhs, const Address& rhs);
207 CompareLoadAddress (const Address& lhs, const Address& rhs, Target *target);
210 CompareModulePointerAndOffset (const Address& lhs, const Address& rhs);
212 // For use with std::map, std::multi_map
213 class ModulePointerAndOffsetLessThanFunctionObject
216 ModulePointerAndOffsetLessThanFunctionObject () {}
219 operator() (const Address& a, const Address& b) const
221 return Address::CompareModulePointerAndOffset(a, b) < 0;
225 //------------------------------------------------------------------
226 /// Dump a description of this object to a Stream.
228 /// Dump a description of the contents of this object to the
229 /// supplied stream \a s. There are many ways to display a section
230 /// offset based address, and \a style lets the user choose.
233 /// The stream to which to dump the object descripton.
236 /// The display style for the address.
238 /// @param[in] fallback_style
239 /// The display style for the address.
242 /// Returns \b true if the address was able to be displayed.
243 /// File and load addresses may be unresolved and it may not be
244 /// possible to display a valid value, \b false will be returned
247 /// @see Address::DumpStyle
248 //------------------------------------------------------------------
251 ExecutionContextScope *exe_scope,
253 DumpStyle fallback_style = DumpStyleInvalid,
254 uint32_t addr_byte_size = UINT32_MAX) const;
257 GetAddressClass () const;
259 //------------------------------------------------------------------
260 /// Get the file address.
262 /// If an address comes from a file on disk that has section
263 /// relative addresses, then it has a virtual address that is
264 /// relative to unique section in the object file.
267 /// The valid file virtual address, or LLDB_INVALID_ADDRESS if
268 /// the address doesn't have a file virtual address (image is
269 /// from memory only with no representation on disk).
270 //------------------------------------------------------------------
272 GetFileAddress () const;
274 //------------------------------------------------------------------
275 /// Get the load address.
277 /// If an address comes from a file on disk that has section
278 /// relative addresses, then it has a virtual address that is
279 /// relative to unique section in the object file. Sections get
280 /// resolved at runtime by DynamicLoader plug-ins as images
281 /// (executables and shared libraries) get loaded/unloaded. If a
282 /// section is loaded, then the load address can be resolved.
285 /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
286 /// the address is currently not loaded.
287 //------------------------------------------------------------------
289 GetLoadAddress (Target *target) const;
291 //------------------------------------------------------------------
292 /// Get the load address as a callable code load address.
294 /// This function will first resolve its address to a load address.
295 /// Then, if the address turns out to be in code address, return the
296 /// load address that would be required to call or return to. The
297 /// address might have extra bits set (bit zero will be set to Thumb
298 /// functions for an ARM target) that are required when changing the
299 /// program counter to setting a return address.
302 /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
303 /// the address is currently not loaded.
304 //------------------------------------------------------------------
306 GetCallableLoadAddress (Target *target, bool is_indirect = false) const;
308 //------------------------------------------------------------------
309 /// Get the load address as an opcode load address.
311 /// This function will first resolve its address to a load address.
312 /// Then, if the address turns out to be in code address, return the
313 /// load address for a an opcode. This address object might have
314 /// extra bits set (bit zero will be set to Thumb functions for an
315 /// ARM target) that are required for changing the program counter
316 /// and this function will remove any bits that are intended for
317 /// these special purposes. The result of this function can be used
318 /// to safely write a software breakpoint trap to memory.
321 /// The valid load virtual address with extra callable bits
322 /// removed, or LLDB_INVALID_ADDRESS if the address is currently
324 //------------------------------------------------------------------
326 GetOpcodeLoadAddress (Target *target) const;
328 //------------------------------------------------------------------
329 /// Get the section relative offset value.
332 /// The current offset, or LLDB_INVALID_ADDRESS if this address
333 /// doesn't contain a valid offset.
334 //------------------------------------------------------------------
336 GetOffset () const { return m_offset; }
338 //------------------------------------------------------------------
339 /// Check if an address is section offset.
341 /// When converting a virtual file or load address into a section
342 /// offset based address, we often need to know if, given a section
343 /// list, if the address was able to be converted to section offset.
344 /// This function returns true if the current value contained in
345 /// this object is section offset based.
348 /// Returns \b true if the address has a valid section and
349 /// offset, \b false otherwise.
350 //------------------------------------------------------------------
352 IsSectionOffset() const
354 return IsValid() && (GetSection().get() != NULL);
357 //------------------------------------------------------------------
358 /// Check if the object state is valid.
360 /// A valid Address object contains either a section pointer and
361 /// and offset (for section offset based addresses), or just a valid
362 /// offset (for absolute addresses that have no section).
365 /// Returns \b true if the the offset is valid, \b false
367 //------------------------------------------------------------------
371 return m_offset != LLDB_INVALID_ADDRESS;
375 //------------------------------------------------------------------
376 /// Get the memory cost of this object.
379 /// The number of bytes that this object occupies in memory.
380 //------------------------------------------------------------------
384 //------------------------------------------------------------------
385 /// Resolve a file virtual address using a section list.
387 /// Given a list of sections, attempt to resolve \a addr as a
388 /// an offset into one of the file sections.
391 /// Returns \b true if \a addr was able to be resolved, \b false
393 //------------------------------------------------------------------
395 ResolveAddressUsingFileSections (lldb::addr_t addr, const SectionList *sections);
397 //------------------------------------------------------------------
398 /// Set the address to represent \a load_addr.
400 /// The address will attempt to find a loaded section within
401 /// \a target that contains \a load_addr. If successful, this
402 /// address object will have a valid section and offset. Else this
403 /// address object will have no section (NULL) and the offset will
406 /// @param[in] load_addr
407 /// A load address from a current process.
409 /// @param[in] target
410 /// The target to use when trying resolve the address into
411 /// a section + offset. The Target's SectionLoadList object
412 /// is used to resolve the address.
415 /// Returns \b true if the load address was resolved to be
416 /// section/offset, \b false otherwise. It is often ok for an
417 /// address no not resolve to a section in a module, this often
418 /// happens for JIT'ed code, or any load addresses on the stack
420 //------------------------------------------------------------------
422 SetLoadAddress (lldb::addr_t load_addr, Target *target);
425 SetOpcodeLoadAddress (lldb::addr_t load_addr, Target *target);
428 SetCallableLoadAddress (lldb::addr_t load_addr, Target *target);
430 //------------------------------------------------------------------
431 /// Get accessor for the module for this address.
434 /// Returns the Module pointer that this address is an offset
435 /// in, or NULL if this address doesn't belong in a module, or
436 /// isn't resolved yet.
437 //------------------------------------------------------------------
441 //------------------------------------------------------------------
442 /// Get const accessor for the section.
445 /// Returns the const lldb::Section pointer that this address is an
446 /// offset in, or NULL if this address is absolute.
447 //------------------------------------------------------------------
449 GetSection () const { return m_section_wp.lock(); }
451 //------------------------------------------------------------------
452 /// Set accessor for the offset.
454 /// @param[in] offset
455 /// A new offset value for this object.
458 /// Returns \b true if the offset changed, \b false otherwise.
459 //------------------------------------------------------------------
461 SetOffset (lldb::addr_t offset)
463 bool changed = m_offset != offset;
469 SetRawAddress (lldb::addr_t addr)
471 m_section_wp.reset();
476 Slide (int64_t offset)
478 if (m_offset != LLDB_INVALID_ADDRESS)
486 //------------------------------------------------------------------
487 /// Set accessor for the section.
489 /// @param[in] section
490 /// A new lldb::Section pointer to use as the section base. Can
491 /// be NULL for absolute addresses that are not relative to
493 //------------------------------------------------------------------
495 SetSection (const lldb::SectionSP §ion_sp)
497 m_section_wp = section_sp;
503 m_section_wp.reset();
505 //------------------------------------------------------------------
506 /// Reconstruct a symbol context from an address.
508 /// This class doesn't inherit from SymbolContextScope because many
509 /// address objects have short lifespans. Address objects that are
510 /// section offset can reconstruct their symbol context by looking
511 /// up the address in the module found in the section.
513 /// @see SymbolContextScope::CalculateSymbolContext(SymbolContext*)
514 //------------------------------------------------------------------
516 CalculateSymbolContext (SymbolContext *sc,
517 uint32_t resolve_scope = lldb::eSymbolContextEverything) const;
520 CalculateSymbolContextModule () const;
523 CalculateSymbolContextCompileUnit () const;
526 CalculateSymbolContextFunction () const;
529 CalculateSymbolContextBlock () const;
532 CalculateSymbolContextSymbol () const;
535 CalculateSymbolContextLineEntry (LineEntry &line_entry) const;
538 //------------------------------------------------------------------
540 //------------------------------------------------------------------
541 lldb::SectionWP m_section_wp; ///< The section for the address, can be NULL.
542 std::atomic<lldb::addr_t> m_offset; ///< Offset into section if \a m_section_wp is valid...
546 //----------------------------------------------------------------------
547 // NOTE: Be careful using this operator. It can correctly compare two
548 // addresses from the same Module correctly. It can't compare two
549 // addresses from different modules in any meaningful way, but it will
550 // compare the module pointers.
553 // - works great for addresses within the same module
554 // - it works for addresses across multiple modules, but don't expect the
555 // address results to make much sense
557 // This basically lets Address objects be used in ordered collection
559 //----------------------------------------------------------------------
560 bool operator< (const Address& lhs, const Address& rhs);
561 bool operator> (const Address& lhs, const Address& rhs);
565 bool operator== (const Address& lhs, const Address& rhs);
566 bool operator!= (const Address& lhs, const Address& rhs);
568 } // namespace lldb_private
570 #endif // liblldb_Address_h_