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