ObjectFile.h revision ac725afac61b48d1dc0e38370d824fe45c52c3b7
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/lldb-private.h"
14#include "lldb/Core/DataExtractor.h"
15#include "lldb/Host/FileSpec.h"
16#include "lldb/Core/ModuleChild.h"
17#include "lldb/Core/PluginInterface.h"
18#include "lldb/Host/Endian.h"
19#include "lldb/Symbol/Symtab.h"
20#include "lldb/Symbol/UnwindTable.h"
21
22namespace lldb_private {
23
24//----------------------------------------------------------------------
25/// @class ObjectFile ObjectFile.h "lldb/Symbol/ObjectFile.h"
26/// @brief A plug-in interface definition class for object file parsers.
27///
28/// Object files belong to Module objects and know how to extract
29/// information from executable, shared library, and object (.o) files
30/// used by operating system runtime. The symbol table and section list
31/// for an object file.
32///
33/// Object files can be represented by the entire file, or by part of a
34/// file. Examples of object files that are part of a file include
35/// object files that contain information for multiple architectures in
36/// the same file, or archive files that contain multiple objects
37/// (ranlib archives) (possibly for multiple architectures as well).
38///
39/// Object archive files (e.g. ranlib archives) can contain
40/// multiple .o (object) files that must be selected by index or by name.
41/// The number of objects that an ObjectFile contains can be determined
42/// using the ObjectFile::GetNumObjects() const
43/// function, and followed by a call to
44/// ObjectFile::SelectObjectAtIndex (uint32_t) to change the currently
45/// selected object. Objects can also be selected by name using the
46/// ObjectFile::SelectObject(const char *) function.
47///
48/// Once an architecture is selected (and an object is selected for
49/// for archives), the object file information can be extracted from
50/// this abstract class.
51//----------------------------------------------------------------------
52class ObjectFile:
53    public std::tr1::enable_shared_from_this<ObjectFile>,
54    public PluginInterface,
55    public ModuleChild
56{
57friend class lldb_private::Module;
58
59public:
60    typedef enum
61    {
62        eTypeInvalid = 0,
63        eTypeCoreFile,      /// A core file that has a checkpoint of a program's execution state
64        eTypeExecutable,    /// A normal executable
65        eTypeDebugInfo,     /// An object file that contains only debug information
66        eTypeDynamicLinker, /// The platform's dynamic linker executable
67        eTypeObjectFile,    /// An intermediate object file
68        eTypeSharedLibrary, /// A shared library that can be used during execution
69        eTypeStubLibrary,   /// A library that can be linked against but not used for execution
70        eTypeUnknown
71    } Type;
72
73    typedef enum
74    {
75        eStrataInvalid = 0,
76        eStrataUnknown,
77        eStrataUser,
78        eStrataKernel,
79        eStrataRawImage
80    } Strata;
81
82    //------------------------------------------------------------------
83    /// Construct with a parent module, offset, and header data.
84    ///
85    /// Object files belong to modules and a valid module must be
86    /// supplied upon construction. The at an offset within a file for
87    /// objects that contain more than one architecture or object.
88    //------------------------------------------------------------------
89    ObjectFile (Module* module,
90                const FileSpec *file_spec_ptr,
91                lldb::addr_t offset,
92                lldb::addr_t length,
93                lldb::DataBufferSP& headerDataSP);
94
95    ObjectFile (Module* module,
96                const lldb::ProcessSP &process_sp,
97                lldb::addr_t header_addr,
98                lldb::DataBufferSP& headerDataSP);
99
100    //------------------------------------------------------------------
101    /// Destructor.
102    ///
103    /// The destructor is virtual since this class is designed to be
104    /// inherited from by the plug-in instance.
105    //------------------------------------------------------------------
106    virtual
107    ~ObjectFile();
108
109    //------------------------------------------------------------------
110    /// Dump a description of this object to a Stream.
111    ///
112    /// Dump a description of the current contents of this object
113    /// to the supplied stream \a s. The dumping should include the
114    /// section list if it has been parsed, and the symbol table
115    /// if it has been parsed.
116    ///
117    /// @param[in] s
118    ///     The stream to which to dump the object descripton.
119    //------------------------------------------------------------------
120    virtual void
121    Dump (Stream *s) = 0;
122
123    //------------------------------------------------------------------
124    /// Find a ObjectFile plug-in that can parse \a file_spec.
125    ///
126    /// Scans all loaded plug-in interfaces that implement versions of
127    /// the ObjectFile plug-in interface and returns the first
128    /// instance that can parse the file.
129    ///
130    /// @param[in] module
131    ///     The parent module that owns this object file.
132    ///
133    /// @param[in] file_spec
134    ///     A file specification that indicates which file to use as the
135    ///     object file.
136    ///
137    /// @param[in] file_offset
138    ///     The offset into the file at which to start parsing the
139    ///     object. This is for files that contain multiple
140    ///     architectures or objects.
141    ///
142    /// @param[in] file_size
143    ///     The size of the current object file if it can be determined
144    ///     or if it is known. This can be zero.
145    ///
146    /// @see ObjectFile::ParseHeader()
147    //------------------------------------------------------------------
148    static lldb::ObjectFileSP
149    FindPlugin (Module* module,
150                const FileSpec* file_spec,
151                lldb::addr_t file_offset,
152                lldb::addr_t file_size,
153                lldb::DataBufferSP &data_sp);
154
155    //------------------------------------------------------------------
156    /// Find a ObjectFile plug-in that can parse a file in memory.
157    ///
158    /// Scans all loaded plug-in interfaces that implement versions of
159    /// the ObjectFile plug-in interface and returns the first
160    /// instance that can parse the file.
161    ///
162    /// @param[in] module
163    ///     The parent module that owns this object file.
164    ///
165    /// @param[in] process_sp
166    ///     A shared pointer to the process whose memory space contains
167    ///     an object file. This will be stored as a std::weak_ptr.
168    ///
169    /// @param[in] header_addr
170    ///     The address of the header for the object file in memory.
171    //------------------------------------------------------------------
172    static lldb::ObjectFileSP
173    FindPlugin (Module* module,
174                const lldb::ProcessSP &process_sp,
175                lldb::addr_t header_addr,
176                lldb::DataBufferSP &file_data_sp);
177
178    //------------------------------------------------------------------
179    /// Gets the address size in bytes for the current object file.
180    ///
181    /// @return
182    ///     The size of an address in bytes for the currently selected
183    ///     architecture (and object for archives). Returns zero if no
184    ///     architecture or object has been selected.
185    //------------------------------------------------------------------
186    virtual size_t
187    GetAddressByteSize ()  const = 0;
188
189    //------------------------------------------------------------------
190    /// Get the address type given a file address in an object file.
191    ///
192    /// Many binary file formats know what kinds
193    /// This is primarily for ARM binaries, though it can be applied to
194    /// any executable file format that supports different opcode types
195    /// within the same binary. ARM binaries support having both ARM and
196    /// Thumb within the same executable container. We need to be able
197    /// to get
198    /// @return
199    ///     The size of an address in bytes for the currently selected
200    ///     architecture (and object for archives). Returns zero if no
201    ///     architecture or object has been selected.
202    //------------------------------------------------------------------
203    virtual AddressClass
204    GetAddressClass (lldb::addr_t file_addr);
205
206    //------------------------------------------------------------------
207    /// Extract the dependent modules from an object file.
208    ///
209    /// If an object file has information about which other images it
210    /// depends on (such as shared libraries), this function will
211    /// provide the list. Since many executables or shared libraries
212    /// may depend on the same files,
213    /// FileSpecList::AppendIfUnique(const FileSpec &) should be
214    /// used to make sure any files that are added are not already in
215    /// the list.
216    ///
217    /// @param[out] file_list
218    ///     A list of file specification objects that gets dependent
219    ///     files appended to.
220    ///
221    /// @return
222    ///     The number of new files that were appended to \a file_list.
223    ///
224    /// @see FileSpecList::AppendIfUnique(const FileSpec &)
225    //------------------------------------------------------------------
226    virtual uint32_t
227    GetDependentModules (FileSpecList& file_list) = 0;
228
229    //------------------------------------------------------------------
230    /// Tells whether this object file is capable of being the main executable
231    /// for a process.
232    ///
233    /// @return
234    ///     \b true if it is, \b false otherwise.
235    //------------------------------------------------------------------
236    virtual bool
237    IsExecutable () const = 0;
238
239    //------------------------------------------------------------------
240    /// Returns the offset into a file at which this object resides.
241    ///
242    /// Some files contain many object files, and this function allows
243    /// access to an object's offset within the file.
244    ///
245    /// @return
246    ///     The offset in bytes into the file. Defaults to zero for
247    ///     simple object files that a represented by an entire file.
248    //------------------------------------------------------------------
249    virtual lldb::addr_t
250    GetOffset () const
251    { return m_offset; }
252
253    virtual lldb::addr_t
254    GetByteSize () const
255    { return m_length; }
256
257    //------------------------------------------------------------------
258    /// Get accessor to the object file specification.
259    ///
260    /// @return
261    ///     The file specification object pointer if there is one, or
262    ///     NULL if this object is only from memory.
263    //------------------------------------------------------------------
264    virtual FileSpec&
265    GetFileSpec() { return m_file; }
266
267    //------------------------------------------------------------------
268    /// Get const accessor to the object file specification.
269    ///
270    /// @return
271    ///     The const file specification object pointer if there is one,
272    ///     or NULL if this object is only from memory.
273    //------------------------------------------------------------------
274    virtual const FileSpec&
275    GetFileSpec() const { return m_file; }
276
277    //------------------------------------------------------------------
278    /// Get the name of the cpu, vendor and OS for this object file.
279    ///
280    /// This value is a string that represents the target triple where
281    /// the cpu type, the vendor and the OS are encoded into a string.
282    ///
283    /// @param[out] target_triple
284    ///     The string value of the target triple.
285    ///
286    /// @return
287    ///     \b True if the target triple was able to be computed, \b
288    ///     false otherwise.
289    //------------------------------------------------------------------
290    virtual bool
291    GetArchitecture (ArchSpec &arch) = 0;
292
293    //------------------------------------------------------------------
294    /// Gets the section list for the currently selected architecture
295    /// (and object for archives).
296    ///
297    /// Section list parsing can be deferred by ObjectFile instances
298    /// until this accessor is called the first time.
299    ///
300    /// @return
301    ///     The list of sections contained in this object file.
302    //------------------------------------------------------------------
303    virtual SectionList *
304    GetSectionList () = 0;
305
306    //------------------------------------------------------------------
307    /// Gets the symbol table for the currently selected architecture
308    /// (and object for archives).
309    ///
310    /// Symbol table parsing can be deferred by ObjectFile instances
311    /// until this accessor is called the first time.
312    ///
313    /// @return
314    ///     The symbol table for this object file.
315    //------------------------------------------------------------------
316    virtual Symtab *
317    GetSymtab () = 0;
318
319    //------------------------------------------------------------------
320    /// Gets the UUID for this object file.
321    ///
322    /// If the object file format contains a UUID, the value should be
323    /// returned. Else ObjectFile instances should return the MD5
324    /// checksum of all of the bytes for the object file (or memory for
325    /// memory based object files).
326    ///
327    /// @return
328    ///     Returns \b true if a UUID was successfully extracted into
329    ///     \a uuid, \b false otherwise.
330    //------------------------------------------------------------------
331    virtual bool
332    GetUUID (lldb_private::UUID* uuid) = 0;
333
334    //------------------------------------------------------------------
335    /// Gets whether endian swapping should occur when extracting data
336    /// from this object file.
337    ///
338    /// @return
339    ///     Returns \b true if endian swapping is needed, \b false
340    ///     otherwise.
341    //------------------------------------------------------------------
342    virtual lldb::ByteOrder
343    GetByteOrder () const = 0;
344
345    //------------------------------------------------------------------
346    /// Attempts to parse the object header.
347    ///
348    /// This function is used as a test to see if a given plug-in
349    /// instance can parse the header data already contained in
350    /// ObjectFile::m_data. If an object file parser does not
351    /// recognize that magic bytes in a header, false should be returned
352    /// and the next plug-in can attempt to parse an object file.
353    ///
354    /// @return
355    ///     Returns \b true if the header was parsed succesfully, \b
356    ///     false otherwise.
357    //------------------------------------------------------------------
358    virtual bool
359    ParseHeader () = 0;
360
361    //------------------------------------------------------------------
362    /// Returns a reference to the UnwindTable for this ObjectFile
363    ///
364    /// The UnwindTable contains FuncUnwinders objects for any function in
365    /// this ObjectFile.  If a FuncUnwinders object hasn't been created yet
366    /// (i.e. the function has yet to be unwound in a stack walk), it
367    /// will be created when requested.  Specifically, we do not create
368    /// FuncUnwinders objects for functions until they are needed.
369    ///
370    /// @return
371    ///     Returns the unwind table for this object file.
372    //------------------------------------------------------------------
373    virtual lldb_private::UnwindTable&
374    GetUnwindTable () { return m_unwind_table; }
375
376    //------------------------------------------------------------------
377    /// Similar to Process::GetImageInfoAddress().
378    ///
379    /// Some platforms embed auxiliary structures useful to debuggers in the
380    /// address space of the inferior process.  This method returns the address
381    /// of such a structure if the information can be resolved via entries in
382    /// the object file.  ELF, for example, provides a means to hook into the
383    /// runtime linker so that a debugger may monitor the loading and unloading
384    /// of shared libraries.
385    ///
386    /// @return
387    ///     The address of any auxiliary tables, or an invalid address if this
388    ///     object file format does not support or contain such information.
389    virtual lldb_private::Address
390    GetImageInfoAddress () { return Address(); }
391
392    //------------------------------------------------------------------
393    /// Returns the address of the Entry Point in this object file - if
394    /// the object file doesn't have an entry point (because it is not an
395    /// executable file) then an invalid address is returned.
396    ///
397    /// @return
398    ///     Returns the entry address for this module.
399    //------------------------------------------------------------------
400    virtual lldb_private::Address
401    GetEntryPointAddress () { return Address();}
402
403    //------------------------------------------------------------------
404    /// Returns the address that represents the header of this object
405    /// file.
406    ///
407    /// The header address is defined as where the header for the object
408    /// file is that describes the content of the file. If the header
409    /// doesn't appear in a section that is defined in the object file,
410    /// an address with no section is returned that has the file offset
411    /// set in the m_offset member of the lldb_private::Address object.
412    ///
413    /// @return
414    ///     Returns the entry address for this module.
415    //------------------------------------------------------------------
416    virtual lldb_private::Address
417    GetHeaderAddress () { return Address();}
418
419
420    virtual uint32_t
421    GetNumThreadContexts ()
422    {
423        return 0;
424    }
425
426    virtual lldb::RegisterContextSP
427    GetThreadContextAtIndex (uint32_t idx, lldb_private::Thread &thread)
428    {
429        return lldb::RegisterContextSP();
430    }
431    //------------------------------------------------------------------
432    /// The object file should be able to calculate its type by looking
433    /// at its file header and possibly the sections or other data in
434    /// the object file. The file type is used in the debugger to help
435    /// select the correct plug-ins for the job at hand, so this is
436    /// important to get right. If any eTypeXXX definitions do not match
437    /// up with the type of file you are loading, please feel free to
438    /// add a new enumeration value.
439    ///
440    /// @return
441    ///     The calculated file type for the current object file.
442    //------------------------------------------------------------------
443    virtual Type
444    CalculateType() = 0;
445
446    //------------------------------------------------------------------
447    /// The object file should be able to calculate the strata of the
448    /// object file.
449    ///
450    /// Many object files for platforms might be for either user space
451    /// debugging or for kernel debugging. If your object file subclass
452    /// can figure this out, it will help with debugger plug-in selection
453    /// when it comes time to debug.
454    ///
455    /// @return
456    ///     The calculated object file strata for the current object
457    ///     file.
458    //------------------------------------------------------------------
459    virtual Strata
460    CalculateStrata() = 0;
461
462    //------------------------------------------------------------------
463    // Member Functions
464    //------------------------------------------------------------------
465    Type
466    GetType ()
467    {
468        if (m_type == eTypeInvalid)
469            m_type = CalculateType();
470        return m_type;
471    }
472
473    Strata
474    GetStrata ()
475    {
476        if (m_strata == eStrataInvalid)
477            m_strata = CalculateStrata();
478        return m_strata;
479    }
480
481    // When an object file is in memory, subclasses should try and lock
482    // the process weak pointer. If the process weak pointer produces a
483    // valid ProcessSP, then subclasses can call this function to read
484    // memory.
485    static lldb::DataBufferSP
486    ReadMemory (const lldb::ProcessSP &process_sp,
487                lldb::addr_t addr,
488                size_t byte_size);
489
490    size_t
491    GetData (off_t offset, size_t length, DataExtractor &data) const;
492
493    size_t
494    CopyData (off_t offset, size_t length, void *dst) const;
495
496    size_t
497    ReadSectionData (const Section *section,
498                     off_t section_offset,
499                     void *dst,
500                     size_t dst_len) const;
501    size_t
502    ReadSectionData (const Section *section,
503                     DataExtractor& section_data) const;
504
505    size_t
506    MemoryMapSectionData (const Section *section,
507                          DataExtractor& section_data) const;
508protected:
509    //------------------------------------------------------------------
510    // Member variables.
511    //------------------------------------------------------------------
512    FileSpec m_file;
513    Type m_type;
514    Strata m_strata;
515    lldb::addr_t m_offset; ///< The offset in bytes into the file, or the address in memory
516    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).
517    DataExtractor m_data; ///< The data for this object file so things can be parsed lazily.
518    lldb_private::UnwindTable m_unwind_table; /// < Table of FuncUnwinders objects created for this ObjectFile's functions
519    lldb::ProcessWP m_process_wp;
520    const lldb::addr_t m_memory_addr;
521
522    bool
523    IsInMemory () const
524    {
525        return m_memory_addr != LLDB_INVALID_ADDRESS;
526    }
527    //------------------------------------------------------------------
528    /// Sets the architecture for a module.  At present the architecture
529    /// can only be set if it is invalid.  It is not allowed to switch from
530    /// one concrete architecture to another.
531    ///
532    /// @param[in] new_arch
533    ///     The architecture this module will be set to.
534    ///
535    /// @return
536    ///     Returns \b true if the architecture was changed, \b
537    ///     false otherwise.
538    //------------------------------------------------------------------
539    bool SetModulesArchitecture (const ArchSpec &new_arch);
540
541private:
542    DISALLOW_COPY_AND_ASSIGN (ObjectFile);
543};
544
545} // namespace lldb_private
546
547#endif  // liblldb_ObjectFile_h_
548
549