Coverage Report

Created: 2022-01-18 06:27

/Users/buildslave/jenkins/workspace/coverage/llvm-project/lldb/include/lldb/Core/Address.h
Line
Count
Source (jump to first uncovered line)
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 <cstddef>
18
#include <cstdint>
19
20
namespace lldb_private {
21
class Block;
22
class CompileUnit;
23
class ExecutionContextScope;
24
class Function;
25
class SectionList;
26
class Stream;
27
class Symbol;
28
class SymbolContext;
29
class Target;
30
struct 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.
59
class Address {
60
public:
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
225M
  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
315M
      : 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
2.38k
        m_offset(offset) {
144
2.38k
    if (section_sp)
145
2.14k
      m_section_wp = section_sp;
146
2.38k
  }
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
4.44M
  void Clear() {
179
4.44M
    m_section_wp.reset();
180
4.44M
    m_offset = LLDB_INVALID_ADDRESS;
181
4.44M
  }
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
50.8k
    bool operator()(const Address &a, const Address &b) const {
209
50.8k
      return Address::CompareModulePointerAndOffset(a, b) < 0;
210
50.8k
    }
211
  };
212
213
  /// Write a description of this object to a Stream.
214
  bool GetDescription(Stream &s, Target &target,
215
                      lldb::DescriptionLevel level) const;
216
217
  /// Dump a description of this object to a Stream.
218
  ///
219
  /// Dump a description of the contents of this object to the supplied stream
220
  /// \a s. There are many ways to display a section offset based address, and
221
  /// \a style lets the user choose.
222
  ///
223
  /// \param[in] s
224
  ///     The stream to which to dump the object description.
225
  ///
226
  /// \param[in] style
227
  ///     The display style for the address.
228
  ///
229
  /// \param[in] fallback_style
230
  ///     The display style for the address.
231
  ///
232
  /// \return
233
  ///     Returns \b true if the address was able to be displayed.
234
  ///     File and load addresses may be unresolved and it may not be
235
  ///     possible to display a valid value, \b false will be returned
236
  ///     in such cases.
237
  ///
238
  /// \see Address::DumpStyle
239
  bool Dump(Stream *s, ExecutionContextScope *exe_scope, DumpStyle style,
240
            DumpStyle fallback_style = DumpStyleInvalid,
241
            uint32_t addr_byte_size = UINT32_MAX) const;
242
243
  AddressClass GetAddressClass() const;
244
245
  /// Get the file address.
246
  ///
247
  /// If an address comes from a file on disk that has section relative
248
  /// addresses, then it has a virtual address that is relative to unique
249
  /// section in the object file.
250
  ///
251
  /// \return
252
  ///     The valid file virtual address, or LLDB_INVALID_ADDRESS if
253
  ///     the address doesn't have a file virtual address (image is
254
  ///     from memory only with no representation on disk).
255
  lldb::addr_t GetFileAddress() const;
256
257
  /// Get the load address.
258
  ///
259
  /// If an address comes from a file on disk that has section relative
260
  /// addresses, then it has a virtual address that is relative to unique
261
  /// section in the object file. Sections get resolved at runtime by
262
  /// DynamicLoader plug-ins as images (executables and shared libraries) get
263
  /// loaded/unloaded. If a section is loaded, then the load address can be
264
  /// resolved.
265
  ///
266
  /// \return
267
  ///     The valid load virtual address, or LLDB_INVALID_ADDRESS if
268
  ///     the address is currently not loaded.
269
  lldb::addr_t GetLoadAddress(Target *target) const;
270
271
  /// Get the load address as a callable code load address.
272
  ///
273
  /// This function will first resolve its address to a load address. Then, if
274
  /// the address turns out to be in code address, return the load address
275
  /// that would be required to call or return to. The address might have
276
  /// extra bits set (bit zero will be set to Thumb functions for an ARM
277
  /// target) that are required when changing the program counter to setting a
278
  /// return address.
279
  ///
280
  /// \return
281
  ///     The valid load virtual address, or LLDB_INVALID_ADDRESS if
282
  ///     the address is currently not loaded.
283
  lldb::addr_t GetCallableLoadAddress(Target *target,
284
                                      bool is_indirect = false) const;
285
286
  /// Get the load address as an opcode load address.
287
  ///
288
  /// This function will first resolve its address to a load address. Then, if
289
  /// the address turns out to be in code address, return the load address for
290
  /// an opcode. This address object might have extra bits set (bit zero will
291
  /// be set to Thumb functions for an
292
  /// ARM target) that are required for changing the program counter
293
  /// and this function will remove any bits that are intended for these
294
  /// special purposes. The result of this function can be used to safely
295
  /// write a software breakpoint trap to memory.
296
  ///
297
  /// \return
298
  ///     The valid load virtual address with extra callable bits
299
  ///     removed, or LLDB_INVALID_ADDRESS if the address is currently
300
  ///     not loaded.
301
  lldb::addr_t GetOpcodeLoadAddress(
302
      Target *target,
303
      AddressClass addr_class = AddressClass::eInvalid) const;
304
305
  /// Get the section relative offset value.
306
  ///
307
  /// \return
308
  ///     The current offset, or LLDB_INVALID_ADDRESS if this address
309
  ///     doesn't contain a valid offset.
310
1.60M
  lldb::addr_t GetOffset() const { return m_offset; }
311
312
  /// Check if an address is section offset.
313
  ///
314
  /// When converting a virtual file or load address into a section offset
315
  /// based address, we often need to know if, given a section list, if the
316
  /// address was able to be converted to section offset. This function
317
  /// returns true if the current value contained in this object is section
318
  /// offset based.
319
  ///
320
  /// \return
321
  ///     Returns \b true if the address has a valid section and
322
  ///     offset, \b false otherwise.
323
978k
  bool IsSectionOffset() const {
324
978k
    return IsValid() && 
(GetSection().get() != nullptr)978k
;
325
978k
  }
326
327
  /// Check if the object state is valid.
328
  ///
329
  /// A valid Address object contains either a section pointer and
330
  /// offset (for section offset based addresses), or just a valid offset
331
  /// (for absolute addresses that have no section).
332
  ///
333
  /// \return
334
  ///     Returns \b true if the offset is valid, \b false
335
  ///     otherwise.
336
9.29M
  bool IsValid() const { return m_offset != LLDB_INVALID_ADDRESS; }
337
338
  /// Get the memory cost of this object.
339
  ///
340
  /// \return
341
  ///     The number of bytes that this object occupies in memory.
342
  size_t MemorySize() const;
343
344
  /// Resolve a file virtual address using a section list.
345
  ///
346
  /// Given a list of sections, attempt to resolve \a addr as an offset into
347
  /// one of the file sections.
348
  ///
349
  /// \return
350
  ///     Returns \b true if \a addr was able to be resolved, \b false
351
  ///     otherwise.
352
  bool ResolveAddressUsingFileSections(lldb::addr_t addr,
353
                                       const SectionList *sections);
354
355
  /// Resolve this address to its containing function and optionally get
356
  /// that function's address range.
357
  ///
358
  /// \param[out] sym_ctx
359
  ///     The symbol context describing the function in which this address lies
360
  ///
361
  /// \parm[out] addr_range_ptr
362
  ///     Pointer to the AddressRange to fill in with the function's address
363
  ///     range.  Caller may pass null if they don't need the address range.
364
  ///
365
  /// \return
366
  ///     Returns \b false if the function/symbol could not be resolved
367
  ///     or if the address range was requested and could not be resolved;
368
  ///     returns \b true otherwise.
369
  bool ResolveFunctionScope(lldb_private::SymbolContext &sym_ctx,
370
                            lldb_private::AddressRange *addr_range_ptr = nullptr);
371
372
  /// Set the address to represent \a load_addr.
373
  ///
374
  /// The address will attempt to find a loaded section within \a target that
375
  /// contains \a load_addr. If successful, this address object will have a
376
  /// valid section and offset. Else this address object will have no section
377
  /// (NULL) and the offset will be \a load_addr.
378
  ///
379
  /// \param[in] load_addr
380
  ///     A load address from a current process.
381
  ///
382
  /// \param[in] target
383
  ///     The target to use when trying resolve the address into
384
  ///     a section + offset. The Target's SectionLoadList object
385
  ///     is used to resolve the address.
386
  ///
387
  /// \param[in] allow_section_end
388
  ///     If true, treat an address pointing to the end of the module as
389
  ///     belonging to that module.
390
  ///
391
  /// \return
392
  ///     Returns \b true if the load address was resolved to be
393
  ///     section/offset, \b false otherwise. It is often ok for an
394
  ///     address to not resolve to a section in a module, this often
395
  ///     happens for JIT'ed code, or any load addresses on the stack
396
  ///     or heap.
397
  bool SetLoadAddress(lldb::addr_t load_addr, Target *target,
398
                      bool allow_section_end = false);
399
400
  bool SetOpcodeLoadAddress(
401
      lldb::addr_t load_addr, Target *target,
402
      AddressClass addr_class = AddressClass::eInvalid,
403
      bool allow_section_end = false);
404
405
  bool SetCallableLoadAddress(lldb::addr_t load_addr, Target *target);
406
407
  /// Get accessor for the module for this address.
408
  ///
409
  /// \return
410
  ///     Returns the Module pointer that this address is an offset
411
  ///     in, or NULL if this address doesn't belong in a module, or
412
  ///     isn't resolved yet.
413
  lldb::ModuleSP GetModule() const;
414
415
  /// Get const accessor for the section.
416
  ///
417
  /// \return
418
  ///     Returns the const lldb::Section pointer that this address is an
419
  ///     offset in, or NULL if this address is absolute.
420
816M
  lldb::SectionSP GetSection() const { return m_section_wp.lock(); }
421
422
  /// Set accessor for the offset.
423
  ///
424
  /// \param[in] offset
425
  ///     A new offset value for this object.
426
  ///
427
  /// \return
428
  ///     Returns \b true if the offset changed, \b false otherwise.
429
159M
  bool SetOffset(lldb::addr_t offset) {
430
159M
    bool changed = m_offset != offset;
431
159M
    m_offset = offset;
432
159M
    return changed;
433
159M
  }
434
435
1.04k
  void SetRawAddress(lldb::addr_t addr) {
436
1.04k
    m_section_wp.reset();
437
1.04k
    m_offset = addr;
438
1.04k
  }
439
440
1.00M
  bool Slide(int64_t offset) {
441
1.00M
    if (m_offset != LLDB_INVALID_ADDRESS) {
442
1.00M
      m_offset += offset;
443
1.00M
      return true;
444
1.00M
    }
445
8
    return false;
446
1.00M
  }
447
448
  /// Set accessor for the section.
449
  ///
450
  /// \param[in] section_sp
451
  ///     A new lldb::Section pointer to use as the section base. Can
452
  ///     be NULL for absolute addresses that are not relative to
453
  ///     any section.
454
159M
  void SetSection(const lldb::SectionSP &section_sp) {
455
159M
    m_section_wp = section_sp;
456
159M
  }
457
458
0
  void ClearSection() { m_section_wp.reset(); }
459
460
  /// Reconstruct a symbol context from an address.
461
  ///
462
  /// This class doesn't inherit from SymbolContextScope because many address
463
  /// objects have short lifespans. Address objects that are section offset
464
  /// can reconstruct their symbol context by looking up the address in the
465
  /// module found in the section.
466
  ///
467
  /// \see SymbolContextScope::CalculateSymbolContext(SymbolContext*)
468
  uint32_t CalculateSymbolContext(SymbolContext *sc,
469
                                  lldb::SymbolContextItem resolve_scope =
470
                                      lldb::eSymbolContextEverything) const;
471
472
  lldb::ModuleSP CalculateSymbolContextModule() const;
473
474
  CompileUnit *CalculateSymbolContextCompileUnit() const;
475
476
  Function *CalculateSymbolContextFunction() const;
477
478
  Block *CalculateSymbolContextBlock() const;
479
480
  Symbol *CalculateSymbolContextSymbol() const;
481
482
  bool CalculateSymbolContextLineEntry(LineEntry &line_entry) const;
483
484
  // Returns true if the section should be valid, but isn't because the shared
485
  // pointer to the section can't be reconstructed from a weak pointer that
486
  // contains a valid weak reference to a section. Returns false if the section
487
  // weak pointer has no reference to a section, or if the section is still
488
  // valid
489
  bool SectionWasDeleted() const;
490
491
protected:
492
  // Member variables.
493
  lldb::SectionWP m_section_wp; ///< The section for the address, can be NULL.
494
  lldb::addr_t m_offset = LLDB_INVALID_ADDRESS; ///< Offset into section if \a
495
                                                ///< m_section_wp is valid...
496
497
  // Returns true if the m_section_wp once had a reference to a valid section
498
  // shared pointer, but no longer does. This can happen if we have an address
499
  // from a module that gets unloaded and deleted. This function should only be
500
  // called if GetSection() returns an empty shared pointer and you want to
501
  // know if this address used to have a valid section.
502
  bool SectionWasDeletedPrivate() const;
503
};
504
505
// NOTE: Be careful using this operator. It can correctly compare two
506
// addresses from the same Module correctly. It can't compare two addresses
507
// from different modules in any meaningful way, but it will compare the module
508
// pointers.
509
//
510
// To sum things up:
511
// - works great for addresses within the same module - it works for addresses
512
// across multiple modules, but don't expect the
513
//   address results to make much sense
514
//
515
// This basically lets Address objects be used in ordered collection classes.
516
bool operator<(const Address &lhs, const Address &rhs);
517
bool operator>(const Address &lhs, const Address &rhs);
518
bool operator==(const Address &lhs, const Address &rhs);
519
bool operator!=(const Address &lhs, const Address &rhs);
520
521
} // namespace lldb_private
522
523
#endif // LLDB_CORE_ADDRESS_H