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 | |
45 | namespace lldb_private { |
46 | class CompilerDeclContext; |
47 | class Function; |
48 | class Log; |
49 | class ObjectFile; |
50 | class RegularExpression; |
51 | class SectionList; |
52 | class Stream; |
53 | class Symbol; |
54 | class SymbolContext; |
55 | class SymbolContextList; |
56 | class SymbolFile; |
57 | class Symtab; |
58 | class Target; |
59 | class TypeList; |
60 | class TypeMap; |
61 | class VariableList; |
62 | |
63 | /// Options used by Module::FindFunctions. This cannot be a nested class |
64 | /// because it must be forward-declared in ModuleList.h. |
65 | struct 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. |
87 | class Module : public std::enable_shared_from_this<Module>, |
88 | public SymbolContextScope { |
89 | public: |
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 ®ex, 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 ®ex, |
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 ®ex, 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 , 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(); |
989 | protected: |
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 | |
1077 | private: |
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 | |