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