contrib/llvm/tools/lldb/include/lldb/Target/Platform.h

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