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