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