1 //===-- NativeProcessProtocol.h ---------------------------------*- C++ -*-===// 2 // 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 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_HOST_COMMON_NATIVEPROCESSPROTOCOL_H 10 #define LLDB_HOST_COMMON_NATIVEPROCESSPROTOCOL_H 11 12 #include "NativeBreakpointList.h" 13 #include "NativeThreadProtocol.h" 14 #include "NativeWatchpointList.h" 15 #include "lldb/Host/Host.h" 16 #include "lldb/Host/MainLoop.h" 17 #include "lldb/Utility/ArchSpec.h" 18 #include "lldb/Utility/Iterable.h" 19 #include "lldb/Utility/Status.h" 20 #include "lldb/Utility/TraceGDBRemotePackets.h" 21 #include "lldb/Utility/UnimplementedError.h" 22 #include "lldb/lldb-private-forward.h" 23 #include "lldb/lldb-types.h" 24 #include "llvm/ADT/ArrayRef.h" 25 #include "llvm/ADT/DenseSet.h" 26 #include "llvm/ADT/StringRef.h" 27 #include "llvm/Support/Error.h" 28 #include "llvm/Support/MemoryBuffer.h" 29 #include <mutex> 30 #include <unordered_map> 31 #include <vector> 32 33 namespace lldb_private { 34 LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE(); 35 36 class MemoryRegionInfo; 37 class ResumeActionList; 38 39 struct SVR4LibraryInfo { 40 std::string name; 41 lldb::addr_t link_map; 42 lldb::addr_t base_addr; 43 lldb::addr_t ld_addr; 44 lldb::addr_t next; 45 }; 46 47 // NativeProcessProtocol 48 class NativeProcessProtocol { 49 public: 50 virtual ~NativeProcessProtocol() = default; 51 52 typedef std::vector<std::unique_ptr<NativeThreadProtocol>> thread_collection; 53 template <typename I> 54 static NativeThreadProtocol &thread_list_adapter(I &iter) { 55 assert(*iter); 56 return **iter; 57 } 58 typedef LockingAdaptedIterable<thread_collection, NativeThreadProtocol &, 59 thread_list_adapter, std::recursive_mutex> 60 ThreadIterable; 61 62 virtual Status Resume(const ResumeActionList &resume_actions) = 0; 63 64 virtual Status Halt() = 0; 65 66 virtual Status Detach() = 0; 67 68 /// Sends a process a UNIX signal \a signal. 69 /// 70 /// \return 71 /// Returns an error object. 72 virtual Status Signal(int signo) = 0; 73 74 /// Tells a process to interrupt all operations as if by a Ctrl-C. 75 /// 76 /// The default implementation will send a local host's equivalent of 77 /// a SIGSTOP to the process via the NativeProcessProtocol::Signal() 78 /// operation. 79 /// 80 /// \return 81 /// Returns an error object. 82 virtual Status Interrupt(); 83 84 virtual Status Kill() = 0; 85 86 // Tells a process not to stop the inferior on given signals and just 87 // reinject them back. 88 virtual Status IgnoreSignals(llvm::ArrayRef<int> signals); 89 90 // Memory and memory region functions 91 92 virtual Status GetMemoryRegionInfo(lldb::addr_t load_addr, 93 MemoryRegionInfo &range_info); 94 95 virtual Status ReadMemory(lldb::addr_t addr, void *buf, size_t size, 96 size_t &bytes_read) = 0; 97 98 Status ReadMemoryWithoutTrap(lldb::addr_t addr, void *buf, size_t size, 99 size_t &bytes_read); 100 101 virtual Status ReadMemoryTags(int32_t type, lldb::addr_t addr, size_t len, 102 std::vector<uint8_t> &tags); 103 104 virtual Status WriteMemoryTags(int32_t type, lldb::addr_t addr, size_t len, 105 const std::vector<uint8_t> &tags); 106 107 /// Reads a null terminated string from memory. 108 /// 109 /// Reads up to \p max_size bytes of memory until it finds a '\0'. 110 /// If a '\0' is not found then it reads max_size-1 bytes as a string and a 111 /// '\0' is added as the last character of the \p buffer. 112 /// 113 /// \param[in] addr 114 /// The address in memory to read from. 115 /// 116 /// \param[in] buffer 117 /// An allocated buffer with at least \p max_size size. 118 /// 119 /// \param[in] max_size 120 /// The maximum number of bytes to read from memory until it reads the 121 /// string. 122 /// 123 /// \param[out] total_bytes_read 124 /// The number of bytes read from memory into \p buffer. 125 /// 126 /// \return 127 /// Returns a StringRef backed up by the \p buffer passed in. 128 llvm::Expected<llvm::StringRef> 129 ReadCStringFromMemory(lldb::addr_t addr, char *buffer, size_t max_size, 130 size_t &total_bytes_read); 131 132 virtual Status WriteMemory(lldb::addr_t addr, const void *buf, size_t size, 133 size_t &bytes_written) = 0; 134 135 virtual llvm::Expected<lldb::addr_t> AllocateMemory(size_t size, 136 uint32_t permissions) { 137 return llvm::make_error<UnimplementedError>(); 138 } 139 140 virtual llvm::Error DeallocateMemory(lldb::addr_t addr) { 141 return llvm::make_error<UnimplementedError>(); 142 } 143 144 virtual lldb::addr_t GetSharedLibraryInfoAddress() = 0; 145 146 virtual llvm::Expected<std::vector<SVR4LibraryInfo>> 147 GetLoadedSVR4Libraries() { 148 return llvm::createStringError(llvm::inconvertibleErrorCode(), 149 "Not implemented"); 150 } 151 152 virtual bool IsAlive() const; 153 154 virtual size_t UpdateThreads() = 0; 155 156 virtual const ArchSpec &GetArchitecture() const = 0; 157 158 // Breakpoint functions 159 virtual Status SetBreakpoint(lldb::addr_t addr, uint32_t size, 160 bool hardware) = 0; 161 162 virtual Status RemoveBreakpoint(lldb::addr_t addr, bool hardware = false); 163 164 // Hardware Breakpoint functions 165 virtual const HardwareBreakpointMap &GetHardwareBreakpointMap() const; 166 167 virtual Status SetHardwareBreakpoint(lldb::addr_t addr, size_t size); 168 169 virtual Status RemoveHardwareBreakpoint(lldb::addr_t addr); 170 171 // Watchpoint functions 172 virtual const NativeWatchpointList::WatchpointMap &GetWatchpointMap() const; 173 174 virtual llvm::Optional<std::pair<uint32_t, uint32_t>> 175 GetHardwareDebugSupportInfo() const; 176 177 virtual Status SetWatchpoint(lldb::addr_t addr, size_t size, 178 uint32_t watch_flags, bool hardware); 179 180 virtual Status RemoveWatchpoint(lldb::addr_t addr); 181 182 // Accessors 183 lldb::pid_t GetID() const { return m_pid; } 184 185 lldb::StateType GetState() const; 186 187 bool IsRunning() const { 188 return m_state == lldb::eStateRunning || IsStepping(); 189 } 190 191 bool IsStepping() const { return m_state == lldb::eStateStepping; } 192 193 bool CanResume() const { return m_state == lldb::eStateStopped; } 194 195 lldb::ByteOrder GetByteOrder() const { 196 return GetArchitecture().GetByteOrder(); 197 } 198 199 uint32_t GetAddressByteSize() const { 200 return GetArchitecture().GetAddressByteSize(); 201 } 202 203 virtual llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>> 204 GetAuxvData() const = 0; 205 206 // Exit Status 207 virtual llvm::Optional<WaitStatus> GetExitStatus(); 208 209 virtual bool SetExitStatus(WaitStatus status, bool bNotifyStateChange); 210 211 // Access to threads 212 NativeThreadProtocol *GetThreadAtIndex(uint32_t idx); 213 214 NativeThreadProtocol *GetThreadByID(lldb::tid_t tid); 215 216 void SetCurrentThreadID(lldb::tid_t tid) { m_current_thread_id = tid; } 217 218 lldb::tid_t GetCurrentThreadID() const { return m_current_thread_id; } 219 220 NativeThreadProtocol *GetCurrentThread() { 221 return GetThreadByID(m_current_thread_id); 222 } 223 224 ThreadIterable Threads() const { 225 return ThreadIterable(m_threads, m_threads_mutex); 226 } 227 228 // Access to inferior stdio 229 virtual int GetTerminalFileDescriptor() { return m_terminal_fd; } 230 231 // Stop id interface 232 233 uint32_t GetStopID() const; 234 235 // Callbacks for low-level process state changes 236 class NativeDelegate { 237 public: 238 virtual ~NativeDelegate() = default; 239 240 virtual void InitializeDelegate(NativeProcessProtocol *process) = 0; 241 242 virtual void ProcessStateChanged(NativeProcessProtocol *process, 243 lldb::StateType state) = 0; 244 245 virtual void DidExec(NativeProcessProtocol *process) = 0; 246 247 virtual void 248 NewSubprocess(NativeProcessProtocol *parent_process, 249 std::unique_ptr<NativeProcessProtocol> child_process) = 0; 250 }; 251 252 virtual Status GetLoadedModuleFileSpec(const char *module_path, 253 FileSpec &file_spec) = 0; 254 255 virtual Status GetFileLoadAddress(const llvm::StringRef &file_name, 256 lldb::addr_t &load_addr) = 0; 257 258 /// Extension flag constants, returned by Factory::GetSupportedExtensions() 259 /// and passed to SetEnabledExtension() 260 enum class Extension { 261 multiprocess = (1u << 0), 262 fork = (1u << 1), 263 vfork = (1u << 2), 264 pass_signals = (1u << 3), 265 auxv = (1u << 4), 266 libraries_svr4 = (1u << 5), 267 memory_tagging = (1u << 6), 268 savecore = (1u << 7), 269 siginfo_read = (1u << 8), 270 271 LLVM_MARK_AS_BITMASK_ENUM(siginfo_read) 272 }; 273 274 class Factory { 275 public: 276 virtual ~Factory(); 277 /// Launch a process for debugging. 278 /// 279 /// \param[in] launch_info 280 /// Information required to launch the process. 281 /// 282 /// \param[in] native_delegate 283 /// The delegate that will receive messages regarding the 284 /// inferior. Must outlive the NativeProcessProtocol 285 /// instance. 286 /// 287 /// \param[in] mainloop 288 /// The mainloop instance with which the process can register 289 /// callbacks. Must outlive the NativeProcessProtocol 290 /// instance. 291 /// 292 /// \return 293 /// A NativeProcessProtocol shared pointer if the operation succeeded or 294 /// an error object if it failed. 295 virtual llvm::Expected<std::unique_ptr<NativeProcessProtocol>> 296 Launch(ProcessLaunchInfo &launch_info, NativeDelegate &native_delegate, 297 MainLoop &mainloop) const = 0; 298 299 /// Attach to an existing process. 300 /// 301 /// \param[in] pid 302 /// pid of the process locatable 303 /// 304 /// \param[in] native_delegate 305 /// The delegate that will receive messages regarding the 306 /// inferior. Must outlive the NativeProcessProtocol 307 /// instance. 308 /// 309 /// \param[in] mainloop 310 /// The mainloop instance with which the process can register 311 /// callbacks. Must outlive the NativeProcessProtocol 312 /// instance. 313 /// 314 /// \return 315 /// A NativeProcessProtocol shared pointer if the operation succeeded or 316 /// an error object if it failed. 317 virtual llvm::Expected<std::unique_ptr<NativeProcessProtocol>> 318 Attach(lldb::pid_t pid, NativeDelegate &native_delegate, 319 MainLoop &mainloop) const = 0; 320 321 /// Get the bitmask of extensions supported by this process plugin. 322 /// 323 /// \return 324 /// A NativeProcessProtocol::Extension bitmask. 325 virtual Extension GetSupportedExtensions() const { return {}; } 326 }; 327 328 /// Notify tracers that the target process will resume 329 virtual void NotifyTracersProcessWillResume() {} 330 331 /// Notify tracers that the target process just stopped 332 virtual void NotifyTracersProcessDidStop() {} 333 334 /// Start tracing a process or its threads. 335 /// 336 /// \param[in] json_params 337 /// JSON object with the information of what and how to trace. 338 /// In the case of gdb-remote, this object should conform to the 339 /// jLLDBTraceStart packet. 340 /// 341 /// This object should have a string entry called "type", which is the 342 /// tracing technology name. 343 /// 344 /// \param[in] type 345 /// Tracing technology type, as described in the \a json_params. 346 /// 347 /// \return 348 /// \a llvm::Error::success if the operation was successful, or an 349 /// \a llvm::Error otherwise. 350 virtual llvm::Error TraceStart(llvm::StringRef json_params, 351 llvm::StringRef type) { 352 return llvm::createStringError(llvm::inconvertibleErrorCode(), 353 "Unsupported tracing type '%s'", 354 type.data()); 355 } 356 357 /// \copydoc Process::TraceStop(const TraceStopRequest &) 358 virtual llvm::Error TraceStop(const TraceStopRequest &request) { 359 return llvm::createStringError(llvm::inconvertibleErrorCode(), 360 "Unsupported tracing type '%s'", 361 request.type.data()); 362 } 363 364 /// \copydoc Process::TraceGetState(llvm::StringRef type) 365 virtual llvm::Expected<llvm::json::Value> 366 TraceGetState(llvm::StringRef type) { 367 return llvm::createStringError(llvm::inconvertibleErrorCode(), 368 "Unsupported tracing type '%s'", 369 type.data()); 370 } 371 372 /// \copydoc Process::TraceGetBinaryData(const TraceGetBinaryDataRequest &) 373 virtual llvm::Expected<std::vector<uint8_t>> 374 TraceGetBinaryData(const TraceGetBinaryDataRequest &request) { 375 return llvm::createStringError( 376 llvm::inconvertibleErrorCode(), 377 "Unsupported data kind '%s' for the '%s' tracing technology", 378 request.kind.c_str(), request.type.c_str()); 379 } 380 381 /// \copydoc Process::TraceSupported() 382 virtual llvm::Expected<TraceSupportedResponse> TraceSupported() { 383 return llvm::make_error<UnimplementedError>(); 384 } 385 386 /// Method called in order to propagate the bitmap of protocol 387 /// extensions supported by the client. 388 /// 389 /// \param[in] flags 390 /// The bitmap of enabled extensions. 391 virtual void SetEnabledExtensions(Extension flags) { 392 m_enabled_extensions = flags; 393 } 394 395 /// Write a core dump (without crashing the program). 396 /// 397 /// \param[in] path_hint 398 /// Suggested core dump path (optional, can be empty). 399 /// 400 /// \return 401 /// Path to the core dump if successfully written, an error 402 /// otherwise. 403 virtual llvm::Expected<std::string> SaveCore(llvm::StringRef path_hint) { 404 return llvm::createStringError(llvm::inconvertibleErrorCode(), 405 "Not implemented"); 406 } 407 408 protected: 409 struct SoftwareBreakpoint { 410 uint32_t ref_count; 411 llvm::SmallVector<uint8_t, 4> saved_opcodes; 412 llvm::ArrayRef<uint8_t> breakpoint_opcodes; 413 }; 414 415 std::unordered_map<lldb::addr_t, SoftwareBreakpoint> m_software_breakpoints; 416 lldb::pid_t m_pid; 417 418 std::vector<std::unique_ptr<NativeThreadProtocol>> m_threads; 419 lldb::tid_t m_current_thread_id = LLDB_INVALID_THREAD_ID; 420 mutable std::recursive_mutex m_threads_mutex; 421 422 lldb::StateType m_state = lldb::eStateInvalid; 423 mutable std::recursive_mutex m_state_mutex; 424 425 llvm::Optional<WaitStatus> m_exit_status; 426 427 NativeDelegate &m_delegate; 428 NativeWatchpointList m_watchpoint_list; 429 HardwareBreakpointMap m_hw_breakpoints_map; 430 int m_terminal_fd; 431 uint32_t m_stop_id = 0; 432 433 // Set of signal numbers that LLDB directly injects back to inferior without 434 // stopping it. 435 llvm::DenseSet<int> m_signals_to_ignore; 436 437 // Extensions enabled per the last SetEnabledExtensions() call. 438 Extension m_enabled_extensions; 439 440 // lldb_private::Host calls should be used to launch a process for debugging, 441 // and then the process should be attached to. When attaching to a process 442 // lldb_private::Host calls should be used to locate the process to attach 443 // to, and then this function should be called. 444 NativeProcessProtocol(lldb::pid_t pid, int terminal_fd, 445 NativeDelegate &delegate); 446 447 void SetID(lldb::pid_t pid) { m_pid = pid; } 448 449 // interface for state handling 450 void SetState(lldb::StateType state, bool notify_delegates = true); 451 452 // Derived classes need not implement this. It can be used as a hook to 453 // clear internal caches that should be invalidated when stop ids change. 454 // 455 // Note this function is called with the state mutex obtained by the caller. 456 virtual void DoStopIDBumped(uint32_t newBumpId); 457 458 // interface for software breakpoints 459 460 Status SetSoftwareBreakpoint(lldb::addr_t addr, uint32_t size_hint); 461 Status RemoveSoftwareBreakpoint(lldb::addr_t addr); 462 463 virtual llvm::Expected<llvm::ArrayRef<uint8_t>> 464 GetSoftwareBreakpointTrapOpcode(size_t size_hint); 465 466 /// Return the offset of the PC relative to the software breakpoint that was hit. If an 467 /// architecture (e.g. arm) reports breakpoint hits before incrementing the PC, this offset 468 /// will be 0. If an architecture (e.g. intel) reports breakpoints hits after incrementing the 469 /// PC, this offset will be the size of the breakpoint opcode. 470 virtual size_t GetSoftwareBreakpointPCOffset(); 471 472 // Adjust the thread's PC after hitting a software breakpoint. On 473 // architectures where the PC points after the breakpoint instruction, this 474 // resets it to point to the breakpoint itself. 475 void FixupBreakpointPCAsNeeded(NativeThreadProtocol &thread); 476 477 /// Notify the delegate that an exec occurred. 478 /// 479 /// Provide a mechanism for a delegate to clear out any exec- 480 /// sensitive data. 481 virtual void NotifyDidExec(); 482 483 NativeThreadProtocol *GetThreadByIDUnlocked(lldb::tid_t tid); 484 485 private: 486 void SynchronouslyNotifyProcessStateChanged(lldb::StateType state); 487 llvm::Expected<SoftwareBreakpoint> 488 EnableSoftwareBreakpoint(lldb::addr_t addr, uint32_t size_hint); 489 }; 490 } // namespace lldb_private 491 492 #endif // LLDB_HOST_COMMON_NATIVEPROCESSPROTOCOL_H 493