1//===-- Module.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_CORE_MODULE_H
10#define LLDB_CORE_MODULE_H
11
12#include "lldb/Core/Address.h"
13#include "lldb/Core/ModuleList.h"
14#include "lldb/Core/ModuleSpec.h"
15#include "lldb/Symbol/ObjectFile.h"
16#include "lldb/Symbol/SymbolContextScope.h"
17#include "lldb/Symbol/TypeSystem.h"
18#include "lldb/Target/PathMappingList.h"
19#include "lldb/Target/Statistics.h"
20#include "lldb/Utility/ArchSpec.h"
21#include "lldb/Utility/ConstString.h"
22#include "lldb/Utility/FileSpec.h"
23#include "lldb/Utility/Status.h"
24#include "lldb/Utility/UUID.h"
25#include "lldb/Utility/XcodeSDK.h"
26#include "lldb/lldb-defines.h"
27#include "lldb/lldb-enumerations.h"
28#include "lldb/lldb-forward.h"
29#include "lldb/lldb-types.h"
30
31#include "llvm/ADT/DenseSet.h"
32#include "llvm/ADT/STLFunctionalExtras.h"
33#include "llvm/ADT/StringRef.h"
34#include "llvm/Support/Chrono.h"
35
36#include <atomic>
37#include <cstddef>
38#include <cstdint>
39#include <memory>
40#include <mutex>
41#include <optional>
42#include <string>
43#include <vector>
44
45namespace lldb_private {
46class CompilerDeclContext;
47class Function;
48class Log;
49class ObjectFile;
50class RegularExpression;
51class SectionList;
52class Stream;
53class Symbol;
54class SymbolContext;
55class SymbolContextList;
56class SymbolFile;
57class Symtab;
58class Target;
59class TypeList;
60class TypeMap;
61class VariableList;
62
63/// Options used by Module::FindFunctions. This cannot be a nested class
64/// because it must be forward-declared in ModuleList.h.
65struct ModuleFunctionSearchOptions {
66 /// Include the symbol table.
67 bool include_symbols = false;
68 /// Include inlined functions.
69 bool include_inlines = false;
70};
71
72/// \class Module Module.h "lldb/Core/Module.h"
73/// A class that describes an executable image and its associated
74/// object and symbol files.
75///
76/// The module is designed to be able to select a single slice of an
77/// executable image as it would appear on disk and during program execution.
78///
79/// Modules control when and if information is parsed according to which
80/// accessors are called. For example the object file (ObjectFile)
81/// representation will only be parsed if the object file is requested using
82/// the Module::GetObjectFile() is called. The debug symbols will only be
83/// parsed if the symbol file (SymbolFile) is requested using the
84/// Module::GetSymbolFile() method.
85///
86/// The module will parse more detailed information as more queries are made.
87class Module : public std::enable_shared_from_this<Module>,
88 public SymbolContextScope {
89public:
90 class LookupInfo;
91 // Static functions that can track the lifetime of module objects. This is
92 // handy because we might have Module objects that are in shared pointers
93 // that aren't in the global module list (from ModuleList). If this is the
94 // case we need to know about it. The modules in the global list maintained
95 // by these functions can be viewed using the "target modules list" command
96 // using the "--global" (-g for short).
97 static size_t GetNumberAllocatedModules();
98
99 static Module *GetAllocatedModuleAtIndex(size_t idx);
100
101 static std::recursive_mutex &GetAllocationModuleCollectionMutex();
102
103 /// Construct with file specification and architecture.
104 ///
105 /// Clients that wish to share modules with other targets should use
106 /// ModuleList::GetSharedModule().
107 ///
108 /// \param[in] file_spec
109 /// The file specification for the on disk representation of
110 /// this executable image.
111 ///
112 /// \param[in] arch
113 /// The architecture to set as the current architecture in
114 /// this module.
115 ///
116 /// \param[in] object_name
117 /// The name of an object in a module used to extract a module
118 /// within a module (.a files and modules that contain multiple
119 /// architectures).
120 ///
121 /// \param[in] object_offset
122 /// The offset within an existing module used to extract a
123 /// module within a module (.a files and modules that contain
124 /// multiple architectures).
125 Module(
126 const FileSpec &file_spec, const ArchSpec &arch,
127 ConstString object_name = ConstString(), lldb::offset_t object_offset = 0,
128 const llvm::sys::TimePoint<> &object_mod_time = llvm::sys::TimePoint<>());
129
130 Module(const ModuleSpec &module_spec);
131
132 template <typename ObjFilePlugin, typename... Args>
133 static lldb::ModuleSP CreateModuleFromObjectFile(Args &&...args) {
134 // Must create a module and place it into a shared pointer before we can
135 // create an object file since it has a std::weak_ptr back to the module,
136 // so we need to control the creation carefully in this static function
137 lldb::ModuleSP module_sp(new Module());
138 module_sp->m_objfile_sp =
139 std::make_shared<ObjFilePlugin>(module_sp, std::forward<Args>(args)...);
140 module_sp->m_did_load_objfile.store(i: true, m: std::memory_order_relaxed);
141
142 // Once we get the object file, set module ArchSpec to the one we get from
143 // the object file. If the object file does not have an architecture, we
144 // consider the creation a failure.
145 ArchSpec arch = module_sp->m_objfile_sp->GetArchitecture();
146 if (!arch)
147 return nullptr;
148 module_sp->m_arch = arch;
149
150 // Also copy the object file's FileSpec.
151 module_sp->m_file = module_sp->m_objfile_sp->GetFileSpec();
152 return module_sp;
153 }
154
155 /// Destructor.
156 ~Module() override;
157
158 bool MatchesModuleSpec(const ModuleSpec &module_ref);
159
160 /// Set the load address for all sections in a module to be the file address
161 /// plus \a slide.
162 ///
163 /// Many times a module will be loaded in a target with a constant offset
164 /// applied to all top level sections. This function can set the load
165 /// address for all top level sections to be the section file address +
166 /// offset.
167 ///
168 /// \param[in] target
169 /// The target in which to apply the section load addresses.
170 ///
171 /// \param[in] value
172 /// if \a value_is_offset is true, then value is the offset to
173 /// apply to all file addresses for all top level sections in
174 /// the object file as each section load address is being set.
175 /// If \a value_is_offset is false, then "value" is the new
176 /// absolute base address for the image.
177 ///
178 /// \param[in] value_is_offset
179 /// If \b true, then \a value is an offset to apply to each
180 /// file address of each top level section.
181 /// If \b false, then \a value is the image base address that
182 /// will be used to rigidly slide all loadable sections.
183 ///
184 /// \param[out] changed
185 /// If any section load addresses were changed in \a target,
186 /// then \a changed will be set to \b true. Else \a changed
187 /// will be set to false. This allows this function to be
188 /// called multiple times on the same module for the same
189 /// target. If the module hasn't moved, then \a changed will
190 /// be false and no module updated notification will need to
191 /// be sent out.
192 ///
193 /// \return
194 /// /b True if any sections were successfully loaded in \a target,
195 /// /b false otherwise.
196 bool SetLoadAddress(Target &target, lldb::addr_t value, bool value_is_offset,
197 bool &changed);
198
199 /// \copydoc SymbolContextScope::CalculateSymbolContext(SymbolContext*)
200 ///
201 /// \see SymbolContextScope
202 void CalculateSymbolContext(SymbolContext *sc) override;
203
204 lldb::ModuleSP CalculateSymbolContextModule() override;
205
206 void
207 GetDescription(llvm::raw_ostream &s,
208 lldb::DescriptionLevel level = lldb::eDescriptionLevelFull);
209
210 /// Get the module path and object name.
211 ///
212 /// Modules can refer to object files. In this case the specification is
213 /// simple and would return the path to the file:
214 ///
215 /// "/usr/lib/foo.dylib"
216 ///
217 /// Modules can be .o files inside of a BSD archive (.a file). In this case,
218 /// the object specification will look like:
219 ///
220 /// "/usr/lib/foo.a(bar.o)"
221 ///
222 /// There are many places where logging wants to log this fully qualified
223 /// specification, so we centralize this functionality here.
224 ///
225 /// \return
226 /// The object path + object name if there is one.
227 std::string GetSpecificationDescription() const;
228
229 /// Dump a description of this object to a Stream.
230 ///
231 /// Dump a description of the contents of this object to the supplied stream
232 /// \a s. The dumped content will be only what has been loaded or parsed up
233 /// to this point at which this function is called, so this is a good way to
234 /// see what has been parsed in a module.
235 ///
236 /// \param[in] s
237 /// The stream to which to dump the object description.
238 void Dump(Stream *s);
239
240 /// \copydoc SymbolContextScope::DumpSymbolContext(Stream*)
241 ///
242 /// \see SymbolContextScope
243 void DumpSymbolContext(Stream *s) override;
244
245 /// Find a symbol in the object file's symbol table.
246 ///
247 /// \param[in] name
248 /// The name of the symbol that we are looking for.
249 ///
250 /// \param[in] symbol_type
251 /// If set to eSymbolTypeAny, find a symbol of any type that
252 /// has a name that matches \a name. If set to any other valid
253 /// SymbolType enumeration value, then search only for
254 /// symbols that match \a symbol_type.
255 ///
256 /// \return
257 /// Returns a valid symbol pointer if a symbol was found,
258 /// nullptr otherwise.
259 const Symbol *FindFirstSymbolWithNameAndType(
260 ConstString name, lldb::SymbolType symbol_type = lldb::eSymbolTypeAny);
261
262 void FindSymbolsWithNameAndType(ConstString name,
263 lldb::SymbolType symbol_type,
264 SymbolContextList &sc_list);
265
266 void FindSymbolsMatchingRegExAndType(
267 const RegularExpression &regex, lldb::SymbolType symbol_type,
268 SymbolContextList &sc_list,
269 Mangled::NamePreference mangling_preference = Mangled::ePreferDemangled);
270
271 /// Find a function symbols in the object file's symbol table.
272 ///
273 /// \param[in] name
274 /// The name of the symbol that we are looking for.
275 ///
276 /// \param[in] name_type_mask
277 /// A mask that has one or more bitwise OR'ed values from the
278 /// lldb::FunctionNameType enumeration type that indicate what
279 /// kind of names we are looking for.
280 ///
281 /// \param[out] sc_list
282 /// A list to append any matching symbol contexts to.
283 void FindFunctionSymbols(ConstString name, uint32_t name_type_mask,
284 SymbolContextList &sc_list);
285
286 /// Find compile units by partial or full path.
287 ///
288 /// Finds all compile units that match \a path in all of the modules and
289 /// returns the results in \a sc_list.
290 ///
291 /// \param[in] path
292 /// The name of the function we are looking for.
293 ///
294 /// \param[out] sc_list
295 /// A symbol context list that gets filled in with all of the
296 /// matches.
297 void FindCompileUnits(const FileSpec &path, SymbolContextList &sc_list);
298
299 /// Find functions by lookup info.
300 ///
301 /// If the function is an inlined function, it will have a block,
302 /// representing the inlined function, and the function will be the
303 /// containing function. If it is not inlined, then the block will be NULL.
304 ///
305 /// \param[in] lookup_info
306 /// The lookup info of the function we are looking for.
307 ///
308 /// \param[out] sc_list
309 /// A symbol context list that gets filled in with all of the
310 /// matches.
311 void FindFunctions(const LookupInfo &lookup_info,
312 const CompilerDeclContext &parent_decl_ctx,
313 const ModuleFunctionSearchOptions &options,
314 SymbolContextList &sc_list);
315
316 /// Find functions by name.
317 ///
318 /// If the function is an inlined function, it will have a block,
319 /// representing the inlined function, and the function will be the
320 /// containing function. If it is not inlined, then the block will be NULL.
321 ///
322 /// \param[in] name
323 /// The name of the function we are looking for.
324 ///
325 /// \param[in] name_type_mask
326 /// A bit mask of bits that indicate what kind of names should
327 /// be used when doing the lookup. Bits include fully qualified
328 /// names, base names, C++ methods, or ObjC selectors.
329 /// See FunctionNameType for more details.
330 ///
331 /// \param[out] sc_list
332 /// A symbol context list that gets filled in with all of the
333 /// matches.
334 void FindFunctions(ConstString name,
335 const CompilerDeclContext &parent_decl_ctx,
336 lldb::FunctionNameType name_type_mask,
337 const ModuleFunctionSearchOptions &options,
338 SymbolContextList &sc_list);
339
340 /// Find functions by compiler context.
341 void FindFunctions(llvm::ArrayRef<CompilerContext> compiler_ctx,
342 lldb::FunctionNameType name_type_mask,
343 const ModuleFunctionSearchOptions &options,
344 SymbolContextList &sc_list);
345
346 /// Find functions by name.
347 ///
348 /// If the function is an inlined function, it will have a block,
349 /// representing the inlined function, and the function will be the
350 /// containing function. If it is not inlined, then the block will be NULL.
351 ///
352 /// \param[in] regex
353 /// A regular expression to use when matching the name.
354 ///
355 /// \param[out] sc_list
356 /// A symbol context list that gets filled in with all of the
357 /// matches.
358 void FindFunctions(const RegularExpression &regex,
359 const ModuleFunctionSearchOptions &options,
360 SymbolContextList &sc_list);
361
362 /// Find addresses by file/line
363 ///
364 /// \param[in] target_sp
365 /// The target the addresses are desired for.
366 ///
367 /// \param[in] file
368 /// Source file to locate.
369 ///
370 /// \param[in] line
371 /// Source line to locate.
372 ///
373 /// \param[in] function
374 /// Optional filter function. Addresses within this function will be
375 /// added to the 'local' list. All others will be added to the 'extern'
376 /// list.
377 ///
378 /// \param[out] output_local
379 /// All matching addresses within 'function'
380 ///
381 /// \param[out] output_extern
382 /// All matching addresses not within 'function'
383 void FindAddressesForLine(const lldb::TargetSP target_sp,
384 const FileSpec &file, uint32_t line,
385 Function *function,
386 std::vector<Address> &output_local,
387 std::vector<Address> &output_extern);
388
389 /// Find global and static variables by name.
390 ///
391 /// \param[in] name
392 /// The name of the global or static variable we are looking
393 /// for.
394 ///
395 /// \param[in] parent_decl_ctx
396 /// If valid, a decl context that results must exist within
397 ///
398 /// \param[in] max_matches
399 /// Allow the number of matches to be limited to \a
400 /// max_matches. Specify UINT32_MAX to get all possible matches.
401 ///
402 /// \param[in] variable_list
403 /// A list of variables that gets the matches appended to.
404 ///
405 void FindGlobalVariables(ConstString name,
406 const CompilerDeclContext &parent_decl_ctx,
407 size_t max_matches, VariableList &variable_list);
408
409 /// Find global and static variables by regular expression.
410 ///
411 /// \param[in] regex
412 /// A regular expression to use when matching the name.
413 ///
414 /// \param[in] max_matches
415 /// Allow the number of matches to be limited to \a
416 /// max_matches. Specify UINT32_MAX to get all possible matches.
417 ///
418 /// \param[in] variable_list
419 /// A list of variables that gets the matches appended to.
420 ///
421 void FindGlobalVariables(const RegularExpression &regex, size_t max_matches,
422 VariableList &variable_list);
423
424 /// Find types using a type-matching object that contains all search
425 /// parameters.
426 ///
427 /// \see lldb_private::TypeQuery
428 ///
429 /// \param[in] query
430 /// A type matching object that contains all of the details of the type
431 /// search.
432 ///
433 /// \param[in] results
434 /// Any matching types will be populated into the \a results object using
435 /// TypeMap::InsertUnique(...).
436 void FindTypes(const TypeQuery &query, TypeResults &results);
437
438 /// Get const accessor for the module architecture.
439 ///
440 /// \return
441 /// A const reference to the architecture object.
442 const ArchSpec &GetArchitecture() const;
443
444 /// Get const accessor for the module file specification.
445 ///
446 /// This function returns the file for the module on the host system that is
447 /// running LLDB. This can differ from the path on the platform since we
448 /// might be doing remote debugging.
449 ///
450 /// \return
451 /// A const reference to the file specification object.
452 const FileSpec &GetFileSpec() const { return m_file; }
453
454 /// Get accessor for the module platform file specification.
455 ///
456 /// Platform file refers to the path of the module as it is known on the
457 /// remote system on which it is being debugged. For local debugging this is
458 /// always the same as Module::GetFileSpec(). But remote debugging might
459 /// mention a file "/usr/lib/liba.dylib" which might be locally downloaded
460 /// and cached. In this case the platform file could be something like:
461 /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" The
462 /// file could also be cached in a local developer kit directory.
463 ///
464 /// \return
465 /// A const reference to the file specification object.
466 const FileSpec &GetPlatformFileSpec() const {
467 if (m_platform_file)
468 return m_platform_file;
469 return m_file;
470 }
471
472 void SetPlatformFileSpec(const FileSpec &file) { m_platform_file = file; }
473
474 const FileSpec &GetRemoteInstallFileSpec() const {
475 return m_remote_install_file;
476 }
477
478 void SetRemoteInstallFileSpec(const FileSpec &file) {
479 m_remote_install_file = file;
480 }
481
482 const FileSpec &GetSymbolFileFileSpec() const { return m_symfile_spec; }
483
484 void PreloadSymbols();
485
486 void SetSymbolFileFileSpec(const FileSpec &file);
487
488 const llvm::sys::TimePoint<> &GetModificationTime() const {
489 return m_mod_time;
490 }
491
492 const llvm::sys::TimePoint<> &GetObjectModificationTime() const {
493 return m_object_mod_time;
494 }
495
496 /// This callback will be called by SymbolFile implementations when
497 /// parsing a compile unit that contains SDK information.
498 /// \param sysroot will be added to the path remapping dictionary.
499 void RegisterXcodeSDK(llvm::StringRef sdk, llvm::StringRef sysroot);
500
501 /// Tells whether this module is capable of being the main executable for a
502 /// process.
503 ///
504 /// \return
505 /// \b true if it is, \b false otherwise.
506 bool IsExecutable();
507
508 /// Tells whether this module has been loaded in the target passed in. This
509 /// call doesn't distinguish between whether the module is loaded by the
510 /// dynamic loader, or by a "target module add" type call.
511 ///
512 /// \param[in] target
513 /// The target to check whether this is loaded in.
514 ///
515 /// \return
516 /// \b true if it is, \b false otherwise.
517 bool IsLoadedInTarget(Target *target);
518
519 bool LoadScriptingResourceInTarget(Target *target, Status &error,
520 Stream &feedback_stream);
521
522 /// Get the number of compile units for this module.
523 ///
524 /// \return
525 /// The number of compile units that the symbol vendor plug-in
526 /// finds.
527 size_t GetNumCompileUnits();
528
529 lldb::CompUnitSP GetCompileUnitAtIndex(size_t idx);
530
531 ConstString GetObjectName() const;
532
533 uint64_t GetObjectOffset() const { return m_object_offset; }
534
535 /// Get the object file representation for the current architecture.
536 ///
537 /// If the object file has not been located or parsed yet, this function
538 /// will find the best ObjectFile plug-in that can parse Module::m_file.
539 ///
540 /// \return
541 /// If Module::m_file does not exist, or no plug-in was found
542 /// that can parse the file, or the object file doesn't contain
543 /// the current architecture in Module::m_arch, nullptr will be
544 /// returned, else a valid object file interface will be
545 /// returned. The returned pointer is owned by this object and
546 /// remains valid as long as the object is around.
547 virtual ObjectFile *GetObjectFile();
548
549 /// Get the unified section list for the module. This is the section list
550 /// created by the module's object file and any debug info and symbol files
551 /// created by the symbol vendor.
552 ///
553 /// If the symbol vendor has not been loaded yet, this function will return
554 /// the section list for the object file.
555 ///
556 /// \return
557 /// Unified module section list.
558 virtual SectionList *GetSectionList();
559
560 /// Notify the module that the file addresses for the Sections have been
561 /// updated.
562 ///
563 /// If the Section file addresses for a module are updated, this method
564 /// should be called. Any parts of the module, object file, or symbol file
565 /// that has cached those file addresses must invalidate or update its
566 /// cache.
567 virtual void SectionFileAddressesChanged();
568
569 /// Returns a reference to the UnwindTable for this Module
570 ///
571 /// The UnwindTable contains FuncUnwinders objects for any function in this
572 /// Module. If a FuncUnwinders object hasn't been created yet (i.e. the
573 /// function has yet to be unwound in a stack walk), it will be created when
574 /// requested. Specifically, we do not create FuncUnwinders objects for
575 /// functions until they are needed.
576 ///
577 /// \return
578 /// Returns the unwind table for this module. If this object has no
579 /// associated object file, an empty UnwindTable is returned.
580 UnwindTable &GetUnwindTable();
581
582 llvm::VersionTuple GetVersion();
583
584 /// Load an object file from memory.
585 ///
586 /// If available, the size of the object file in memory may be passed to
587 /// avoid additional round trips to process memory. If the size is not
588 /// provided, a default value is used. This value should be large enough to
589 /// enable the ObjectFile plugins to read the header of the object file
590 /// without going back to the process.
591 ///
592 /// \return
593 /// The object file loaded from memory or nullptr, if the operation
594 /// failed (see the `error` for more information in that case).
595 ObjectFile *GetMemoryObjectFile(const lldb::ProcessSP &process_sp,
596 lldb::addr_t header_addr, Status &error,
597 size_t size_to_read = 512);
598
599 /// Get the module's symbol file
600 ///
601 /// If the symbol file has already been loaded, this function returns it. All
602 /// arguments are ignored. If the symbol file has not been located yet, and
603 /// the can_create argument is false, the function returns nullptr. If
604 /// can_create is true, this function will find the best SymbolFile plug-in
605 /// that can use the current object file. feedback_strm, if not null, is used
606 /// to report the details of the search process.
607 virtual SymbolFile *GetSymbolFile(bool can_create = true,
608 Stream *feedback_strm = nullptr);
609
610 Symtab *GetSymtab();
611
612 /// Get a reference to the UUID value contained in this object.
613 ///
614 /// If the executable image file doesn't not have a UUID value built into
615 /// the file format, an MD5 checksum of the entire file, or slice of the
616 /// file for the current architecture should be used.
617 ///
618 /// \return
619 /// A const pointer to the internal copy of the UUID value in
620 /// this module if this module has a valid UUID value, NULL
621 /// otherwise.
622 const lldb_private::UUID &GetUUID();
623
624 /// A debugging function that will cause everything in a module to
625 /// be parsed.
626 ///
627 /// All compile units will be parsed, along with all globals and static
628 /// variables and all functions for those compile units. All types, scopes,
629 /// local variables, static variables, global variables, and line tables
630 /// will be parsed. This can be used prior to dumping a module to see a
631 /// complete list of the resulting debug information that gets parsed, or as
632 /// a debug function to ensure that the module can consume all of the debug
633 /// data the symbol vendor provides.
634 void ParseAllDebugSymbols();
635
636 bool ResolveFileAddress(lldb::addr_t vm_addr, Address &so_addr);
637
638 /// Resolve the symbol context for the given address.
639 ///
640 /// Tries to resolve the matching symbol context based on a lookup from the
641 /// current symbol vendor. If the lazy lookup fails, an attempt is made to
642 /// parse the eh_frame section to handle stripped symbols. If this fails,
643 /// an attempt is made to resolve the symbol to the previous address to
644 /// handle the case of a function with a tail call.
645 ///
646 /// Use properties of the modified SymbolContext to inspect any resolved
647 /// target, module, compilation unit, symbol, function, function block or
648 /// line entry. Use the return value to determine which of these properties
649 /// have been modified.
650 ///
651 /// \param[in] so_addr
652 /// A load address to resolve.
653 ///
654 /// \param[in] resolve_scope
655 /// The scope that should be resolved (see SymbolContext::Scope).
656 /// A combination of flags from the enumeration SymbolContextItem
657 /// requesting a resolution depth. Note that the flags that are
658 /// actually resolved may be a superset of the requested flags.
659 /// For instance, eSymbolContextSymbol requires resolution of
660 /// eSymbolContextModule, and eSymbolContextFunction requires
661 /// eSymbolContextSymbol.
662 ///
663 /// \param[out] sc
664 /// The SymbolContext that is modified based on symbol resolution.
665 ///
666 /// \param[in] resolve_tail_call_address
667 /// Determines if so_addr should resolve to a symbol in the case
668 /// of a function whose last instruction is a call. In this case,
669 /// the PC can be one past the address range of the function.
670 ///
671 /// \return
672 /// The scope that has been resolved (see SymbolContext::Scope).
673 ///
674 /// \see SymbolContext::Scope
675 uint32_t ResolveSymbolContextForAddress(
676 const Address &so_addr, lldb::SymbolContextItem resolve_scope,
677 SymbolContext &sc, bool resolve_tail_call_address = false);
678
679 /// Resolve items in the symbol context for a given file and line.
680 ///
681 /// Tries to resolve \a file_path and \a line to a list of matching symbol
682 /// contexts.
683 ///
684 /// The line table entries contains addresses that can be used to further
685 /// resolve the values in each match: the function, block, symbol. Care
686 /// should be taken to minimize the amount of information that is requested
687 /// to only what is needed -- typically the module, compile unit, line table
688 /// and line table entry are sufficient.
689 ///
690 /// \param[in] file_path
691 /// A path to a source file to match. If \a file_path does not
692 /// specify a directory, then this query will match all files
693 /// whose base filename matches. If \a file_path does specify
694 /// a directory, the fullpath to the file must match.
695 ///
696 /// \param[in] line
697 /// The source line to match, or zero if just the compile unit
698 /// should be resolved.
699 ///
700 /// \param[in] check_inlines
701 /// Check for inline file and line number matches. This option
702 /// should be used sparingly as it will cause all line tables
703 /// for every compile unit to be parsed and searched for
704 /// matching inline file entries.
705 ///
706 /// \param[in] resolve_scope
707 /// The scope that should be resolved (see
708 /// SymbolContext::Scope).
709 ///
710 /// \param[out] sc_list
711 /// A symbol context list that gets matching symbols contexts
712 /// appended to.
713 ///
714 /// \return
715 /// The number of matches that were added to \a sc_list.
716 ///
717 /// \see SymbolContext::Scope
718 uint32_t ResolveSymbolContextForFilePath(
719 const char *file_path, uint32_t line, bool check_inlines,
720 lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list);
721
722 /// Resolve items in the symbol context for a given file and line.
723 ///
724 /// Tries to resolve \a file_spec and \a line to a list of matching symbol
725 /// contexts.
726 ///
727 /// The line table entries contains addresses that can be used to further
728 /// resolve the values in each match: the function, block, symbol. Care
729 /// should be taken to minimize the amount of information that is requested
730 /// to only what is needed -- typically the module, compile unit, line table
731 /// and line table entry are sufficient.
732 ///
733 /// \param[in] file_spec
734 /// A file spec to a source file to match. If \a file_path does
735 /// not specify a directory, then this query will match all
736 /// files whose base filename matches. If \a file_path does
737 /// specify a directory, the fullpath to the file must match.
738 ///
739 /// \param[in] line
740 /// The source line to match, or zero if just the compile unit
741 /// should be resolved.
742 ///
743 /// \param[in] check_inlines
744 /// Check for inline file and line number matches. This option
745 /// should be used sparingly as it will cause all line tables
746 /// for every compile unit to be parsed and searched for
747 /// matching inline file entries.
748 ///
749 /// \param[in] resolve_scope
750 /// The scope that should be resolved (see
751 /// SymbolContext::Scope).
752 ///
753 /// \param[out] sc_list
754 /// A symbol context list that gets filled in with all of the
755 /// matches.
756 ///
757 /// \return
758 /// A integer that contains SymbolContext::Scope bits set for
759 /// each item that was successfully resolved.
760 ///
761 /// \see SymbolContext::Scope
762 uint32_t ResolveSymbolContextsForFileSpec(
763 const FileSpec &file_spec, uint32_t line, bool check_inlines,
764 lldb::SymbolContextItem resolve_scope, SymbolContextList &sc_list);
765
766 void SetFileSpecAndObjectName(const FileSpec &file, ConstString object_name);
767
768 bool GetIsDynamicLinkEditor();
769
770 llvm::Expected<lldb::TypeSystemSP>
771 GetTypeSystemForLanguage(lldb::LanguageType language);
772
773 /// Call \p callback for each \p TypeSystem in this \p Module.
774 /// Return true from callback to keep iterating, false to stop iterating.
775 void ForEachTypeSystem(llvm::function_ref<bool(lldb::TypeSystemSP)> callback);
776
777 // Special error functions that can do printf style formatting that will
778 // prepend the message with something appropriate for this module (like the
779 // architecture, path and object name (if any)). This centralizes code so
780 // that everyone doesn't need to format their error and log messages on their
781 // own and keeps the output a bit more consistent.
782 template <typename... Args>
783 void LogMessage(Log *log, const char *format, Args &&...args) {
784 LogMessage(log, llvm::formatv(format, std::forward<Args>(args)...));
785 }
786
787 template <typename... Args>
788 void LogMessageVerboseBacktrace(Log *log, const char *format,
789 Args &&...args) {
790 LogMessageVerboseBacktrace(
791 log, llvm::formatv(format, std::forward<Args>(args)...));
792 }
793
794 template <typename... Args>
795 void ReportWarning(const char *format, Args &&...args) {
796 ReportWarning(llvm::formatv(format, std::forward<Args>(args)...));
797 }
798
799 template <typename... Args>
800 void ReportError(const char *format, Args &&...args) {
801 ReportError(llvm::formatv(format, std::forward<Args>(args)...));
802 }
803
804 // Only report an error once when the module is first detected to be modified
805 // so we don't spam the console with many messages.
806 template <typename... Args>
807 void ReportErrorIfModifyDetected(const char *format, Args &&...args) {
808 ReportErrorIfModifyDetected(
809 llvm::formatv(format, std::forward<Args>(args)...));
810 }
811
812 void ReportWarningOptimization(std::optional<lldb::user_id_t> debugger_id);
813
814 void
815 ReportWarningUnsupportedLanguage(lldb::LanguageType language,
816 std::optional<lldb::user_id_t> debugger_id);
817
818 // Return true if the file backing this module has changed since the module
819 // was originally created since we saved the initial file modification time
820 // when the module first gets created.
821 bool FileHasChanged() const;
822
823 // SymbolFile and ObjectFile member objects should lock the
824 // module mutex to avoid deadlocks.
825 std::recursive_mutex &GetMutex() const { return m_mutex; }
826
827 PathMappingList &GetSourceMappingList() { return m_source_mappings; }
828
829 const PathMappingList &GetSourceMappingList() const {
830 return m_source_mappings;
831 }
832
833 /// Finds a source file given a file spec using the module source path
834 /// remappings (if any).
835 ///
836 /// Tries to resolve \a orig_spec by checking the module source path
837 /// remappings. It makes sure the file exists, so this call can be expensive
838 /// if the remappings are on a network file system, so use this function
839 /// sparingly (not in a tight debug info parsing loop).
840 ///
841 /// \param[in] orig_spec
842 /// The original source file path to try and remap.
843 ///
844 /// \param[out] new_spec
845 /// The newly remapped filespec that is guaranteed to exist.
846 ///
847 /// \return
848 /// /b true if \a orig_spec was successfully located and
849 /// \a new_spec is filled in with an existing file spec,
850 /// \b false otherwise.
851 bool FindSourceFile(const FileSpec &orig_spec, FileSpec &new_spec) const;
852
853 /// Remaps a source file given \a path into \a new_path.
854 ///
855 /// Remaps \a path if any source remappings match. This function does NOT
856 /// stat the file system so it can be used in tight loops where debug info
857 /// is being parsed.
858 ///
859 /// \param[in] path
860 /// The original source file path to try and remap.
861 ///
862 /// \return
863 /// The newly remapped filespec that is may or may not exist if
864 /// \a path was successfully located.
865 std::optional<std::string> RemapSourceFile(llvm::StringRef path) const;
866 bool RemapSourceFile(const char *, std::string &) const = delete;
867
868 /// Update the ArchSpec to a more specific variant.
869 bool MergeArchitecture(const ArchSpec &arch_spec);
870
871 /// Accessor for the symbol table parse time metric.
872 ///
873 /// The value is returned as a reference to allow it to be updated by the
874 /// ElapsedTime RAII object.
875 StatsDuration &GetSymtabParseTime() { return m_symtab_parse_time; }
876
877 /// Accessor for the symbol table index time metric.
878 ///
879 /// The value is returned as a reference to allow it to be updated by the
880 /// ElapsedTime RAII object.
881 StatsDuration &GetSymtabIndexTime() { return m_symtab_index_time; }
882
883 /// \class LookupInfo Module.h "lldb/Core/Module.h"
884 /// A class that encapsulates name lookup information.
885 ///
886 /// Users can type a wide variety of partial names when setting breakpoints
887 /// by name or when looking for functions by name. The SymbolFile object is
888 /// only required to implement name lookup for function basenames and for
889 /// fully mangled names. This means if the user types in a partial name, we
890 /// must reduce this to a name lookup that will work with all SymbolFile
891 /// objects. So we might reduce a name lookup to look for a basename, and then
892 /// prune out any results that don't match.
893 ///
894 /// The "m_name" member variable represents the name as it was typed by the
895 /// user. "m_lookup_name" will be the name we actually search for through
896 /// the symbol or objects files. Lanaguage is included in case we need to
897 /// filter results by language at a later date. The "m_name_type_mask"
898 /// member variable tells us what kinds of names we are looking for and can
899 /// help us prune out unwanted results.
900 ///
901 /// Function lookups are done in Module.cpp, ModuleList.cpp and in
902 /// BreakpointResolverName.cpp and they all now use this class to do lookups
903 /// correctly.
904 class LookupInfo {
905 public:
906 LookupInfo() = default;
907
908 LookupInfo(ConstString name, lldb::FunctionNameType name_type_mask,
909 lldb::LanguageType language);
910
911 ConstString GetName() const { return m_name; }
912
913 void SetName(ConstString name) { m_name = name; }
914
915 ConstString GetLookupName() const { return m_lookup_name; }
916
917 void SetLookupName(ConstString name) { m_lookup_name = name; }
918
919 lldb::FunctionNameType GetNameTypeMask() const { return m_name_type_mask; }
920
921 void SetNameTypeMask(lldb::FunctionNameType mask) {
922 m_name_type_mask = mask;
923 }
924
925 lldb::LanguageType GetLanguageType() const { return m_language; }
926
927 bool NameMatchesLookupInfo(
928 ConstString function_name,
929 lldb::LanguageType language_type = lldb::eLanguageTypeUnknown) const;
930
931 void Prune(SymbolContextList &sc_list, size_t start_idx) const;
932
933 protected:
934 /// What the user originally typed
935 ConstString m_name;
936
937 /// The actual name will lookup when calling in the object or symbol file
938 ConstString m_lookup_name;
939
940 /// Limit matches to only be for this language
941 lldb::LanguageType m_language = lldb::eLanguageTypeUnknown;
942
943 /// One or more bits from lldb::FunctionNameType that indicate what kind of
944 /// names we are looking for
945 lldb::FunctionNameType m_name_type_mask = lldb::eFunctionNameTypeNone;
946
947 ///< If \b true, then demangled names that match will need to contain
948 ///< "m_name" in order to be considered a match
949 bool m_match_name_after_lookup = false;
950 };
951
952 /// Get a unique hash for this module.
953 ///
954 /// The hash should be enough to identify the file on disk and the
955 /// architecture of the file. If the module represents an object inside of a
956 /// file, then the hash should include the object name and object offset to
957 /// ensure a unique hash. Some examples:
958 /// - just a regular object file (mach-o, elf, coff, etc) should create a hash
959 /// - a universal mach-o file that contains to multiple architectures,
960 /// each architecture slice should have a unique hash even though they come
961 /// from the same file
962 /// - a .o file inside of a BSD archive. Each .o file will have an object name
963 /// and object offset that should produce a unique hash. The object offset
964 /// is needed as BSD archive files can contain multiple .o files that have
965 /// the same name.
966 uint32_t Hash();
967
968 /// Get a unique cache key for the current module.
969 ///
970 /// The cache key must be unique for a file on disk and not change if the file
971 /// is updated. This allows cache data to use this key as a prefix and as
972 /// files are modified in disk, we will overwrite the cache files. If one file
973 /// can contain multiple files, like a universal mach-o file or like a BSD
974 /// archive, the cache key must contain enough information to differentiate
975 /// these different files.
976 std::string GetCacheKey();
977
978 /// Get the global index file cache.
979 ///
980 /// LLDB can cache data for a module between runs. This cache directory can be
981 /// used to stored data that previously was manually created each time you debug.
982 /// Examples include debug information indexes, symbol tables, symbol table
983 /// indexes, and more.
984 ///
985 /// \returns
986 /// If caching is enabled in the lldb settings, return a pointer to the data
987 /// file cache. If caching is not enabled, return NULL.
988 static DataFileCache *GetIndexCache();
989protected:
990 // Member Variables
991 mutable std::recursive_mutex m_mutex; ///< A mutex to keep this object happy
992 /// in multi-threaded environments.
993
994 /// The modification time for this module when it was created.
995 llvm::sys::TimePoint<> m_mod_time;
996
997 ArchSpec m_arch; ///< The architecture for this module.
998 UUID m_uuid; ///< Each module is assumed to have a unique identifier to help
999 /// match it up to debug symbols.
1000 FileSpec m_file; ///< The file representation on disk for this module (if
1001 /// there is one).
1002 FileSpec m_platform_file; ///< The path to the module on the platform on which
1003 /// it is being debugged
1004 FileSpec m_remote_install_file; ///< If set when debugging on remote
1005 /// platforms, this module will be installed
1006 /// at this location
1007 FileSpec m_symfile_spec; ///< If this path is valid, then this is the file
1008 /// that _will_ be used as the symbol file for this
1009 /// module
1010 ConstString m_object_name; ///< The name an object within this module that is
1011 /// selected, or empty of the module is represented
1012 /// by \a m_file.
1013 uint64_t m_object_offset = 0;
1014 llvm::sys::TimePoint<> m_object_mod_time;
1015
1016 /// DataBuffer containing the module image, if it was provided at
1017 /// construction time. Otherwise the data will be retrieved by mapping
1018 /// one of the FileSpec members above.
1019 lldb::DataBufferSP m_data_sp;
1020
1021 lldb::ObjectFileSP m_objfile_sp; ///< A shared pointer to the object file
1022 /// parser for this module as it may or may
1023 /// not be shared with the SymbolFile
1024 std::optional<UnwindTable> m_unwind_table; ///< Table of FuncUnwinders
1025 /// objects created for this
1026 /// Module's functions
1027 lldb::SymbolVendorUP
1028 m_symfile_up; ///< A pointer to the symbol vendor for this module.
1029 std::vector<lldb::SymbolVendorUP>
1030 m_old_symfiles; ///< If anyone calls Module::SetSymbolFileFileSpec() and
1031 /// changes the symbol file,
1032 ///< we need to keep all old symbol files around in case anyone has type
1033 /// references to them
1034 TypeSystemMap m_type_system_map; ///< A map of any type systems associated
1035 /// with this module
1036 /// Module specific source remappings for when you have debug info for a
1037 /// module that doesn't match where the sources currently are.
1038 PathMappingList m_source_mappings =
1039 ModuleList::GetGlobalModuleListProperties().GetSymlinkMappings();
1040
1041 lldb::SectionListUP m_sections_up; ///< Unified section list for module that
1042 /// is used by the ObjectFile and
1043 /// ObjectFile instances for the debug info
1044
1045 std::atomic<bool> m_did_load_objfile{false};
1046 std::atomic<bool> m_did_load_symfile{false};
1047 std::atomic<bool> m_did_set_uuid{false};
1048 mutable bool m_file_has_changed : 1,
1049 m_first_file_changed_log : 1; /// See if the module was modified after it
1050 /// was initially opened.
1051 /// We store a symbol table parse time duration here because we might have
1052 /// an object file and a symbol file which both have symbol tables. The parse
1053 /// time for the symbol tables can be aggregated here.
1054 StatsDuration m_symtab_parse_time;
1055 /// We store a symbol named index time duration here because we might have
1056 /// an object file and a symbol file which both have symbol tables. The parse
1057 /// time for the symbol tables can be aggregated here.
1058 StatsDuration m_symtab_index_time;
1059
1060 std::once_flag m_optimization_warning;
1061 std::once_flag m_language_warning;
1062
1063 void SymbolIndicesToSymbolContextList(Symtab *symtab,
1064 std::vector<uint32_t> &symbol_indexes,
1065 SymbolContextList &sc_list);
1066
1067 bool SetArchitecture(const ArchSpec &new_arch);
1068
1069 void SetUUID(const lldb_private::UUID &uuid);
1070
1071 SectionList *GetUnifiedSectionList();
1072
1073 friend class ModuleList;
1074 friend class ObjectFile;
1075 friend class SymbolFile;
1076
1077private:
1078 Module(); // Only used internally by CreateJITModule ()
1079
1080 Module(const Module &) = delete;
1081 const Module &operator=(const Module &) = delete;
1082
1083 void LogMessage(Log *log, const llvm::formatv_object_base &payload);
1084 void LogMessageVerboseBacktrace(Log *log,
1085 const llvm::formatv_object_base &payload);
1086 void ReportWarning(const llvm::formatv_object_base &payload);
1087 void ReportError(const llvm::formatv_object_base &payload);
1088 void ReportErrorIfModifyDetected(const llvm::formatv_object_base &payload);
1089};
1090
1091} // namespace lldb_private
1092
1093#endif // LLDB_CORE_MODULE_H
1094

source code of lldb/include/lldb/Core/Module.h