1 //===-- Platform.h ----------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_Platform_h_
11 #define liblldb_Platform_h_
19 // Other libraries and framework 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/Host/Mutex.h"
27 namespace lldb_private {
29 //----------------------------------------------------------------------
30 /// @class Platform Platform.h "lldb/Target/Platform.h"
31 /// @brief A plug-in interface definition class for debug platform that
32 /// includes many platform abilities such as:
33 /// @li getting platform information such as supported architectures,
34 /// supported binary file formats and more
35 /// @li launching new processes
36 /// @li attaching to existing processes
37 /// @li download/upload files
38 /// @li execute shell commands
39 /// @li listing and getting info for existing processes
40 /// @li attaching and possibly debugging the platform's kernel
41 //----------------------------------------------------------------------
42 class Platform : public PluginInterface
46 //------------------------------------------------------------------
47 /// Get the native host platform plug-in.
49 /// There should only be one of these for each host that LLDB runs
50 /// upon that should be statically compiled in and registered using
51 /// preprocessor macros or other similar build mechanisms in a
52 /// PlatformSubclass::Initialize() function.
54 /// This platform will be used as the default platform when launching
55 /// or attaching to processes unless another platform is specified.
56 //------------------------------------------------------------------
57 static lldb::PlatformSP
58 GetDefaultPlatform ();
60 static lldb::PlatformSP
61 GetPlatformForArchitecture (const ArchSpec &arch,
62 ArchSpec *platform_arch_ptr);
65 GetHostPlatformName ();
68 SetDefaultPlatform (const lldb::PlatformSP &platform_sp);
70 static lldb::PlatformSP
71 Create (const char *platform_name, Error &error);
73 static lldb::PlatformSP
74 Create (const ArchSpec &arch, ArchSpec *platform_arch_ptr, Error &error);
77 GetNumConnectedRemotePlatforms ();
79 static lldb::PlatformSP
80 GetConnectedRemotePlatformAtIndex (uint32_t idx);
82 //------------------------------------------------------------------
83 /// Default Constructor
84 //------------------------------------------------------------------
85 Platform (bool is_host_platform);
87 //------------------------------------------------------------------
90 /// The destructor is virtual since this class is designed to be
91 /// inherited from by the plug-in instance.
92 //------------------------------------------------------------------
96 //------------------------------------------------------------------
97 /// Find a platform plugin for a given process.
99 /// Scans the installed Platform plug-ins and tries to find
100 /// an instance that can be used for \a process
102 /// @param[in] process
103 /// The process for which to try and locate a platform
104 /// plug-in instance.
106 /// @param[in] plugin_name
107 /// An optional name of a specific platform plug-in that
108 /// should be used. If NULL, pick the best plug-in.
109 //------------------------------------------------------------------
111 FindPlugin (Process *process, const ConstString &plugin_name);
113 //------------------------------------------------------------------
114 /// Set the target's executable based off of the existing
115 /// architecture information in \a target given a path to an
116 /// executable \a exe_file.
118 /// Each platform knows the architectures that it supports and can
119 /// select the correct architecture slice within \a exe_file by
120 /// inspecting the architecture in \a target. If the target had an
121 /// architecture specified, then in can try and obey that request
122 /// and optionally fail if the architecture doesn't match up.
123 /// If no architecture is specified, the platform should select the
124 /// default architecture from \a exe_file. Any application bundles
125 /// or executable wrappers can also be inspected for the actual
126 /// application binary within the bundle that should be used.
129 /// Returns \b true if this Platform plug-in was able to find
130 /// a suitable executable, \b false otherwise.
131 //------------------------------------------------------------------
133 ResolveExecutable (const FileSpec &exe_file,
134 const ArchSpec &arch,
135 lldb::ModuleSP &module_sp,
136 const FileSpecList *module_search_paths_ptr);
139 //------------------------------------------------------------------
140 /// Find a symbol file given a symbol file module specification.
142 /// Each platform might have tricks to find symbol files for an
143 /// executable given information in a symbol file ModuleSpec. Some
144 /// platforms might also support symbol files that are bundles and
145 /// know how to extract the right symbol file given a bundle.
147 /// @param[in] target
148 /// The target in which we are trying to resolve the symbol file.
149 /// The target has a list of modules that we might be able to
150 /// use in order to help find the right symbol file. If the
151 /// "m_file" or "m_platform_file" entries in the \a sym_spec
152 /// are filled in, then we might be able to locate a module in
153 /// the target, extract its UUID and locate a symbol file.
154 /// If just the "m_uuid" is specified, then we might be able
155 /// to find the module in the target that matches that UUID
156 /// and pair the symbol file along with it. If just "m_symbol_file"
157 /// is specified, we can use a variety of tricks to locate the
158 /// symbols in an SDK, PDK, or other development kit location.
160 /// @param[in] sym_spec
161 /// A module spec that describes some information about the
162 /// symbol file we are trying to resolve. The ModuleSpec might
163 /// contain the following:
164 /// m_file - A full or partial path to an executable from the
165 /// target (might be empty).
166 /// m_platform_file - Another executable hint that contains
167 /// the path to the file as known on the
168 /// local/remote platform.
169 /// m_symbol_file - A full or partial path to a symbol file
170 /// or symbol bundle that should be used when
171 /// trying to resolve the symbol file.
172 /// m_arch - The architecture we are looking for when resolving
174 /// m_uuid - The UUID of the executable and symbol file. This
175 /// can often be used to match up an exectuable with
176 /// a symbol file, or resolve an symbol file in a
177 /// symbol file bundle.
179 /// @param[out] sym_file
180 /// The resolved symbol file spec if the returned error
181 /// indicates succes.
184 /// Returns an error that describes success or failure.
185 //------------------------------------------------------------------
187 ResolveSymbolFile (Target &target,
188 const ModuleSpec &sym_spec,
191 //------------------------------------------------------------------
192 /// Resolves the FileSpec to a (possibly) remote path. Remote
193 /// platforms must override this to resolve to a path on the remote
195 //------------------------------------------------------------------
197 ResolveRemotePath (const FileSpec &platform_path,
198 FileSpec &resolved_platform_path);
201 GetOSVersion (uint32_t &major,
206 SetOSVersion (uint32_t major,
211 GetOSBuildString (std::string &s);
214 GetOSKernelDescription (std::string &s);
216 // Returns the the hostname if we are connected, else the short plugin
225 GetDescription () = 0;
227 //------------------------------------------------------------------
228 /// Report the current status for this platform.
230 /// The returned string usually involves returning the OS version
231 /// (if available), and any SDK directory that might be being used
232 /// for local file caching, and if connected a quick blurb about
233 /// what this platform is connected to.
234 //------------------------------------------------------------------
236 GetStatus (Stream &strm);
238 //------------------------------------------------------------------
239 // Subclasses must be able to fetch the current OS version
241 // Remote classes must be connected for this to succeed. Local
242 // subclasses don't need to override this function as it will just
243 // call the Host::GetOSVersion().
244 //------------------------------------------------------------------
246 GetRemoteOSVersion ()
252 GetRemoteOSBuildString (std::string &s)
259 GetRemoteOSKernelDescription (std::string &s)
265 // Remote Platform subclasses need to override this function
267 GetRemoteSystemArchitecture ()
269 return ArchSpec(); // Return an invalid architecture
273 GetUserName (uint32_t uid);
276 GetGroupName (uint32_t gid);
278 //------------------------------------------------------------------
279 /// Locate a file for a platform.
281 /// The default implementation of this function will return the same
282 /// file patch in \a local_file as was in \a platform_file.
284 /// @param[in] platform_file
285 /// The platform file path to locate and cache locally.
287 /// @param[in] uuid_ptr
288 /// If we know the exact UUID of the file we are looking for, it
289 /// can be specified. If it is not specified, we might now know
290 /// the exact file. The UUID is usually some sort of MD5 checksum
291 /// for the file and is sometimes known by dynamic linkers/loaders.
292 /// If the UUID is known, it is best to supply it to platform
293 /// file queries to ensure we are finding the correct file, not
294 /// just a file at the correct path.
296 /// @param[out] local_file
297 /// A locally cached version of the platform file. For platforms
298 /// that describe the current host computer, this will just be
299 /// the same file. For remote platforms, this file might come from
300 /// and SDK directory, or might need to be sync'ed over to the
301 /// current machine for efficient debugging access.
305 //------------------------------------------------------------------
307 GetFile (const FileSpec &platform_file,
308 const UUID *uuid_ptr,
309 FileSpec &local_file);
311 //----------------------------------------------------------------------
312 // Locate the scripting resource given a module specification.
314 // Locating the file should happen only on the local computer or using
315 // the current computers global settings.
316 //----------------------------------------------------------------------
318 LocateExecutableScriptingResources (Target *target,
322 GetSharedModule (const ModuleSpec &module_spec,
323 lldb::ModuleSP &module_sp,
324 const FileSpecList *module_search_paths_ptr,
325 lldb::ModuleSP *old_module_sp_ptr,
326 bool *did_create_ptr);
329 ConnectRemote (Args& args);
334 //------------------------------------------------------------------
335 /// Get the platform's supported architectures in the order in which
336 /// they should be searched.
339 /// A zero based architecture index
342 /// A copy of the archgitecture at index if the return value is
346 /// \b true if \a arch was filled in and is valid, \b false
348 //------------------------------------------------------------------
350 GetSupportedArchitectureAtIndex (uint32_t idx, ArchSpec &arch) = 0;
353 GetSoftwareBreakpointTrapOpcode (Target &target,
354 BreakpointSite *bp_site) = 0;
356 //------------------------------------------------------------------
357 /// Launch a new process on a platform, not necessarily for
358 /// debugging, it could be just for running the process.
359 //------------------------------------------------------------------
361 LaunchProcess (ProcessLaunchInfo &launch_info);
363 //------------------------------------------------------------------
364 /// Lets a platform answer if it is compatible with a given
365 /// architecture and the target triple contained within.
366 //------------------------------------------------------------------
368 IsCompatibleArchitecture (const ArchSpec &arch,
369 bool exact_arch_match,
370 ArchSpec *compatible_arch_ptr);
372 //------------------------------------------------------------------
373 /// Not all platforms will support debugging a process by spawning
374 /// somehow halted for a debugger (specified using the
375 /// "eLaunchFlagDebug" launch flag) and then attaching. If your
376 /// platform doesn't support this, override this function and return
378 //------------------------------------------------------------------
385 //------------------------------------------------------------------
386 /// Subclasses should NOT need to implement this function as it uses
387 /// the Platform::LaunchProcess() followed by Platform::Attach ()
388 //------------------------------------------------------------------
390 DebugProcess (ProcessLaunchInfo &launch_info,
392 Target *target, // Can be NULL, if NULL create a new target, else use existing one
396 //------------------------------------------------------------------
397 /// Attach to an existing process using a process ID.
399 /// Each platform subclass needs to implement this function and
400 /// attempt to attach to the process with the process ID of \a pid.
401 /// The platform subclass should return an appropriate ProcessSP
402 /// subclass that is attached to the process, or an empty shared
403 /// pointer with an appriopriate error.
406 /// The process ID that we should attempt to attach to.
409 /// An appropriate ProcessSP containing a valid shared pointer
410 /// to the default Process subclass for the platform that is
411 /// attached to the process, or an empty shared pointer with an
412 /// appriopriate error fill into the \a error object.
413 //------------------------------------------------------------------
414 virtual lldb::ProcessSP
415 Attach (ProcessAttachInfo &attach_info,
417 Target *target, // Can be NULL, if NULL create a new target, else use existing one
421 //------------------------------------------------------------------
422 /// Attach to an existing process by process name.
424 /// This function is not meant to be overridden by Process
425 /// subclasses. It will first call
426 /// Process::WillAttach (const char *) and if that returns \b
427 /// true, Process::DoAttach (const char *) will be called to
428 /// actually do the attach. If DoAttach returns \b true, then
429 /// Process::DidAttach() will be called.
431 /// @param[in] process_name
432 /// A process name to match against the current process list.
435 /// Returns \a pid if attaching was successful, or
436 /// LLDB_INVALID_PROCESS_ID if attaching fails.
437 //------------------------------------------------------------------
438 // virtual lldb::ProcessSP
439 // Attach (const char *process_name,
440 // bool wait_for_launch,
441 // Error &error) = 0;
443 //------------------------------------------------------------------
444 // The base class Platform will take care of the host platform.
445 // Subclasses will need to fill in the remote case.
446 //------------------------------------------------------------------
448 FindProcesses (const ProcessInstanceInfoMatch &match_info,
449 ProcessInstanceInfoList &proc_infos);
452 GetProcessInfo (lldb::pid_t pid, ProcessInstanceInfo &proc_info);
454 //------------------------------------------------------------------
455 // Set a breakpoint on all functions that can end up creating a thread
456 // for this platform. This is needed when running expressions and
457 // also for process control.
458 //------------------------------------------------------------------
459 virtual lldb::BreakpointSP
460 SetThreadCreationBreakpoint (Target &target);
464 GetRemoteURL () const
472 return m_is_host; // Is this the default host platform?
484 // Remote subclasses should override this function
489 GetSystemArchitecture();
492 SetSystemArchitecture (const ArchSpec &arch)
494 m_system_arch = arch;
496 m_os_version_set_while_connected = m_system_arch.IsValid();
499 // Used for column widths
501 GetMaxUserIDNameLength() const
503 return m_max_uid_name_len;
505 // Used for column widths
507 GetMaxGroupIDNameLength() const
509 return m_max_gid_name_len;
513 GetSDKRootDirectory () const
515 return m_sdk_sysroot;
519 SetSDKRootDirectory (const ConstString &dir)
531 SetSDKBuild (const ConstString &sdk_build)
533 m_sdk_build = sdk_build;
536 // There may be modules that we don't want to find by default for operations like "setting breakpoint by name".
537 // The platform will return "true" from this call if the passed in module happens to be one of these.
540 ModuleIsExcludedForNonModuleSpecificSearches (Target &target, const lldb::ModuleSP &module_sp)
546 GetEnvironment (StringList &environment);
550 // Set to true when we are able to actually set the OS version while
551 // being connected. For remote platforms, we might set the version ahead
552 // of time before we actually connect and this version might change when
553 // we actually connect to a remote platform. For the host platform this
554 // will be set to the once we call Host::GetOSVersion().
555 bool m_os_version_set_while_connected;
556 bool m_system_arch_set_while_connected;
557 ConstString m_sdk_sysroot; // the root location of where the SDK files are all located
558 ConstString m_sdk_build;
559 std::string m_remote_url;
561 uint32_t m_major_os_version;
562 uint32_t m_minor_os_version;
563 uint32_t m_update_os_version;
564 ArchSpec m_system_arch; // The architecture of the kernel or the remote platform
565 typedef std::map<uint32_t, ConstString> IDToNameMap;
566 Mutex m_uid_map_mutex;
567 Mutex m_gid_map_mutex;
568 IDToNameMap m_uid_map;
569 IDToNameMap m_gid_map;
570 size_t m_max_uid_name_len;
571 size_t m_max_gid_name_len;
574 GetCachedUserName (uint32_t uid)
576 Mutex::Locker locker (m_uid_map_mutex);
577 IDToNameMap::iterator pos = m_uid_map.find (uid);
578 if (pos != m_uid_map.end())
580 // return the empty string if our string is NULL
581 // so we can tell when things were in the negative
582 // cached (didn't find a valid user name, don't keep
584 return pos->second.AsCString("");
590 SetCachedUserName (uint32_t uid, const char *name, size_t name_len)
592 Mutex::Locker locker (m_uid_map_mutex);
593 ConstString const_name (name);
594 m_uid_map[uid] = const_name;
595 if (m_max_uid_name_len < name_len)
596 m_max_uid_name_len = name_len;
597 // Const strings lives forever in our const string pool, so we can return the const char *
598 return const_name.GetCString();
602 SetUserNameNotFound (uint32_t uid)
604 Mutex::Locker locker (m_uid_map_mutex);
605 m_uid_map[uid] = ConstString();
610 ClearCachedUserNames ()
612 Mutex::Locker locker (m_uid_map_mutex);
617 GetCachedGroupName (uint32_t gid)
619 Mutex::Locker locker (m_gid_map_mutex);
620 IDToNameMap::iterator pos = m_gid_map.find (gid);
621 if (pos != m_gid_map.end())
623 // return the empty string if our string is NULL
624 // so we can tell when things were in the negative
625 // cached (didn't find a valid group name, don't keep
627 return pos->second.AsCString("");
633 SetCachedGroupName (uint32_t gid, const char *name, size_t name_len)
635 Mutex::Locker locker (m_gid_map_mutex);
636 ConstString const_name (name);
637 m_gid_map[gid] = const_name;
638 if (m_max_gid_name_len < name_len)
639 m_max_gid_name_len = name_len;
640 // Const strings lives forever in our const string pool, so we can return the const char *
641 return const_name.GetCString();
645 SetGroupNameNotFound (uint32_t gid)
647 Mutex::Locker locker (m_gid_map_mutex);
648 m_gid_map[gid] = ConstString();
652 ClearCachedGroupNames ()
654 Mutex::Locker locker (m_gid_map_mutex);
659 DISALLOW_COPY_AND_ASSIGN (Platform);
667 m_mutex (Mutex::eMutexTypeRecursive),
669 m_selected_platform_sp()
678 Append (const lldb::PlatformSP &platform_sp, bool set_selected)
680 Mutex::Locker locker (m_mutex);
681 m_platforms.push_back (platform_sp);
683 m_selected_platform_sp = m_platforms.back();
689 Mutex::Locker locker (m_mutex);
690 return m_platforms.size();
694 GetAtIndex (uint32_t idx)
696 lldb::PlatformSP platform_sp;
698 Mutex::Locker locker (m_mutex);
699 if (idx < m_platforms.size())
700 platform_sp = m_platforms[idx];
705 //------------------------------------------------------------------
706 /// Select the active platform.
708 /// In order to debug remotely, other platform's can be remotely
709 /// connected to and set as the selected platform for any subsequent
710 /// debugging. This allows connection to remote targets and allows
711 /// the ability to discover process info, launch and attach to remote
713 //------------------------------------------------------------------
715 GetSelectedPlatform ()
717 Mutex::Locker locker (m_mutex);
718 if (!m_selected_platform_sp && !m_platforms.empty())
719 m_selected_platform_sp = m_platforms.front();
721 return m_selected_platform_sp;
725 SetSelectedPlatform (const lldb::PlatformSP &platform_sp)
729 Mutex::Locker locker (m_mutex);
730 const size_t num_platforms = m_platforms.size();
731 for (size_t idx=0; idx<num_platforms; ++idx)
733 if (m_platforms[idx].get() == platform_sp.get())
735 m_selected_platform_sp = m_platforms[idx];
739 m_platforms.push_back (platform_sp);
740 m_selected_platform_sp = m_platforms.back();
745 typedef std::vector<lldb::PlatformSP> collection;
746 mutable Mutex m_mutex;
747 collection m_platforms;
748 lldb::PlatformSP m_selected_platform_sp;
751 DISALLOW_COPY_AND_ASSIGN (PlatformList);
753 } // namespace lldb_private
755 #endif // liblldb_Platform_h_