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_
13 #include "lldb/lldb-defines.h"
14 #include "lldb/lldb-forward.h"
15 #include "lldb/lldb-private-enumerations.h"
16 #include "lldb/lldb-types.h"
21 namespace lldb_private {
24 namespace lldb_private {
27 namespace lldb_private {
28 class ExecutionContextScope;
30 namespace lldb_private {
33 namespace lldb_private {
36 namespace lldb_private {
39 namespace lldb_private {
42 namespace lldb_private {
45 namespace lldb_private {
48 namespace lldb_private {
52 namespace lldb_private {
54 //----------------------------------------------------------------------
55 /// @class Address Address.h "lldb/Core/Address.h"
56 /// A section + offset based address class.
58 /// The Address class allows addresses to be relative to a section that can
59 /// move during runtime due to images (executables, shared libraries, bundles,
60 /// frameworks) being loaded at different addresses than the addresses found
61 /// in the object file that represents them on disk. There are currently two
62 /// types of addresses for a section:
63 /// @li file addresses
64 /// @li load addresses
66 /// File addresses represent the virtual addresses that are in the "on disk"
67 /// object files. These virtual addresses are converted to be relative to
68 /// unique sections scoped to the object file so that when/if the addresses
69 /// slide when the images are loaded/unloaded in memory, we can easily track
70 /// these changes without having to update every object (compile unit ranges,
71 /// line tables, function address ranges, lexical block and inlined subroutine
72 /// address ranges, global and static variables) each time an image is loaded
75 /// Load addresses represent the virtual addresses where each section ends up
76 /// getting loaded at runtime. Before executing a program, it is common for
77 /// all of the load addresses to be unresolved. When a DynamicLoader plug-in
78 /// receives notification that shared libraries have been loaded/unloaded, the
79 /// load addresses of the main executable and any images (shared libraries)
80 /// will be resolved/unresolved. When this happens, breakpoints that are in
81 /// one of these sections can be set/cleared.
82 //----------------------------------------------------------------------
85 //------------------------------------------------------------------
86 /// Dump styles allow the Address::Dump(Stream *,DumpStyle) const function
87 /// to display Address contents in a variety of ways.
88 //------------------------------------------------------------------
90 DumpStyleInvalid, ///< Invalid dump style
91 DumpStyleSectionNameOffset, ///< Display as the section name + offset.
93 /// // address for printf in libSystem.B.dylib as a section name + offset
94 /// libSystem.B.dylib.__TEXT.__text + 0x0005cfdf \endcode
95 DumpStyleSectionPointerOffset, ///< Display as the section pointer + offset
98 /// // address for printf in libSystem.B.dylib as a section pointer +
99 /// offset (lldb::Section *)0x35cc50 + 0x000000000005cfdf \endcode
100 DumpStyleFileAddress, ///< Display as the file address (if any).
102 /// // address for printf in libSystem.B.dylib as a file address
103 /// 0x000000000005dcff \endcode
104 DumpStyleModuleWithFileAddress, ///< Display as the file address with the
105 ///module name prepended (if any).
107 /// // address for printf in libSystem.B.dylib as a file address
108 /// libSystem.B.dylib[0x000000000005dcff] \endcode
109 DumpStyleLoadAddress, ///< Display as the load address (if resolved).
111 /// // address for printf in libSystem.B.dylib as a load address
112 /// 0x00007fff8306bcff \endcode
113 DumpStyleResolvedDescription, ///< Display the details about what an address
114 ///resolves to. This can
115 ///< be anything from a symbol context summary (module, function/symbol,
116 ///< and file and line), to information about what the pointer points to
117 ///< if the address is in a section (section of pointers, c strings, etc).
118 DumpStyleResolvedDescriptionNoModule,
119 DumpStyleResolvedDescriptionNoFunctionArguments,
120 DumpStyleNoFunctionName, ///< Elide the function name; display an offset
121 ///into the current function.
122 ///< Used primarily in disassembly symbolication
123 DumpStyleDetailedSymbolContext, ///< Detailed symbol context information for
124 ///an address for all symbol
125 ///< context members.
126 DumpStyleResolvedPointerDescription ///< Dereference a pointer at the
127 ///current address and then lookup the
128 ///< dereferenced address using DumpStyleResolvedDescription
131 //------------------------------------------------------------------
132 /// Default constructor.
134 /// Initialize with a invalid section (NULL) and an invalid offset
135 /// (LLDB_INVALID_ADDRESS).
136 //------------------------------------------------------------------
137 Address() : m_section_wp(), m_offset(LLDB_INVALID_ADDRESS) {}
139 //------------------------------------------------------------------
142 /// Makes a copy of the another Address object \a rhs.
145 /// A const Address object reference to copy.
146 //------------------------------------------------------------------
147 Address(const Address &rhs)
148 : m_section_wp(rhs.m_section_wp), m_offset(rhs.m_offset) {}
150 //------------------------------------------------------------------
151 /// Construct with a section pointer and offset.
153 /// Initialize the address with the supplied \a section and \a offset.
155 /// @param[in] section
156 /// A section pointer to a valid lldb::Section, or NULL if the
157 /// address doesn't have a section or will get resolved later.
159 /// @param[in] offset
160 /// The offset in bytes into \a section.
161 //------------------------------------------------------------------
162 Address(const lldb::SectionSP §ion_sp, lldb::addr_t offset)
163 : m_section_wp(), // Don't init with section_sp in case section_sp is
164 // invalid (the weak_ptr will throw)
167 m_section_wp = section_sp;
170 //------------------------------------------------------------------
171 /// Construct with a virtual address and section list.
173 /// Initialize and resolve the address with the supplied virtual address \a
176 /// @param[in] file_addr
177 /// A virtual file address.
179 /// @param[in] section_list
180 /// A list of sections, one of which may contain the \a file_addr.
181 //------------------------------------------------------------------
182 Address(lldb::addr_t file_addr, const SectionList *section_list);
184 Address(lldb::addr_t abs_addr);
186 //------------------------------------------------------------------
187 /// Assignment operator.
189 /// Copies the address value from another Address object \a rhs into \a this
193 /// A const Address object reference to copy.
196 /// A const Address object reference to \a this.
197 //------------------------------------------------------------------
199 const Address &operator=(const Address &rhs);
202 //------------------------------------------------------------------
203 /// Clear the object's state.
205 /// Sets the section to an invalid value (NULL) and an invalid offset
206 /// (LLDB_INVALID_ADDRESS).
207 //------------------------------------------------------------------
209 m_section_wp.reset();
210 m_offset = LLDB_INVALID_ADDRESS;
213 //------------------------------------------------------------------
214 /// Compare two Address objects.
217 /// The Left Hand Side const Address object reference.
220 /// The Right Hand Side const Address object reference.
223 /// @li -1 if lhs < rhs
224 /// @li 0 if lhs == rhs
225 /// @li 1 if lhs > rhs
226 //------------------------------------------------------------------
227 static int CompareFileAddress(const Address &lhs, const Address &rhs);
229 static int CompareLoadAddress(const Address &lhs, const Address &rhs,
232 static int CompareModulePointerAndOffset(const Address &lhs,
235 // For use with std::map, std::multi_map
236 class ModulePointerAndOffsetLessThanFunctionObject {
238 ModulePointerAndOffsetLessThanFunctionObject() = default;
240 bool operator()(const Address &a, const Address &b) const {
241 return Address::CompareModulePointerAndOffset(a, b) < 0;
245 //------------------------------------------------------------------
246 /// Dump a description of this object to a Stream.
248 /// Dump a description of the contents of this object to the supplied stream
249 /// \a s. There are many ways to display a section offset based address, and
250 /// \a style lets the user choose.
253 /// The stream to which to dump the object description.
256 /// The display style for the address.
258 /// @param[in] fallback_style
259 /// The display style for the address.
262 /// Returns \b true if the address was able to be displayed.
263 /// File and load addresses may be unresolved and it may not be
264 /// possible to display a valid value, \b false will be returned
267 /// @see Address::DumpStyle
268 //------------------------------------------------------------------
269 bool Dump(Stream *s, ExecutionContextScope *exe_scope, DumpStyle style,
270 DumpStyle fallback_style = DumpStyleInvalid,
271 uint32_t addr_byte_size = UINT32_MAX) const;
273 AddressClass GetAddressClass() const;
275 //------------------------------------------------------------------
276 /// Get the file address.
278 /// If an address comes from a file on disk that has section relative
279 /// addresses, then it has a virtual address that is relative to unique
280 /// section in the object file.
283 /// The valid file virtual address, or LLDB_INVALID_ADDRESS if
284 /// the address doesn't have a file virtual address (image is
285 /// from memory only with no representation on disk).
286 //------------------------------------------------------------------
287 lldb::addr_t GetFileAddress() const;
289 //------------------------------------------------------------------
290 /// Get the load address.
292 /// If an address comes from a file on disk that has section relative
293 /// addresses, then it has a virtual address that is relative to unique
294 /// section in the object file. Sections get resolved at runtime by
295 /// DynamicLoader plug-ins as images (executables and shared libraries) get
296 /// loaded/unloaded. If a section is loaded, then the load address can be
300 /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
301 /// the address is currently not loaded.
302 //------------------------------------------------------------------
303 lldb::addr_t GetLoadAddress(Target *target) const;
305 //------------------------------------------------------------------
306 /// Get the load address as a callable code load address.
308 /// This function will first resolve its address to a load address. Then, if
309 /// the address turns out to be in code address, return the load address
310 /// that would be required to call or return to. The address might have
311 /// extra bits set (bit zero will be set to Thumb functions for an ARM
312 /// target) that are required when changing the program counter to setting a
316 /// The valid load virtual address, or LLDB_INVALID_ADDRESS if
317 /// the address is currently not loaded.
318 //------------------------------------------------------------------
319 lldb::addr_t GetCallableLoadAddress(Target *target,
320 bool is_indirect = false) const;
322 //------------------------------------------------------------------
323 /// Get the load address as an opcode load address.
325 /// This function will first resolve its address to a load address. Then, if
326 /// the address turns out to be in code address, return the load address for
327 /// an opcode. This address object might have extra bits set (bit zero will
328 /// be set to Thumb functions for an
329 /// ARM target) that are required for changing the program counter
330 /// and this function will remove any bits that are intended for these
331 /// special purposes. The result of this function can be used to safely
332 /// write a software breakpoint trap to memory.
335 /// The valid load virtual address with extra callable bits
336 /// removed, or LLDB_INVALID_ADDRESS if the address is currently
338 //------------------------------------------------------------------
339 lldb::addr_t GetOpcodeLoadAddress(
341 AddressClass addr_class = AddressClass::eInvalid) const;
343 //------------------------------------------------------------------
344 /// Get the section relative offset value.
347 /// The current offset, or LLDB_INVALID_ADDRESS if this address
348 /// doesn't contain a valid offset.
349 //------------------------------------------------------------------
350 lldb::addr_t GetOffset() const { return m_offset; }
352 //------------------------------------------------------------------
353 /// Check if an address is section offset.
355 /// When converting a virtual file or load address into a section offset
356 /// based address, we often need to know if, given a section list, if the
357 /// address was able to be converted to section offset. This function
358 /// returns true if the current value contained in this object is section
362 /// Returns \b true if the address has a valid section and
363 /// offset, \b false otherwise.
364 //------------------------------------------------------------------
365 bool IsSectionOffset() const {
366 return IsValid() && (GetSection().get() != nullptr);
369 //------------------------------------------------------------------
370 /// Check if the object state is valid.
372 /// A valid Address object contains either a section pointer and
373 /// offset (for section offset based addresses), or just a valid offset
374 /// (for absolute addresses that have no section).
377 /// Returns \b true if the offset is valid, \b false
379 //------------------------------------------------------------------
380 bool IsValid() const { return m_offset != LLDB_INVALID_ADDRESS; }
382 //------------------------------------------------------------------
383 /// Get the memory cost of this object.
386 /// The number of bytes that this object occupies in memory.
387 //------------------------------------------------------------------
388 size_t MemorySize() const;
390 //------------------------------------------------------------------
391 /// Resolve a file virtual address using a section list.
393 /// Given a list of sections, attempt to resolve \a addr as an offset into
394 /// one of the file sections.
397 /// Returns \b true if \a addr was able to be resolved, \b false
399 //------------------------------------------------------------------
400 bool ResolveAddressUsingFileSections(lldb::addr_t addr,
401 const SectionList *sections);
403 //------------------------------------------------------------------
404 /// Set the address to represent \a load_addr.
406 /// The address will attempt to find a loaded section within \a target that
407 /// contains \a load_addr. If successful, this address object will have a
408 /// valid section and offset. Else this address object will have no section
409 /// (NULL) and the offset will be \a load_addr.
411 /// @param[in] load_addr
412 /// A load address from a current process.
414 /// @param[in] target
415 /// The target to use when trying resolve the address into
416 /// a section + offset. The Target's SectionLoadList object
417 /// is used to resolve the address.
419 /// @param[in] allow_section_end
420 /// If true, treat an address pointing to the end of the module as
421 /// belonging to that module.
424 /// Returns \b true if the load address was resolved to be
425 /// section/offset, \b false otherwise. It is often ok for an
426 /// address no not resolve to a section in a module, this often
427 /// happens for JIT'ed code, or any load addresses on the stack
429 //------------------------------------------------------------------
430 bool SetLoadAddress(lldb::addr_t load_addr, Target *target,
431 bool allow_section_end = false);
433 bool SetOpcodeLoadAddress(
434 lldb::addr_t load_addr, Target *target,
435 AddressClass addr_class = AddressClass::eInvalid,
436 bool allow_section_end = false);
438 bool SetCallableLoadAddress(lldb::addr_t load_addr, Target *target);
440 //------------------------------------------------------------------
441 /// Get accessor for the module for this address.
444 /// Returns the Module pointer that this address is an offset
445 /// in, or NULL if this address doesn't belong in a module, or
446 /// isn't resolved yet.
447 //------------------------------------------------------------------
448 lldb::ModuleSP GetModule() const;
450 //------------------------------------------------------------------
451 /// Get const accessor for the section.
454 /// Returns the const lldb::Section pointer that this address is an
455 /// offset in, or NULL if this address is absolute.
456 //------------------------------------------------------------------
457 lldb::SectionSP GetSection() const { return m_section_wp.lock(); }
459 //------------------------------------------------------------------
460 /// Set accessor for the offset.
462 /// @param[in] offset
463 /// A new offset value for this object.
466 /// Returns \b true if the offset changed, \b false otherwise.
467 //------------------------------------------------------------------
468 bool SetOffset(lldb::addr_t offset) {
469 bool changed = m_offset != offset;
474 void SetRawAddress(lldb::addr_t addr) {
475 m_section_wp.reset();
479 bool Slide(int64_t offset) {
480 if (m_offset != LLDB_INVALID_ADDRESS) {
487 //------------------------------------------------------------------
488 /// Set accessor for the section.
490 /// @param[in] section
491 /// A new lldb::Section pointer to use as the section base. Can
492 /// be NULL for absolute addresses that are not relative to
494 //------------------------------------------------------------------
495 void SetSection(const lldb::SectionSP §ion_sp) {
496 m_section_wp = section_sp;
499 void ClearSection() { m_section_wp.reset(); }
501 //------------------------------------------------------------------
502 /// Reconstruct a symbol context from an address.
504 /// This class doesn't inherit from SymbolContextScope because many address
505 /// objects have short lifespans. Address objects that are section offset
506 /// can reconstruct their symbol context by looking up the address in the
507 /// module found in the section.
509 /// @see SymbolContextScope::CalculateSymbolContext(SymbolContext*)
510 //------------------------------------------------------------------
511 uint32_t CalculateSymbolContext(SymbolContext *sc,
512 lldb::SymbolContextItem resolve_scope =
513 lldb::eSymbolContextEverything) const;
515 lldb::ModuleSP CalculateSymbolContextModule() const;
517 CompileUnit *CalculateSymbolContextCompileUnit() const;
519 Function *CalculateSymbolContextFunction() const;
521 Block *CalculateSymbolContextBlock() const;
523 Symbol *CalculateSymbolContextSymbol() const;
525 bool CalculateSymbolContextLineEntry(LineEntry &line_entry) const;
527 //------------------------------------------------------------------
528 // Returns true if the section should be valid, but isn't because the shared
529 // pointer to the section can't be reconstructed from a weak pointer that
530 // contains a valid weak reference to a section. Returns false if the section
531 // weak pointer has no reference to a section, or if the section is still
533 //------------------------------------------------------------------
534 bool SectionWasDeleted() const;
537 //------------------------------------------------------------------
539 //------------------------------------------------------------------
540 lldb::SectionWP m_section_wp; ///< The section for the address, can be NULL.
541 lldb::addr_t m_offset; ///< Offset into section if \a m_section_wp is valid...
543 //------------------------------------------------------------------
544 // Returns true if the m_section_wp once had a reference to a valid section
545 // shared pointer, but no longer does. This can happen if we have an address
546 // from a module that gets unloaded and deleted. This function should only be
547 // called if GetSection() returns an empty shared pointer and you want to
548 // know if this address used to have a valid section.
549 //------------------------------------------------------------------
550 bool SectionWasDeletedPrivate() const;
553 //----------------------------------------------------------------------
554 // NOTE: Be careful using this operator. It can correctly compare two
555 // addresses from the same Module correctly. It can't compare two addresses
556 // from different modules in any meaningful way, but it will compare the module
560 // - works great for addresses within the same module - it works for addresses
561 // across multiple modules, but don't expect the
562 // address results to make much sense
564 // This basically lets Address objects be used in ordered collection classes.
565 //----------------------------------------------------------------------
566 bool operator<(const Address &lhs, const Address &rhs);
567 bool operator>(const Address &lhs, const Address &rhs);
568 bool operator==(const Address &lhs, const Address &rhs);
569 bool operator!=(const Address &lhs, const Address &rhs);
571 } // namespace lldb_private
573 #endif // liblldb_Address_h_