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
27namespace 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.
42class ObjectFile : public std::enable_shared_from_this<ObjectFile>,
43 public PluginInterface,
44 public ModuleChild {
45 friend class lldb_private::Module;
46
47public:
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;
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.
265 virtual lldb::addr_t GetFileOffset() const { return m_file_offset; }
266
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
479 virtual lldb_private::Address GetBaseAddress() {
480 return Address(m_memory_addr);
481 }
482
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.
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.
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.
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 ///
561 virtual bool GetCorefileThreadExtraInfos(std::vector<lldb::tid_t> &tids) {
562 return false;
563 }
564
565 virtual lldb::RegisterContextSP
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.
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.
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.
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.
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.
640 virtual bool GetIsDynamicLinkEditor() { return false; }
641
642 // Member Functions
643 Type GetType() {
644 if (m_type == eTypeInvalid)
645 m_type = CalculateType();
646 return m_type;
647 }
648
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 &section_data);
681
682 // Returns the section data size. This is special-cased for PECOFF
683 // due to file alignment.
684 virtual size_t GetSectionDataSize(Section *section) {
685 return section->GetFileSize();
686 }
687
688 /// Returns true if the object file exists only in memory.
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
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.
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
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
745protected:
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
785private:
786 ObjectFile(const ObjectFile &) = delete;
787 const ObjectFile &operator=(const ObjectFile &) = delete;
788};
789
790} // namespace lldb_private
791
792namespace llvm {
793template <> 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
798template <> 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
803namespace json {
804bool 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

source code of lldb/include/lldb/Symbol/ObjectFile.h