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