1 //===-- ObjectFile.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_SYMBOL_OBJECTFILE_H 10 #define LLDB_SYMBOL_OBJECTFILE_H 11 12 #include "lldb/Core/ModuleChild.h" 13 #include "lldb/Core/PluginInterface.h" 14 #include "lldb/Symbol/Symtab.h" 15 #include "lldb/Symbol/UnwindTable.h" 16 #include "lldb/Utility/AddressableBits.h" 17 #include "lldb/Utility/DataExtractor.h" 18 #include "lldb/Utility/Endian.h" 19 #include "lldb/Utility/FileSpec.h" 20 #include "lldb/Utility/FileSpecList.h" 21 #include "lldb/Utility/UUID.h" 22 #include "lldb/lldb-private.h" 23 #include "llvm/Support/Threading.h" 24 #include "llvm/Support/VersionTuple.h" 25 #include <optional> 26 27 namespace lldb_private { 28 29 /// \class ObjectFile ObjectFile.h "lldb/Symbol/ObjectFile.h" 30 /// A plug-in interface definition class for object file parsers. 31 /// 32 /// Object files belong to Module objects and know how to extract information 33 /// from executable, shared library, and object (.o) files used by operating 34 /// system runtime. The symbol table and section list for an object file. 35 /// 36 /// Object files can be represented by the entire file, or by part of a file. 37 /// An example of a partial file ObjectFile is one that contains information 38 /// for one of multiple architectures in the same file. 39 /// 40 /// Once an architecture is selected the object file information can be 41 /// extracted from this abstract class. 42 class ObjectFile : public std::enable_shared_from_this<ObjectFile>, 43 public PluginInterface, 44 public ModuleChild { 45 friend class lldb_private::Module; 46 47 public: 48 enum Type { 49 eTypeInvalid = 0, 50 /// A core file that has a checkpoint of a program's execution state. 51 eTypeCoreFile, 52 /// A normal executable. 53 eTypeExecutable, 54 /// An object file that contains only debug information. 55 eTypeDebugInfo, 56 /// The platform's dynamic linker executable. 57 eTypeDynamicLinker, 58 /// An intermediate object file. 59 eTypeObjectFile, 60 /// A shared library that can be used during execution. 61 eTypeSharedLibrary, 62 /// A library that can be linked against but not used for execution. 63 eTypeStubLibrary, 64 /// JIT code that has symbols, sections and possibly debug info. 65 eTypeJIT, 66 eTypeUnknown 67 }; 68 69 enum Strata { 70 eStrataInvalid = 0, 71 eStrataUnknown, 72 eStrataUser, 73 eStrataKernel, 74 eStrataRawImage, 75 eStrataJIT 76 }; 77 78 /// If we have a corefile binary hint, this enum 79 /// specifies the binary type which we can use to 80 /// select the correct DynamicLoader plugin. 81 enum BinaryType { 82 eBinaryTypeInvalid = 0, 83 eBinaryTypeUnknown, 84 eBinaryTypeKernel, /// kernel binary 85 eBinaryTypeUser, /// user process binary 86 eBinaryTypeStandalone /// standalone binary / firmware 87 }; 88 89 struct LoadableData { 90 lldb::addr_t Dest; 91 llvm::ArrayRef<uint8_t> Contents; 92 }; 93 94 /// Construct with a parent module, offset, and header data. 95 /// 96 /// Object files belong to modules and a valid module must be supplied upon 97 /// construction. The at an offset within a file for objects that contain 98 /// more than one architecture or object. 99 ObjectFile(const lldb::ModuleSP &module_sp, const FileSpec *file_spec_ptr, 100 lldb::offset_t file_offset, lldb::offset_t length, 101 lldb::DataBufferSP data_sp, lldb::offset_t data_offset); 102 103 ObjectFile(const lldb::ModuleSP &module_sp, const lldb::ProcessSP &process_sp, 104 lldb::addr_t header_addr, lldb::DataBufferSP data_sp); 105 106 /// Destructor. 107 /// 108 /// The destructor is virtual since this class is designed to be inherited 109 /// from by the plug-in instance. 110 ~ObjectFile() override; 111 112 /// Dump a description of this object to a Stream. 113 /// 114 /// Dump a description of the current contents of this object to the 115 /// supplied stream \a s. The dumping should include the section list if it 116 /// has been parsed, and the symbol table if it has been parsed. 117 /// 118 /// \param[in] s 119 /// The stream to which to dump the object description. 120 virtual void Dump(Stream *s) = 0; 121 122 /// Find a ObjectFile plug-in that can parse \a file_spec. 123 /// 124 /// Scans all loaded plug-in interfaces that implement versions of the 125 /// ObjectFile plug-in interface and returns the first instance that can 126 /// parse the file. 127 /// 128 /// \param[in] module_sp 129 /// The parent module that owns this object file. 130 /// 131 /// \param[in] file_spec 132 /// A file specification that indicates which file to use as the 133 /// object file. 134 /// 135 /// \param[in] file_offset 136 /// The offset into the file at which to start parsing the 137 /// object. This is for files that contain multiple 138 /// architectures or objects. 139 /// 140 /// \param[in] file_size 141 /// The size of the current object file if it can be determined 142 /// or if it is known. This can be zero. 143 /// 144 /// \see ObjectFile::ParseHeader() 145 static lldb::ObjectFileSP 146 FindPlugin(const lldb::ModuleSP &module_sp, const FileSpec *file_spec, 147 lldb::offset_t file_offset, lldb::offset_t file_size, 148 lldb::DataBufferSP &data_sp, lldb::offset_t &data_offset); 149 150 /// Find a ObjectFile plug-in that can parse a file in memory. 151 /// 152 /// Scans all loaded plug-in interfaces that implement versions of the 153 /// ObjectFile plug-in interface and returns the first instance that can 154 /// parse the file. 155 /// 156 /// \param[in] module_sp 157 /// The parent module that owns this object file. 158 /// 159 /// \param[in] process_sp 160 /// A shared pointer to the process whose memory space contains 161 /// an object file. This will be stored as a std::weak_ptr. 162 /// 163 /// \param[in] header_addr 164 /// The address of the header for the object file in memory. 165 static lldb::ObjectFileSP FindPlugin(const lldb::ModuleSP &module_sp, 166 const lldb::ProcessSP &process_sp, 167 lldb::addr_t header_addr, 168 lldb::WritableDataBufferSP file_data_sp); 169 170 static size_t 171 GetModuleSpecifications(const FileSpec &file, lldb::offset_t file_offset, 172 lldb::offset_t file_size, ModuleSpecList &specs, 173 lldb::DataBufferSP data_sp = lldb::DataBufferSP()); 174 175 static size_t GetModuleSpecifications(const lldb_private::FileSpec &file, 176 lldb::DataBufferSP &data_sp, 177 lldb::offset_t data_offset, 178 lldb::offset_t file_offset, 179 lldb::offset_t file_size, 180 lldb_private::ModuleSpecList &specs); 181 /// Split a path into a file path with object name. 182 /// 183 /// For paths like "/tmp/foo.a(bar.o)" we often need to split a path up into 184 /// the actual path name and into the object name so we can make a valid 185 /// object file from it. 186 /// 187 /// \param[in] path_with_object 188 /// A path that might contain an archive path with a .o file 189 /// specified in parens in the basename of the path. 190 /// 191 /// \param[out] archive_file 192 /// If \b true is returned, \a file_spec will be filled in with 193 /// the path to the archive. 194 /// 195 /// \param[out] archive_object 196 /// If \b true is returned, \a object will be filled in with 197 /// the name of the object inside the archive. 198 /// 199 /// \return 200 /// \b true if the path matches the pattern of archive + object 201 /// and \a archive_file and \a archive_object are modified, 202 /// \b false otherwise and \a archive_file and \a archive_object 203 /// are guaranteed to be remain unchanged. 204 static bool SplitArchivePathWithObject( 205 llvm::StringRef path_with_object, lldb_private::FileSpec &archive_file, 206 lldb_private::ConstString &archive_object, bool must_exist); 207 208 // LLVM RTTI support 209 static char ID; isA(const void * ClassID)210 virtual bool isA(const void *ClassID) const { return ClassID == &ID; } 211 212 /// Gets the address size in bytes for the current object file. 213 /// 214 /// \return 215 /// The size of an address in bytes for the currently selected 216 /// architecture (and object for archives). Returns zero if no 217 /// architecture or object has been selected. 218 virtual uint32_t GetAddressByteSize() const = 0; 219 220 /// Get the address type given a file address in an object file. 221 /// 222 /// Many binary file formats know what kinds This is primarily for ARM 223 /// binaries, though it can be applied to any executable file format that 224 /// supports different opcode types within the same binary. ARM binaries 225 /// support having both ARM and Thumb within the same executable container. 226 /// We need to be able to get \return 227 /// The size of an address in bytes for the currently selected 228 /// architecture (and object for archives). Returns zero if no 229 /// architecture or object has been selected. 230 virtual AddressClass GetAddressClass(lldb::addr_t file_addr); 231 232 /// Extract the dependent modules from an object file. 233 /// 234 /// If an object file has information about which other images it depends on 235 /// (such as shared libraries), this function will provide the list. Since 236 /// many executables or shared libraries may depend on the same files, 237 /// FileSpecList::AppendIfUnique(const FileSpec &) should be used to make 238 /// sure any files that are added are not already in the list. 239 /// 240 /// \param[out] file_list 241 /// A list of file specification objects that gets dependent 242 /// files appended to. 243 /// 244 /// \return 245 /// The number of new files that were appended to \a file_list. 246 /// 247 /// \see FileSpecList::AppendIfUnique(const FileSpec &) 248 virtual uint32_t GetDependentModules(FileSpecList &file_list) = 0; 249 250 /// Tells whether this object file is capable of being the main executable 251 /// for a process. 252 /// 253 /// \return 254 /// \b true if it is, \b false otherwise. 255 virtual bool IsExecutable() const = 0; 256 257 /// Returns the offset into a file at which this object resides. 258 /// 259 /// Some files contain many object files, and this function allows access to 260 /// an object's offset within the file. 261 /// 262 /// \return 263 /// The offset in bytes into the file. Defaults to zero for 264 /// simple object files that a represented by an entire file. GetFileOffset()265 virtual lldb::addr_t GetFileOffset() const { return m_file_offset; } 266 GetByteSize()267 virtual lldb::addr_t GetByteSize() const { return m_length; } 268 269 /// Get accessor to the object file specification. 270 /// 271 /// \return 272 /// The file specification object pointer if there is one, or 273 /// NULL if this object is only from memory. GetFileSpec()274 virtual FileSpec &GetFileSpec() { return m_file; } 275 276 /// Get const accessor to the object file specification. 277 /// 278 /// \return 279 /// The const file specification object pointer if there is one, 280 /// or NULL if this object is only from memory. GetFileSpec()281 virtual const FileSpec &GetFileSpec() const { return m_file; } 282 283 /// Get the ArchSpec for this object file. 284 /// 285 /// \return 286 /// The ArchSpec of this object file. In case of error, an invalid 287 /// ArchSpec object is returned. 288 virtual ArchSpec GetArchitecture() = 0; 289 290 /// Gets the section list for the currently selected architecture (and 291 /// object for archives). 292 /// 293 /// Section list parsing can be deferred by ObjectFile instances until this 294 /// accessor is called the first time. 295 /// 296 /// \return 297 /// The list of sections contained in this object file. 298 virtual SectionList *GetSectionList(bool update_module_section_list = true); 299 300 virtual void CreateSections(SectionList &unified_section_list) = 0; 301 302 /// Notify the ObjectFile that the file addresses in the Sections for this 303 /// module have been changed. SectionFileAddressesChanged()304 virtual void SectionFileAddressesChanged() {} 305 306 /// Gets the symbol table for the currently selected architecture (and 307 /// object for archives). 308 /// 309 /// This function will manage when ParseSymtab(...) is called to actually do 310 /// the symbol table parsing in each plug-in. This function will take care of 311 /// taking all the necessary locks and finalizing the symbol table when the 312 /// symbol table does get parsed. 313 /// 314 /// \return 315 /// The symbol table for this object file. 316 Symtab *GetSymtab(); 317 318 /// Parse the symbol table into the provides symbol table object. 319 /// 320 /// Symbol table parsing will be done once when this function is called by 321 /// each object file plugin. All of the necessary locks will already be 322 /// acquired before this function is called and the symbol table object to 323 /// populate is supplied as an argument and doesn't need to be created by 324 /// each plug-in. 325 /// 326 /// \param 327 /// The symbol table to populate. 328 virtual void ParseSymtab(Symtab &symtab) = 0; 329 330 /// Perform relocations on the section if necessary. 331 /// 332 virtual void RelocateSection(lldb_private::Section *section); 333 334 /// Appends a Symbol for the specified so_addr to the symbol table. 335 /// 336 /// If verify_unique is false, the symbol table is not searched to determine 337 /// if a Symbol found at this address has already been added to the symbol 338 /// table. When verify_unique is true, this method resolves the Symbol as 339 /// the first match in the SymbolTable and appends a Symbol only if 340 /// required/found. 341 /// 342 /// \return 343 /// The resolved symbol or nullptr. Returns nullptr if a 344 /// a Symbol could not be found for the specified so_addr. ResolveSymbolForAddress(const Address & so_addr,bool verify_unique)345 virtual Symbol *ResolveSymbolForAddress(const Address &so_addr, 346 bool verify_unique) { 347 // Typically overridden to lazily add stripped symbols recoverable from the 348 // exception handling unwind information (i.e. without parsing the entire 349 // eh_frame section. 350 // 351 // The availability of LC_FUNCTION_STARTS allows ObjectFileMachO to 352 // efficiently add stripped symbols when the symbol table is first 353 // constructed. Poorer cousins are PECoff and ELF. 354 return nullptr; 355 } 356 357 /// Detect if this object file has been stripped of local symbols. 358 /// Detect if this object file has been stripped of local symbols. 359 /// 360 /// \return 361 /// Return \b true if the object file has been stripped of local 362 /// symbols. 363 virtual bool IsStripped() = 0; 364 365 /// Frees the symbol table. 366 /// 367 /// This function should only be used when an object file is 368 virtual void ClearSymtab(); 369 370 /// Gets the UUID for this object file. 371 /// 372 /// If the object file format contains a UUID, the value should be returned. 373 /// Else ObjectFile instances should return the MD5 checksum of all of the 374 /// bytes for the object file (or memory for memory based object files). 375 /// 376 /// \return 377 /// The object file's UUID. In case of an error, an empty UUID is 378 /// returned. 379 virtual UUID GetUUID() = 0; 380 381 /// Gets the file spec list of libraries re-exported by this object file. 382 /// 383 /// If the object file format has the notion of one library re-exporting the 384 /// symbols from another, the re-exported libraries will be returned in the 385 /// FileSpecList. 386 /// 387 /// \return 388 /// Returns filespeclist. GetReExportedLibraries()389 virtual lldb_private::FileSpecList GetReExportedLibraries() { 390 return FileSpecList(); 391 } 392 393 /// Sets the load address for an entire module, assuming a rigid slide of 394 /// sections, if possible in the implementation. 395 /// 396 /// \return 397 /// Returns true iff any section's load address changed. SetLoadAddress(Target & target,lldb::addr_t value,bool value_is_offset)398 virtual bool SetLoadAddress(Target &target, lldb::addr_t value, 399 bool value_is_offset) { 400 return false; 401 } 402 403 /// Gets whether endian swapping should occur when extracting data from this 404 /// object file. 405 /// 406 /// \return 407 /// Returns \b true if endian swapping is needed, \b false 408 /// otherwise. 409 virtual lldb::ByteOrder GetByteOrder() const = 0; 410 411 /// Attempts to parse the object header. 412 /// 413 /// This function is used as a test to see if a given plug-in instance can 414 /// parse the header data already contained in ObjectFile::m_data. If an 415 /// object file parser does not recognize that magic bytes in a header, 416 /// false should be returned and the next plug-in can attempt to parse an 417 /// object file. 418 /// 419 /// \return 420 /// Returns \b true if the header was parsed successfully, \b 421 /// false otherwise. 422 virtual bool ParseHeader() = 0; 423 424 /// Returns if the function bounds for symbols in this symbol file are 425 /// likely accurate. 426 /// 427 /// The unwinder can emulate the instructions of functions to understand 428 /// prologue/epilogue code sequences, where registers are spilled on the 429 /// stack, etc. This feature relies on having the correct start addresses 430 /// of all functions. If the ObjectFile has a way to tell that symbols have 431 /// been stripped and there's no way to reconstruct start addresses (e.g. 432 /// LC_FUNCTION_STARTS on Mach-O, or eh_frame unwind info), the ObjectFile 433 /// should indicate that assembly emulation should not be used for this 434 /// module. 435 /// 436 /// It is uncommon for this to return false. An ObjectFile needs to be sure 437 /// that symbol start addresses are unavailable before false is returned. 438 /// If it is unclear, this should return true. 439 /// 440 /// \return 441 /// Returns true if assembly emulation should be used for this 442 /// module. 443 /// Only returns false if the ObjectFile is sure that symbol 444 /// addresses are insufficient for accurate assembly emulation. AllowAssemblyEmulationUnwindPlans()445 virtual bool AllowAssemblyEmulationUnwindPlans() { return true; } 446 447 /// Similar to Process::GetImageInfoAddress(). 448 /// 449 /// Some platforms embed auxiliary structures useful to debuggers in the 450 /// address space of the inferior process. This method returns the address 451 /// of such a structure if the information can be resolved via entries in 452 /// the object file. ELF, for example, provides a means to hook into the 453 /// runtime linker so that a debugger may monitor the loading and unloading 454 /// of shared libraries. 455 /// 456 /// \return 457 /// The address of any auxiliary tables, or an invalid address if this 458 /// object file format does not support or contain such information. GetImageInfoAddress(Target * target)459 virtual lldb_private::Address GetImageInfoAddress(Target *target) { 460 return Address(); 461 } 462 463 /// Returns the address of the Entry Point in this object file - if the 464 /// object file doesn't have an entry point (because it is not an executable 465 /// file) then an invalid address is returned. 466 /// 467 /// \return 468 /// Returns the entry address for this module. GetEntryPointAddress()469 virtual lldb_private::Address GetEntryPointAddress() { return Address(); } 470 471 /// Returns base address of this object file. 472 /// 473 /// This also sometimes referred to as the "preferred load address" or the 474 /// "image base address". Addresses within object files are often expressed 475 /// relative to this base. If this address corresponds to a specific section 476 /// (usually the first byte of the first section) then the returned address 477 /// will have this section set. Otherwise, the address will just have the 478 /// offset member filled in, indicating that this represents a file address. GetBaseAddress()479 virtual lldb_private::Address GetBaseAddress() { 480 return Address(m_memory_addr); 481 } 482 GetNumThreadContexts()483 virtual uint32_t GetNumThreadContexts() { return 0; } 484 485 /// Some object files may have an identifier string embedded in them, e.g. 486 /// in a Mach-O core file using the LC_IDENT load command (which is 487 /// obsolete, but can still be found in some old files) 488 /// 489 /// \return 490 /// Returns the identifier string if one exists, else an empty 491 /// string. GetIdentifierString()492 virtual std::string GetIdentifierString () { 493 return std::string(); 494 } 495 496 /// Some object files may have the number of bits used for addressing 497 /// embedded in them, e.g. a Mach-O core file using an LC_NOTE. These 498 /// object files can return an AddressableBits object that can can be 499 /// used to set the address masks in the Process. 500 /// 501 /// \return 502 /// Returns an AddressableBits object which can be used to set 503 /// the address masks in the Process. GetAddressableBits()504 virtual lldb_private::AddressableBits GetAddressableBits() { return {}; } 505 506 /// When the ObjectFile is a core file, lldb needs to locate the "binary" in 507 /// the core file. lldb can iterate over the pages looking for a valid 508 /// binary, but some core files may have metadata describing where the main 509 /// binary is exactly which removes ambiguity when there are multiple 510 /// binaries present in the captured memory pages. 511 /// 512 /// \param[out] value 513 /// The address or offset (slide) where the binary is loaded in memory. 514 /// LLDB_INVALID_ADDRESS for unspecified. If an offset is given, 515 /// this offset should be added to the binary's file address to get 516 /// the load address. 517 /// 518 /// \param[out] value_is_offset 519 /// Specifies if \b value is a load address, or an offset to calculate 520 /// the load address. 521 /// 522 /// \param[out] uuid 523 /// If the uuid of the binary is specified, this will be set. 524 /// If no UUID is available, will be cleared. 525 /// 526 /// \param[out] type 527 /// Return the type of the binary, which will dictate which 528 /// DynamicLoader plugin should be used. 529 /// 530 /// \return 531 /// Returns true if either address or uuid has been set. GetCorefileMainBinaryInfo(lldb::addr_t & value,bool & value_is_offset,UUID & uuid,ObjectFile::BinaryType & type)532 virtual bool GetCorefileMainBinaryInfo(lldb::addr_t &value, 533 bool &value_is_offset, UUID &uuid, 534 ObjectFile::BinaryType &type) { 535 value = LLDB_INVALID_ADDRESS; 536 value_is_offset = false; 537 uuid.Clear(); 538 return false; 539 } 540 541 /// Get metadata about threads from the corefile. 542 /// 543 /// The corefile may have metadata (e.g. a Mach-O "thread extrainfo" 544 /// LC_NOTE) which for the threads in the process; this method tries 545 /// to retrieve them. 546 /// 547 /// \param[out] tids 548 /// Filled in with a vector of tid_t's that matches the number 549 /// of threads in the corefile (ObjectFile::GetNumThreadContexts). 550 /// If a tid is not specified for one of the corefile threads, 551 /// that entry in the vector will have LLDB_INVALID_THREAD_ID and 552 /// the caller should assign a tid to the thread that does not 553 /// conflict with the ones provided in this array. 554 /// As additional metadata are added, this method may return a 555 /// \a tids vector with no thread id's specified at all; the 556 /// corefile may only specify one of the other metadata. 557 /// 558 /// \return 559 /// Returns true if thread metadata was found in this corefile. 560 /// GetCorefileThreadExtraInfos(std::vector<lldb::tid_t> & tids)561 virtual bool GetCorefileThreadExtraInfos(std::vector<lldb::tid_t> &tids) { 562 return false; 563 } 564 565 virtual lldb::RegisterContextSP GetThreadContextAtIndex(uint32_t idx,lldb_private::Thread & thread)566 GetThreadContextAtIndex(uint32_t idx, lldb_private::Thread &thread) { 567 return lldb::RegisterContextSP(); 568 } 569 570 /// The object file should be able to calculate its type by looking at its 571 /// file header and possibly the sections or other data in the object file. 572 /// The file type is used in the debugger to help select the correct plug- 573 /// ins for the job at hand, so this is important to get right. If any 574 /// eTypeXXX definitions do not match up with the type of file you are 575 /// loading, please feel free to add a new enumeration value. 576 /// 577 /// \return 578 /// The calculated file type for the current object file. 579 virtual Type CalculateType() = 0; 580 581 /// In cases where the type can't be calculated (elf files), this routine 582 /// allows someone to explicitly set it. As an example, SymbolVendorELF uses 583 /// this routine to set eTypeDebugInfo when loading debug link files. SetType(Type type)584 virtual void SetType(Type type) { m_type = type; } 585 586 /// The object file should be able to calculate the strata of the object 587 /// file. 588 /// 589 /// Many object files for platforms might be for either user space debugging 590 /// or for kernel debugging. If your object file subclass can figure this 591 /// out, it will help with debugger plug-in selection when it comes time to 592 /// debug. 593 /// 594 /// \return 595 /// The calculated object file strata for the current object 596 /// file. 597 virtual Strata CalculateStrata() = 0; 598 599 /// Get the object file version numbers. 600 /// 601 /// Many object files have a set of version numbers that describe the 602 /// version of the executable or shared library. Typically there are major, 603 /// minor and build, but there may be more. This function will extract the 604 /// versions from object files if they are available. 605 /// 606 /// \return 607 /// This function returns extracted version numbers as a 608 /// llvm::VersionTuple. In case of error an empty VersionTuple is 609 /// returned. GetVersion()610 virtual llvm::VersionTuple GetVersion() { return llvm::VersionTuple(); } 611 612 /// Get the minimum OS version this object file can run on. 613 /// 614 /// Some object files have information that specifies the minimum OS version 615 /// that they can be used on. 616 /// 617 /// \return 618 /// This function returns extracted version numbers as a 619 /// llvm::VersionTuple. In case of error an empty VersionTuple is 620 /// returned. GetMinimumOSVersion()621 virtual llvm::VersionTuple GetMinimumOSVersion() { 622 return llvm::VersionTuple(); 623 } 624 625 /// Get the SDK OS version this object file was built with. 626 /// 627 /// \return 628 /// This function returns extracted version numbers as a 629 /// llvm::VersionTuple. In case of error an empty VersionTuple is 630 /// returned. GetSDKVersion()631 virtual llvm::VersionTuple GetSDKVersion() { return llvm::VersionTuple(); } 632 633 /// Return true if this file is a dynamic link editor (dyld) 634 /// 635 /// Often times dyld has symbols that mirror symbols in libc and other 636 /// shared libraries (like "malloc" and "free") and the user does _not_ want 637 /// to stop in these shared libraries by default. We can ask the ObjectFile 638 /// if it is such a file and should be avoided for things like settings 639 /// breakpoints and doing function lookups for expressions. GetIsDynamicLinkEditor()640 virtual bool GetIsDynamicLinkEditor() { return false; } 641 642 // Member Functions GetType()643 Type GetType() { 644 if (m_type == eTypeInvalid) 645 m_type = CalculateType(); 646 return m_type; 647 } 648 GetStrata()649 Strata GetStrata() { 650 if (m_strata == eStrataInvalid) 651 m_strata = CalculateStrata(); 652 return m_strata; 653 } 654 655 // When an object file is in memory, subclasses should try and lock the 656 // process weak pointer. If the process weak pointer produces a valid 657 // ProcessSP, then subclasses can call this function to read memory. 658 static lldb::DataBufferSP ReadMemory(const lldb::ProcessSP &process_sp, 659 lldb::addr_t addr, size_t byte_size); 660 661 // This function returns raw file contents. Do not use it if you want 662 // transparent decompression of section contents. 663 size_t GetData(lldb::offset_t offset, size_t length, 664 DataExtractor &data) const; 665 666 // This function returns raw file contents. Do not use it if you want 667 // transparent decompression of section contents. 668 size_t CopyData(lldb::offset_t offset, size_t length, void *dst) const; 669 670 // This function will transparently decompress section data if the section if 671 // compressed. 672 virtual size_t ReadSectionData(Section *section, 673 lldb::offset_t section_offset, void *dst, 674 size_t dst_len); 675 676 // This function will transparently decompress section data if the section if 677 // compressed. Note that for compressed section the resulting data size may 678 // be larger than what Section::GetFileSize reports. 679 virtual size_t ReadSectionData(Section *section, 680 DataExtractor §ion_data); 681 682 // Returns the section data size. This is special-cased for PECOFF 683 // due to file alignment. GetSectionDataSize(Section * section)684 virtual size_t GetSectionDataSize(Section *section) { 685 return section->GetFileSize(); 686 } 687 688 /// Returns true if the object file exists only in memory. IsInMemory()689 bool IsInMemory() const { return m_memory_addr != LLDB_INVALID_ADDRESS; } 690 691 // Strip linker annotations (such as @@VERSION) from symbol names. 692 virtual llvm::StringRef StripLinkerSymbolAnnotations(llvm::StringRef symbol_name)693 StripLinkerSymbolAnnotations(llvm::StringRef symbol_name) const { 694 return symbol_name; 695 } 696 697 /// Can we trust the address ranges accelerator associated with this object 698 /// file to be complete. CanTrustAddressRanges()699 virtual bool CanTrustAddressRanges() { return false; } 700 701 static lldb::SymbolType GetSymbolTypeFromName( 702 llvm::StringRef name, 703 lldb::SymbolType symbol_type_hint = lldb::eSymbolTypeUndefined); 704 705 /// Loads this objfile to memory. 706 /// 707 /// Loads the bits needed to create an executable image to the memory. It is 708 /// useful with bare-metal targets where target does not have the ability to 709 /// start a process itself. 710 /// 711 /// \param[in] target 712 /// Target where to load. 713 virtual std::vector<LoadableData> GetLoadableData(Target &target); 714 715 /// Creates a plugin-specific call frame info 716 virtual std::unique_ptr<CallFrameInfo> CreateCallFrameInfo(); 717 718 /// Load binaries listed in a corefile 719 /// 720 /// A corefile may have metadata listing binaries that can be loaded, 721 /// and the offsets at which they were loaded. This method will try 722 /// to add them to the Target. If any binaries were loaded, 723 /// 724 /// \param[in] process 725 /// Process where to load binaries. 726 /// 727 /// \return 728 /// Returns true if any binaries were loaded. 729 LoadCoreFileImages(lldb_private::Process & process)730 virtual bool LoadCoreFileImages(lldb_private::Process &process) { 731 return false; 732 } 733 734 /// Get a hash that can be used for caching object file releated information. 735 /// 736 /// Data for object files can be cached between runs of debug sessions and 737 /// a module can end up using a main file and a symbol file, both of which 738 /// can be object files. So we need a unique hash that identifies an object 739 /// file when storing cached data. 740 uint32_t GetCacheHash(); 741 742 static lldb::DataBufferSP MapFileData(const FileSpec &file, uint64_t Size, 743 uint64_t Offset); 744 745 protected: 746 // Member variables. 747 FileSpec m_file; 748 Type m_type; 749 Strata m_strata; 750 lldb::addr_t m_file_offset; ///< The offset in bytes into the file, or the 751 ///address in memory 752 lldb::addr_t m_length; ///< The length of this object file if it is known (can 753 ///be zero if length is unknown or can't be 754 ///determined). 755 DataExtractor 756 m_data; ///< The data for this object file so things can be parsed lazily. 757 lldb::ProcessWP m_process_wp; 758 /// Set if the object file only exists in memory. 759 const lldb::addr_t m_memory_addr; 760 std::unique_ptr<lldb_private::SectionList> m_sections_up; 761 std::unique_ptr<lldb_private::Symtab> m_symtab_up; 762 /// We need a llvm::once_flag that we can use to avoid locking the module 763 /// lock and deadlocking LLDB. See comments in ObjectFile::GetSymtab() for 764 /// the full details. We also need to be able to clear the symbol table, so we 765 /// need to use a std::unique_ptr to a llvm::once_flag so if we clear the 766 /// symbol table, we can have a new once flag to use when it is created again. 767 std::unique_ptr<llvm::once_flag> m_symtab_once_up; 768 std::optional<uint32_t> m_cache_hash; 769 770 /// Sets the architecture for a module. At present the architecture can 771 /// only be set if it is invalid. It is not allowed to switch from one 772 /// concrete architecture to another. 773 /// 774 /// \param[in] new_arch 775 /// The architecture this module will be set to. 776 /// 777 /// \return 778 /// Returns \b true if the architecture was changed, \b 779 /// false otherwise. 780 bool SetModulesArchitecture(const ArchSpec &new_arch); 781 782 /// The number of bytes to read when going through the plugins. 783 static size_t g_initial_bytes_to_read; 784 785 private: 786 ObjectFile(const ObjectFile &) = delete; 787 const ObjectFile &operator=(const ObjectFile &) = delete; 788 }; 789 790 } // namespace lldb_private 791 792 namespace llvm { 793 template <> struct format_provider<lldb_private::ObjectFile::Type> { 794 static void format(const lldb_private::ObjectFile::Type &type, 795 raw_ostream &OS, StringRef Style); 796 }; 797 798 template <> struct format_provider<lldb_private::ObjectFile::Strata> { 799 static void format(const lldb_private::ObjectFile::Strata &strata, 800 raw_ostream &OS, StringRef Style); 801 }; 802 803 namespace json { 804 bool fromJSON(const llvm::json::Value &value, lldb_private::ObjectFile::Type &, 805 llvm::json::Path path); 806 } // namespace json 807 } // namespace llvm 808 809 #endif // LLDB_SYMBOL_OBJECTFILE_H 810