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