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