Coverage Report

Created: 2022-01-15 10:30

/Users/buildslave/jenkins/workspace/coverage/llvm-project/lldb/include/lldb/Target/Platform.h
Line
Count
Source (jump to first uncovered line)
1
//===-- Platform.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_TARGET_PLATFORM_H
10
#define LLDB_TARGET_PLATFORM_H
11
12
#include <functional>
13
#include <map>
14
#include <memory>
15
#include <mutex>
16
#include <string>
17
#include <vector>
18
19
#include "lldb/Core/PluginInterface.h"
20
#include "lldb/Core/UserSettingsController.h"
21
#include "lldb/Host/File.h"
22
#include "lldb/Interpreter/Options.h"
23
#include "lldb/Utility/ArchSpec.h"
24
#include "lldb/Utility/ConstString.h"
25
#include "lldb/Utility/FileSpec.h"
26
#include "lldb/Utility/StructuredData.h"
27
#include "lldb/Utility/Timeout.h"
28
#include "lldb/Utility/UserIDResolver.h"
29
#include "lldb/lldb-private-forward.h"
30
#include "lldb/lldb-public.h"
31
#include "llvm/Support/VersionTuple.h"
32
33
namespace lldb_private {
34
35
class ProcessInstanceInfo;
36
class ProcessInstanceInfoMatch;
37
typedef std::vector<ProcessInstanceInfo> ProcessInstanceInfoList;
38
39
class ModuleCache;
40
enum MmapFlags { eMmapFlagsPrivate = 1, eMmapFlagsAnon = 2 };
41
42
class PlatformProperties : public Properties {
43
public:
44
  PlatformProperties();
45
46
  static ConstString GetSettingName();
47
48
  bool GetUseModuleCache() const;
49
  bool SetUseModuleCache(bool use_module_cache);
50
51
  FileSpec GetModuleCacheDirectory() const;
52
  bool SetModuleCacheDirectory(const FileSpec &dir_spec);
53
54
private:
55
  void SetDefaultModuleCacheDirectory(const FileSpec &dir_spec);
56
};
57
58
typedef llvm::SmallVector<lldb::addr_t, 6> MmapArgList;
59
60
/// \class Platform Platform.h "lldb/Target/Platform.h"
61
/// A plug-in interface definition class for debug platform that
62
/// includes many platform abilities such as:
63
///     \li getting platform information such as supported architectures,
64
///         supported binary file formats and more
65
///     \li launching new processes
66
///     \li attaching to existing processes
67
///     \li download/upload files
68
///     \li execute shell commands
69
///     \li listing and getting info for existing processes
70
///     \li attaching and possibly debugging the platform's kernel
71
class Platform : public PluginInterface {
72
public:
73
  /// Default Constructor
74
  Platform(bool is_host_platform);
75
76
  /// The destructor is virtual since this class is designed to be inherited
77
  /// from by the plug-in instance.
78
  ~Platform() override;
79
80
  static void Initialize();
81
82
  static void Terminate();
83
84
  static PlatformProperties &GetGlobalPlatformProperties();
85
86
  /// Get the native host platform plug-in.
87
  ///
88
  /// There should only be one of these for each host that LLDB runs upon that
89
  /// should be statically compiled in and registered using preprocessor
90
  /// macros or other similar build mechanisms in a
91
  /// PlatformSubclass::Initialize() function.
92
  ///
93
  /// This platform will be used as the default platform when launching or
94
  /// attaching to processes unless another platform is specified.
95
  static lldb::PlatformSP GetHostPlatform();
96
97
  static lldb::PlatformSP
98
  GetPlatformForArchitecture(const ArchSpec &arch, ArchSpec *platform_arch_ptr);
99
100
  static const char *GetHostPlatformName();
101
102
  static void SetHostPlatform(const lldb::PlatformSP &platform_sp);
103
104
  // Find an existing platform plug-in by name
105
  static lldb::PlatformSP Find(ConstString name);
106
107
  static lldb::PlatformSP Create(ConstString name, Status &error);
108
109
  static lldb::PlatformSP Create(const ArchSpec &arch,
110
                                 ArchSpec *platform_arch_ptr, Status &error);
111
112
  /// Augments the triple either with information from platform or the host
113
  /// system (if platform is null).
114
  static ArchSpec GetAugmentedArchSpec(Platform *platform,
115
                                       llvm::StringRef triple);
116
117
  /// Find a platform plugin for a given process.
118
  ///
119
  /// Scans the installed Platform plug-ins and tries to find an instance that
120
  /// can be used for \a process
121
  ///
122
  /// \param[in] process
123
  ///     The process for which to try and locate a platform
124
  ///     plug-in instance.
125
  ///
126
  /// \param[in] plugin_name
127
  ///     An optional name of a specific platform plug-in that
128
  ///     should be used. If nullptr, pick the best plug-in.
129
  //        static lldb::PlatformSP
130
  //        FindPlugin (Process *process, ConstString plugin_name);
131
132
  /// Set the target's executable based off of the existing architecture
133
  /// information in \a target given a path to an executable \a exe_file.
134
  ///
135
  /// Each platform knows the architectures that it supports and can select
136
  /// the correct architecture slice within \a exe_file by inspecting the
137
  /// architecture in \a target. If the target had an architecture specified,
138
  /// then in can try and obey that request and optionally fail if the
139
  /// architecture doesn't match up. If no architecture is specified, the
140
  /// platform should select the default architecture from \a exe_file. Any
141
  /// application bundles or executable wrappers can also be inspected for the
142
  /// actual application binary within the bundle that should be used.
143
  ///
144
  /// \return
145
  ///     Returns \b true if this Platform plug-in was able to find
146
  ///     a suitable executable, \b false otherwise.
147
  virtual Status ResolveExecutable(const ModuleSpec &module_spec,
148
                                   lldb::ModuleSP &module_sp,
149
                                   const FileSpecList *module_search_paths_ptr);
150
151
  /// Find a symbol file given a symbol file module specification.
152
  ///
153
  /// Each platform might have tricks to find symbol files for an executable
154
  /// given information in a symbol file ModuleSpec. Some platforms might also
155
  /// support symbol files that are bundles and know how to extract the right
156
  /// symbol file given a bundle.
157
  ///
158
  /// \param[in] target
159
  ///     The target in which we are trying to resolve the symbol file.
160
  ///     The target has a list of modules that we might be able to
161
  ///     use in order to help find the right symbol file. If the
162
  ///     "m_file" or "m_platform_file" entries in the \a sym_spec
163
  ///     are filled in, then we might be able to locate a module in
164
  ///     the target, extract its UUID and locate a symbol file.
165
  ///     If just the "m_uuid" is specified, then we might be able
166
  ///     to find the module in the target that matches that UUID
167
  ///     and pair the symbol file along with it. If just "m_symbol_file"
168
  ///     is specified, we can use a variety of tricks to locate the
169
  ///     symbols in an SDK, PDK, or other development kit location.
170
  ///
171
  /// \param[in] sym_spec
172
  ///     A module spec that describes some information about the
173
  ///     symbol file we are trying to resolve. The ModuleSpec might
174
  ///     contain the following:
175
  ///     m_file - A full or partial path to an executable from the
176
  ///              target (might be empty).
177
  ///     m_platform_file - Another executable hint that contains
178
  ///                       the path to the file as known on the
179
  ///                       local/remote platform.
180
  ///     m_symbol_file - A full or partial path to a symbol file
181
  ///                     or symbol bundle that should be used when
182
  ///                     trying to resolve the symbol file.
183
  ///     m_arch - The architecture we are looking for when resolving
184
  ///              the symbol file.
185
  ///     m_uuid - The UUID of the executable and symbol file. This
186
  ///              can often be used to match up an executable with
187
  ///              a symbol file, or resolve an symbol file in a
188
  ///              symbol file bundle.
189
  ///
190
  /// \param[out] sym_file
191
  ///     The resolved symbol file spec if the returned error
192
  ///     indicates success.
193
  ///
194
  /// \return
195
  ///     Returns an error that describes success or failure.
196
  virtual Status ResolveSymbolFile(Target &target, const ModuleSpec &sym_spec,
197
                                   FileSpec &sym_file);
198
199
  /// Resolves the FileSpec to a (possibly) remote path. Remote platforms must
200
  /// override this to resolve to a path on the remote side.
201
  virtual bool ResolveRemotePath(const FileSpec &platform_path,
202
                                 FileSpec &resolved_platform_path);
203
204
  /// Get the OS version from a connected platform.
205
  ///
206
  /// Some platforms might not be connected to a remote platform, but can
207
  /// figure out the OS version for a process. This is common for simulator
208
  /// platforms that will run native programs on the current host, but the
209
  /// simulator might be simulating a different OS. The \a process parameter
210
  /// might be specified to help to determine the OS version.
211
  virtual llvm::VersionTuple GetOSVersion(Process *process = nullptr);
212
213
  bool SetOSVersion(llvm::VersionTuple os_version);
214
215
  llvm::Optional<std::string> GetOSBuildString();
216
217
  llvm::Optional<std::string> GetOSKernelDescription();
218
219
  // Returns the name of the platform
220
  ConstString GetName();
221
222
  virtual const char *GetHostname();
223
224
  virtual ConstString GetFullNameForDylib(ConstString basename);
225
226
  virtual llvm::StringRef GetDescription() = 0;
227
228
  /// Report the current status for this platform.
229
  ///
230
  /// The returned string usually involves returning the OS version (if
231
  /// available), and any SDK directory that might be being used for local
232
  /// file caching, and if connected a quick blurb about what this platform is
233
  /// connected to.
234
  virtual void GetStatus(Stream &strm);
235
236
  // Subclasses must be able to fetch the current OS version
237
  //
238
  // Remote classes must be connected for this to succeed. Local subclasses
239
  // don't need to override this function as it will just call the
240
  // HostInfo::GetOSVersion().
241
1
  virtual bool GetRemoteOSVersion() { return false; }
242
243
0
  virtual llvm::Optional<std::string> GetRemoteOSBuildString() {
244
0
    return llvm::None;
245
0
  }
246
247
1
  virtual llvm::Optional<std::string> GetRemoteOSKernelDescription() {
248
1
    return llvm::None;
249
1
  }
250
251
  // Remote Platform subclasses need to override this function
252
1
  virtual ArchSpec GetRemoteSystemArchitecture() {
253
1
    return ArchSpec(); // Return an invalid architecture
254
1
  }
255
256
29
  virtual FileSpec GetRemoteWorkingDirectory() { return m_working_dir; }
257
258
  virtual bool SetRemoteWorkingDirectory(const FileSpec &working_dir);
259
260
  virtual UserIDResolver &GetUserIDResolver() = 0;
261
262
  /// Locate a file for a platform.
263
  ///
264
  /// The default implementation of this function will return the same file
265
  /// patch in \a local_file as was in \a platform_file.
266
  ///
267
  /// \param[in] platform_file
268
  ///     The platform file path to locate and cache locally.
269
  ///
270
  /// \param[in] uuid_ptr
271
  ///     If we know the exact UUID of the file we are looking for, it
272
  ///     can be specified. If it is not specified, we might now know
273
  ///     the exact file. The UUID is usually some sort of MD5 checksum
274
  ///     for the file and is sometimes known by dynamic linkers/loaders.
275
  ///     If the UUID is known, it is best to supply it to platform
276
  ///     file queries to ensure we are finding the correct file, not
277
  ///     just a file at the correct path.
278
  ///
279
  /// \param[out] local_file
280
  ///     A locally cached version of the platform file. For platforms
281
  ///     that describe the current host computer, this will just be
282
  ///     the same file. For remote platforms, this file might come from
283
  ///     and SDK directory, or might need to be sync'ed over to the
284
  ///     current machine for efficient debugging access.
285
  ///
286
  /// \return
287
  ///     An error object.
288
  virtual Status GetFileWithUUID(const FileSpec &platform_file,
289
                                 const UUID *uuid_ptr, FileSpec &local_file);
290
291
  // Locate the scripting resource given a module specification.
292
  //
293
  // Locating the file should happen only on the local computer or using the
294
  // current computers global settings.
295
  virtual FileSpecList
296
  LocateExecutableScriptingResources(Target *target, Module &module,
297
                                     Stream *feedback_stream);
298
299
  virtual Status GetSharedModule(
300
      const ModuleSpec &module_spec, Process *process,
301
      lldb::ModuleSP &module_sp, const FileSpecList *module_search_paths_ptr,
302
      llvm::SmallVectorImpl<lldb::ModuleSP> *old_modules, bool *did_create_ptr);
303
304
  virtual bool GetModuleSpec(const FileSpec &module_file_spec,
305
                             const ArchSpec &arch, ModuleSpec &module_spec);
306
307
  virtual Status ConnectRemote(Args &args);
308
309
  virtual Status DisconnectRemote();
310
311
  /// Get the platform's supported architectures in the order in which they
312
  /// should be searched.
313
  virtual std::vector<ArchSpec> GetSupportedArchitectures() = 0;
314
315
  virtual size_t GetSoftwareBreakpointTrapOpcode(Target &target,
316
                                                 BreakpointSite *bp_site);
317
318
  /// Launch a new process on a platform, not necessarily for debugging, it
319
  /// could be just for running the process.
320
  virtual Status LaunchProcess(ProcessLaunchInfo &launch_info);
321
322
  /// Perform expansion of the command-line for this launch info This can
323
  /// potentially involve wildcard expansion
324
  /// environment variable replacement, and whatever other
325
  /// argument magic the platform defines as part of its typical
326
  /// user experience
327
  virtual Status ShellExpandArguments(ProcessLaunchInfo &launch_info);
328
329
  /// Kill process on a platform.
330
  virtual Status KillProcess(const lldb::pid_t pid);
331
332
  /// Lets a platform answer if it is compatible with a given architecture and
333
  /// the target triple contained within.
334
  virtual bool IsCompatibleArchitecture(const ArchSpec &arch,
335
                                        bool exact_arch_match,
336
                                        ArchSpec *compatible_arch_ptr);
337
338
  /// Not all platforms will support debugging a process by spawning somehow
339
  /// halted for a debugger (specified using the "eLaunchFlagDebug" launch
340
  /// flag) and then attaching. If your platform doesn't support this,
341
  /// override this function and return false.
342
2.60k
  virtual bool CanDebugProcess() { return true; }
343
344
  /// Subclasses do not need to implement this function as it uses the
345
  /// Platform::LaunchProcess() followed by Platform::Attach (). Remote
346
  /// platforms will want to subclass this function in order to be able to
347
  /// intercept STDIO and possibly launch a separate process that will debug
348
  /// the debuggee.
349
  virtual lldb::ProcessSP DebugProcess(ProcessLaunchInfo &launch_info,
350
                                       Debugger &debugger, Target &target,
351
                                       Status &error);
352
353
  virtual lldb::ProcessSP ConnectProcess(llvm::StringRef connect_url,
354
                                         llvm::StringRef plugin_name,
355
                                         Debugger &debugger, Target *target,
356
                                         Status &error);
357
358
  virtual lldb::ProcessSP
359
  ConnectProcessSynchronous(llvm::StringRef connect_url,
360
                            llvm::StringRef plugin_name, Debugger &debugger,
361
                            Stream &stream, Target *target, Status &error);
362
363
  /// Attach to an existing process using a process ID.
364
  ///
365
  /// Each platform subclass needs to implement this function and attempt to
366
  /// attach to the process with the process ID of \a pid. The platform
367
  /// subclass should return an appropriate ProcessSP subclass that is
368
  /// attached to the process, or an empty shared pointer with an appropriate
369
  /// error.
370
  ///
371
  /// \return
372
  ///     An appropriate ProcessSP containing a valid shared pointer
373
  ///     to the default Process subclass for the platform that is
374
  ///     attached to the process, or an empty shared pointer with an
375
  ///     appropriate error fill into the \a error object.
376
  virtual lldb::ProcessSP Attach(ProcessAttachInfo &attach_info,
377
                                 Debugger &debugger,
378
                                 Target *target, // Can be nullptr, if nullptr
379
                                                 // create a new target, else
380
                                                 // use existing one
381
                                 Status &error) = 0;
382
383
  /// Attach to an existing process by process name.
384
  ///
385
  /// This function is not meant to be overridden by Process subclasses. It
386
  /// will first call Process::WillAttach (const char *) and if that returns
387
  /// \b true, Process::DoAttach (const char *) will be called to actually do
388
  /// the attach. If DoAttach returns \b true, then Process::DidAttach() will
389
  /// be called.
390
  ///
391
  /// \param[in] process_name
392
  ///     A process name to match against the current process list.
393
  ///
394
  /// \return
395
  ///     Returns \a pid if attaching was successful, or
396
  ///     LLDB_INVALID_PROCESS_ID if attaching fails.
397
  //        virtual lldb::ProcessSP
398
  //        Attach (const char *process_name,
399
  //                bool wait_for_launch,
400
  //                Status &error) = 0;
401
402
  // The base class Platform will take care of the host platform. Subclasses
403
  // will need to fill in the remote case.
404
  virtual uint32_t FindProcesses(const ProcessInstanceInfoMatch &match_info,
405
                                 ProcessInstanceInfoList &proc_infos);
406
407
  virtual bool GetProcessInfo(lldb::pid_t pid, ProcessInstanceInfo &proc_info);
408
409
  // Set a breakpoint on all functions that can end up creating a thread for
410
  // this platform. This is needed when running expressions and also for
411
  // process control.
412
  virtual lldb::BreakpointSP SetThreadCreationBreakpoint(Target &target);
413
414
  // Given a target, find the local SDK directory if one exists on the current
415
  // host.
416
  virtual lldb_private::ConstString
417
0
  GetSDKDirectory(lldb_private::Target &target) {
418
0
    return lldb_private::ConstString();
419
0
  }
420
421
0
  const std::string &GetRemoteURL() const { return m_remote_url; }
422
423
184k
  bool IsHost() const {
424
184k
    return m_is_host; // Is this the default host platform?
425
184k
  }
426
427
146k
  bool IsRemote() const { return !m_is_host; }
428
429
0
  virtual bool IsConnected() const {
430
    // Remote subclasses should override this function
431
0
    return IsHost();
432
0
  }
433
434
  const ArchSpec &GetSystemArchitecture();
435
436
3.44k
  void SetSystemArchitecture(const ArchSpec &arch) {
437
3.44k
    m_system_arch = arch;
438
3.44k
    if (IsHost())
439
3.44k
      m_os_version_set_while_connected = m_system_arch.IsValid();
440
3.44k
  }
441
442
  /// If the triple contains not specify the vendor, os, and environment
443
  /// parts, we "augment" these using information from the platform and return
444
  /// the resulting ArchSpec object.
445
  ArchSpec GetAugmentedArchSpec(llvm::StringRef triple);
446
447
  // Used for column widths
448
0
  size_t GetMaxUserIDNameLength() const { return m_max_uid_name_len; }
449
450
  // Used for column widths
451
0
  size_t GetMaxGroupIDNameLength() const { return m_max_gid_name_len; }
452
453
9
  ConstString GetSDKRootDirectory() const { return m_sdk_sysroot; }
454
455
23
  void SetSDKRootDirectory(ConstString dir) { m_sdk_sysroot = dir; }
456
457
0
  ConstString GetSDKBuild() const { return m_sdk_build; }
458
459
0
  void SetSDKBuild(ConstString sdk_build) { m_sdk_build = sdk_build; }
460
461
  // Override this to return true if your platform supports Clang modules. You
462
  // may also need to override AddClangModuleCompilationOptions to pass the
463
  // right Clang flags for your platform.
464
4
  virtual bool SupportsModules() { return false; }
465
466
  // Appends the platform-specific options required to find the modules for the
467
  // current platform.
468
  virtual void
469
  AddClangModuleCompilationOptions(Target *target,
470
                                   std::vector<std::string> &options);
471
472
  FileSpec GetWorkingDirectory();
473
474
  bool SetWorkingDirectory(const FileSpec &working_dir);
475
476
  // There may be modules that we don't want to find by default for operations
477
  // like "setting breakpoint by name". The platform will return "true" from
478
  // this call if the passed in module happens to be one of these.
479
480
  virtual bool
481
  ModuleIsExcludedForUnconstrainedSearches(Target &target,
482
0
                                           const lldb::ModuleSP &module_sp) {
483
0
    return false;
484
0
  }
485
486
  virtual Status MakeDirectory(const FileSpec &file_spec, uint32_t permissions);
487
488
  virtual Status GetFilePermissions(const FileSpec &file_spec,
489
                                    uint32_t &file_permissions);
490
491
  virtual Status SetFilePermissions(const FileSpec &file_spec,
492
                                    uint32_t file_permissions);
493
494
  virtual lldb::user_id_t OpenFile(const FileSpec &file_spec,
495
                                   File::OpenOptions flags, uint32_t mode,
496
0
                                   Status &error) {
497
0
    return UINT64_MAX;
498
0
  }
499
500
0
  virtual bool CloseFile(lldb::user_id_t fd, Status &error) { return false; }
501
502
0
  virtual lldb::user_id_t GetFileSize(const FileSpec &file_spec) {
503
0
    return UINT64_MAX;
504
0
  }
505
506
  virtual void AutoCompleteDiskFileOrDirectory(CompletionRequest &request,
507
0
                                               bool only_dir) {}
508
509
  virtual uint64_t ReadFile(lldb::user_id_t fd, uint64_t offset, void *dst,
510
0
                            uint64_t dst_len, Status &error) {
511
0
    error.SetErrorStringWithFormat(
512
0
        "Platform::ReadFile() is not supported in the %s platform",
513
0
        GetName().GetCString());
514
0
    return -1;
515
0
  }
516
517
  virtual uint64_t WriteFile(lldb::user_id_t fd, uint64_t offset,
518
0
                             const void *src, uint64_t src_len, Status &error) {
519
0
    error.SetErrorStringWithFormat(
520
0
        "Platform::WriteFile() is not supported in the %s platform",
521
0
        GetName().GetCString());
522
0
    return -1;
523
0
  }
524
525
  virtual Status GetFile(const FileSpec &source, const FileSpec &destination);
526
527
  virtual Status PutFile(const FileSpec &source, const FileSpec &destination,
528
                         uint32_t uid = UINT32_MAX, uint32_t gid = UINT32_MAX);
529
530
  virtual Status
531
  CreateSymlink(const FileSpec &src,  // The name of the link is in src
532
                const FileSpec &dst); // The symlink points to dst
533
534
  /// Install a file or directory to the remote system.
535
  ///
536
  /// Install is similar to Platform::PutFile(), but it differs in that if an
537
  /// application/framework/shared library is installed on a remote platform
538
  /// and the remote platform requires something to be done to register the
539
  /// application/framework/shared library, then this extra registration can
540
  /// be done.
541
  ///
542
  /// \param[in] src
543
  ///     The source file/directory to install on the remote system.
544
  ///
545
  /// \param[in] dst
546
  ///     The destination file/directory where \a src will be installed.
547
  ///     If \a dst has no filename specified, then its filename will
548
  ///     be set from \a src. It \a dst has no directory specified, it
549
  ///     will use the platform working directory. If \a dst has a
550
  ///     directory specified, but the directory path is relative, the
551
  ///     platform working directory will be prepended to the relative
552
  ///     directory.
553
  ///
554
  /// \return
555
  ///     An error object that describes anything that went wrong.
556
  virtual Status Install(const FileSpec &src, const FileSpec &dst);
557
558
  virtual Environment GetEnvironment();
559
560
  virtual bool GetFileExists(const lldb_private::FileSpec &file_spec);
561
562
  virtual Status Unlink(const FileSpec &file_spec);
563
564
  virtual MmapArgList GetMmapArgumentList(const ArchSpec &arch,
565
                                          lldb::addr_t addr,
566
                                          lldb::addr_t length,
567
                                          unsigned prot, unsigned flags,
568
                                          lldb::addr_t fd, lldb::addr_t offset);
569
570
19
  virtual bool GetSupportsRSync() { return m_supports_rsync; }
571
572
0
  virtual void SetSupportsRSync(bool flag) { m_supports_rsync = flag; }
573
574
0
  virtual const char *GetRSyncOpts() { return m_rsync_opts.c_str(); }
575
576
0
  virtual void SetRSyncOpts(const char *opts) { m_rsync_opts.assign(opts); }
577
578
0
  virtual const char *GetRSyncPrefix() { return m_rsync_prefix.c_str(); }
579
580
0
  virtual void SetRSyncPrefix(const char *prefix) {
581
0
    m_rsync_prefix.assign(prefix);
582
0
  }
583
584
18
  virtual bool GetSupportsSSH() { return m_supports_ssh; }
585
586
0
  virtual void SetSupportsSSH(bool flag) { m_supports_ssh = flag; }
587
588
0
  virtual const char *GetSSHOpts() { return m_ssh_opts.c_str(); }
589
590
0
  virtual void SetSSHOpts(const char *opts) { m_ssh_opts.assign(opts); }
591
592
0
  virtual bool GetIgnoresRemoteHostname() { return m_ignores_remote_hostname; }
593
594
0
  virtual void SetIgnoresRemoteHostname(bool flag) {
595
0
    m_ignores_remote_hostname = flag;
596
0
  }
597
598
  virtual lldb_private::OptionGroupOptions *
599
12
  GetConnectionOptions(CommandInterpreter &interpreter) {
600
12
    return nullptr;
601
12
  }
602
603
  virtual lldb_private::Status RunShellCommand(
604
      llvm::StringRef command,
605
      const FileSpec &working_dir, // Pass empty FileSpec to use the current
606
                                   // working directory
607
      int *status_ptr, // Pass nullptr if you don't want the process exit status
608
      int *signo_ptr,  // Pass nullptr if you don't want the signal that caused
609
                       // the process to exit
610
      std::string
611
          *command_output, // Pass nullptr if you don't want the command output
612
      const Timeout<std::micro> &timeout);
613
614
  virtual lldb_private::Status RunShellCommand(
615
      llvm::StringRef shell, llvm::StringRef command,
616
      const FileSpec &working_dir, // Pass empty FileSpec to use the current
617
                                   // working directory
618
      int *status_ptr, // Pass nullptr if you don't want the process exit status
619
      int *signo_ptr,  // Pass nullptr if you don't want the signal that caused
620
                       // the process to exit
621
      std::string
622
          *command_output, // Pass nullptr if you don't want the command output
623
      const Timeout<std::micro> &timeout);
624
625
  virtual void SetLocalCacheDirectory(const char *local);
626
627
  virtual const char *GetLocalCacheDirectory();
628
629
13
  virtual std::string GetPlatformSpecificConnectionInformation() { return ""; }
630
631
  virtual bool CalculateMD5(const FileSpec &file_spec, uint64_t &low,
632
                            uint64_t &high);
633
634
0
  virtual uint32_t GetResumeCountForLaunchInfo(ProcessLaunchInfo &launch_info) {
635
0
    return 1;
636
0
  }
637
638
  virtual const lldb::UnixSignalsSP &GetRemoteUnixSignals();
639
640
  lldb::UnixSignalsSP GetUnixSignals();
641
642
  /// Locate a queue name given a thread's qaddr
643
  ///
644
  /// On a system using libdispatch ("Grand Central Dispatch") style queues, a
645
  /// thread may be associated with a GCD queue or not, and a queue may be
646
  /// associated with multiple threads. The process/thread must provide a way
647
  /// to find the "dispatch_qaddr" for each thread, and from that
648
  /// dispatch_qaddr this Platform method will locate the queue name and
649
  /// provide that.
650
  ///
651
  /// \param[in] process
652
  ///     A process is required for reading memory.
653
  ///
654
  /// \param[in] dispatch_qaddr
655
  ///     The dispatch_qaddr for this thread.
656
  ///
657
  /// \return
658
  ///     The name of the queue, if there is one.  An empty string
659
  ///     means that this thread is not associated with a dispatch
660
  ///     queue.
661
  virtual std::string
662
0
  GetQueueNameForThreadQAddress(Process *process, lldb::addr_t dispatch_qaddr) {
663
0
    return "";
664
0
  }
665
666
  /// Locate a queue ID given a thread's qaddr
667
  ///
668
  /// On a system using libdispatch ("Grand Central Dispatch") style queues, a
669
  /// thread may be associated with a GCD queue or not, and a queue may be
670
  /// associated with multiple threads. The process/thread must provide a way
671
  /// to find the "dispatch_qaddr" for each thread, and from that
672
  /// dispatch_qaddr this Platform method will locate the queue ID and provide
673
  /// that.
674
  ///
675
  /// \param[in] process
676
  ///     A process is required for reading memory.
677
  ///
678
  /// \param[in] dispatch_qaddr
679
  ///     The dispatch_qaddr for this thread.
680
  ///
681
  /// \return
682
  ///     The queue_id for this thread, if this thread is associated
683
  ///     with a dispatch queue.  Else LLDB_INVALID_QUEUE_ID is returned.
684
  virtual lldb::queue_id_t
685
0
  GetQueueIDForThreadQAddress(Process *process, lldb::addr_t dispatch_qaddr) {
686
0
    return LLDB_INVALID_QUEUE_ID;
687
0
  }
688
689
  /// Provide a list of trap handler function names for this platform
690
  ///
691
  /// The unwinder needs to treat trap handlers specially -- the stack frame
692
  /// may not be aligned correctly for a trap handler (the kernel often won't
693
  /// perturb the stack pointer, or won't re-align it properly, in the process
694
  /// of calling the handler) and the frame above the handler needs to be
695
  /// treated by the unwinder's "frame 0" rules instead of its "middle of the
696
  /// stack frame" rules.
697
  ///
698
  /// In a user process debugging scenario, the list of trap handlers is
699
  /// typically just "_sigtramp".
700
  ///
701
  /// The Platform base class provides the m_trap_handlers ivar but it does
702
  /// not populate it.  Subclasses should add the names of the asynchronous
703
  /// signal handler routines as needed.  For most Unix platforms, add
704
  /// _sigtramp.
705
  ///
706
  /// \return
707
  ///     A list of symbol names.  The list may be empty.
708
  virtual const std::vector<ConstString> &GetTrapHandlerSymbolNames();
709
710
  /// Try to get a specific unwind plan for a named trap handler.
711
  /// The default is not to have specific unwind plans for trap handlers.
712
  ///
713
  /// \param[in] triple
714
  ///     Triple of the current target.
715
  ///
716
  /// \param[in] name
717
  ///     Name of the trap handler function.
718
  ///
719
  /// \return
720
  ///     A specific unwind plan for that trap handler, or an empty
721
  ///     shared pointer. The latter means there is no specific plan,
722
  ///     unwind as normal.
723
  virtual lldb::UnwindPlanSP
724
11
  GetTrapHandlerUnwindPlan(const llvm::Triple &triple, ConstString name) {
725
11
    return {};
726
11
  }
727
728
  /// Find a support executable that may not live within in the standard
729
  /// locations related to LLDB.
730
  ///
731
  /// Executable might exist within the Platform SDK directories, or in
732
  /// standard tool directories within the current IDE that is running LLDB.
733
  ///
734
  /// \param[in] basename
735
  ///     The basename of the executable to locate in the current
736
  ///     platform.
737
  ///
738
  /// \return
739
  ///     A FileSpec pointing to the executable on disk, or an invalid
740
  ///     FileSpec if the executable cannot be found.
741
0
  virtual FileSpec LocateExecutable(const char *basename) { return FileSpec(); }
742
743
  /// Allow the platform to set preferred memory cache line size. If non-zero
744
  /// (and the user has not set cache line size explicitly), this value will
745
  /// be used as the cache line size for memory reads.
746
3.02k
  virtual uint32_t GetDefaultMemoryCacheLineSize() { return 0; }
747
748
  /// Load a shared library into this process.
749
  ///
750
  /// Try and load a shared library into the current process. This call might
751
  /// fail in the dynamic loader plug-in says it isn't safe to try and load
752
  /// shared libraries at the moment.
753
  ///
754
  /// \param[in] process
755
  ///     The process to load the image.
756
  ///
757
  /// \param[in] local_file
758
  ///     The file spec that points to the shared library that you want
759
  ///     to load if the library is located on the host. The library will
760
  ///     be copied over to the location specified by remote_file or into
761
  ///     the current working directory with the same filename if the
762
  ///     remote_file isn't specified.
763
  ///
764
  /// \param[in] remote_file
765
  ///     If local_file is specified then the location where the library
766
  ///     should be copied over from the host. If local_file isn't
767
  ///     specified, then the path for the shared library on the target
768
  ///     what you want to load.
769
  ///
770
  /// \param[out] error
771
  ///     An error object that gets filled in with any errors that
772
  ///     might occur when trying to load the shared library.
773
  ///
774
  /// \return
775
  ///     A token that represents the shared library that can be
776
  ///     later used to unload the shared library. A value of
777
  ///     LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
778
  ///     library can't be opened.
779
  uint32_t LoadImage(lldb_private::Process *process,
780
                     const lldb_private::FileSpec &local_file,
781
                     const lldb_private::FileSpec &remote_file,
782
                     lldb_private::Status &error);
783
784
  /// Load a shared library specified by base name into this process,
785
  /// looking by hand along a set of paths.
786
  ///
787
  /// \param[in] process
788
  ///     The process to load the image.
789
  ///
790
  /// \param[in] library_name
791
  ///     The name of the library to look for.  If library_name is an
792
  ///     absolute path, the basename will be extracted and searched for
793
  ///     along the paths.  This emulates the behavior of the loader when
794
  ///     given an install name and a set (e.g. DYLD_LIBRARY_PATH provided) of
795
  ///     alternate paths.
796
  ///
797
  /// \param[in] paths
798
  ///     The list of paths to use to search for the library.  First
799
  ///     match wins.
800
  ///
801
  /// \param[out] error
802
  ///     An error object that gets filled in with any errors that
803
  ///     might occur when trying to load the shared library.
804
  ///
805
  /// \param[out] loaded_path
806
  ///      If non-null, the path to the dylib that was successfully loaded
807
  ///      is stored in this path.
808
  ///
809
  /// \return
810
  ///     A token that represents the shared library which can be
811
  ///     passed to UnloadImage. A value of
812
  ///     LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
813
  ///     library can't be opened.
814
  uint32_t LoadImageUsingPaths(lldb_private::Process *process,
815
                               const lldb_private::FileSpec &library_name,
816
                               const std::vector<std::string> &paths,
817
                               lldb_private::Status &error,
818
                               lldb_private::FileSpec *loaded_path);
819
820
  virtual uint32_t DoLoadImage(lldb_private::Process *process,
821
                               const lldb_private::FileSpec &remote_file,
822
                               const std::vector<std::string> *paths,
823
                               lldb_private::Status &error,
824
                               lldb_private::FileSpec *loaded_path = nullptr);
825
826
  virtual Status UnloadImage(lldb_private::Process *process,
827
                             uint32_t image_token);
828
829
  /// Connect to all processes waiting for a debugger to attach
830
  ///
831
  /// If the platform have a list of processes waiting for a debugger to
832
  /// connect to them then connect to all of these pending processes.
833
  ///
834
  /// \param[in] debugger
835
  ///     The debugger used for the connect.
836
  ///
837
  /// \param[out] error
838
  ///     If an error occurred during the connect then this object will
839
  ///     contain the error message.
840
  ///
841
  /// \return
842
  ///     The number of processes we are successfully connected to.
843
  virtual size_t ConnectToWaitingProcesses(lldb_private::Debugger &debugger,
844
                                           lldb_private::Status &error);
845
846
  /// Gather all of crash informations into a structured data dictionary.
847
  ///
848
  /// If the platform have a crashed process with crash information entries,
849
  /// gather all the entries into an structured data dictionary or return a
850
  /// nullptr. This dictionary is generic and extensible, as it contains an
851
  /// array for each different type of crash information.
852
  ///
853
  /// \param[in] process
854
  ///     The crashed process.
855
  ///
856
  /// \return
857
  ///     A structured data dictionary containing at each entry, the crash
858
  ///     information type as the entry key and the matching  an array as the
859
  ///     entry value. \b nullptr if not implemented or  if the process has no
860
  ///     crash information entry. \b error if an error occured.
861
  virtual llvm::Expected<StructuredData::DictionarySP>
862
0
  FetchExtendedCrashInformation(lldb_private::Process &process) {
863
0
    return nullptr;
864
0
  }
865
866
protected:
867
  /// Create a list of ArchSpecs with the given OS and a architectures. The
868
  /// vendor field is left as an "unspecified unknown".
869
  static std::vector<ArchSpec>
870
  CreateArchList(llvm::ArrayRef<llvm::Triple::ArchType> archs,
871
                 llvm::Triple::OSType os);
872
873
  /// Private implementation of connecting to a process. If the stream is set
874
  /// we connect synchronously.
875
  lldb::ProcessSP DoConnectProcess(llvm::StringRef connect_url,
876
                                   llvm::StringRef plugin_name,
877
                                   Debugger &debugger, Stream *stream,
878
                                   Target *target, Status &error);
879
  bool m_is_host;
880
  // Set to true when we are able to actually set the OS version while being
881
  // connected. For remote platforms, we might set the version ahead of time
882
  // before we actually connect and this version might change when we actually
883
  // connect to a remote platform. For the host platform this will be set to
884
  // the once we call HostInfo::GetOSVersion().
885
  bool m_os_version_set_while_connected;
886
  bool m_system_arch_set_while_connected;
887
  ConstString
888
      m_sdk_sysroot; // the root location of where the SDK files are all located
889
  ConstString m_sdk_build;
890
  FileSpec m_working_dir; // The working directory which is used when installing
891
                          // modules that have no install path set
892
  std::string m_remote_url;
893
  std::string m_name;
894
  llvm::VersionTuple m_os_version;
895
  ArchSpec
896
      m_system_arch; // The architecture of the kernel or the remote platform
897
  typedef std::map<uint32_t, ConstString> IDToNameMap;
898
  // Mutex for modifying Platform data structures that should only be used for
899
  // non-reentrant code
900
  std::mutex m_mutex;
901
  size_t m_max_uid_name_len;
902
  size_t m_max_gid_name_len;
903
  bool m_supports_rsync;
904
  std::string m_rsync_opts;
905
  std::string m_rsync_prefix;
906
  bool m_supports_ssh;
907
  std::string m_ssh_opts;
908
  bool m_ignores_remote_hostname;
909
  std::string m_local_cache_directory;
910
  std::vector<ConstString> m_trap_handlers;
911
  bool m_calculated_trap_handlers;
912
  const std::unique_ptr<ModuleCache> m_module_cache;
913
914
  /// Ask the Platform subclass to fill in the list of trap handler names
915
  ///
916
  /// For most Unix user process environments, this will be a single function
917
  /// name, _sigtramp.  More specialized environments may have additional
918
  /// handler names.  The unwinder code needs to know when a trap handler is
919
  /// on the stack because the unwind rules for the frame that caused the trap
920
  /// are different.
921
  ///
922
  /// The base class Platform ivar m_trap_handlers should be updated by the
923
  /// Platform subclass when this method is called.  If there are no
924
  /// predefined trap handlers, this method may be a no-op.
925
  virtual void CalculateTrapHandlerSymbolNames() = 0;
926
927
  Status GetCachedExecutable(ModuleSpec &module_spec, lldb::ModuleSP &module_sp,
928
                             const FileSpecList *module_search_paths_ptr);
929
930
  virtual Status DownloadModuleSlice(const FileSpec &src_file_spec,
931
                                     const uint64_t src_offset,
932
                                     const uint64_t src_size,
933
                                     const FileSpec &dst_file_spec);
934
935
  virtual Status DownloadSymbolFile(const lldb::ModuleSP &module_sp,
936
                                    const FileSpec &dst_file_spec);
937
938
  virtual const char *GetCacheHostname();
939
940
  virtual Status
941
  ResolveRemoteExecutable(const ModuleSpec &module_spec,
942
                          lldb::ModuleSP &exe_module_sp,
943
                          const FileSpecList *module_search_paths_ptr);
944
945
private:
946
  typedef std::function<Status(const ModuleSpec &)> ModuleResolver;
947
948
  Status GetRemoteSharedModule(const ModuleSpec &module_spec, Process *process,
949
                               lldb::ModuleSP &module_sp,
950
                               const ModuleResolver &module_resolver,
951
                               bool *did_create_ptr);
952
953
  bool GetCachedSharedModule(const ModuleSpec &module_spec,
954
                             lldb::ModuleSP &module_sp, bool *did_create_ptr);
955
956
  FileSpec GetModuleCacheRoot();
957
};
958
959
class PlatformList {
960
public:
961
5.94k
  PlatformList() {}
962
963
5.93k
  ~PlatformList() = default;
964
965
6.00k
  void Append(const lldb::PlatformSP &platform_sp, bool set_selected) {
966
6.00k
    std::lock_guard<std::recursive_mutex> guard(m_mutex);
967
6.00k
    m_platforms.push_back(platform_sp);
968
6.00k
    if (set_selected)
969
6.00k
      m_selected_platform_sp = m_platforms.back();
970
6.00k
  }
971
972
3
  size_t GetSize() {
973
3
    std::lock_guard<std::recursive_mutex> guard(m_mutex);
974
3
    return m_platforms.size();
975
3
  }
976
977
4
  lldb::PlatformSP GetAtIndex(uint32_t idx) {
978
4
    lldb::PlatformSP platform_sp;
979
4
    {
980
4
      std::lock_guard<std::recursive_mutex> guard(m_mutex);
981
4
      if (idx < m_platforms.size())
982
4
        platform_sp = m_platforms[idx];
983
4
    }
984
4
    return platform_sp;
985
4
  }
986
987
  /// Select the active platform.
988
  ///
989
  /// In order to debug remotely, other platform's can be remotely connected
990
  /// to and set as the selected platform for any subsequent debugging. This
991
  /// allows connection to remote targets and allows the ability to discover
992
  /// process info, launch and attach to remote processes.
993
39.7k
  lldb::PlatformSP GetSelectedPlatform() {
994
39.7k
    std::lock_guard<std::recursive_mutex> guard(m_mutex);
995
39.7k
    if (!m_selected_platform_sp && 
!m_platforms.empty()0
)
996
0
      m_selected_platform_sp = m_platforms.front();
997
998
39.7k
    return m_selected_platform_sp;
999
39.7k
  }
1000
1001
3.54k
  void SetSelectedPlatform(const lldb::PlatformSP &platform_sp) {
1002
3.54k
    if (platform_sp) {
1003
3.54k
      std::lock_guard<std::recursive_mutex> guard(m_mutex);
1004
3.54k
      const size_t num_platforms = m_platforms.size();
1005
3.60k
      for (size_t idx = 0; idx < num_platforms; 
++idx54
) {
1006
3.58k
        if (m_platforms[idx].get() == platform_sp.get()) {
1007
3.52k
          m_selected_platform_sp = m_platforms[idx];
1008
3.52k
          return;
1009
3.52k
        }
1010
3.58k
      }
1011
22
      m_platforms.push_back(platform_sp);
1012
22
      m_selected_platform_sp = m_platforms.back();
1013
22
    }
1014
3.54k
  }
1015
1016
protected:
1017
  typedef std::vector<lldb::PlatformSP> collection;
1018
  mutable std::recursive_mutex m_mutex;
1019
  collection m_platforms;
1020
  lldb::PlatformSP m_selected_platform_sp;
1021
1022
private:
1023
  PlatformList(const PlatformList &) = delete;
1024
  const PlatformList &operator=(const PlatformList &) = delete;
1025
};
1026
1027
class OptionGroupPlatformRSync : public lldb_private::OptionGroup {
1028
public:
1029
3.57k
  OptionGroupPlatformRSync() = default;
1030
1031
3.24k
  ~OptionGroupPlatformRSync() override = default;
1032
1033
  lldb_private::Status
1034
  SetOptionValue(uint32_t option_idx, llvm::StringRef option_value,
1035
                 ExecutionContext *execution_context) override;
1036
1037
  void OptionParsingStarting(ExecutionContext *execution_context) override;
1038
1039
  llvm::ArrayRef<OptionDefinition> GetDefinitions() override;
1040
1041
  // Instance variables to hold the values for command options.
1042
1043
  bool m_rsync;
1044
  std::string m_rsync_opts;
1045
  std::string m_rsync_prefix;
1046
  bool m_ignores_remote_hostname;
1047
1048
private:
1049
  OptionGroupPlatformRSync(const OptionGroupPlatformRSync &) = delete;
1050
  const OptionGroupPlatformRSync &
1051
  operator=(const OptionGroupPlatformRSync &) = delete;
1052
};
1053
1054
class OptionGroupPlatformSSH : public lldb_private::OptionGroup {
1055
public:
1056
3.57k
  OptionGroupPlatformSSH() = default;
1057
1058
3.24k
  ~OptionGroupPlatformSSH() override = default;
1059
1060
  lldb_private::Status
1061
  SetOptionValue(uint32_t option_idx, llvm::StringRef option_value,
1062
                 ExecutionContext *execution_context) override;
1063
1064
  void OptionParsingStarting(ExecutionContext *execution_context) override;
1065
1066
  llvm::ArrayRef<OptionDefinition> GetDefinitions() override;
1067
1068
  // Instance variables to hold the values for command options.
1069
1070
  bool m_ssh;
1071
  std::string m_ssh_opts;
1072
1073
private:
1074
  OptionGroupPlatformSSH(const OptionGroupPlatformSSH &) = delete;
1075
  const OptionGroupPlatformSSH &
1076
  operator=(const OptionGroupPlatformSSH &) = delete;
1077
};
1078
1079
class OptionGroupPlatformCaching : public lldb_private::OptionGroup {
1080
public:
1081
3.57k
  OptionGroupPlatformCaching() = default;
1082
1083
3.24k
  ~OptionGroupPlatformCaching() override = default;
1084
1085
  lldb_private::Status
1086
  SetOptionValue(uint32_t option_idx, llvm::StringRef option_value,
1087
                 ExecutionContext *execution_context) override;
1088
1089
  void OptionParsingStarting(ExecutionContext *execution_context) override;
1090
1091
  llvm::ArrayRef<OptionDefinition> GetDefinitions() override;
1092
1093
  // Instance variables to hold the values for command options.
1094
1095
  std::string m_cache_dir;
1096
1097
private:
1098
  OptionGroupPlatformCaching(const OptionGroupPlatformCaching &) = delete;
1099
  const OptionGroupPlatformCaching &
1100
  operator=(const OptionGroupPlatformCaching &) = delete;
1101
};
1102
1103
} // namespace lldb_private
1104
1105
#endif // LLDB_TARGET_PLATFORM_H