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 , 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 , |
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 | 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 | virtual lldb::addr_t GetFileOffset() const { return m_file_offset; } |
266 | |
267 | 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 | 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 | 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 | 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 | 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 | return nullptr; |
355 | } |
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 | virtual lldb_private::FileSpecList GetReExportedLibraries() { |
390 | return FileSpecList(); |
391 | } |
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 | bool value_is_offset) { |
400 | return false; |
401 | } |
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 () = 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 | 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 | virtual lldb_private::Address GetImageInfoAddress(Target *target) { |
460 | return Address(); |
461 | } |
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 | 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 | virtual lldb_private::Address GetBaseAddress() { |
480 | return Address(m_memory_addr); |
481 | } |
482 | |
483 | 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 | virtual std::string GetIdentifierString () { |
493 | return std::string(); |
494 | } |
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 | 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 | ObjectFile::BinaryType &type) { |
535 | value = LLDB_INVALID_ADDRESS; |
536 | value_is_offset = false; |
537 | uuid.Clear(); |
538 | return false; |
539 | } |
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 | virtual bool (std::vector<lldb::tid_t> &tids) { |
562 | return false; |
563 | } |
564 | |
565 | virtual lldb::RegisterContextSP |
566 | GetThreadContextAtIndex(uint32_t idx, lldb_private::Thread &thread) { |
567 | return lldb::RegisterContextSP(); |
568 | } |
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 | 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 | 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 | virtual llvm::VersionTuple GetMinimumOSVersion() { |
622 | return llvm::VersionTuple(); |
623 | } |
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 | 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 | virtual bool GetIsDynamicLinkEditor() { return false; } |
641 | |
642 | // Member Functions |
643 | Type GetType() { |
644 | if (m_type == eTypeInvalid) |
645 | m_type = CalculateType(); |
646 | return m_type; |
647 | } |
648 | |
649 | Strata GetStrata() { |
650 | if (m_strata == eStrataInvalid) |
651 | m_strata = CalculateStrata(); |
652 | return m_strata; |
653 | } |
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 (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 (Section *section, |
680 | DataExtractor §ion_data); |
681 | |
682 | // Returns the section data size. This is special-cased for PECOFF |
683 | // due to file alignment. |
684 | virtual size_t GetSectionDataSize(Section *section) { |
685 | return section->GetFileSize(); |
686 | } |
687 | |
688 | /// Returns true if the object file exists only in memory. |
689 | 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 | StripLinkerSymbolAnnotations(llvm::StringRef symbol_name) const { |
694 | return symbol_name; |
695 | } |
696 | |
697 | /// Can we trust the address ranges accelerator associated with this object |
698 | /// file to be complete. |
699 | 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 | virtual bool LoadCoreFileImages(lldb_private::Process &process) { |
731 | return false; |
732 | } |
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 |
810 | |