1 //===-- Platform.h ----------------------------------------------*- C++ -*-===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===----------------------------------------------------------------------===//
9 #ifndef liblldb_Platform_h_
10 #define liblldb_Platform_h_
19 #include "lldb/Core/PluginInterface.h"
20 #include "lldb/Core/UserSettingsController.h"
21 #include "lldb/Interpreter/Options.h"
22 #include "lldb/Utility/ArchSpec.h"
23 #include "lldb/Utility/ConstString.h"
24 #include "lldb/Utility/FileSpec.h"
25 #include "lldb/Utility/Timeout.h"
26 #include "lldb/Utility/UserIDResolver.h"
27 #include "lldb/lldb-private-forward.h"
28 #include "lldb/lldb-public.h"
29 #include "llvm/Support/VersionTuple.h"
31 namespace lldb_private {
33 class ProcessInstanceInfo;
34 class ProcessInstanceInfoList;
35 class ProcessInstanceInfoMatch;
38 enum MmapFlags { eMmapFlagsPrivate = 1, eMmapFlagsAnon = 2 };
40 class PlatformProperties : public Properties {
44 static ConstString GetSettingName();
46 bool GetUseModuleCache() const;
47 bool SetUseModuleCache(bool use_module_cache);
49 FileSpec GetModuleCacheDirectory() const;
50 bool SetModuleCacheDirectory(const FileSpec &dir_spec);
53 typedef std::shared_ptr<PlatformProperties> PlatformPropertiesSP;
54 typedef llvm::SmallVector<lldb::addr_t, 6> MmapArgList;
56 /// \class Platform Platform.h "lldb/Target/Platform.h"
57 /// A plug-in interface definition class for debug platform that
58 /// includes many platform abilities such as:
59 /// \li getting platform information such as supported architectures,
60 /// supported binary file formats and more
61 /// \li launching new processes
62 /// \li attaching to existing processes
63 /// \li download/upload files
64 /// \li execute shell commands
65 /// \li listing and getting info for existing processes
66 /// \li attaching and possibly debugging the platform's kernel
67 class Platform : public PluginInterface {
69 /// Default Constructor
70 Platform(bool is_host_platform);
74 /// The destructor is virtual since this class is designed to be inherited
75 /// from by the plug-in instance.
78 static void Initialize();
80 static void Terminate();
82 static const PlatformPropertiesSP &GetGlobalPlatformProperties();
84 /// Get the native host platform plug-in.
86 /// There should only be one of these for each host that LLDB runs upon that
87 /// should be statically compiled in and registered using preprocessor
88 /// macros or other similar build mechanisms in a
89 /// PlatformSubclass::Initialize() function.
91 /// This platform will be used as the default platform when launching or
92 /// attaching to processes unless another platform is specified.
93 static lldb::PlatformSP GetHostPlatform();
95 static lldb::PlatformSP
96 GetPlatformForArchitecture(const ArchSpec &arch, ArchSpec *platform_arch_ptr);
98 static const char *GetHostPlatformName();
100 static void SetHostPlatform(const lldb::PlatformSP &platform_sp);
102 // Find an existing platform plug-in by name
103 static lldb::PlatformSP Find(ConstString name);
105 static lldb::PlatformSP Create(ConstString name, Status &error);
107 static lldb::PlatformSP Create(const ArchSpec &arch,
108 ArchSpec *platform_arch_ptr, Status &error);
110 /// Augments the triple either with information from platform or the host
111 /// system (if platform is null).
112 static ArchSpec GetAugmentedArchSpec(Platform *platform,
113 llvm::StringRef triple);
115 /// Find a platform plugin for a given process.
117 /// Scans the installed Platform plug-ins and tries to find an instance that
118 /// can be used for \a process
120 /// \param[in] process
121 /// The process for which to try and locate a platform
122 /// plug-in instance.
124 /// \param[in] plugin_name
125 /// An optional name of a specific platform plug-in that
126 /// should be used. If nullptr, pick the best plug-in.
127 // static lldb::PlatformSP
128 // FindPlugin (Process *process, ConstString plugin_name);
130 /// Set the target's executable based off of the existing architecture
131 /// information in \a target given a path to an executable \a exe_file.
133 /// Each platform knows the architectures that it supports and can select
134 /// the correct architecture slice within \a exe_file by inspecting the
135 /// architecture in \a target. If the target had an architecture specified,
136 /// then in can try and obey that request and optionally fail if the
137 /// architecture doesn't match up. If no architecture is specified, the
138 /// platform should select the default architecture from \a exe_file. Any
139 /// application bundles or executable wrappers can also be inspected for the
140 /// actual application binary within the bundle that should be used.
143 /// Returns \b true if this Platform plug-in was able to find
144 /// a suitable executable, \b false otherwise.
145 virtual Status ResolveExecutable(const ModuleSpec &module_spec,
146 lldb::ModuleSP &module_sp,
147 const FileSpecList *module_search_paths_ptr);
149 /// Find a symbol file given a symbol file module specification.
151 /// Each platform might have tricks to find symbol files for an executable
152 /// given information in a symbol file ModuleSpec. Some platforms might also
153 /// support symbol files that are bundles and know how to extract the right
154 /// symbol file given a bundle.
156 /// \param[in] target
157 /// The target in which we are trying to resolve the symbol file.
158 /// The target has a list of modules that we might be able to
159 /// use in order to help find the right symbol file. If the
160 /// "m_file" or "m_platform_file" entries in the \a sym_spec
161 /// are filled in, then we might be able to locate a module in
162 /// the target, extract its UUID and locate a symbol file.
163 /// If just the "m_uuid" is specified, then we might be able
164 /// to find the module in the target that matches that UUID
165 /// and pair the symbol file along with it. If just "m_symbol_file"
166 /// is specified, we can use a variety of tricks to locate the
167 /// symbols in an SDK, PDK, or other development kit location.
169 /// \param[in] sym_spec
170 /// A module spec that describes some information about the
171 /// symbol file we are trying to resolve. The ModuleSpec might
172 /// contain the following:
173 /// m_file - A full or partial path to an executable from the
174 /// target (might be empty).
175 /// m_platform_file - Another executable hint that contains
176 /// the path to the file as known on the
177 /// local/remote platform.
178 /// m_symbol_file - A full or partial path to a symbol file
179 /// or symbol bundle that should be used when
180 /// trying to resolve the symbol file.
181 /// m_arch - The architecture we are looking for when resolving
183 /// m_uuid - The UUID of the executable and symbol file. This
184 /// can often be used to match up an executable with
185 /// a symbol file, or resolve an symbol file in a
186 /// symbol file bundle.
188 /// \param[out] sym_file
189 /// The resolved symbol file spec if the returned error
190 /// indicates success.
193 /// Returns an error that describes success or failure.
194 virtual Status ResolveSymbolFile(Target &target, const ModuleSpec &sym_spec,
197 /// Resolves the FileSpec to a (possibly) remote path. Remote platforms must
198 /// override this to resolve to a path on the remote side.
199 virtual bool ResolveRemotePath(const FileSpec &platform_path,
200 FileSpec &resolved_platform_path);
202 /// Get the OS version from a connected platform.
204 /// Some platforms might not be connected to a remote platform, but can
205 /// figure out the OS version for a process. This is common for simulator
206 /// platforms that will run native programs on the current host, but the
207 /// simulator might be simulating a different OS. The \a process parameter
208 /// might be specified to help to determine the OS version.
209 virtual llvm::VersionTuple GetOSVersion(Process *process = nullptr);
211 bool SetOSVersion(llvm::VersionTuple os_version);
213 bool GetOSBuildString(std::string &s);
215 bool GetOSKernelDescription(std::string &s);
217 // Returns the name of the platform
218 ConstString GetName();
220 virtual const char *GetHostname();
222 virtual ConstString GetFullNameForDylib(ConstString basename);
224 virtual const char *GetDescription() = 0;
226 /// Report the current status for this platform.
228 /// The returned string usually involves returning the OS version (if
229 /// available), and any SDK directory that might be being used for local
230 /// file caching, and if connected a quick blurb about what this platform is
232 virtual void GetStatus(Stream &strm);
234 // Subclasses must be able to fetch the current OS version
236 // Remote classes must be connected for this to succeed. Local subclasses
237 // don't need to override this function as it will just call the
238 // HostInfo::GetOSVersion().
239 virtual bool GetRemoteOSVersion() { return false; }
241 virtual bool GetRemoteOSBuildString(std::string &s) {
246 virtual bool GetRemoteOSKernelDescription(std::string &s) {
251 // Remote Platform subclasses need to override this function
252 virtual ArchSpec GetRemoteSystemArchitecture() {
253 return ArchSpec(); // Return an invalid architecture
256 virtual FileSpec GetRemoteWorkingDirectory() { return m_working_dir; }
258 virtual bool SetRemoteWorkingDirectory(const FileSpec &working_dir);
260 /// Retrieve the system include directories on this platform for the
264 /// The language for which the include directories should be queried.
266 /// \param[out] directories
267 /// The include directories for this system.
268 virtual std::vector<std::string>
269 GetSystemIncludeDirectories(lldb::LanguageType lang) {
273 virtual UserIDResolver &GetUserIDResolver() = 0;
275 /// Locate a file for a platform.
277 /// The default implementation of this function will return the same file
278 /// patch in \a local_file as was in \a platform_file.
280 /// \param[in] platform_file
281 /// The platform file path to locate and cache locally.
283 /// \param[in] uuid_ptr
284 /// If we know the exact UUID of the file we are looking for, it
285 /// can be specified. If it is not specified, we might now know
286 /// the exact file. The UUID is usually some sort of MD5 checksum
287 /// for the file and is sometimes known by dynamic linkers/loaders.
288 /// If the UUID is known, it is best to supply it to platform
289 /// file queries to ensure we are finding the correct file, not
290 /// just a file at the correct path.
292 /// \param[out] local_file
293 /// A locally cached version of the platform file. For platforms
294 /// that describe the current host computer, this will just be
295 /// the same file. For remote platforms, this file might come from
296 /// and SDK directory, or might need to be sync'ed over to the
297 /// current machine for efficient debugging access.
301 virtual Status GetFileWithUUID(const FileSpec &platform_file,
302 const UUID *uuid_ptr, FileSpec &local_file);
304 // Locate the scripting resource given a module specification.
306 // Locating the file should happen only on the local computer or using the
307 // current computers global settings.
309 LocateExecutableScriptingResources(Target *target, Module &module,
310 Stream *feedback_stream);
312 virtual Status GetSharedModule(const ModuleSpec &module_spec,
313 Process *process, lldb::ModuleSP &module_sp,
314 const FileSpecList *module_search_paths_ptr,
315 lldb::ModuleSP *old_module_sp_ptr,
316 bool *did_create_ptr);
318 virtual bool GetModuleSpec(const FileSpec &module_file_spec,
319 const ArchSpec &arch, ModuleSpec &module_spec);
321 virtual Status ConnectRemote(Args &args);
323 virtual Status DisconnectRemote();
325 /// Get the platform's supported architectures in the order in which they
326 /// should be searched.
329 /// A zero based architecture index
332 /// A copy of the architecture at index if the return value is
336 /// \b true if \a arch was filled in and is valid, \b false
338 virtual bool GetSupportedArchitectureAtIndex(uint32_t idx,
341 virtual size_t GetSoftwareBreakpointTrapOpcode(Target &target,
342 BreakpointSite *bp_site);
344 /// Launch a new process on a platform, not necessarily for debugging, it
345 /// could be just for running the process.
346 virtual Status LaunchProcess(ProcessLaunchInfo &launch_info);
348 /// Perform expansion of the command-line for this launch info This can
349 /// potentially involve wildcard expansion
350 /// environment variable replacement, and whatever other
351 /// argument magic the platform defines as part of its typical
353 virtual Status ShellExpandArguments(ProcessLaunchInfo &launch_info);
355 /// Kill process on a platform.
356 virtual Status KillProcess(const lldb::pid_t pid);
358 /// Lets a platform answer if it is compatible with a given architecture and
359 /// the target triple contained within.
360 virtual bool IsCompatibleArchitecture(const ArchSpec &arch,
361 bool exact_arch_match,
362 ArchSpec *compatible_arch_ptr);
364 /// Not all platforms will support debugging a process by spawning somehow
365 /// halted for a debugger (specified using the "eLaunchFlagDebug" launch
366 /// flag) and then attaching. If your platform doesn't support this,
367 /// override this function and return false.
368 virtual bool CanDebugProcess() { return true; }
370 /// Subclasses do not need to implement this function as it uses the
371 /// Platform::LaunchProcess() followed by Platform::Attach (). Remote
372 /// platforms will want to subclass this function in order to be able to
373 /// intercept STDIO and possibly launch a separate process that will debug
375 virtual lldb::ProcessSP
376 DebugProcess(ProcessLaunchInfo &launch_info, Debugger &debugger,
377 Target *target, // Can be nullptr, if nullptr create a new
378 // target, else use existing one
381 virtual lldb::ProcessSP ConnectProcess(llvm::StringRef connect_url,
382 llvm::StringRef plugin_name,
383 lldb_private::Debugger &debugger,
384 lldb_private::Target *target,
385 lldb_private::Status &error);
387 /// Attach to an existing process using a process ID.
389 /// Each platform subclass needs to implement this function and attempt to
390 /// attach to the process with the process ID of \a pid. The platform
391 /// subclass should return an appropriate ProcessSP subclass that is
392 /// attached to the process, or an empty shared pointer with an appropriate
396 /// The process ID that we should attempt to attach to.
399 /// An appropriate ProcessSP containing a valid shared pointer
400 /// to the default Process subclass for the platform that is
401 /// attached to the process, or an empty shared pointer with an
402 /// appropriate error fill into the \a error object.
403 virtual lldb::ProcessSP Attach(ProcessAttachInfo &attach_info,
405 Target *target, // Can be nullptr, if nullptr
406 // create a new target, else
410 /// Attach to an existing process by process name.
412 /// This function is not meant to be overridden by Process subclasses. It
413 /// will first call Process::WillAttach (const char *) and if that returns
414 /// \b true, Process::DoAttach (const char *) will be called to actually do
415 /// the attach. If DoAttach returns \b true, then Process::DidAttach() will
418 /// \param[in] process_name
419 /// A process name to match against the current process list.
422 /// Returns \a pid if attaching was successful, or
423 /// LLDB_INVALID_PROCESS_ID if attaching fails.
424 // virtual lldb::ProcessSP
425 // Attach (const char *process_name,
426 // bool wait_for_launch,
427 // Status &error) = 0;
429 // The base class Platform will take care of the host platform. Subclasses
430 // will need to fill in the remote case.
431 virtual uint32_t FindProcesses(const ProcessInstanceInfoMatch &match_info,
432 ProcessInstanceInfoList &proc_infos);
434 virtual bool GetProcessInfo(lldb::pid_t pid, ProcessInstanceInfo &proc_info);
436 // Set a breakpoint on all functions that can end up creating a thread for
437 // this platform. This is needed when running expressions and also for
439 virtual lldb::BreakpointSP SetThreadCreationBreakpoint(Target &target);
441 // Given a target, find the local SDK directory if one exists on the current
443 virtual lldb_private::ConstString
444 GetSDKDirectory(lldb_private::Target &target) {
445 return lldb_private::ConstString();
448 const std::string &GetRemoteURL() const { return m_remote_url; }
450 bool IsHost() const {
451 return m_is_host; // Is this the default host platform?
454 bool IsRemote() const { return !m_is_host; }
456 virtual bool IsConnected() const {
457 // Remote subclasses should override this function
461 const ArchSpec &GetSystemArchitecture();
463 void SetSystemArchitecture(const ArchSpec &arch) {
464 m_system_arch = arch;
466 m_os_version_set_while_connected = m_system_arch.IsValid();
469 /// If the triple contains not specify the vendor, os, and environment
470 /// parts, we "augment" these using information from the platform and return
471 /// the resulting ArchSpec object.
472 ArchSpec GetAugmentedArchSpec(llvm::StringRef triple);
474 // Used for column widths
475 size_t GetMaxUserIDNameLength() const { return m_max_uid_name_len; }
477 // Used for column widths
478 size_t GetMaxGroupIDNameLength() const { return m_max_gid_name_len; }
480 ConstString GetSDKRootDirectory() const { return m_sdk_sysroot; }
482 void SetSDKRootDirectory(ConstString dir) { m_sdk_sysroot = dir; }
484 ConstString GetSDKBuild() const { return m_sdk_build; }
486 void SetSDKBuild(ConstString sdk_build) { m_sdk_build = sdk_build; }
488 // Override this to return true if your platform supports Clang modules. You
489 // may also need to override AddClangModuleCompilationOptions to pass the
490 // right Clang flags for your platform.
491 virtual bool SupportsModules() { return false; }
493 // Appends the platform-specific options required to find the modules for the
496 AddClangModuleCompilationOptions(Target *target,
497 std::vector<std::string> &options);
499 FileSpec GetWorkingDirectory();
501 bool SetWorkingDirectory(const FileSpec &working_dir);
503 // There may be modules that we don't want to find by default for operations
504 // like "setting breakpoint by name". The platform will return "true" from
505 // this call if the passed in module happens to be one of these.
508 ModuleIsExcludedForUnconstrainedSearches(Target &target,
509 const lldb::ModuleSP &module_sp) {
513 virtual Status MakeDirectory(const FileSpec &file_spec, uint32_t permissions);
515 virtual Status GetFilePermissions(const FileSpec &file_spec,
516 uint32_t &file_permissions);
518 virtual Status SetFilePermissions(const FileSpec &file_spec,
519 uint32_t file_permissions);
521 virtual lldb::user_id_t OpenFile(const FileSpec &file_spec, uint32_t flags,
522 uint32_t mode, Status &error) {
526 virtual bool CloseFile(lldb::user_id_t fd, Status &error) { return false; }
528 virtual lldb::user_id_t GetFileSize(const FileSpec &file_spec) {
532 virtual uint64_t ReadFile(lldb::user_id_t fd, uint64_t offset, void *dst,
533 uint64_t dst_len, Status &error) {
534 error.SetErrorStringWithFormat(
535 "Platform::ReadFile() is not supported in the %s platform",
536 GetName().GetCString());
540 virtual uint64_t WriteFile(lldb::user_id_t fd, uint64_t offset,
541 const void *src, uint64_t src_len, Status &error) {
542 error.SetErrorStringWithFormat(
543 "Platform::WriteFile() is not supported in the %s platform",
544 GetName().GetCString());
548 virtual Status GetFile(const FileSpec &source, const FileSpec &destination);
550 virtual Status PutFile(const FileSpec &source, const FileSpec &destination,
551 uint32_t uid = UINT32_MAX, uint32_t gid = UINT32_MAX);
554 CreateSymlink(const FileSpec &src, // The name of the link is in src
555 const FileSpec &dst); // The symlink points to dst
557 /// Install a file or directory to the remote system.
559 /// Install is similar to Platform::PutFile(), but it differs in that if an
560 /// application/framework/shared library is installed on a remote platform
561 /// and the remote platform requires something to be done to register the
562 /// application/framework/shared library, then this extra registration can
566 /// The source file/directory to install on the remote system.
569 /// The destination file/directory where \a src will be installed.
570 /// If \a dst has no filename specified, then its filename will
571 /// be set from \a src. It \a dst has no directory specified, it
572 /// will use the platform working directory. If \a dst has a
573 /// directory specified, but the directory path is relative, the
574 /// platform working directory will be prepended to the relative
578 /// An error object that describes anything that went wrong.
579 virtual Status Install(const FileSpec &src, const FileSpec &dst);
581 virtual Environment GetEnvironment();
583 virtual bool GetFileExists(const lldb_private::FileSpec &file_spec);
585 virtual Status Unlink(const FileSpec &file_spec);
587 virtual MmapArgList GetMmapArgumentList(const ArchSpec &arch,
590 unsigned prot, unsigned flags,
591 lldb::addr_t fd, lldb::addr_t offset);
593 virtual bool GetSupportsRSync() { return m_supports_rsync; }
595 virtual void SetSupportsRSync(bool flag) { m_supports_rsync = flag; }
597 virtual const char *GetRSyncOpts() { return m_rsync_opts.c_str(); }
599 virtual void SetRSyncOpts(const char *opts) { m_rsync_opts.assign(opts); }
601 virtual const char *GetRSyncPrefix() { return m_rsync_prefix.c_str(); }
603 virtual void SetRSyncPrefix(const char *prefix) {
604 m_rsync_prefix.assign(prefix);
607 virtual bool GetSupportsSSH() { return m_supports_ssh; }
609 virtual void SetSupportsSSH(bool flag) { m_supports_ssh = flag; }
611 virtual const char *GetSSHOpts() { return m_ssh_opts.c_str(); }
613 virtual void SetSSHOpts(const char *opts) { m_ssh_opts.assign(opts); }
615 virtual bool GetIgnoresRemoteHostname() { return m_ignores_remote_hostname; }
617 virtual void SetIgnoresRemoteHostname(bool flag) {
618 m_ignores_remote_hostname = flag;
621 virtual lldb_private::OptionGroupOptions *
622 GetConnectionOptions(CommandInterpreter &interpreter) {
626 virtual lldb_private::Status RunShellCommand(
627 const char *command, // Shouldn't be nullptr
628 const FileSpec &working_dir, // Pass empty FileSpec to use the current
630 int *status_ptr, // Pass nullptr if you don't want the process exit status
631 int *signo_ptr, // Pass nullptr if you don't want the signal that caused
632 // the process to exit
634 *command_output, // Pass nullptr if you don't want the command output
635 const Timeout<std::micro> &timeout);
637 virtual void SetLocalCacheDirectory(const char *local);
639 virtual const char *GetLocalCacheDirectory();
641 virtual std::string GetPlatformSpecificConnectionInformation() { return ""; }
643 virtual bool CalculateMD5(const FileSpec &file_spec, uint64_t &low,
646 virtual int32_t GetResumeCountForLaunchInfo(ProcessLaunchInfo &launch_info) {
650 virtual const lldb::UnixSignalsSP &GetRemoteUnixSignals();
652 lldb::UnixSignalsSP GetUnixSignals();
654 /// Locate a queue name given a thread's qaddr
656 /// On a system using libdispatch ("Grand Central Dispatch") style queues, a
657 /// thread may be associated with a GCD queue or not, and a queue may be
658 /// associated with multiple threads. The process/thread must provide a way
659 /// to find the "dispatch_qaddr" for each thread, and from that
660 /// dispatch_qaddr this Platform method will locate the queue name and
663 /// \param[in] process
664 /// A process is required for reading memory.
666 /// \param[in] dispatch_qaddr
667 /// The dispatch_qaddr for this thread.
670 /// The name of the queue, if there is one. An empty string
671 /// means that this thread is not associated with a dispatch
674 GetQueueNameForThreadQAddress(Process *process, lldb::addr_t dispatch_qaddr) {
678 /// Locate a queue ID given a thread's qaddr
680 /// On a system using libdispatch ("Grand Central Dispatch") style queues, a
681 /// thread may be associated with a GCD queue or not, and a queue may be
682 /// associated with multiple threads. The process/thread must provide a way
683 /// to find the "dispatch_qaddr" for each thread, and from that
684 /// dispatch_qaddr this Platform method will locate the queue ID and provide
687 /// \param[in] process
688 /// A process is required for reading memory.
690 /// \param[in] dispatch_qaddr
691 /// The dispatch_qaddr for this thread.
694 /// The queue_id for this thread, if this thread is associated
695 /// with a dispatch queue. Else LLDB_INVALID_QUEUE_ID is returned.
696 virtual lldb::queue_id_t
697 GetQueueIDForThreadQAddress(Process *process, lldb::addr_t dispatch_qaddr) {
698 return LLDB_INVALID_QUEUE_ID;
701 /// Provide a list of trap handler function names for this platform
703 /// The unwinder needs to treat trap handlers specially -- the stack frame
704 /// may not be aligned correctly for a trap handler (the kernel often won't
705 /// perturb the stack pointer, or won't re-align it properly, in the process
706 /// of calling the handler) and the frame above the handler needs to be
707 /// treated by the unwinder's "frame 0" rules instead of its "middle of the
708 /// stack frame" rules.
710 /// In a user process debugging scenario, the list of trap handlers is
711 /// typically just "_sigtramp".
713 /// The Platform base class provides the m_trap_handlers ivar but it does
714 /// not populate it. Subclasses should add the names of the asynchronous
715 /// signal handler routines as needed. For most Unix platforms, add
719 /// A list of symbol names. The list may be empty.
720 virtual const std::vector<ConstString> &GetTrapHandlerSymbolNames();
722 /// Find a support executable that may not live within in the standard
723 /// locations related to LLDB.
725 /// Executable might exist within the Platform SDK directories, or in
726 /// standard tool directories within the current IDE that is running LLDB.
728 /// \param[in] basename
729 /// The basename of the executable to locate in the current
733 /// A FileSpec pointing to the executable on disk, or an invalid
734 /// FileSpec if the executable cannot be found.
735 virtual FileSpec LocateExecutable(const char *basename) { return FileSpec(); }
737 /// Allow the platform to set preferred memory cache line size. If non-zero
738 /// (and the user has not set cache line size explicitly), this value will
739 /// be used as the cache line size for memory reads.
740 virtual uint32_t GetDefaultMemoryCacheLineSize() { return 0; }
742 /// Load a shared library into this process.
744 /// Try and load a shared library into the current process. This call might
745 /// fail in the dynamic loader plug-in says it isn't safe to try and load
746 /// shared libraries at the moment.
748 /// \param[in] process
749 /// The process to load the image.
751 /// \param[in] local_file
752 /// The file spec that points to the shared library that you want
753 /// to load if the library is located on the host. The library will
754 /// be copied over to the location specified by remote_file or into
755 /// the current working directory with the same filename if the
756 /// remote_file isn't specified.
758 /// \param[in] remote_file
759 /// If local_file is specified then the location where the library
760 /// should be copied over from the host. If local_file isn't
761 /// specified, then the path for the shared library on the target
762 /// what you want to load.
764 /// \param[out] error
765 /// An error object that gets filled in with any errors that
766 /// might occur when trying to load the shared library.
769 /// A token that represents the shared library that can be
770 /// later used to unload the shared library. A value of
771 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
772 /// library can't be opened.
773 uint32_t LoadImage(lldb_private::Process *process,
774 const lldb_private::FileSpec &local_file,
775 const lldb_private::FileSpec &remote_file,
776 lldb_private::Status &error);
778 /// Load a shared library specified by base name into this process,
779 /// looking by hand along a set of paths.
781 /// \param[in] process
782 /// The process to load the image.
784 /// \param[in] library_name
785 /// The name of the library to look for. If library_name is an
786 /// absolute path, the basename will be extracted and searched for
787 /// along the paths. This emulates the behavior of the loader when
788 /// given an install name and a set (e.g. DYLD_LIBRARY_PATH provided) of
791 /// \param[in] path_list
792 /// The list of paths to use to search for the library. First
795 /// \param[out] error
796 /// An error object that gets filled in with any errors that
797 /// might occur when trying to load the shared library.
799 /// \param[out] loaded_path
800 /// If non-null, the path to the dylib that was successfully loaded
801 /// is stored in this path.
804 /// A token that represents the shared library which can be
805 /// passed to UnloadImage. A value of
806 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared
807 /// library can't be opened.
808 uint32_t LoadImageUsingPaths(lldb_private::Process *process,
809 const lldb_private::FileSpec &library_name,
810 const std::vector<std::string> &paths,
811 lldb_private::Status &error,
812 lldb_private::FileSpec *loaded_path);
814 virtual uint32_t DoLoadImage(lldb_private::Process *process,
815 const lldb_private::FileSpec &remote_file,
816 const std::vector<std::string> *paths,
817 lldb_private::Status &error,
818 lldb_private::FileSpec *loaded_path = nullptr);
820 virtual Status UnloadImage(lldb_private::Process *process,
821 uint32_t image_token);
823 /// Connect to all processes waiting for a debugger to attach
825 /// If the platform have a list of processes waiting for a debugger to
826 /// connect to them then connect to all of these pending processes.
828 /// \param[in] debugger
829 /// The debugger used for the connect.
831 /// \param[out] error
832 /// If an error occurred during the connect then this object will
833 /// contain the error message.
836 /// The number of processes we are successfully connected to.
837 virtual size_t ConnectToWaitingProcesses(lldb_private::Debugger &debugger,
838 lldb_private::Status &error);
842 // Set to true when we are able to actually set the OS version while being
843 // connected. For remote platforms, we might set the version ahead of time
844 // before we actually connect and this version might change when we actually
845 // connect to a remote platform. For the host platform this will be set to
846 // the once we call HostInfo::GetOSVersion().
847 bool m_os_version_set_while_connected;
848 bool m_system_arch_set_while_connected;
850 m_sdk_sysroot; // the root location of where the SDK files are all located
851 ConstString m_sdk_build;
852 FileSpec m_working_dir; // The working directory which is used when installing
853 // modules that have no install path set
854 std::string m_remote_url;
856 llvm::VersionTuple m_os_version;
858 m_system_arch; // The architecture of the kernel or the remote platform
859 typedef std::map<uint32_t, ConstString> IDToNameMap;
860 // Mutex for modifying Platform data structures that should only be used for
861 // non-reentrant code
863 size_t m_max_uid_name_len;
864 size_t m_max_gid_name_len;
865 bool m_supports_rsync;
866 std::string m_rsync_opts;
867 std::string m_rsync_prefix;
869 std::string m_ssh_opts;
870 bool m_ignores_remote_hostname;
871 std::string m_local_cache_directory;
872 std::vector<ConstString> m_trap_handlers;
873 bool m_calculated_trap_handlers;
874 const std::unique_ptr<ModuleCache> m_module_cache;
876 /// Ask the Platform subclass to fill in the list of trap handler names
878 /// For most Unix user process environments, this will be a single function
879 /// name, _sigtramp. More specialized environments may have additional
880 /// handler names. The unwinder code needs to know when a trap handler is
881 /// on the stack because the unwind rules for the frame that caused the trap
884 /// The base class Platform ivar m_trap_handlers should be updated by the
885 /// Platform subclass when this method is called. If there are no
886 /// predefined trap handlers, this method may be a no-op.
887 virtual void CalculateTrapHandlerSymbolNames() = 0;
889 Status GetCachedExecutable(ModuleSpec &module_spec, lldb::ModuleSP &module_sp,
890 const FileSpecList *module_search_paths_ptr,
891 Platform &remote_platform);
893 virtual Status DownloadModuleSlice(const FileSpec &src_file_spec,
894 const uint64_t src_offset,
895 const uint64_t src_size,
896 const FileSpec &dst_file_spec);
898 virtual Status DownloadSymbolFile(const lldb::ModuleSP &module_sp,
899 const FileSpec &dst_file_spec);
901 virtual const char *GetCacheHostname();
904 typedef std::function<Status(const ModuleSpec &)> ModuleResolver;
906 Status GetRemoteSharedModule(const ModuleSpec &module_spec, Process *process,
907 lldb::ModuleSP &module_sp,
908 const ModuleResolver &module_resolver,
909 bool *did_create_ptr);
911 bool GetCachedSharedModule(const ModuleSpec &module_spec,
912 lldb::ModuleSP &module_sp, bool *did_create_ptr);
914 Status LoadCachedExecutable(const ModuleSpec &module_spec,
915 lldb::ModuleSP &module_sp,
916 const FileSpecList *module_search_paths_ptr,
917 Platform &remote_platform);
919 FileSpec GetModuleCacheRoot();
921 DISALLOW_COPY_AND_ASSIGN(Platform);
926 PlatformList() : m_mutex(), m_platforms(), m_selected_platform_sp() {}
928 ~PlatformList() = default;
930 void Append(const lldb::PlatformSP &platform_sp, bool set_selected) {
931 std::lock_guard<std::recursive_mutex> guard(m_mutex);
932 m_platforms.push_back(platform_sp);
934 m_selected_platform_sp = m_platforms.back();
938 std::lock_guard<std::recursive_mutex> guard(m_mutex);
939 return m_platforms.size();
942 lldb::PlatformSP GetAtIndex(uint32_t idx) {
943 lldb::PlatformSP platform_sp;
945 std::lock_guard<std::recursive_mutex> guard(m_mutex);
946 if (idx < m_platforms.size())
947 platform_sp = m_platforms[idx];
952 /// Select the active platform.
954 /// In order to debug remotely, other platform's can be remotely connected
955 /// to and set as the selected platform for any subsequent debugging. This
956 /// allows connection to remote targets and allows the ability to discover
957 /// process info, launch and attach to remote processes.
958 lldb::PlatformSP GetSelectedPlatform() {
959 std::lock_guard<std::recursive_mutex> guard(m_mutex);
960 if (!m_selected_platform_sp && !m_platforms.empty())
961 m_selected_platform_sp = m_platforms.front();
963 return m_selected_platform_sp;
966 void SetSelectedPlatform(const lldb::PlatformSP &platform_sp) {
968 std::lock_guard<std::recursive_mutex> guard(m_mutex);
969 const size_t num_platforms = m_platforms.size();
970 for (size_t idx = 0; idx < num_platforms; ++idx) {
971 if (m_platforms[idx].get() == platform_sp.get()) {
972 m_selected_platform_sp = m_platforms[idx];
976 m_platforms.push_back(platform_sp);
977 m_selected_platform_sp = m_platforms.back();
982 typedef std::vector<lldb::PlatformSP> collection;
983 mutable std::recursive_mutex m_mutex;
984 collection m_platforms;
985 lldb::PlatformSP m_selected_platform_sp;
988 DISALLOW_COPY_AND_ASSIGN(PlatformList);
991 class OptionGroupPlatformRSync : public lldb_private::OptionGroup {
993 OptionGroupPlatformRSync() = default;
995 ~OptionGroupPlatformRSync() override = default;
998 SetOptionValue(uint32_t option_idx, llvm::StringRef option_value,
999 ExecutionContext *execution_context) override;
1001 void OptionParsingStarting(ExecutionContext *execution_context) override;
1003 llvm::ArrayRef<OptionDefinition> GetDefinitions() override;
1005 // Instance variables to hold the values for command options.
1008 std::string m_rsync_opts;
1009 std::string m_rsync_prefix;
1010 bool m_ignores_remote_hostname;
1013 DISALLOW_COPY_AND_ASSIGN(OptionGroupPlatformRSync);
1016 class OptionGroupPlatformSSH : public lldb_private::OptionGroup {
1018 OptionGroupPlatformSSH() = default;
1020 ~OptionGroupPlatformSSH() override = default;
1022 lldb_private::Status
1023 SetOptionValue(uint32_t option_idx, llvm::StringRef option_value,
1024 ExecutionContext *execution_context) override;
1026 void OptionParsingStarting(ExecutionContext *execution_context) override;
1028 llvm::ArrayRef<OptionDefinition> GetDefinitions() override;
1030 // Instance variables to hold the values for command options.
1033 std::string m_ssh_opts;
1036 DISALLOW_COPY_AND_ASSIGN(OptionGroupPlatformSSH);
1039 class OptionGroupPlatformCaching : public lldb_private::OptionGroup {
1041 OptionGroupPlatformCaching() = default;
1043 ~OptionGroupPlatformCaching() override = default;
1045 lldb_private::Status
1046 SetOptionValue(uint32_t option_idx, llvm::StringRef option_value,
1047 ExecutionContext *execution_context) override;
1049 void OptionParsingStarting(ExecutionContext *execution_context) override;
1051 llvm::ArrayRef<OptionDefinition> GetDefinitions() override;
1053 // Instance variables to hold the values for command options.
1055 std::string m_cache_dir;
1058 DISALLOW_COPY_AND_ASSIGN(OptionGroupPlatformCaching);
1061 } // namespace lldb_private
1063 #endif // liblldb_Platform_h_