Address.h revision 13d24fb1817faa7ccc4cfd799113ba1a2b8968eb
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 } DumpStyle; 92 93 //------------------------------------------------------------------ 94 /// Default constructor. 95 /// 96 /// Initialize with a invalid section (NULL) and an invalid 97 /// offset (LLDB_INVALID_ADDRESS). 98 //------------------------------------------------------------------ 99 Address () : 100 m_section (NULL), 101 m_offset (LLDB_INVALID_ADDRESS) 102 { 103 } 104 105 106 //------------------------------------------------------------------ 107 /// Copy constructor 108 /// 109 /// Makes a copy of the another Address object \a rhs. 110 /// 111 /// @param[in] rhs 112 /// A const Address object reference to copy. 113 //------------------------------------------------------------------ 114 Address (const Address& rhs) : 115 m_section (rhs.m_section), 116 m_offset (rhs.m_offset) 117 { 118 } 119 120 //------------------------------------------------------------------ 121 /// Construct with a section pointer and offset. 122 /// 123 /// Initialize the address with the supplied \a section and \a 124 /// offset. 125 /// 126 /// @param[in] section 127 /// A section pointer to a valid lldb::Section, or NULL if the 128 /// address doesn't have a section or will get resolved later. 129 /// 130 /// @param[in] offset 131 /// The offset in bytes into \a section. 132 //------------------------------------------------------------------ 133 Address (const Section* section, lldb::addr_t offset) : 134 m_section (section), 135 m_offset (offset) 136 { 137 } 138 139 //------------------------------------------------------------------ 140 /// Construct with a virtual address and section list. 141 /// 142 /// Initialize and resolve the address with the supplied virtual 143 /// address \a file_addr. 144 /// 145 /// @param[in] file_addr 146 /// A virtual file address. 147 /// 148 /// @param[in] section_list 149 /// A list of sections, one of which may contain the \a file_addr. 150 //------------------------------------------------------------------ 151 Address (lldb::addr_t file_addr, const SectionList * section_list); 152 153 //------------------------------------------------------------------ 154 /// Assignment operator. 155 /// 156 /// Copies the address value from another Address object \a rhs 157 /// into \a this object. 158 /// 159 /// @param[in] rhs 160 /// A const Address object reference to copy. 161 /// 162 /// @return 163 /// A const Address object reference to \a this. 164 //------------------------------------------------------------------ 165#ifndef SWIG 166 const Address& 167 operator= (const Address& rhs); 168#endif 169 //------------------------------------------------------------------ 170 /// Clear the object's state. 171 /// 172 /// Sets the section to an invalid value (NULL) and an invalid 173 /// offset (LLDB_INVALID_ADDRESS). 174 //------------------------------------------------------------------ 175 void 176 Clear () 177 { 178 m_section = NULL; 179 m_offset = LLDB_INVALID_ADDRESS; 180 } 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 /// @li -1 if lhs < rhs 193 /// @li 0 if lhs == rhs 194 /// @li 1 if lhs > rhs 195 //------------------------------------------------------------------ 196 static int 197 CompareFileAddress (const Address& lhs, const Address& rhs); 198 199 static int 200 CompareLoadAddress (const Address& lhs, const Address& rhs, Target *target); 201 202 static int 203 CompareModulePointerAndOffset (const Address& lhs, const Address& rhs); 204 205 // For use with std::map, std::multi_map 206 class ModulePointerAndOffsetLessThanFunctionObject 207 { 208 public: 209 ModulePointerAndOffsetLessThanFunctionObject () {} 210 211 bool 212 operator() (const Address& a, const Address& b) const 213 { 214 return Address::CompareModulePointerAndOffset(a, b) < 0; 215 } 216 }; 217 218 //------------------------------------------------------------------ 219 /// Dump a description of this object to a Stream. 220 /// 221 /// Dump a description of the contents of this object to the 222 /// supplied stream \a s. There are many ways to display a section 223 /// offset based address, and \a style lets the user choose. 224 /// 225 /// @param[in] s 226 /// The stream to which to dump the object descripton. 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 /// @return 235 /// Returns \b true if the address was able to be displayed. 236 /// File and load addresses may be unresolved and it may not be 237 /// possible to display a valid value, \b false will be returned 238 /// in such cases. 239 /// 240 /// @see Address::DumpStyle 241 //------------------------------------------------------------------ 242 bool 243 Dump (Stream *s, 244 ExecutionContextScope *exe_scope, 245 DumpStyle style, 246 DumpStyle fallback_style = DumpStyleInvalid, 247 uint32_t addr_byte_size = UINT32_MAX) const; 248 249 AddressClass 250 GetAddressClass () const; 251 252 //------------------------------------------------------------------ 253 /// Get the file address. 254 /// 255 /// If an address comes from a file on disk that has section 256 /// relative addresses, then it has a virtual address that is 257 /// relative to unique section in the object file. 258 /// 259 /// @return 260 /// The valid file virtual address, or LLDB_INVALID_ADDRESS if 261 /// the address doesn't have a file virtual address (image is 262 /// from memory only with no representation on disk). 263 //------------------------------------------------------------------ 264 lldb::addr_t 265 GetFileAddress () const; 266 267 //------------------------------------------------------------------ 268 /// Get the load address. 269 /// 270 /// If an address comes from a file on disk that has section 271 /// relative addresses, then it has a virtual address that is 272 /// relative to unique section in the object file. Sections get 273 /// resolved at runtime by DynamicLoader plug-ins as images 274 /// (executables and shared libraries) get loaded/unloaded. If a 275 /// section is loaded, then the load address can be resolved. 276 /// 277 /// @return 278 /// The valid load virtual address, or LLDB_INVALID_ADDRESS if 279 /// the address is currently not loaded. 280 //------------------------------------------------------------------ 281 lldb::addr_t 282 GetLoadAddress (Target *target) const; 283 284 //------------------------------------------------------------------ 285 /// Get the load address as a callable code load address. 286 /// 287 /// This function will first resolve its address to a load address. 288 /// Then, if the address turns out to be in code address, return the 289 /// load address that would be required to call or return to. The 290 /// address might have extra bits set (bit zero will be set to Thumb 291 /// functions for an ARM target) that are required when changing the 292 /// program counter to setting a return address. 293 /// 294 /// @return 295 /// The valid load virtual address, or LLDB_INVALID_ADDRESS if 296 /// the address is currently not loaded. 297 //------------------------------------------------------------------ 298 lldb::addr_t 299 GetCallableLoadAddress (Target *target) const; 300 301 //------------------------------------------------------------------ 302 /// Get the load address as an opcode load address. 303 /// 304 /// This function will first resolve its address to a load address. 305 /// Then, if the address turns out to be in code address, return the 306 /// load address for a an opcode. This address object might have 307 /// extra bits set (bit zero will be set to Thumb functions for an 308 /// ARM target) that are required for changing the program counter 309 /// and this function will remove any bits that are intended for 310 /// these special purposes. The result of this function can be used 311 /// to safely write a software breakpoint trap to memory. 312 /// 313 /// @return 314 /// The valid load virtual address with extra callable bits 315 /// removed, or LLDB_INVALID_ADDRESS if the address is currently 316 /// not loaded. 317 //------------------------------------------------------------------ 318 lldb::addr_t 319 GetOpcodeLoadAddress (Target *target) const; 320 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 //------------------------------------------------------------------ 328 lldb::addr_t 329 GetOffset () const { return m_offset; } 330 331 //------------------------------------------------------------------ 332 /// Check if an address is section offset. 333 /// 334 /// When converting a virtual file or load address into a section 335 /// offset based address, we often need to know if, given a section 336 /// list, if the address was able to be converted to section offset. 337 /// This function returns true if the current value contained in 338 /// this object is section offset based. 339 /// 340 /// @return 341 /// Returns \b true if the address has a valid section and 342 /// offset, \b false otherwise. 343 //------------------------------------------------------------------ 344 bool 345 IsSectionOffset() const 346 { 347 return m_section != NULL && IsValid(); 348 } 349 350 //------------------------------------------------------------------ 351 /// Check if the object state is valid. 352 /// 353 /// A valid Address object contains either a section pointer and 354 /// and offset (for section offset based addresses), or just a valid 355 /// offset (for absolute addresses that have no section). 356 /// 357 /// @return 358 /// Returns \b true if the the offset is valid, \b false 359 /// otherwise. 360 //------------------------------------------------------------------ 361 bool 362 IsValid() const 363 { 364 return m_offset != LLDB_INVALID_ADDRESS; 365 } 366 367 368 //------------------------------------------------------------------ 369 /// Get the memory cost of this object. 370 /// 371 /// @return 372 /// The number of bytes that this object occupies in memory. 373 //------------------------------------------------------------------ 374 size_t 375 MemorySize () const; 376 377 //------------------------------------------------------------------ 378 /// Resolve a file virtual address using a section list. 379 /// 380 /// Given a list of sections, attempt to resolve \a addr as a 381 /// an offset into one of the file sections. 382 /// 383 /// @return 384 /// Returns \b true if \a addr was able to be resolved, \b false 385 /// otherwise. 386 //------------------------------------------------------------------ 387 bool 388 ResolveAddressUsingFileSections (lldb::addr_t addr, const SectionList *sections); 389 390 bool 391 IsLinkedAddress () const; 392 393 void 394 ResolveLinkedAddress (); 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 Module * 438 GetModulePtr () const; 439 440 lldb::ModuleSP 441 GetModuleSP () const; 442 443 //------------------------------------------------------------------ 444 /// Get const accessor for the section. 445 /// 446 /// @return 447 /// Returns the const lldb::Section pointer that this address is an 448 /// offset in, or NULL if this address is absolute. 449 //------------------------------------------------------------------ 450 const Section* 451 GetSection() const { return m_section; } 452 453 //------------------------------------------------------------------ 454 /// Set accessor for the offset. 455 /// 456 /// @param[in] offset 457 /// A new offset value for this object. 458 /// 459 /// @return 460 /// Returns \b true if the offset changed, \b false otherwise. 461 //------------------------------------------------------------------ 462 bool 463 SetOffset (lldb::addr_t offset) 464 { 465 bool changed = m_offset != offset; 466 m_offset = offset; 467 return changed; 468 } 469 470 bool 471 Slide (int64_t offset) 472 { 473 if (m_offset != LLDB_INVALID_ADDRESS) 474 { 475 m_offset += offset; 476 return true; 477 } 478 return false; 479 } 480 481 //------------------------------------------------------------------ 482 /// Set accessor for the section. 483 /// 484 /// @param[in] section 485 /// A new lldb::Section pointer to use as the section base. Can 486 /// be NULL for absolute addresses that are not relative to 487 /// any section. 488 //------------------------------------------------------------------ 489 void 490 SetSection (const Section* section) { m_section = section; } 491 492 //------------------------------------------------------------------ 493 /// Reconstruct a symbol context from an address. 494 /// 495 /// This class doesn't inherit from SymbolContextScope because many 496 /// address objects have short lifespans. Address objects that are 497 /// section offset can reconstruct their symbol context by looking 498 /// up the address in the module found in the section. 499 /// 500 /// @see SymbolContextScope::CalculateSymbolContext(SymbolContext*) 501 //------------------------------------------------------------------ 502 uint32_t 503 CalculateSymbolContext (SymbolContext *sc, 504 uint32_t resolve_scope = lldb::eSymbolContextEverything) const; 505 506 Module * 507 CalculateSymbolContextModule () const; 508 509 CompileUnit * 510 CalculateSymbolContextCompileUnit () const; 511 512 Function * 513 CalculateSymbolContextFunction () const; 514 515 Block * 516 CalculateSymbolContextBlock () const; 517 518 Symbol * 519 CalculateSymbolContextSymbol () const; 520 521 bool 522 CalculateSymbolContextLineEntry (LineEntry &line_entry) const; 523 524protected: 525 //------------------------------------------------------------------ 526 // Member variables. 527 //------------------------------------------------------------------ 528 const Section* m_section; ///< The section for the address, can be NULL. 529 lldb::addr_t m_offset; ///< Offset into section if \a m_section != NULL, else the absolute address value. 530}; 531 532 533//---------------------------------------------------------------------- 534// NOTE: Be careful using this operator. It can correctly compare two 535// addresses from the same Module correctly. It can't compare two 536// addresses from different modules in any meaningful way, but it will 537// compare the module pointers. 538// 539// To sum things up: 540// - works great for addresses within the same module 541// - it works for addresses across multiple modules, but don't expect the 542// address results to make much sense 543// 544// This basically lets Address objects be used in ordered collection 545// classes. 546//---------------------------------------------------------------------- 547bool operator< (const Address& lhs, const Address& rhs); 548bool operator> (const Address& lhs, const Address& rhs); 549 550 551 552bool operator== (const Address& lhs, const Address& rhs); 553bool operator!= (const Address& lhs, const Address& rhs); 554 555} // namespace lldb_private 556 557#endif // liblldb_Address_h_ 558