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