LLDB mainline
LocateSymbolFile.cpp
Go to the documentation of this file.
1//===-- LocateSymbolFile.cpp ----------------------------------------------===//
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
10
11#include "lldb/Core/Debugger.h"
12#include "lldb/Core/Module.h"
15#include "lldb/Core/Progress.h"
22#include "lldb/Utility/Log.h"
24#include "lldb/Utility/Timer.h"
25#include "lldb/Utility/UUID.h"
26
27#include "llvm/ADT/SmallSet.h"
28#include "llvm/Support/FileSystem.h"
29#include "llvm/Support/ThreadPool.h"
30
31// From MacOSX system header "mach/machine.h"
32typedef int cpu_type_t;
33typedef int cpu_subtype_t;
34
35using namespace lldb;
36using namespace lldb_private;
37
38#if defined(__APPLE__)
39
40// Forward declaration of method defined in source/Host/macosx/Symbols.cpp
42 ModuleSpec &return_module_spec);
43
44#else
45
47 ModuleSpec &return_module_spec) {
48 // Cannot find MacOSX files using debug symbols on non MacOSX.
49 return 0;
50}
51
52#endif
53
54static bool FileAtPathContainsArchAndUUID(const FileSpec &file_fspec,
55 const ArchSpec *arch,
56 const lldb_private::UUID *uuid) {
57 ModuleSpecList module_specs;
58 if (ObjectFile::GetModuleSpecifications(file_fspec, 0, 0, module_specs)) {
59 ModuleSpec spec;
60 for (size_t i = 0; i < module_specs.GetSize(); ++i) {
61 bool got_spec = module_specs.GetModuleSpecAtIndex(i, spec);
63 assert(got_spec);
64 if ((uuid == nullptr || (spec.GetUUIDPtr() && spec.GetUUID() == *uuid)) &&
65 (arch == nullptr ||
66 (spec.GetArchitecturePtr() &&
67 spec.GetArchitecture().IsCompatibleMatch(*arch)))) {
68 return true;
69 }
70 }
71 }
72 return false;
73}
74
75// Given a binary exec_fspec, and a ModuleSpec with an architecture/uuid,
76// return true if there is a matching dSYM bundle next to the exec_fspec,
77// and return that value in dsym_fspec.
78// If there is a .dSYM.yaa compressed archive next to the exec_fspec,
79// call through Symbols::DownloadObjectAndSymbolFile to download the
80// expanded/uncompressed dSYM and return that filepath in dsym_fspec.
81
82static bool LookForDsymNextToExecutablePath(const ModuleSpec &mod_spec,
83 const FileSpec &exec_fspec,
84 FileSpec &dsym_fspec) {
85 ConstString filename = exec_fspec.GetFilename();
86 FileSpec dsym_directory = exec_fspec;
87 dsym_directory.RemoveLastPathComponent();
88
89 std::string dsym_filename = filename.AsCString();
90 dsym_filename += ".dSYM";
91 dsym_directory.AppendPathComponent(dsym_filename);
92 dsym_directory.AppendPathComponent("Contents");
93 dsym_directory.AppendPathComponent("Resources");
94 dsym_directory.AppendPathComponent("DWARF");
95
96 if (FileSystem::Instance().Exists(dsym_directory)) {
97
98 // See if the binary name exists in the dSYM DWARF
99 // subdir.
100 dsym_fspec = dsym_directory;
101 dsym_fspec.AppendPathComponent(filename.AsCString());
102 if (FileSystem::Instance().Exists(dsym_fspec) &&
104 mod_spec.GetUUIDPtr())) {
105 return true;
106 }
107
108 // See if we have "../CF.framework" - so we'll look for
109 // CF.framework.dSYM/Contents/Resources/DWARF/CF
110 // We need to drop the last suffix after '.' to match
111 // 'CF' in the DWARF subdir.
112 std::string binary_name(filename.AsCString());
113 auto last_dot = binary_name.find_last_of('.');
114 if (last_dot != std::string::npos) {
115 binary_name.erase(last_dot);
116 dsym_fspec = dsym_directory;
117 dsym_fspec.AppendPathComponent(binary_name);
118 if (FileSystem::Instance().Exists(dsym_fspec) &&
120 mod_spec.GetArchitecturePtr(),
121 mod_spec.GetUUIDPtr())) {
122 return true;
123 }
124 }
125 }
126
127 // See if we have a .dSYM.yaa next to this executable path.
128 FileSpec dsym_yaa_fspec = exec_fspec;
129 dsym_yaa_fspec.RemoveLastPathComponent();
130 std::string dsym_yaa_filename = filename.AsCString();
131 dsym_yaa_filename += ".dSYM.yaa";
132 dsym_yaa_fspec.AppendPathComponent(dsym_yaa_filename);
133
134 if (FileSystem::Instance().Exists(dsym_yaa_fspec)) {
135 ModuleSpec mutable_mod_spec = mod_spec;
137 if (Symbols::DownloadObjectAndSymbolFile(mutable_mod_spec, error, true) &&
138 FileSystem::Instance().Exists(mutable_mod_spec.GetSymbolFileSpec())) {
139 dsym_fspec = mutable_mod_spec.GetSymbolFileSpec();
140 return true;
141 }
142 }
143
144 return false;
145}
146
147// Given a ModuleSpec with a FileSpec and optionally uuid/architecture
148// filled in, look for a .dSYM bundle next to that binary. Returns true
149// if a .dSYM bundle is found, and that path is returned in the dsym_fspec
150// FileSpec.
151//
152// This routine looks a few directory layers above the given exec_path -
153// exec_path might be /System/Library/Frameworks/CF.framework/CF and the
154// dSYM might be /System/Library/Frameworks/CF.framework.dSYM.
155//
156// If there is a .dSYM.yaa compressed archive found next to the binary,
157// we'll call DownloadObjectAndSymbolFile to expand it into a plain .dSYM
158
159static bool LocateDSYMInVincinityOfExecutable(const ModuleSpec &module_spec,
160 FileSpec &dsym_fspec) {
161 Log *log = GetLog(LLDBLog::Host);
162 const FileSpec &exec_fspec = module_spec.GetFileSpec();
163 if (exec_fspec) {
164 if (::LookForDsymNextToExecutablePath(module_spec, exec_fspec,
165 dsym_fspec)) {
166 if (log) {
167 LLDB_LOGF(log, "dSYM with matching UUID & arch found at %s",
168 dsym_fspec.GetPath().c_str());
169 }
170 return true;
171 } else {
172 FileSpec parent_dirs = exec_fspec;
173
174 // Remove the binary name from the FileSpec
175 parent_dirs.RemoveLastPathComponent();
176
177 // Add a ".dSYM" name to each directory component of the path,
178 // stripping off components. e.g. we may have a binary like
179 // /S/L/F/Foundation.framework/Versions/A/Foundation and
180 // /S/L/F/Foundation.framework.dSYM
181 //
182 // so we'll need to start with
183 // /S/L/F/Foundation.framework/Versions/A, add the .dSYM part to the
184 // "A", and if that doesn't exist, strip off the "A" and try it again
185 // with "Versions", etc., until we find a dSYM bundle or we've
186 // stripped off enough path components that there's no need to
187 // continue.
188
189 for (int i = 0; i < 4; i++) {
190 // Does this part of the path have a "." character - could it be a
191 // bundle's top level directory?
192 const char *fn = parent_dirs.GetFilename().AsCString();
193 if (fn == nullptr)
194 break;
195 if (::strchr(fn, '.') != nullptr) {
196 if (::LookForDsymNextToExecutablePath(module_spec, parent_dirs,
197 dsym_fspec)) {
198 if (log) {
199 LLDB_LOGF(log, "dSYM with matching UUID & arch found at %s",
200 dsym_fspec.GetPath().c_str());
201 }
202 return true;
203 }
204 }
205 parent_dirs.RemoveLastPathComponent();
206 }
207 }
208 }
209 dsym_fspec.Clear();
210 return false;
211}
212
214 const FileSpec *exec_fspec = module_spec.GetFileSpecPtr();
215 const ArchSpec *arch = module_spec.GetArchitecturePtr();
216 const UUID *uuid = module_spec.GetUUIDPtr();
217
219 "LocateExecutableSymbolFileDsym (file = %s, arch = %s, uuid = %p)",
220 exec_fspec ? exec_fspec->GetFilename().AsCString("<NULL>") : "<NULL>",
221 arch ? arch->GetArchitectureName() : "<NULL>", (const void *)uuid);
222
223 FileSpec symbol_fspec;
224 ModuleSpec dsym_module_spec;
225 // First try and find the dSYM in the same directory as the executable or in
226 // an appropriate parent directory
227 if (!LocateDSYMInVincinityOfExecutable(module_spec, symbol_fspec)) {
228 // We failed to easily find the dSYM above, so use DebugSymbols
229 LocateMacOSXFilesUsingDebugSymbols(module_spec, dsym_module_spec);
230 } else {
231 dsym_module_spec.GetSymbolFileSpec() = symbol_fspec;
232 }
233
234 return dsym_module_spec.GetSymbolFileSpec();
235}
236
238 ModuleSpec result;
239 const FileSpec &exec_fspec = module_spec.GetFileSpec();
240 const ArchSpec *arch = module_spec.GetArchitecturePtr();
241 const UUID *uuid = module_spec.GetUUIDPtr();
243 "LocateExecutableObjectFile (file = %s, arch = %s, uuid = %p)",
244 exec_fspec ? exec_fspec.GetFilename().AsCString("<NULL>") : "<NULL>",
245 arch ? arch->GetArchitectureName() : "<NULL>", (const void *)uuid);
246
247 ModuleSpecList module_specs;
248 ModuleSpec matched_module_spec;
249 if (exec_fspec &&
250 ObjectFile::GetModuleSpecifications(exec_fspec, 0, 0, module_specs) &&
251 module_specs.FindMatchingModuleSpec(module_spec, matched_module_spec)) {
252 result.GetFileSpec() = exec_fspec;
253 } else {
254 LocateMacOSXFilesUsingDebugSymbols(module_spec, result);
255 }
256
257 return result;
258}
259
260// Keep "symbols.enable-external-lookup" description in sync with this function.
261
264 const FileSpecList &default_search_paths) {
265 FileSpec symbol_file_spec = module_spec.GetSymbolFileSpec();
266 if (symbol_file_spec.IsAbsolute() &&
267 FileSystem::Instance().Exists(symbol_file_spec))
268 return symbol_file_spec;
269
270 Progress progress(llvm::formatv(
271 "Locating external symbol file for {0}",
272 module_spec.GetFileSpec().GetFilename().AsCString("<Unknown>")));
273
274 FileSpecList debug_file_search_paths = default_search_paths;
275
276 // Add module directory.
277 FileSpec module_file_spec = module_spec.GetFileSpec();
278 // We keep the unresolved pathname if it fails.
279 FileSystem::Instance().ResolveSymbolicLink(module_file_spec,
280 module_file_spec);
281
282 ConstString file_dir = module_file_spec.GetDirectory();
283 {
284 FileSpec file_spec(file_dir.AsCString("."));
285 FileSystem::Instance().Resolve(file_spec);
286 debug_file_search_paths.AppendIfUnique(file_spec);
287 }
288
289 if (ModuleList::GetGlobalModuleListProperties().GetEnableExternalLookup()) {
290
291 // Add current working directory.
292 {
293 FileSpec file_spec(".");
294 FileSystem::Instance().Resolve(file_spec);
295 debug_file_search_paths.AppendIfUnique(file_spec);
296 }
297
298#ifndef _WIN32
299#if defined(__NetBSD__)
300 // Add /usr/libdata/debug directory.
301 {
302 FileSpec file_spec("/usr/libdata/debug");
303 FileSystem::Instance().Resolve(file_spec);
304 debug_file_search_paths.AppendIfUnique(file_spec);
305 }
306#else
307 // Add /usr/lib/debug directory.
308 {
309 FileSpec file_spec("/usr/lib/debug");
310 FileSystem::Instance().Resolve(file_spec);
311 debug_file_search_paths.AppendIfUnique(file_spec);
312 }
313#endif
314#endif // _WIN32
315 }
316
317 std::string uuid_str;
318 const UUID &module_uuid = module_spec.GetUUID();
319 if (module_uuid.IsValid()) {
320 // Some debug files are stored in the .build-id directory like this:
321 // /usr/lib/debug/.build-id/ff/e7fe727889ad82bb153de2ad065b2189693315.debug
322 uuid_str = module_uuid.GetAsString("");
323 std::transform(uuid_str.begin(), uuid_str.end(), uuid_str.begin(),
324 ::tolower);
325 uuid_str.insert(2, 1, '/');
326 uuid_str = uuid_str + ".debug";
327 }
328
329 size_t num_directories = debug_file_search_paths.GetSize();
330 for (size_t idx = 0; idx < num_directories; ++idx) {
331 FileSpec dirspec = debug_file_search_paths.GetFileSpecAtIndex(idx);
332 FileSystem::Instance().Resolve(dirspec);
333 if (!FileSystem::Instance().IsDirectory(dirspec))
334 continue;
335
336 std::vector<std::string> files;
337 std::string dirname = dirspec.GetPath();
338
339 if (!uuid_str.empty())
340 files.push_back(dirname + "/.build-id/" + uuid_str);
341 if (symbol_file_spec.GetFilename()) {
342 files.push_back(dirname + "/" +
343 symbol_file_spec.GetFilename().GetCString());
344 files.push_back(dirname + "/.debug/" +
345 symbol_file_spec.GetFilename().GetCString());
346
347 // Some debug files may stored in the module directory like this:
348 // /usr/lib/debug/usr/lib/library.so.debug
349 if (!file_dir.IsEmpty())
350 files.push_back(dirname + file_dir.AsCString() + "/" +
351 symbol_file_spec.GetFilename().GetCString());
352 }
353
354 const uint32_t num_files = files.size();
355 for (size_t idx_file = 0; idx_file < num_files; ++idx_file) {
356 const std::string &filename = files[idx_file];
357 FileSpec file_spec(filename);
358 FileSystem::Instance().Resolve(file_spec);
359
360 if (llvm::sys::fs::equivalent(file_spec.GetPath(),
361 module_file_spec.GetPath()))
362 continue;
363
364 if (FileSystem::Instance().Exists(file_spec)) {
366 const size_t num_specs =
367 ObjectFile::GetModuleSpecifications(file_spec, 0, 0, specs);
368 ModuleSpec mspec;
369 bool valid_mspec = false;
370 if (num_specs == 2) {
371 // Special case to handle both i386 and i686 from ObjectFilePECOFF
372 ModuleSpec mspec2;
373 if (specs.GetModuleSpecAtIndex(0, mspec) &&
374 specs.GetModuleSpecAtIndex(1, mspec2) &&
375 mspec.GetArchitecture().GetTriple().isCompatibleWith(
376 mspec2.GetArchitecture().GetTriple())) {
377 valid_mspec = true;
378 }
379 }
380 if (!valid_mspec) {
381 assert(num_specs <= 1 &&
382 "Symbol Vendor supports only a single architecture");
383 if (num_specs == 1) {
384 if (specs.GetModuleSpecAtIndex(0, mspec)) {
385 valid_mspec = true;
386 }
387 }
388 }
389 if (valid_mspec) {
390 // Skip the uuids check if module_uuid is invalid. For example,
391 // this happens for *.dwp files since at the moment llvm-dwp
392 // doesn't output build ids, nor does binutils dwp.
393 if (!module_uuid.IsValid() || module_uuid == mspec.GetUUID())
394 return file_spec;
395 }
396 }
397 }
398 }
399
400 return LocateExecutableSymbolFileDsym(module_spec);
401}
402
404 if (!ModuleList::GetGlobalModuleListProperties().GetEnableBackgroundLookup())
405 return;
406
407 static llvm::SmallSet<UUID, 8> g_seen_uuids;
408 static std::mutex g_mutex;
409 Debugger::GetThreadPool().async([=]() {
410 {
411 std::lock_guard<std::mutex> guard(g_mutex);
412 if (g_seen_uuids.count(uuid))
413 return;
414 g_seen_uuids.insert(uuid);
415 }
416
418 ModuleSpec module_spec;
419 module_spec.GetUUID() = uuid;
421 /*force_lookup=*/true,
422 /*copy_executable=*/false))
423 return;
424
425 if (error.Fail())
426 return;
427
428 Debugger::ReportSymbolChange(module_spec);
429 });
430}
431
432#if !defined(__APPLE__)
433
435 const lldb_private::UUID *uuid,
436 const ArchSpec *arch) {
437 // FIXME
438 return FileSpec();
439}
440
442 Status &error, bool force_lookup,
443 bool copy_executable) {
444 // Fill in the module_spec.GetFileSpec() for the object file and/or the
445 // module_spec.GetSymbolFileSpec() for the debug symbols file.
446 return false;
447}
448
449#endif
static llvm::raw_ostream & error(Stream &strm)
int LocateMacOSXFilesUsingDebugSymbols(const ModuleSpec &module_spec, ModuleSpec &return_module_spec)
int cpu_subtype_t
int cpu_type_t
static bool LocateDSYMInVincinityOfExecutable(const ModuleSpec &module_spec, FileSpec &dsym_fspec)
static FileSpec LocateExecutableSymbolFileDsym(const ModuleSpec &module_spec)
static bool FileAtPathContainsArchAndUUID(const FileSpec &file_fspec, const ArchSpec *arch, const lldb_private::UUID *uuid)
static bool LookForDsymNextToExecutablePath(const ModuleSpec &mod_spec, const FileSpec &exec_fspec, FileSpec &dsym_fspec)
#define LLDB_LOGF(log,...)
Definition: Log.h:349
#define LLDB_SCOPED_TIMERF(...)
Definition: Timer.h:86
An architecture specification class.
Definition: ArchSpec.h:31
llvm::Triple & GetTriple()
Architecture triple accessor.
Definition: ArchSpec.h:450
bool IsCompatibleMatch(const ArchSpec &rhs) const
Shorthand for IsMatch(rhs, CompatibleMatch).
Definition: ArchSpec.h:502
const char * GetArchitectureName() const
Returns a static string representing the current architecture.
Definition: ArchSpec.cpp:552
A uniqued constant string class.
Definition: ConstString.h:40
const char * AsCString(const char *value_if_empty=nullptr) const
Get the string value as a C string.
Definition: ConstString.h:182
bool IsEmpty() const
Test for empty string.
Definition: ConstString.h:293
const char * GetCString() const
Get the string value as a C string.
Definition: ConstString.h:205
static llvm::ThreadPool & GetThreadPool()
Shared thread poll. Use only with ThreadPoolTaskGroup.
Definition: Debugger.cpp:2181
static void ReportSymbolChange(const ModuleSpec &module_spec)
Definition: Debugger.cpp:1553
A file collection class.
Definition: FileSpecList.h:24
const FileSpec & GetFileSpecAtIndex(size_t idx) const
Get file at index.
size_t GetSize() const
Get the number of files in the file list.
bool AppendIfUnique(const FileSpec &file)
Append a FileSpec object if unique.
A file utility class.
Definition: FileSpec.h:56
void AppendPathComponent(llvm::StringRef component)
Definition: FileSpec.cpp:447
const ConstString & GetFilename() const
Filename string const get accessor.
Definition: FileSpec.h:240
bool RemoveLastPathComponent()
Removes the last path component by replacing the current path with its parent.
Definition: FileSpec.cpp:458
const ConstString & GetDirectory() const
Directory string const get accessor.
Definition: FileSpec.h:223
bool IsAbsolute() const
Returns true if the filespec represents an absolute path.
Definition: FileSpec.cpp:511
size_t GetPath(char *path, size_t max_path_length, bool denormalize=true) const
Extract the full path to the file.
Definition: FileSpec.cpp:367
void Clear()
Clears the object state.
Definition: FileSpec.cpp:259
void Resolve(llvm::SmallVectorImpl< char > &path)
Resolve path to make it canonical.
Status ResolveSymbolicLink(const FileSpec &src, FileSpec &dst)
bool Exists(const FileSpec &file_spec) const
Returns whether the given file exists.
static FileSystem & Instance()
static ModuleListProperties & GetGlobalModuleListProperties()
Definition: ModuleList.cpp:751
bool GetModuleSpecAtIndex(size_t i, ModuleSpec &module_spec) const
Definition: ModuleSpec.h:323
bool FindMatchingModuleSpec(const ModuleSpec &module_spec, ModuleSpec &match_module_spec) const
Definition: ModuleSpec.h:333
FileSpec & GetFileSpec()
Definition: ModuleSpec.h:53
ArchSpec & GetArchitecture()
Definition: ModuleSpec.h:89
FileSpec * GetFileSpecPtr()
Definition: ModuleSpec.h:47
FileSpec & GetSymbolFileSpec()
Definition: ModuleSpec.h:77
ArchSpec * GetArchitecturePtr()
Definition: ModuleSpec.h:81
static size_t GetModuleSpecifications(const FileSpec &file, lldb::offset_t file_offset, lldb::offset_t file_size, ModuleSpecList &specs, lldb::DataBufferSP data_sp=lldb::DataBufferSP())
Definition: ObjectFile.cpp:187
A Progress indicator helper class.
Definition: Progress.h:56
An error handling class.
Definition: Status.h:44
static void DownloadSymbolFileAsync(const UUID &uuid)
Locate the symbol file for the given UUID on a background thread.
static FileSpec LocateExecutableSymbolFile(const ModuleSpec &module_spec, const FileSpecList &default_search_paths)
static bool DownloadObjectAndSymbolFile(ModuleSpec &module_spec, Status &error, bool force_lookup=true, bool copy_executable=true)
static ModuleSpec LocateExecutableObjectFile(const ModuleSpec &module_spec)
static FileSpec FindSymbolFileInBundle(const FileSpec &dsym_bundle_fspec, const lldb_private::UUID *uuid, const ArchSpec *arch)
std::string GetAsString(llvm::StringRef separator="-") const
Definition: UUID.cpp:49
bool IsValid() const
Definition: UUID.h:69
#define UNUSED_IF_ASSERT_DISABLED(x)
Definition: lldb-defines.h:131
A class that represents a running process on the host machine.
Definition: SBAttachInfo.h:14
Log * GetLog(Cat mask)
Retrieve the Log object for the channel associated with the given log enum.
Definition: Log.h:314
Definition: SBAddress.h:15