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