Coverage Report

Created: 2023-11-11 10:31

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