LLDB mainline
ObjectFile.h
Go to the documentation of this file.
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
14#include "lldb/Symbol/Symtab.h"
18#include "lldb/Utility/Endian.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 {
46
47public:
48 enum Type {
50 /// A core file that has a checkpoint of a program's execution state.
52 /// A normal executable.
54 /// An object file that contains only debug information.
56 /// The platform's dynamic linker executable.
58 /// An intermediate object file.
60 /// A shared library that can be used during execution.
62 /// A library that can be linked against but not used for execution.
64 /// JIT code that has symbols, sections and possibly debug info.
67 };
68
69 enum Strata {
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.
84 eBinaryTypeKernel, /// kernel binary
85 eBinaryTypeUser, /// user process binary
86 eBinaryTypeStandalone /// standalone binary / firmware
87 };
88
89 struct LoadableData {
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,
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,
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.
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.
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.
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.
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.
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.
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.
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.
533 bool &value_is_offset, UUID &uuid,
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
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
644 if (m_type == eTypeInvalid)
646 return m_type;
647 }
648
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.
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
702 llvm::StringRef name,
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
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.
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).
756 m_data; ///< The data for this object file so things can be parsed lazily.
758 /// Set if the object file only exists in memory.
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.
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
A section + offset based address class.
Definition: Address.h:62
A class which holds the metadata from a remote stub/corefile note about how many bits are used for ad...
An architecture specification class.
Definition: ArchSpec.h:31
A uniqued constant string class.
Definition: ConstString.h:40
An data extractor class.
Definition: DataExtractor.h:48
A file collection class.
Definition: FileSpecList.h:85
A file utility class.
Definition: FileSpec.h:56
A mix in class that contains a pointer back to the module that owns the object which inherits from it...
Definition: ModuleChild.h:19
A class that describes an executable image and its associated object and symbol files.
Definition: Module.h:88
A plug-in interface definition class for object file parsers.
Definition: ObjectFile.h:44
virtual bool GetCorefileThreadExtraInfos(std::vector< lldb::tid_t > &tids)
Get metadata about threads from the corefile.
Definition: ObjectFile.h:561
virtual std::string GetIdentifierString()
Some object files may have an identifier string embedded in them, e.g.
Definition: ObjectFile.h:492
static lldb::ObjectFileSP FindPlugin(const lldb::ModuleSP &module_sp, const FileSpec *file_spec, lldb::offset_t file_offset, lldb::offset_t file_size, lldb::DataBufferSP &data_sp, lldb::offset_t &data_offset)
Find a ObjectFile plug-in that can parse file_spec.
Definition: ObjectFile.cpp:53
virtual bool SetLoadAddress(Target &target, lldb::addr_t value, bool value_is_offset)
Sets the load address for an entire module, assuming a rigid slide of sections, if possible in the im...
Definition: ObjectFile.h:398
virtual const FileSpec & GetFileSpec() const
Get const accessor to the object file specification.
Definition: ObjectFile.h:281
DataExtractor m_data
The data for this object file so things can be parsed lazily.
Definition: ObjectFile.h:756
virtual void Dump(Stream *s)=0
Dump a description of this object to a Stream.
Symtab * GetSymtab()
Gets the symbol table for the currently selected architecture (and object for archives).
Definition: ObjectFile.cpp:727
std::unique_ptr< lldb_private::SectionList > m_sections_up
Definition: ObjectFile.h:760
const ObjectFile & operator=(const ObjectFile &)=delete
static lldb::DataBufferSP MapFileData(const FileSpec &file, uint64_t Size, uint64_t Offset)
Definition: ObjectFile.cpp:661
virtual std::vector< LoadableData > GetLoadableData(Target &target)
Loads this objfile to memory.
Definition: ObjectFile.cpp:627
virtual llvm::StringRef StripLinkerSymbolAnnotations(llvm::StringRef symbol_name) const
Definition: ObjectFile.h:693
~ObjectFile() override
Destructor.
Definition: ObjectFile.cpp:283
std::unique_ptr< lldb_private::Symtab > m_symtab_up
Definition: ObjectFile.h:761
virtual uint32_t GetDependentModules(FileSpecList &file_list)=0
Extract the dependent modules from an object file.
const lldb::addr_t m_memory_addr
Set if the object file only exists in memory.
Definition: ObjectFile.h:759
virtual bool IsStripped()=0
Detect if this object file has been stripped of local symbols.
virtual lldb::RegisterContextSP GetThreadContextAtIndex(uint32_t idx, lldb_private::Thread &thread)
Definition: ObjectFile.h:566
virtual uint32_t GetNumThreadContexts()
Definition: ObjectFile.h:483
static size_t g_initial_bytes_to_read
The number of bytes to read when going through the plugins.
Definition: ObjectFile.h:783
virtual lldb_private::Address GetImageInfoAddress(Target *target)
Similar to Process::GetImageInfoAddress().
Definition: ObjectFile.h:459
virtual bool LoadCoreFileImages(lldb_private::Process &process)
Load binaries listed in a corefile.
Definition: ObjectFile.h:730
virtual void ParseSymtab(Symtab &symtab)=0
Parse the symbol table into the provides symbol table object.
virtual AddressClass GetAddressClass(lldb::addr_t file_addr)
Get the address type given a file address in an object file.
Definition: ObjectFile.cpp:295
virtual lldb::addr_t GetFileOffset() const
Returns the offset into a file at which this object resides.
Definition: ObjectFile.h:265
static lldb::DataBufferSP ReadMemory(const lldb::ProcessSP &process_sp, lldb::addr_t addr, size_t byte_size)
Definition: ObjectFile.cpp:448
virtual lldb_private::Address GetEntryPointAddress()
Returns the address of the Entry Point in this object file - if the object file doesn't have an entry...
Definition: ObjectFile.h:469
size_t GetData(lldb::offset_t offset, size_t length, DataExtractor &data) const
Definition: ObjectFile.cpp:462
virtual Strata CalculateStrata()=0
The object file should be able to calculate the strata of the object file.
@ eTypeExecutable
A normal executable.
Definition: ObjectFile.h:53
@ eTypeDebugInfo
An object file that contains only debug information.
Definition: ObjectFile.h:55
@ eTypeStubLibrary
A library that can be linked against but not used for execution.
Definition: ObjectFile.h:63
@ eTypeObjectFile
An intermediate object file.
Definition: ObjectFile.h:59
@ eTypeDynamicLinker
The platform's dynamic linker executable.
Definition: ObjectFile.h:57
@ eTypeCoreFile
A core file that has a checkpoint of a program's execution state.
Definition: ObjectFile.h:51
@ eTypeSharedLibrary
A shared library that can be used during execution.
Definition: ObjectFile.h:61
@ eTypeJIT
JIT code that has symbols, sections and possibly debug info.
Definition: ObjectFile.h:65
virtual void SetType(Type type)
In cases where the type can't be calculated (elf files), this routine allows someone to explicitly se...
Definition: ObjectFile.h:584
virtual lldb_private::AddressableBits GetAddressableBits()
Some object files may have the number of bits used for addressing embedded in them,...
Definition: ObjectFile.h:504
virtual Symbol * ResolveSymbolForAddress(const Address &so_addr, bool verify_unique)
Appends a Symbol for the specified so_addr to the symbol table.
Definition: ObjectFile.h:345
lldb::addr_t m_file_offset
The offset in bytes into the file, or the address in memory.
Definition: ObjectFile.h:750
static lldb::SymbolType GetSymbolTypeFromName(llvm::StringRef name, lldb::SymbolType symbol_type_hint=lldb::eSymbolTypeUndefined)
Definition: ObjectFile.cpp:607
virtual bool IsExecutable() const =0
Tells whether this object file is capable of being the main executable for a process.
virtual size_t GetSectionDataSize(Section *section)
Definition: ObjectFile.h:684
virtual std::unique_ptr< CallFrameInfo > CreateCallFrameInfo()
Creates a plugin-specific call frame info.
Definition: ObjectFile.cpp:653
virtual void ClearSymtab()
Frees the symbol table.
Definition: ObjectFile.cpp:576
bool SetModulesArchitecture(const ArchSpec &new_arch)
Sets the architecture for a module.
Definition: ObjectFile.cpp:288
virtual llvm::VersionTuple GetMinimumOSVersion()
Get the minimum OS version this object file can run on.
Definition: ObjectFile.h:621
virtual bool ParseHeader()=0
Attempts to parse the object header.
virtual FileSpec & GetFileSpec()
Get accessor to the object file specification.
Definition: ObjectFile.h:274
virtual Type CalculateType()=0
The object file should be able to calculate its type by looking at its file header and possibly the s...
ObjectFile(const ObjectFile &)=delete
virtual bool CanTrustAddressRanges()
Can we trust the address ranges accelerator associated with this object file to be complete.
Definition: ObjectFile.h:699
virtual lldb::ByteOrder GetByteOrder() const =0
Gets whether endian swapping should occur when extracting data from this object file.
virtual bool AllowAssemblyEmulationUnwindPlans()
Returns if the function bounds for symbols in this symbol file are likely accurate.
Definition: ObjectFile.h:445
virtual llvm::VersionTuple GetVersion()
Get the object file version numbers.
Definition: ObjectFile.h:610
static bool SplitArchivePathWithObject(llvm::StringRef path_with_object, lldb_private::FileSpec &archive_file, lldb_private::ConstString &archive_object, bool must_exist)
Split a path into a file path with object name.
Definition: ObjectFile.cpp:558
virtual void CreateSections(SectionList &unified_section_list)=0
virtual bool isA(const void *ClassID) const
Definition: ObjectFile.h:210
size_t CopyData(lldb::offset_t offset, size_t length, void *dst) const
Definition: ObjectFile.cpp:469
virtual void SectionFileAddressesChanged()
Notify the ObjectFile that the file addresses in the Sections for this module have been changed.
Definition: ObjectFile.h:304
virtual uint32_t GetAddressByteSize() const =0
Gets the address size in bytes for the current object file.
virtual void RelocateSection(lldb_private::Section *section)
Perform relocations on the section if necessary.
Definition: ObjectFile.cpp:657
std::optional< uint32_t > m_cache_hash
Definition: ObjectFile.h:768
virtual SectionList * GetSectionList(bool update_module_section_list=true)
Gets the section list for the currently selected architecture (and object for archives).
Definition: ObjectFile.cpp:590
virtual UUID GetUUID()=0
Gets the UUID for this object file.
std::unique_ptr< llvm::once_flag > m_symtab_once_up
We need a llvm::once_flag that we can use to avoid locking the module lock and deadlocking LLDB.
Definition: ObjectFile.h:767
bool IsInMemory() const
Returns true if the object file exists only in memory.
Definition: ObjectFile.h:689
lldb::ProcessWP m_process_wp
Definition: ObjectFile.h:757
uint32_t GetCacheHash()
Get a hash that can be used for caching object file releated information.
Definition: ObjectFile.cpp:758
lldb::addr_t m_length
The length of this object file if it is known (can be zero if length is unknown or can't be determine...
Definition: ObjectFile.h:752
virtual bool GetCorefileMainBinaryInfo(lldb::addr_t &value, bool &value_is_offset, UUID &uuid, ObjectFile::BinaryType &type)
When the ObjectFile is a core file, lldb needs to locate the "binary" in the core file.
Definition: ObjectFile.h:532
virtual size_t ReadSectionData(Section *section, lldb::offset_t section_offset, void *dst, size_t dst_len)
Definition: ObjectFile.cpp:476
BinaryType
If we have a corefile binary hint, this enum specifies the binary type which we can use to select the...
Definition: ObjectFile.h:81
@ eBinaryTypeUser
kernel binary
Definition: ObjectFile.h:85
@ eBinaryTypeStandalone
user process binary
Definition: ObjectFile.h:86
virtual lldb_private::Address GetBaseAddress()
Returns base address of this object file.
Definition: ObjectFile.h:479
virtual bool GetIsDynamicLinkEditor()
Return true if this file is a dynamic link editor (dyld)
Definition: ObjectFile.h:640
static size_t GetModuleSpecifications(const FileSpec &file, lldb::offset_t file_offset, lldb::offset_t file_size, ModuleSpecList &specs, lldb::DataBufferSP data_sp=lldb::DataBufferSP())
Definition: ObjectFile.cpp:187
virtual llvm::VersionTuple GetSDKVersion()
Get the SDK OS version this object file was built with.
Definition: ObjectFile.h:631
virtual lldb::addr_t GetByteSize() const
Definition: ObjectFile.h:267
virtual lldb_private::FileSpecList GetReExportedLibraries()
Gets the file spec list of libraries re-exported by this object file.
Definition: ObjectFile.h:389
virtual ArchSpec GetArchitecture()=0
Get the ArchSpec for this object file.
A plug-in interface definition class for debugging a process.
Definition: Process.h:341
lldb::offset_t GetFileSize() const
Definition: Section.h:160
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
void Clear()
Definition: UUID.h:62
#define LLDB_INVALID_ADDRESS
Definition: lldb-defines.h:82
A class that represents a running process on the host machine.
uint64_t offset_t
Definition: lldb-types.h:85
std::shared_ptr< lldb_private::ObjectFile > ObjectFileSP
Definition: lldb-forward.h:370
std::shared_ptr< lldb_private::Process > ProcessSP
Definition: lldb-forward.h:384
SymbolType
Symbol types.
@ eSymbolTypeUndefined
ByteOrder
Byte ordering definitions.
std::weak_ptr< lldb_private::Process > ProcessWP
Definition: lldb-forward.h:387
std::shared_ptr< lldb_private::DataBuffer > DataBufferSP
Definition: lldb-forward.h:331
std::shared_ptr< lldb_private::WritableDataBuffer > WritableDataBufferSP
Definition: lldb-forward.h:332
uint64_t addr_t
Definition: lldb-types.h:80
std::shared_ptr< lldb_private::RegisterContext > RegisterContextSP
Definition: lldb-forward.h:389
std::shared_ptr< lldb_private::Module > ModuleSP
Definition: lldb-forward.h:368
bool fromJSON(const llvm::json::Value &value, lldb_private::JSONSection &section, llvm::json::Path path)
Definition: Section.cpp:686
Definition: Debugger.h:54
llvm::ArrayRef< uint8_t > Contents
Definition: ObjectFile.h:91
static void format(const lldb_private::ObjectFile::Strata &strata, raw_ostream &OS, StringRef Style)
static void format(const lldb_private::ObjectFile::Type &type, raw_ostream &OS, StringRef Style)