Platform.h revision b1888f24fa181489840b9acf193e224d125d0776
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 <string> 16#include <vector> 17 18// Other libraries and framework includes 19// Project includes 20#include "lldb/lldb-include.h" 21#include "lldb/Core/ArchSpec.h" 22#include "lldb/Core/PluginInterface.h" 23#include "lldb/Host/Mutex.h" 24 25namespace lldb_private { 26 27 //---------------------------------------------------------------------- 28 /// @class Platform Platform.h "lldb/Target/Platform.h" 29 /// @brief A plug-in interface definition class for debug platform that 30 /// includes many platform abilities such as: 31 /// @li getting platform information such as supported architectures, 32 /// supported binary file formats and more 33 /// @li launching new processes 34 /// @li attaching to existing processes 35 /// @li download/upload files 36 /// @li execute shell commands 37 /// @li listing and getting info for existing processes 38 /// @li attaching and possibly debugging the platform's kernel 39 //---------------------------------------------------------------------- 40 class Platform : public PluginInterface 41 { 42 public: 43 44 //------------------------------------------------------------------ 45 /// Get the native host platform plug-in. 46 /// 47 /// There should only be one of these for each host that LLDB runs 48 /// upon that should be statically compiled in and registered using 49 /// preprocessor macros or other similar build mechanisms in a 50 /// PlatformSubclass::Initialize() function. 51 /// 52 /// This platform will be used as the default platform when launching 53 /// or attaching to processes unless another platform is specified. 54 //------------------------------------------------------------------ 55 static lldb::PlatformSP 56 GetDefaultPlatform (); 57 58 static void 59 SetDefaultPlatform (const lldb::PlatformSP &platform_sp); 60 61 static lldb::PlatformSP 62 Create (const char *platform_name, Error &error); 63 64 static uint32_t 65 GetNumConnectedRemotePlatforms (); 66 67 static lldb::PlatformSP 68 GetConnectedRemotePlatformAtIndex (uint32_t idx); 69 70 //------------------------------------------------------------------ 71 /// Default Constructor 72 //------------------------------------------------------------------ 73 Platform (bool is_host_platform); 74 75 //------------------------------------------------------------------ 76 /// Destructor. 77 /// 78 /// The destructor is virtual since this class is designed to be 79 /// inherited from by the plug-in instance. 80 //------------------------------------------------------------------ 81 virtual 82 ~Platform(); 83 84 //------------------------------------------------------------------ 85 /// Set the target's executable based off of the existing 86 /// architecture information in \a target given a path to an 87 /// executable \a exe_file. 88 /// 89 /// Each platform knows the architectures that it supports and can 90 /// select the correct architecture slice within \a exe_file by 91 /// inspecting the architecture in \a target. If the target had an 92 /// architecture specified, then in can try and obey that request 93 /// and optionally fail if the architecture doesn't match up. 94 /// If no architecture is specified, the platform should select the 95 /// default architecture from \a exe_file. Any application bundles 96 /// or executable wrappers can also be inspected for the actual 97 /// application binary within the bundle that should be used. 98 /// 99 /// @return 100 /// Returns \b true if this Platform plug-in was able to find 101 /// a suitable executable, \b false otherwise. 102 //------------------------------------------------------------------ 103 virtual Error 104 ResolveExecutable (const FileSpec &exe_file, 105 const ArchSpec &arch, 106 lldb::ModuleSP &module_sp); 107 108 bool 109 GetOSVersion (uint32_t &major, 110 uint32_t &minor, 111 uint32_t &update); 112 113 bool 114 SetOSVersion (uint32_t major, 115 uint32_t minor, 116 uint32_t update); 117 118 virtual const char * 119 GetDescription () = 0; 120 121 //------------------------------------------------------------------ 122 /// Report the current status for this platform. 123 /// 124 /// The returned string usually involves returning the OS version 125 /// (if available), and any SDK directory that might be being used 126 /// for local file caching, and if connected a quick blurb about 127 /// what this platform is connected to. 128 //------------------------------------------------------------------ 129 virtual void 130 GetStatus (Stream &strm) = 0; 131 132 //------------------------------------------------------------------ 133 // Subclasses must be able to fetch the current OS version 134 // 135 // Remote classes must be connected for this to succeed. Local 136 // subclasses don't need to override this function as it will just 137 // call the Host::GetOSVersion(). 138 //------------------------------------------------------------------ 139protected: 140 virtual bool 141 FetchRemoteOSVersion () 142 { 143 return false; 144 } 145 146 //------------------------------------------------------------------ 147 /// Locate a file for a platform. 148 /// 149 /// The default implementation of this function will return the same 150 /// file patch in \a local_file as was in \a platform_file. 151 /// 152 /// @param[in] platform_file 153 /// The platform file path to locate and cache locally. 154 /// 155 /// @param[out] local_file 156 /// A locally cached version of the platform file. For platforms 157 /// that describe the current host computer, this will just be 158 /// the same file. For remote platforms, this file might come from 159 /// and SDK directory, or might need to be sync'ed over to the 160 /// current machine for efficient debugging access. 161 /// 162 /// @return 163 /// An error object. 164 //------------------------------------------------------------------ 165public: 166 virtual Error 167 GetFile (const FileSpec &platform_file, FileSpec &local_file); 168 169 virtual Error 170 ConnectRemote (const char *remote_url); 171 172 virtual Error 173 DisconnectRemote (const lldb::PlatformSP &platform_sp); 174 175 //------------------------------------------------------------------ 176 /// Get the platform's supported architectures in the order in which 177 /// they should be searched. 178 /// 179 /// @param[in] idx 180 /// A zero based architecture index 181 /// 182 /// @param[out] arch 183 /// A copy of the archgitecture at index if the return value is 184 /// \b true. 185 /// 186 /// @return 187 /// \b true if \a arch was filled in and is valid, \b false 188 /// otherwise. 189 //------------------------------------------------------------------ 190 virtual bool 191 GetSupportedArchitectureAtIndex (uint32_t idx, ArchSpec &arch) = 0; 192 193 virtual size_t 194 GetSoftwareBreakpointTrapOpcode (Target &target, 195 BreakpointSite *bp_site) = 0; 196 197 //------------------------------------------------------------------ 198 /// Launch a new process. 199 /// 200 /// Launch a new process by spawning a new process using the 201 /// target object's executable module's file as the file to launch. 202 /// Arguments are given in \a argv, and the environment variables 203 /// are in \a envp. Standard input and output files can be 204 /// optionally re-directed to \a stdin_path, \a stdout_path, and 205 /// \a stderr_path. 206 /// 207 /// This function is not meant to be overridden by Process 208 /// subclasses. It will first call Process::WillLaunch (Module *) 209 /// and if that returns \b true, Process::DoLaunch (Module*, 210 /// char const *[],char const *[],const char *,const char *, 211 /// const char *) will be called to actually do the launching. If 212 /// DoLaunch returns \b true, then Process::DidLaunch() will be 213 /// called. 214 /// 215 /// @param[in] argv 216 /// The argument array. 217 /// 218 /// @param[in] envp 219 /// The environment array. 220 /// 221 /// @param[in] launch_flags 222 /// Flags to modify the launch (@see lldb::LaunchFlags) 223 /// 224 /// @param[in] stdin_path 225 /// The path to use when re-directing the STDIN of the new 226 /// process. If all stdXX_path arguments are NULL, a pseudo 227 /// terminal will be used. 228 /// 229 /// @param[in] stdout_path 230 /// The path to use when re-directing the STDOUT of the new 231 /// process. If all stdXX_path arguments are NULL, a pseudo 232 /// terminal will be used. 233 /// 234 /// @param[in] stderr_path 235 /// The path to use when re-directing the STDERR of the new 236 /// process. If all stdXX_path arguments are NULL, a pseudo 237 /// terminal will be used. 238 /// 239 /// @param[in] working_directory 240 /// The working directory to have the child process run in 241 /// 242 /// @return 243 /// An error object. Call GetID() to get the process ID if 244 /// the error object is success. 245 //------------------------------------------------------------------ 246// virtual lldb::ProcessSP 247// Launch (char const *argv[], 248// char const *envp[], 249// uint32_t launch_flags, 250// const char *stdin_path, 251// const char *stdout_path, 252// const char *stderr_path, 253// const char *working_directory, 254// Error &error) = 0; 255 256 //------------------------------------------------------------------ 257 /// Attach to an existing process using a process ID. 258 /// 259 /// This function is not meant to be overridden by Process 260 /// subclasses. It will first call Process::WillAttach (lldb::pid_t) 261 /// and if that returns \b true, Process::DoAttach (lldb::pid_t) will 262 /// be called to actually do the attach. If DoAttach returns \b 263 /// true, then Process::DidAttach() will be called. 264 /// 265 /// @param[in] pid 266 /// The process ID that we should attempt to attach to. 267 /// 268 /// @return 269 /// Returns \a pid if attaching was successful, or 270 /// LLDB_INVALID_PROCESS_ID if attaching fails. 271 //------------------------------------------------------------------ 272// virtual lldb::ProcessSP 273// Attach (lldb::pid_t pid, 274// Error &error) = 0; 275 276 //------------------------------------------------------------------ 277 /// Attach to an existing process by process name. 278 /// 279 /// This function is not meant to be overridden by Process 280 /// subclasses. It will first call 281 /// Process::WillAttach (const char *) and if that returns \b 282 /// true, Process::DoAttach (const char *) will be called to 283 /// actually do the attach. If DoAttach returns \b true, then 284 /// Process::DidAttach() will be called. 285 /// 286 /// @param[in] process_name 287 /// A process name to match against the current process list. 288 /// 289 /// @return 290 /// Returns \a pid if attaching was successful, or 291 /// LLDB_INVALID_PROCESS_ID if attaching fails. 292 //------------------------------------------------------------------ 293// virtual lldb::ProcessSP 294// Attach (const char *process_name, 295// bool wait_for_launch, 296// Error &error) = 0; 297 298 virtual uint32_t 299 FindProcessesByName (const char *name, 300 lldb::NameMatchType name_match_type, 301 ProcessInfoList &proc_infos) = 0; 302 303 virtual bool 304 GetProcessInfo (lldb::pid_t pid, ProcessInfo &proc_info) = 0; 305 306 const std::string & 307 GetRemoteURL () const 308 { 309 return m_remote_url; 310 } 311 312 bool 313 IsHost () const 314 { 315 return m_is_host; // Is this the default host platform? 316 } 317 318 bool 319 IsRemote () const 320 { 321 return !m_is_host; 322 } 323 324 bool 325 IsConnected () const 326 { 327 return m_is_connected; 328 } 329 330 const ArchSpec & 331 GetSystemArchitecture(); 332 333 void 334 SetSystemArchitecture (const ArchSpec &arch) 335 { 336 m_system_arch = arch; 337 if (IsHost()) 338 m_os_version_set_while_connected = m_system_arch.IsValid(); 339 } 340 341 // Remote Platform subclasses need to override this function 342 virtual ArchSpec 343 FetchRemoteSystemArchitecture () 344 { 345 return ArchSpec(); // Return an invalid architecture 346 } 347 348 protected: 349 bool m_is_host; 350 bool m_is_connected; 351 // Set to true when we are able to actually set the OS version while 352 // being connected. For remote platforms, we might set the version ahead 353 // of time before we actually connect and this version might change when 354 // we actually connect to a remote platform. For the host platform this 355 // will be set to the once we call Host::GetOSVersion(). 356 bool m_os_version_set_while_connected; 357 bool m_system_arch_set_while_connected; 358 std::string m_remote_url; 359 uint32_t m_major_os_version; 360 uint32_t m_minor_os_version; 361 uint32_t m_update_os_version; 362 ArchSpec m_system_arch; // The architecture of the kernel or the remote platform 363 private: 364 DISALLOW_COPY_AND_ASSIGN (Platform); 365 }; 366 367 368 class PlatformList 369 { 370 public: 371 PlatformList() : 372 m_mutex (Mutex::eMutexTypeRecursive), 373 m_platforms () 374 { 375 } 376 377 ~PlatformList() 378 { 379 } 380 381 void 382 Append (const lldb::PlatformSP &platform_sp, bool set_selected) 383 { 384 Mutex::Locker locker (m_mutex); 385 m_platforms.push_back (platform_sp); 386 if (set_selected) 387 m_selected_platform_sp = m_platforms.back(); 388 } 389 390 size_t 391 GetSize() 392 { 393 Mutex::Locker locker (m_mutex); 394 return m_platforms.size(); 395 } 396 397 lldb::PlatformSP 398 GetAtIndex (uint32_t idx) 399 { 400 lldb::PlatformSP platform_sp; 401 { 402 Mutex::Locker locker (m_mutex); 403 if (idx < m_platforms.size()) 404 platform_sp = m_platforms[idx]; 405 } 406 return platform_sp; 407 } 408 409 //------------------------------------------------------------------ 410 /// Select the active platform. 411 /// 412 /// In order to debug remotely, other platform's can be remotely 413 /// connected to and set as the selected platform for any subsequent 414 /// debugging. This allows connection to remote targets and allows 415 /// the ability to discover process info, launch and attach to remote 416 /// processes. 417 //------------------------------------------------------------------ 418 lldb::PlatformSP 419 GetSelectedPlatform () 420 { 421 Mutex::Locker locker (m_mutex); 422 if (!m_selected_platform_sp && !m_platforms.empty()) 423 m_selected_platform_sp = m_platforms.front(); 424 425 return m_selected_platform_sp; 426 } 427 428 void 429 SetSelectedPlatform (const lldb::PlatformSP &platform_sp) 430 { 431 if (platform_sp) 432 { 433 Mutex::Locker locker (m_mutex); 434 const size_t num_platforms = m_platforms.size(); 435 for (size_t idx=0; idx<num_platforms; ++idx) 436 { 437 if (m_platforms[idx].get() == platform_sp.get()) 438 { 439 m_selected_platform_sp = m_platforms[idx]; 440 return; 441 } 442 } 443 m_platforms.push_back (platform_sp); 444 m_selected_platform_sp = m_platforms.back(); 445 } 446 } 447 448 protected: 449 typedef std::vector<lldb::PlatformSP> collection; 450 mutable Mutex m_mutex; 451 collection m_platforms; 452 lldb::PlatformSP m_selected_platform_sp; 453 454 private: 455 DISALLOW_COPY_AND_ASSIGN (PlatformList); 456 }; 457} // namespace lldb_private 458 459#endif // liblldb_Platform_h_ 460