1 //===-- ObjectFile.h --------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_ObjectFile_h_
11 #define liblldb_ObjectFile_h_
13 #include "lldb/lldb-private.h"
14 #include "lldb/Core/DataExtractor.h"
15 #include "lldb/Host/FileSpec.h"
16 #include "lldb/Core/FileSpecList.h"
17 #include "lldb/Core/ModuleChild.h"
18 #include "lldb/Core/PluginInterface.h"
19 #include "lldb/Host/Endian.h"
20 #include "lldb/Symbol/Symtab.h"
21 #include "lldb/Symbol/UnwindTable.h"
23 namespace lldb_private {
25 //----------------------------------------------------------------------
26 /// @class ObjectFile ObjectFile.h "lldb/Symbol/ObjectFile.h"
27 /// @brief A plug-in interface definition class for object file parsers.
29 /// Object files belong to Module objects and know how to extract
30 /// information from executable, shared library, and object (.o) files
31 /// used by operating system runtime. The symbol table and section list
32 /// for an object file.
34 /// Object files can be represented by the entire file, or by part of a
35 /// file. Examples of object files that are part of a file include
36 /// object files that contain information for multiple architectures in
37 /// the same file, or archive files that contain multiple objects
38 /// (ranlib archives) (possibly for multiple architectures as well).
40 /// Object archive files (e.g. ranlib archives) can contain
41 /// multiple .o (object) files that must be selected by index or by name.
42 /// The number of objects that an ObjectFile contains can be determined
43 /// using the ObjectFile::GetNumObjects() const
44 /// function, and followed by a call to
45 /// ObjectFile::SelectObjectAtIndex (uint32_t) to change the currently
46 /// selected object. Objects can also be selected by name using the
47 /// ObjectFile::SelectObject(const char *) function.
49 /// Once an architecture is selected (and an object is selected for
50 /// for archives), the object file information can be extracted from
51 /// this abstract class.
52 //----------------------------------------------------------------------
54 public std::enable_shared_from_this<ObjectFile>,
55 public PluginInterface,
58 friend class lldb_private::Module;
64 eTypeCoreFile, /// A core file that has a checkpoint of a program's execution state
65 eTypeExecutable, /// A normal executable
66 eTypeDebugInfo, /// An object file that contains only debug information
67 eTypeDynamicLinker, /// The platform's dynamic linker executable
68 eTypeObjectFile, /// An intermediate object file
69 eTypeSharedLibrary, /// A shared library that can be used during execution
70 eTypeStubLibrary, /// A library that can be linked against but not used for execution
83 //------------------------------------------------------------------
84 /// Construct with a parent module, offset, and header data.
86 /// Object files belong to modules and a valid module must be
87 /// supplied upon construction. The at an offset within a file for
88 /// objects that contain more than one architecture or object.
89 //------------------------------------------------------------------
90 ObjectFile (const lldb::ModuleSP &module_sp,
91 const FileSpec *file_spec_ptr,
92 lldb::offset_t file_offset,
93 lldb::offset_t length,
94 lldb::DataBufferSP& data_sp,
95 lldb::offset_t data_offset);
97 ObjectFile (const lldb::ModuleSP &module_sp,
98 const lldb::ProcessSP &process_sp,
99 lldb::addr_t header_addr,
100 lldb::DataBufferSP& data_sp);
102 //------------------------------------------------------------------
105 /// The destructor is virtual since this class is designed to be
106 /// inherited from by the plug-in instance.
107 //------------------------------------------------------------------
111 //------------------------------------------------------------------
112 /// Dump a description of this object to a Stream.
114 /// Dump a description of the current contents of this object
115 /// to the supplied stream \a s. The dumping should include the
116 /// section list if it has been parsed, and the symbol table
117 /// if it has been parsed.
120 /// The stream to which to dump the object descripton.
121 //------------------------------------------------------------------
123 Dump (Stream *s) = 0;
125 //------------------------------------------------------------------
126 /// Find a ObjectFile plug-in that can parse \a file_spec.
128 /// Scans all loaded plug-in interfaces that implement versions of
129 /// the ObjectFile plug-in interface and returns the first
130 /// instance that can parse the file.
132 /// @param[in] module
133 /// The parent module that owns this object file.
135 /// @param[in] file_spec
136 /// A file specification that indicates which file to use as the
139 /// @param[in] file_offset
140 /// The offset into the file at which to start parsing the
141 /// object. This is for files that contain multiple
142 /// architectures or objects.
144 /// @param[in] file_size
145 /// The size of the current object file if it can be determined
146 /// or if it is known. This can be zero.
148 /// @see ObjectFile::ParseHeader()
149 //------------------------------------------------------------------
150 static lldb::ObjectFileSP
151 FindPlugin (const lldb::ModuleSP &module_sp,
152 const FileSpec* file_spec,
153 lldb::offset_t file_offset,
154 lldb::offset_t file_size,
155 lldb::DataBufferSP &data_sp,
156 lldb::offset_t &data_offset);
158 //------------------------------------------------------------------
159 /// Find a ObjectFile plug-in that can parse a file in memory.
161 /// Scans all loaded plug-in interfaces that implement versions of
162 /// the ObjectFile plug-in interface and returns the first
163 /// instance that can parse the file.
165 /// @param[in] module
166 /// The parent module that owns this object file.
168 /// @param[in] process_sp
169 /// A shared pointer to the process whose memory space contains
170 /// an object file. This will be stored as a std::weak_ptr.
172 /// @param[in] header_addr
173 /// The address of the header for the object file in memory.
174 //------------------------------------------------------------------
175 static lldb::ObjectFileSP
176 FindPlugin (const lldb::ModuleSP &module_sp,
177 const lldb::ProcessSP &process_sp,
178 lldb::addr_t header_addr,
179 lldb::DataBufferSP &file_data_sp);
183 GetModuleSpecifications (const FileSpec &file,
184 lldb::offset_t file_offset,
185 lldb::offset_t file_size,
186 ModuleSpecList &specs);
189 GetModuleSpecifications (const lldb_private::FileSpec& file,
190 lldb::DataBufferSP& data_sp,
191 lldb::offset_t data_offset,
192 lldb::offset_t file_offset,
193 lldb::offset_t file_size,
194 lldb_private::ModuleSpecList &specs);
195 //------------------------------------------------------------------
196 /// Split a path into a file path with object name.
198 /// For paths like "/tmp/foo.a(bar.o)" we often need to split a path
199 /// up into the actual path name and into the object name so we can
200 /// make a valid object file from it.
202 /// @param[in] path_with_object
203 /// A path that might contain an archive path with a .o file
204 /// specified in parens in the basename of the path.
206 /// @param[out] archive_file
207 /// If \b true is returned, \a file_spec will be filled in with
208 /// the path to the archive.
210 /// @param[out] archive_object
211 /// If \b true is returned, \a object will be filled in with
212 /// the name of the object inside the archive.
215 /// \b true if the path matches the pattern of archive + object
216 /// and \a archive_file and \a archive_object are modified,
217 /// \b false otherwise and \a archive_file and \a archive_object
218 /// are guaranteed to be remain unchanged.
219 //------------------------------------------------------------------
221 SplitArchivePathWithObject (const char *path_with_object,
222 lldb_private::FileSpec &archive_file,
223 lldb_private::ConstString &archive_object,
226 //------------------------------------------------------------------
227 /// Gets the address size in bytes for the current object file.
230 /// The size of an address in bytes for the currently selected
231 /// architecture (and object for archives). Returns zero if no
232 /// architecture or object has been selected.
233 //------------------------------------------------------------------
235 GetAddressByteSize () const = 0;
237 //------------------------------------------------------------------
238 /// Get the address type given a file address in an object file.
240 /// Many binary file formats know what kinds
241 /// This is primarily for ARM binaries, though it can be applied to
242 /// any executable file format that supports different opcode types
243 /// within the same binary. ARM binaries support having both ARM and
244 /// Thumb within the same executable container. We need to be able
247 /// The size of an address in bytes for the currently selected
248 /// architecture (and object for archives). Returns zero if no
249 /// architecture or object has been selected.
250 //------------------------------------------------------------------
251 virtual lldb::AddressClass
252 GetAddressClass (lldb::addr_t file_addr);
254 //------------------------------------------------------------------
255 /// Extract the dependent modules from an object file.
257 /// If an object file has information about which other images it
258 /// depends on (such as shared libraries), this function will
259 /// provide the list. Since many executables or shared libraries
260 /// may depend on the same files,
261 /// FileSpecList::AppendIfUnique(const FileSpec &) should be
262 /// used to make sure any files that are added are not already in
265 /// @param[out] file_list
266 /// A list of file specification objects that gets dependent
267 /// files appended to.
270 /// The number of new files that were appended to \a file_list.
272 /// @see FileSpecList::AppendIfUnique(const FileSpec &)
273 //------------------------------------------------------------------
275 GetDependentModules (FileSpecList& file_list) = 0;
277 //------------------------------------------------------------------
278 /// Tells whether this object file is capable of being the main executable
282 /// \b true if it is, \b false otherwise.
283 //------------------------------------------------------------------
285 IsExecutable () const = 0;
287 //------------------------------------------------------------------
288 /// Returns the offset into a file at which this object resides.
290 /// Some files contain many object files, and this function allows
291 /// access to an object's offset within the file.
294 /// The offset in bytes into the file. Defaults to zero for
295 /// simple object files that a represented by an entire file.
296 //------------------------------------------------------------------
298 GetFileOffset () const
299 { return m_file_offset; }
305 //------------------------------------------------------------------
306 /// Get accessor to the object file specification.
309 /// The file specification object pointer if there is one, or
310 /// NULL if this object is only from memory.
311 //------------------------------------------------------------------
313 GetFileSpec() { return m_file; }
315 //------------------------------------------------------------------
316 /// Get const accessor to the object file specification.
319 /// The const file specification object pointer if there is one,
320 /// or NULL if this object is only from memory.
321 //------------------------------------------------------------------
322 virtual const FileSpec&
323 GetFileSpec() const { return m_file; }
325 //------------------------------------------------------------------
326 /// Get the name of the cpu, vendor and OS for this object file.
328 /// This value is a string that represents the target triple where
329 /// the cpu type, the vendor and the OS are encoded into a string.
331 /// @param[out] target_triple
332 /// The string value of the target triple.
335 /// \b True if the target triple was able to be computed, \b
337 //------------------------------------------------------------------
339 GetArchitecture (ArchSpec &arch) = 0;
341 //------------------------------------------------------------------
342 /// Gets the section list for the currently selected architecture
343 /// (and object for archives).
345 /// Section list parsing can be deferred by ObjectFile instances
346 /// until this accessor is called the first time.
349 /// The list of sections contained in this object file.
350 //------------------------------------------------------------------
351 virtual SectionList *
355 CreateSections (SectionList &unified_section_list) = 0;
357 //------------------------------------------------------------------
358 /// Gets the symbol table for the currently selected architecture
359 /// (and object for archives).
361 /// Symbol table parsing can be deferred by ObjectFile instances
362 /// until this accessor is called the first time.
365 /// The symbol table for this object file.
366 //------------------------------------------------------------------
370 //------------------------------------------------------------------
371 /// Detect if this object file has been stripped of local symbols.
374 /// Return \b true if the object file has been stripped of local
376 //------------------------------------------------------------------
380 //------------------------------------------------------------------
381 /// Frees the symbol table.
383 /// This function should only be used when an object file is
386 /// eSymtabFromUnifiedSectionList: Whether to clear symbol table
387 /// for unified module section list, or object file.
390 /// The symbol table for this object file.
391 //------------------------------------------------------------------
395 //------------------------------------------------------------------
396 /// Gets the UUID for this object file.
398 /// If the object file format contains a UUID, the value should be
399 /// returned. Else ObjectFile instances should return the MD5
400 /// checksum of all of the bytes for the object file (or memory for
401 /// memory based object files).
404 /// Returns \b true if a UUID was successfully extracted into
405 /// \a uuid, \b false otherwise.
406 //------------------------------------------------------------------
408 GetUUID (lldb_private::UUID* uuid) = 0;
410 //------------------------------------------------------------------
411 /// Gets the symbol file spec list for this object file.
413 /// If the object file format contains a debug symbol file link,
414 /// the values will be return in the FileSpecList.
417 /// Returns filespeclist.
418 //------------------------------------------------------------------
419 virtual lldb_private::FileSpecList
420 GetDebugSymbolFilePaths()
422 return FileSpecList();
425 //------------------------------------------------------------------
426 /// Gets whether endian swapping should occur when extracting data
427 /// from this object file.
430 /// Returns \b true if endian swapping is needed, \b false
432 //------------------------------------------------------------------
433 virtual lldb::ByteOrder
434 GetByteOrder () const = 0;
436 //------------------------------------------------------------------
437 /// Attempts to parse the object header.
439 /// This function is used as a test to see if a given plug-in
440 /// instance can parse the header data already contained in
441 /// ObjectFile::m_data. If an object file parser does not
442 /// recognize that magic bytes in a header, false should be returned
443 /// and the next plug-in can attempt to parse an object file.
446 /// Returns \b true if the header was parsed succesfully, \b
448 //------------------------------------------------------------------
452 //------------------------------------------------------------------
453 /// Returns a reference to the UnwindTable for this ObjectFile
455 /// The UnwindTable contains FuncUnwinders objects for any function in
456 /// this ObjectFile. If a FuncUnwinders object hasn't been created yet
457 /// (i.e. the function has yet to be unwound in a stack walk), it
458 /// will be created when requested. Specifically, we do not create
459 /// FuncUnwinders objects for functions until they are needed.
462 /// Returns the unwind table for this object file.
463 //------------------------------------------------------------------
464 virtual lldb_private::UnwindTable&
465 GetUnwindTable () { return m_unwind_table; }
467 //------------------------------------------------------------------
468 /// Similar to Process::GetImageInfoAddress().
470 /// Some platforms embed auxiliary structures useful to debuggers in the
471 /// address space of the inferior process. This method returns the address
472 /// of such a structure if the information can be resolved via entries in
473 /// the object file. ELF, for example, provides a means to hook into the
474 /// runtime linker so that a debugger may monitor the loading and unloading
475 /// of shared libraries.
478 /// The address of any auxiliary tables, or an invalid address if this
479 /// object file format does not support or contain such information.
480 virtual lldb_private::Address
481 GetImageInfoAddress () { return Address(); }
483 //------------------------------------------------------------------
484 /// Returns the address of the Entry Point in this object file - if
485 /// the object file doesn't have an entry point (because it is not an
486 /// executable file) then an invalid address is returned.
489 /// Returns the entry address for this module.
490 //------------------------------------------------------------------
491 virtual lldb_private::Address
492 GetEntryPointAddress () { return Address();}
494 //------------------------------------------------------------------
495 /// Returns the address that represents the header of this object
498 /// The header address is defined as where the header for the object
499 /// file is that describes the content of the file. If the header
500 /// doesn't appear in a section that is defined in the object file,
501 /// an address with no section is returned that has the file offset
502 /// set in the m_file_offset member of the lldb_private::Address object.
505 /// Returns the entry address for this module.
506 //------------------------------------------------------------------
507 virtual lldb_private::Address
508 GetHeaderAddress () { return Address(m_memory_addr);}
512 GetNumThreadContexts ()
517 virtual lldb::RegisterContextSP
518 GetThreadContextAtIndex (uint32_t idx, lldb_private::Thread &thread)
520 return lldb::RegisterContextSP();
523 //------------------------------------------------------------------
524 /// The object file should be able to calculate its type by looking
525 /// at its file header and possibly the sections or other data in
526 /// the object file. The file type is used in the debugger to help
527 /// select the correct plug-ins for the job at hand, so this is
528 /// important to get right. If any eTypeXXX definitions do not match
529 /// up with the type of file you are loading, please feel free to
530 /// add a new enumeration value.
533 /// The calculated file type for the current object file.
534 //------------------------------------------------------------------
538 //------------------------------------------------------------------
539 /// In cases where the type can't be calculated (elf files), this
540 /// routine allows someone to explicitly set it. As an example,
541 /// SymbolVendorELF uses this routine to set eTypeDebugInfo when
542 /// loading debug link files.
549 //------------------------------------------------------------------
550 /// The object file should be able to calculate the strata of the
553 /// Many object files for platforms might be for either user space
554 /// debugging or for kernel debugging. If your object file subclass
555 /// can figure this out, it will help with debugger plug-in selection
556 /// when it comes time to debug.
559 /// The calculated object file strata for the current object
561 //------------------------------------------------------------------
563 CalculateStrata() = 0;
565 //------------------------------------------------------------------
566 /// Get the object file version numbers.
568 /// Many object files have a set of version numbers that describe
569 /// the version of the executable or shared library. Typically there
570 /// are major, minor and build, but there may be more. This function
571 /// will extract the versions from object files if they are available.
573 /// If \a versions is NULL, or if \a num_versions is 0, the return
574 /// value will indicate how many version numbers are available in
575 /// this object file. Then a subsequent call can be made to this
576 /// function with a value of \a versions and \a num_versions that
577 /// has enough storage to store some or all version numbers.
579 /// @param[out] versions
580 /// A pointer to an array of uint32_t types that is \a num_versions
581 /// long. If this value is NULL, the return value will indicate
582 /// how many version numbers are required for a subsequent call
583 /// to this function so that all versions can be retrieved. If
584 /// the value is non-NULL, then at most \a num_versions of the
585 /// existing versions numbers will be filled into \a versions.
586 /// If there is no version information available, \a versions
587 /// will be filled with \a num_versions UINT32_MAX values
588 /// and zero will be returned.
590 /// @param[in] num_versions
591 /// The maximum number of entries to fill into \a versions. If
592 /// this value is zero, then the return value will indicate
593 /// how many version numbers there are in total so another call
594 /// to this function can be make with adequate storage in
595 /// \a versions to get all of the version numbers. If \a
596 /// num_versions is less than the actual number of version
597 /// numbers in this object file, only \a num_versions will be
598 /// filled into \a versions (if \a versions is non-NULL).
601 /// This function always returns the number of version numbers
602 /// that this object file has regardless of the number of
603 /// version numbers that were copied into \a versions.
604 //------------------------------------------------------------------
606 GetVersion (uint32_t *versions, uint32_t num_versions)
608 if (versions && num_versions)
610 for (uint32_t i=0; i<num_versions; ++i)
611 versions[i] = UINT32_MAX;
616 //------------------------------------------------------------------
618 //------------------------------------------------------------------
622 if (m_type == eTypeInvalid)
623 m_type = CalculateType();
630 if (m_strata == eStrataInvalid)
631 m_strata = CalculateStrata();
635 // When an object file is in memory, subclasses should try and lock
636 // the process weak pointer. If the process weak pointer produces a
637 // valid ProcessSP, then subclasses can call this function to read
639 static lldb::DataBufferSP
640 ReadMemory (const lldb::ProcessSP &process_sp,
645 GetData (off_t offset, size_t length, DataExtractor &data) const;
648 CopyData (off_t offset, size_t length, void *dst) const;
651 ReadSectionData (const Section *section,
652 off_t section_offset,
654 size_t dst_len) const;
656 ReadSectionData (const Section *section,
657 DataExtractor& section_data) const;
660 MemoryMapSectionData (const Section *section,
661 DataExtractor& section_data) const;
666 return m_memory_addr != LLDB_INVALID_ADDRESS;
670 //------------------------------------------------------------------
672 //------------------------------------------------------------------
676 lldb::addr_t m_file_offset; ///< The offset in bytes into the file, or the address in memory
677 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 determined).
678 DataExtractor m_data; ///< The data for this object file so things can be parsed lazily.
679 lldb_private::UnwindTable m_unwind_table; /// < Table of FuncUnwinders objects created for this ObjectFile's functions
680 lldb::ProcessWP m_process_wp;
681 const lldb::addr_t m_memory_addr;
682 std::unique_ptr<lldb_private::SectionList> m_sections_ap;
683 std::unique_ptr<lldb_private::Symtab> m_symtab_ap;
685 //------------------------------------------------------------------
686 /// Sets the architecture for a module. At present the architecture
687 /// can only be set if it is invalid. It is not allowed to switch from
688 /// one concrete architecture to another.
690 /// @param[in] new_arch
691 /// The architecture this module will be set to.
694 /// Returns \b true if the architecture was changed, \b
696 //------------------------------------------------------------------
697 bool SetModulesArchitecture (const ArchSpec &new_arch);
700 DISALLOW_COPY_AND_ASSIGN (ObjectFile);
703 } // namespace lldb_private
705 #endif // liblldb_ObjectFile_h_