Platform.h revision e4b9c1fb338ee1ada72e6a3c198afb342d68c5c1
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 //------------------------------------------------------------------ 62 /// Select the active platform. 63 /// 64 /// In order to debug remotely, other platform's can be remotely 65 /// connected to and set as the selected platform for any subsequent 66 /// debugging. This allows connection to remote targets and allows 67 /// the ability to discover process info, launch and attach to remote 68 /// processes. 69 //------------------------------------------------------------------ 70 static lldb::PlatformSP 71 GetSelectedPlatform (); 72 73 static void 74 SetSelectedPlatform (const lldb::PlatformSP &platform_sp); 75 76 //------------------------------------------------------------------ 77 /// Connect to a remote platform 78 /// 79 /// When connecting to a remote platform, the name of that platform 80 /// (the short plug-in name) is required, along with a URL that the 81 /// platform plug-in can use to remotely attach. 82 //------------------------------------------------------------------ 83 static lldb::PlatformSP 84 ConnectRemote (const char *platform_name, 85 const char *remote_connect_url, 86 Error &error); 87 88 static uint32_t 89 GetNumConnectedRemotePlatforms (); 90 91 static lldb::PlatformSP 92 GetConnectedRemotePlatformAtIndex (uint32_t idx); 93 94 95 //------------------------------------------------------------------ 96 /// Default Constructor 97 //------------------------------------------------------------------ 98 Platform (); 99 100 //------------------------------------------------------------------ 101 /// Destructor. 102 /// 103 /// The destructor is virtual since this class is designed to be 104 /// inherited from by the plug-in instance. 105 //------------------------------------------------------------------ 106 virtual 107 ~Platform(); 108 109 //------------------------------------------------------------------ 110 /// Set the target's executable based off of the existing 111 /// architecture information in \a target given a path to an 112 /// executable \a exe_file. 113 /// 114 /// Each platform knows the architectures that it supports and can 115 /// select the correct architecture slice within \a exe_file by 116 /// inspecting the architecture in \a target. If the target had an 117 /// architecture specified, then in can try and obey that request 118 /// and optionally fail if the architecture doesn't match up. 119 /// If no architecture is specified, the platform should select the 120 /// default architecture from \a exe_file. Any application bundles 121 /// or executable wrappers can also be inspected for the actual 122 /// application binary within the bundle that should be used. 123 /// 124 /// @return 125 /// Returns \b true if this Platform plug-in was able to find 126 /// a suitable executable, \b false otherwise. 127 //------------------------------------------------------------------ 128 virtual Error 129 ResolveExecutable (const FileSpec &exe_file, 130 const ArchSpec &arch, 131 lldb::ModuleSP &module_sp); 132 133 //------------------------------------------------------------------ 134 /// Locate a file for a platform. 135 /// 136 /// The default implementation of this function will return the same 137 /// file patch in \a local_file as was in \a platform_file. 138 /// 139 /// @param[in] platform_file 140 /// The platform file path to locate and cache locally. 141 /// 142 /// @param[out] local_file 143 /// A locally cached version of the platform file. For platforms 144 /// that describe the current host computer, this will just be 145 /// the same file. For remote platforms, this file might come from 146 /// and SDK directory, or might need to be sync'ed over to the 147 /// current machine for efficient debugging access. 148 /// 149 /// @return 150 /// An error object. 151 //------------------------------------------------------------------ 152 virtual Error 153 GetFile (const FileSpec &platform_file, FileSpec &local_file); 154 155 virtual Error 156 ConnectRemote (const char *remote_url); 157 158 virtual Error 159 DisconnectRemote (const lldb::PlatformSP &platform_sp); 160 161 //------------------------------------------------------------------ 162 /// Get the platform's supported architectures in the order in which 163 /// they should be searched. 164 /// 165 /// @param[in] idx 166 /// A zero based architecture index 167 /// 168 /// @param[out] arch 169 /// A copy of the archgitecture at index if the return value is 170 /// \b true. 171 /// 172 /// @return 173 /// \b true if \a arch was filled in and is valid, \b false 174 /// otherwise. 175 //------------------------------------------------------------------ 176 virtual bool 177 GetSupportedArchitectureAtIndex (uint32_t idx, ArchSpec &arch) = 0; 178 179 //------------------------------------------------------------------ 180 /// Launch a new process. 181 /// 182 /// Launch a new process by spawning a new process using the 183 /// target object's executable module's file as the file to launch. 184 /// Arguments are given in \a argv, and the environment variables 185 /// are in \a envp. Standard input and output files can be 186 /// optionally re-directed to \a stdin_path, \a stdout_path, and 187 /// \a stderr_path. 188 /// 189 /// This function is not meant to be overridden by Process 190 /// subclasses. It will first call Process::WillLaunch (Module *) 191 /// and if that returns \b true, Process::DoLaunch (Module*, 192 /// char const *[],char const *[],const char *,const char *, 193 /// const char *) will be called to actually do the launching. If 194 /// DoLaunch returns \b true, then Process::DidLaunch() will be 195 /// called. 196 /// 197 /// @param[in] argv 198 /// The argument array. 199 /// 200 /// @param[in] envp 201 /// The environment array. 202 /// 203 /// @param[in] launch_flags 204 /// Flags to modify the launch (@see lldb::LaunchFlags) 205 /// 206 /// @param[in] stdin_path 207 /// The path to use when re-directing the STDIN of the new 208 /// process. If all stdXX_path arguments are NULL, a pseudo 209 /// terminal will be used. 210 /// 211 /// @param[in] stdout_path 212 /// The path to use when re-directing the STDOUT of the new 213 /// process. If all stdXX_path arguments are NULL, a pseudo 214 /// terminal will be used. 215 /// 216 /// @param[in] stderr_path 217 /// The path to use when re-directing the STDERR of the new 218 /// process. If all stdXX_path arguments are NULL, a pseudo 219 /// terminal will be used. 220 /// 221 /// @param[in] working_directory 222 /// The working directory to have the child process run in 223 /// 224 /// @return 225 /// An error object. Call GetID() to get the process ID if 226 /// the error object is success. 227 //------------------------------------------------------------------ 228// virtual lldb::ProcessSP 229// Launch (char const *argv[], 230// char const *envp[], 231// uint32_t launch_flags, 232// const char *stdin_path, 233// const char *stdout_path, 234// const char *stderr_path, 235// const char *working_directory, 236// Error &error) = 0; 237 238 //------------------------------------------------------------------ 239 /// Attach to an existing process using a process ID. 240 /// 241 /// This function is not meant to be overridden by Process 242 /// subclasses. It will first call Process::WillAttach (lldb::pid_t) 243 /// and if that returns \b true, Process::DoAttach (lldb::pid_t) will 244 /// be called to actually do the attach. If DoAttach returns \b 245 /// true, then Process::DidAttach() will be called. 246 /// 247 /// @param[in] pid 248 /// The process ID that we should attempt to attach to. 249 /// 250 /// @return 251 /// Returns \a pid if attaching was successful, or 252 /// LLDB_INVALID_PROCESS_ID if attaching fails. 253 //------------------------------------------------------------------ 254// virtual lldb::ProcessSP 255// Attach (lldb::pid_t pid, 256// Error &error) = 0; 257 258 //------------------------------------------------------------------ 259 /// Attach to an existing process by process name. 260 /// 261 /// This function is not meant to be overridden by Process 262 /// subclasses. It will first call 263 /// Process::WillAttach (const char *) and if that returns \b 264 /// true, Process::DoAttach (const char *) will be called to 265 /// actually do the attach. If DoAttach returns \b true, then 266 /// Process::DidAttach() will be called. 267 /// 268 /// @param[in] process_name 269 /// A process name to match against the current process list. 270 /// 271 /// @return 272 /// Returns \a pid if attaching was successful, or 273 /// LLDB_INVALID_PROCESS_ID if attaching fails. 274 //------------------------------------------------------------------ 275// virtual lldb::ProcessSP 276// Attach (const char *process_name, 277// bool wait_for_launch, 278// Error &error) = 0; 279 280 virtual uint32_t 281 FindProcessesByName (const char *name, 282 lldb::NameMatchType name_match_type, 283 ProcessInfoList &proc_infos) = 0; 284 285 virtual bool 286 GetProcessInfo (lldb::pid_t pid, ProcessInfo &proc_info) = 0; 287 288 const std::string & 289 GetRemoteURL () const 290 { 291 return m_remote_url; 292 } 293 294 protected: 295 296 std::string m_remote_url; 297 298 private: 299 DISALLOW_COPY_AND_ASSIGN (Platform); 300 }; 301 302 303 class PlatformList 304 { 305 public: 306 PlatformList() : 307 m_mutex (Mutex::eMutexTypeRecursive), 308 m_platforms () 309 { 310 } 311 312 ~PlatformList() 313 { 314 } 315 316 void 317 Append (const lldb::PlatformSP &platform_sp) 318 { 319 Mutex::Locker locker (m_mutex); 320 m_platforms.push_back (platform_sp); 321 } 322 323 size_t 324 GetSize() 325 { 326 Mutex::Locker locker (m_mutex); 327 return m_platforms.size(); 328 } 329 330 lldb::PlatformSP 331 GetAtIndex (uint32_t idx) 332 { 333 lldb::PlatformSP platform_sp; 334 { 335 Mutex::Locker locker (m_mutex); 336 if (idx < m_platforms.size()) 337 platform_sp = m_platforms[idx]; 338 } 339 return platform_sp; 340 } 341 342 protected: 343 typedef std::vector<lldb::PlatformSP> collection; 344 mutable Mutex m_mutex; 345 collection m_platforms; 346 347 private: 348 DISALLOW_COPY_AND_ASSIGN (PlatformList); 349 }; 350} // namespace lldb_private 351 352#endif // liblldb_Platform_h_ 353