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). Address()119 Address() : m_section_wp() {} 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. Address(const Address & rhs)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. Address(const lldb::SectionSP & section_sp,lldb::addr_t offset)140 Address(const lldb::SectionSP §ion_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). Clear()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 operator()208 bool operator()(const Address &a, const Address &b) const { 209 return Address::CompareModulePointerAndOffset(a, b) < 0; 210 } 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. GetOffset()310 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. IsSectionOffset()323 bool IsSectionOffset() const { 324 return IsValid() && (GetSection().get() != nullptr); 325 } 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. IsValid()336 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. GetSection()420 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. SetOffset(lldb::addr_t offset)429 bool SetOffset(lldb::addr_t offset) { 430 bool changed = m_offset != offset; 431 m_offset = offset; 432 return changed; 433 } 434 SetRawAddress(lldb::addr_t addr)435 void SetRawAddress(lldb::addr_t addr) { 436 m_section_wp.reset(); 437 m_offset = addr; 438 } 439 Slide(int64_t offset)440 bool Slide(int64_t offset) { 441 if (m_offset != LLDB_INVALID_ADDRESS) { 442 m_offset += offset; 443 return true; 444 } 445 return false; 446 } 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. SetSection(const lldb::SectionSP & section_sp)454 void SetSection(const lldb::SectionSP §ion_sp) { 455 m_section_wp = section_sp; 456 } 457 ClearSection()458 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 524