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