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