1//===-- ProcessDebugger.cpp -----------------------------------------------===//
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#include "ProcessDebugger.h"
10
11// Windows includes
12#include "lldb/Host/windows/windows.h"
13#include <psapi.h>
14
15#include "lldb/Host/FileSystem.h"
16#include "lldb/Host/HostNativeProcessBase.h"
17#include "lldb/Host/HostProcess.h"
18#include "lldb/Host/HostThread.h"
19#include "lldb/Host/ProcessLaunchInfo.h"
20#include "lldb/Target/MemoryRegionInfo.h"
21#include "lldb/Target/Process.h"
22#include "llvm/Support/ConvertUTF.h"
23#include "llvm/Support/Error.h"
24
25#include "DebuggerThread.h"
26#include "ExceptionRecord.h"
27#include "ProcessWindowsLog.h"
28
29using namespace lldb;
30using namespace lldb_private;
31
32static DWORD ConvertLldbToWinApiProtect(uint32_t protect) {
33 // We also can process a read / write permissions here, but if the debugger
34 // will make later a write into the allocated memory, it will fail. To get
35 // around it is possible inside DoWriteMemory to remember memory permissions,
36 // allow write, write and restore permissions, but for now we process only
37 // the executable permission.
38 //
39 // TODO: Process permissions other than executable
40 if (protect & ePermissionsExecutable)
41 return PAGE_EXECUTE_READWRITE;
42
43 return PAGE_READWRITE;
44}
45
46// The Windows page protection bits are NOT independent masks that can be
47// bitwise-ORed together. For example, PAGE_EXECUTE_READ is not (PAGE_EXECUTE
48// | PAGE_READ). To test for an access type, it's necessary to test for any of
49// the bits that provide that access type.
50static bool IsPageReadable(uint32_t protect) {
51 return (protect & PAGE_NOACCESS) == 0;
52}
53
54static bool IsPageWritable(uint32_t protect) {
55 return (protect & (PAGE_EXECUTE_READWRITE | PAGE_EXECUTE_WRITECOPY |
56 PAGE_READWRITE | PAGE_WRITECOPY)) != 0;
57}
58
59static bool IsPageExecutable(uint32_t protect) {
60 return (protect & (PAGE_EXECUTE | PAGE_EXECUTE_READ | PAGE_EXECUTE_READWRITE |
61 PAGE_EXECUTE_WRITECOPY)) != 0;
62}
63
64namespace lldb_private {
65
66ProcessDebugger::~ProcessDebugger() {}
67
68lldb::pid_t ProcessDebugger::GetDebuggedProcessId() const {
69 if (m_session_data)
70 return m_session_data->m_debugger->GetProcess().GetProcessId();
71 return LLDB_INVALID_PROCESS_ID;
72}
73
74Status ProcessDebugger::DetachProcess() {
75 Log *log = GetLog(mask: WindowsLog::Process);
76 DebuggerThreadSP debugger_thread;
77 {
78 // Acquire the lock only long enough to get the DebuggerThread.
79 // StopDebugging() will trigger a call back into ProcessDebugger which will
80 // also acquire the lock. Thus we have to release the lock before calling
81 // StopDebugging().
82 llvm::sys::ScopedLock lock(m_mutex);
83
84 if (!m_session_data) {
85 LLDB_LOG(log, "there is no active session.");
86 return Status();
87 }
88
89 debugger_thread = m_session_data->m_debugger;
90 }
91
92 Status error;
93
94 LLDB_LOG(log, "detaching from process {0}.",
95 debugger_thread->GetProcess().GetNativeProcess().GetSystemHandle());
96 error = debugger_thread->StopDebugging(terminate: false);
97
98 // By the time StopDebugging returns, there is no more debugger thread, so
99 // we can be assured that no other thread will race for the session data.
100 m_session_data.reset();
101
102 return error;
103}
104
105Status ProcessDebugger::LaunchProcess(ProcessLaunchInfo &launch_info,
106 DebugDelegateSP delegate) {
107 // Even though m_session_data is accessed here, it is before a debugger
108 // thread has been kicked off. So there's no race conditions, and it
109 // shouldn't be necessary to acquire the mutex.
110
111 Log *log = GetLog(mask: WindowsLog::Process);
112 Status result;
113
114 FileSpec working_dir = launch_info.GetWorkingDirectory();
115 namespace fs = llvm::sys::fs;
116 if (working_dir) {
117 FileSystem::Instance().Resolve(file_spec&: working_dir);
118 if (!FileSystem::Instance().IsDirectory(file_spec: working_dir)) {
119 result.SetErrorStringWithFormat("No such file or directory: %s",
120 working_dir.GetPath().c_str());
121 return result;
122 }
123 }
124
125 if (!launch_info.GetFlags().Test(bit: eLaunchFlagDebug)) {
126 StreamString stream;
127 stream.Printf(format: "ProcessDebugger unable to launch '%s'. ProcessDebugger can "
128 "only be used for debug launches.",
129 launch_info.GetExecutableFile().GetPath().c_str());
130 std::string message = stream.GetString().str();
131 result.SetErrorString(message.c_str());
132
133 LLDB_LOG(log, "error: {0}", message);
134 return result;
135 }
136
137 bool stop_at_entry = launch_info.GetFlags().Test(bit: eLaunchFlagStopAtEntry);
138 m_session_data.reset(p: new ProcessWindowsData(stop_at_entry));
139 m_session_data->m_debugger.reset(p: new DebuggerThread(delegate));
140 DebuggerThreadSP debugger = m_session_data->m_debugger;
141
142 // Kick off the DebugLaunch asynchronously and wait for it to complete.
143 result = debugger->DebugLaunch(launch_info);
144 if (result.Fail()) {
145 LLDB_LOG(log, "failed launching '{0}'. {1}",
146 launch_info.GetExecutableFile().GetPath(), result);
147 return result;
148 }
149
150 HostProcess process;
151 Status error = WaitForDebuggerConnection(debugger, process);
152 if (error.Fail()) {
153 LLDB_LOG(log, "failed launching '{0}'. {1}",
154 launch_info.GetExecutableFile().GetPath(), error);
155 return error;
156 }
157
158 LLDB_LOG(log, "successfully launched '{0}'",
159 launch_info.GetExecutableFile().GetPath());
160
161 // We've hit the initial stop. If eLaunchFlagsStopAtEntry was specified, the
162 // private state should already be set to eStateStopped as a result of
163 // hitting the initial breakpoint. If it was not set, the breakpoint should
164 // have already been resumed from and the private state should already be
165 // eStateRunning.
166 launch_info.SetProcessID(process.GetProcessId());
167
168 return result;
169}
170
171Status ProcessDebugger::AttachProcess(lldb::pid_t pid,
172 const ProcessAttachInfo &attach_info,
173 DebugDelegateSP delegate) {
174 Log *log = GetLog(mask: WindowsLog::Process);
175 m_session_data.reset(
176 p: new ProcessWindowsData(!attach_info.GetContinueOnceAttached()));
177 DebuggerThreadSP debugger(new DebuggerThread(delegate));
178
179 m_session_data->m_debugger = debugger;
180
181 DWORD process_id = static_cast<DWORD>(pid);
182 Status error = debugger->DebugAttach(pid: process_id, attach_info);
183 if (error.Fail()) {
184 LLDB_LOG(
185 log,
186 "encountered an error occurred initiating the asynchronous attach. {0}",
187 error);
188 return error;
189 }
190
191 HostProcess process;
192 error = WaitForDebuggerConnection(debugger, process);
193 if (error.Fail()) {
194 LLDB_LOG(log,
195 "encountered an error waiting for the debugger to connect. {0}",
196 error);
197 return error;
198 }
199
200 LLDB_LOG(log, "successfully attached to process with pid={0}", process_id);
201
202 // We've hit the initial stop. If eLaunchFlagsStopAtEntry was specified, the
203 // private state should already be set to eStateStopped as a result of
204 // hitting the initial breakpoint. If it was not set, the breakpoint should
205 // have already been resumed from and the private state should already be
206 // eStateRunning.
207
208 return error;
209}
210
211Status ProcessDebugger::DestroyProcess(const lldb::StateType state) {
212 Log *log = GetLog(mask: WindowsLog::Process);
213 DebuggerThreadSP debugger_thread;
214 {
215 // Acquire this lock inside an inner scope, only long enough to get the
216 // DebuggerThread. StopDebugging() will trigger a call back into
217 // ProcessDebugger which will acquire the lock again, so we need to not
218 // deadlock.
219 llvm::sys::ScopedLock lock(m_mutex);
220
221 if (!m_session_data) {
222 LLDB_LOG(log, "warning: state = {0}, but there is no active session.",
223 state);
224 return Status();
225 }
226
227 debugger_thread = m_session_data->m_debugger;
228 }
229
230 if (state == eStateExited || state == eStateDetached) {
231 LLDB_LOG(log, "warning: cannot destroy process {0} while state = {1}.",
232 GetDebuggedProcessId(), state);
233 return Status();
234 }
235
236 LLDB_LOG(log, "Shutting down process {0}.",
237 debugger_thread->GetProcess().GetNativeProcess().GetSystemHandle());
238 auto error = debugger_thread->StopDebugging(terminate: true);
239
240 // By the time StopDebugging returns, there is no more debugger thread, so
241 // we can be assured that no other thread will race for the session data.
242 m_session_data.reset();
243
244 return error;
245}
246
247Status ProcessDebugger::HaltProcess(bool &caused_stop) {
248 Log *log = GetLog(mask: WindowsLog::Process);
249 Status error;
250 llvm::sys::ScopedLock lock(m_mutex);
251 caused_stop = ::DebugBreakProcess(m_session_data->m_debugger->GetProcess()
252 .GetNativeProcess()
253 .GetSystemHandle());
254 if (!caused_stop) {
255 error.SetError(::GetLastError(), eErrorTypeWin32);
256 LLDB_LOG(log, "DebugBreakProcess failed with error {0}", error);
257 }
258
259 return error;
260}
261
262Status ProcessDebugger::ReadMemory(lldb::addr_t vm_addr, void *buf, size_t size,
263 size_t &bytes_read) {
264 Status error;
265 bytes_read = 0;
266 Log *log = GetLog(mask: WindowsLog::Memory);
267 llvm::sys::ScopedLock lock(m_mutex);
268
269 if (!m_session_data) {
270 error.SetErrorString(
271 "cannot read, there is no active debugger connection.");
272 LLDB_LOG(log, "error: {0}", error);
273 return error;
274 }
275
276 LLDB_LOG(log, "attempting to read {0} bytes from address {1:x}", size,
277 vm_addr);
278
279 HostProcess process = m_session_data->m_debugger->GetProcess();
280 void *addr = reinterpret_cast<void *>(vm_addr);
281 SIZE_T num_of_bytes_read = 0;
282 if (!::ReadProcessMemory(process.GetNativeProcess().GetSystemHandle(), addr,
283 buf, size, &num_of_bytes_read)) {
284 error.SetError(err: GetLastError(), type: eErrorTypeWin32);
285 LLDB_LOG(log, "reading failed with error: {0}", error);
286 } else {
287 bytes_read = num_of_bytes_read;
288 }
289 return error;
290}
291
292Status ProcessDebugger::WriteMemory(lldb::addr_t vm_addr, const void *buf,
293 size_t size, size_t &bytes_written) {
294 Status error;
295 bytes_written = 0;
296 Log *log = GetLog(mask: WindowsLog::Memory);
297 llvm::sys::ScopedLock lock(m_mutex);
298 LLDB_LOG(log, "attempting to write {0} bytes into address {1:x}", size,
299 vm_addr);
300
301 if (!m_session_data) {
302 error.SetErrorString(
303 "cannot write, there is no active debugger connection.");
304 LLDB_LOG(log, "error: {0}", error);
305 return error;
306 }
307
308 HostProcess process = m_session_data->m_debugger->GetProcess();
309 void *addr = reinterpret_cast<void *>(vm_addr);
310 SIZE_T num_of_bytes_written = 0;
311 lldb::process_t handle = process.GetNativeProcess().GetSystemHandle();
312 if (::WriteProcessMemory(handle, addr, buf, size, &num_of_bytes_written)) {
313 FlushInstructionCache(handle, addr, num_of_bytes_written);
314 bytes_written = num_of_bytes_written;
315 } else {
316 error.SetError(err: GetLastError(), type: eErrorTypeWin32);
317 LLDB_LOG(log, "writing failed with error: {0}", error);
318 }
319 return error;
320}
321
322Status ProcessDebugger::AllocateMemory(size_t size, uint32_t permissions,
323 lldb::addr_t &addr) {
324 Status error;
325 addr = LLDB_INVALID_ADDRESS;
326 Log *log = GetLog(mask: WindowsLog::Memory);
327 llvm::sys::ScopedLock lock(m_mutex);
328 LLDB_LOG(log, "attempting to allocate {0} bytes with permissions {1}", size,
329 permissions);
330
331 if (!m_session_data) {
332 error.SetErrorString(
333 "cannot allocate, there is no active debugger connection");
334 LLDB_LOG(log, "error: {0}", error);
335 return error;
336 }
337
338 HostProcess process = m_session_data->m_debugger->GetProcess();
339 lldb::process_t handle = process.GetNativeProcess().GetSystemHandle();
340 auto protect = ConvertLldbToWinApiProtect(permissions);
341 auto result = ::VirtualAllocEx(handle, nullptr, size, MEM_COMMIT, protect);
342 if (!result) {
343 error.SetError(err: GetLastError(), type: eErrorTypeWin32);
344 LLDB_LOG(log, "allocating failed with error: {0}", error);
345 } else {
346 addr = reinterpret_cast<addr_t>(result);
347 }
348 return error;
349}
350
351Status ProcessDebugger::DeallocateMemory(lldb::addr_t vm_addr) {
352 Status result;
353
354 Log *log = GetLog(mask: WindowsLog::Memory);
355 llvm::sys::ScopedLock lock(m_mutex);
356 LLDB_LOG(log, "attempting to deallocate bytes at address {0}", vm_addr);
357
358 if (!m_session_data) {
359 result.SetErrorString(
360 "cannot deallocate, there is no active debugger connection");
361 LLDB_LOG(log, "error: {0}", result);
362 return result;
363 }
364
365 HostProcess process = m_session_data->m_debugger->GetProcess();
366 lldb::process_t handle = process.GetNativeProcess().GetSystemHandle();
367 if (!::VirtualFreeEx(handle, reinterpret_cast<LPVOID>(vm_addr), 0,
368 MEM_RELEASE)) {
369 result.SetError(err: GetLastError(), type: eErrorTypeWin32);
370 LLDB_LOG(log, "deallocating failed with error: {0}", result);
371 }
372
373 return result;
374}
375
376Status ProcessDebugger::GetMemoryRegionInfo(lldb::addr_t vm_addr,
377 MemoryRegionInfo &info) {
378 Log *log = GetLog(mask: WindowsLog::Memory);
379 Status error;
380 llvm::sys::ScopedLock lock(m_mutex);
381 info.Clear();
382
383 if (!m_session_data) {
384 error.SetErrorString(
385 "GetMemoryRegionInfo called with no debugging session.");
386 LLDB_LOG(log, "error: {0}", error);
387 return error;
388 }
389 HostProcess process = m_session_data->m_debugger->GetProcess();
390 lldb::process_t handle = process.GetNativeProcess().GetSystemHandle();
391 if (handle == nullptr || handle == LLDB_INVALID_PROCESS) {
392 error.SetErrorString(
393 "GetMemoryRegionInfo called with an invalid target process.");
394 LLDB_LOG(log, "error: {0}", error);
395 return error;
396 }
397
398 LLDB_LOG(log, "getting info for address {0:x}", vm_addr);
399
400 void *addr = reinterpret_cast<void *>(vm_addr);
401 MEMORY_BASIC_INFORMATION mem_info = {};
402 SIZE_T result = ::VirtualQueryEx(handle, addr, &mem_info, sizeof(mem_info));
403 if (result == 0) {
404 DWORD last_error = ::GetLastError();
405 if (last_error == ERROR_INVALID_PARAMETER) {
406 // ERROR_INVALID_PARAMETER is returned if VirtualQueryEx is called with
407 // an address past the highest accessible address. We should return a
408 // range from the vm_addr to LLDB_INVALID_ADDRESS
409 info.GetRange().SetRangeBase(vm_addr);
410 info.GetRange().SetRangeEnd(LLDB_INVALID_ADDRESS);
411 info.SetReadable(MemoryRegionInfo::eNo);
412 info.SetExecutable(MemoryRegionInfo::eNo);
413 info.SetWritable(MemoryRegionInfo::eNo);
414 info.SetMapped(MemoryRegionInfo::eNo);
415 return error;
416 } else {
417 error.SetError(err: last_error, type: eErrorTypeWin32);
418 LLDB_LOG(log,
419 "VirtualQueryEx returned error {0} while getting memory "
420 "region info for address {1:x}",
421 error, vm_addr);
422 return error;
423 }
424 }
425
426 // Protect bits are only valid for MEM_COMMIT regions.
427 if (mem_info.State == MEM_COMMIT) {
428 const bool readable = IsPageReadable(mem_info.Protect);
429 const bool executable = IsPageExecutable(mem_info.Protect);
430 const bool writable = IsPageWritable(mem_info.Protect);
431 info.SetReadable(readable ? MemoryRegionInfo::eYes : MemoryRegionInfo::eNo);
432 info.SetExecutable(executable ? MemoryRegionInfo::eYes
433 : MemoryRegionInfo::eNo);
434 info.SetWritable(writable ? MemoryRegionInfo::eYes : MemoryRegionInfo::eNo);
435 } else {
436 info.SetReadable(MemoryRegionInfo::eNo);
437 info.SetExecutable(MemoryRegionInfo::eNo);
438 info.SetWritable(MemoryRegionInfo::eNo);
439 }
440
441 // AllocationBase is defined for MEM_COMMIT and MEM_RESERVE but not MEM_FREE.
442 if (mem_info.State != MEM_FREE) {
443 info.GetRange().SetRangeBase(
444 reinterpret_cast<addr_t>(mem_info.BaseAddress));
445 info.GetRange().SetRangeEnd(reinterpret_cast<addr_t>(mem_info.BaseAddress) +
446 mem_info.RegionSize);
447 info.SetMapped(MemoryRegionInfo::eYes);
448 } else {
449 // In the unmapped case we need to return the distance to the next block of
450 // memory. VirtualQueryEx nearly does that except that it gives the
451 // distance from the start of the page containing vm_addr.
452 SYSTEM_INFO data;
453 ::GetSystemInfo(&data);
454 DWORD page_offset = vm_addr % data.dwPageSize;
455 info.GetRange().SetRangeBase(vm_addr);
456 info.GetRange().SetByteSize(mem_info.RegionSize - page_offset);
457 info.SetMapped(MemoryRegionInfo::eNo);
458 }
459
460 LLDB_LOGV(log,
461 "Memory region info for address {0}: readable={1}, "
462 "executable={2}, writable={3}",
463 vm_addr, info.GetReadable(), info.GetExecutable(),
464 info.GetWritable());
465 return error;
466}
467
468void ProcessDebugger::OnExitProcess(uint32_t exit_code) {
469 // If the process exits before any initial stop then notify the debugger
470 // of the error otherwise WaitForDebuggerConnection() will be blocked.
471 // An example of this issue is when a process fails to load a dependent DLL.
472 if (m_session_data && !m_session_data->m_initial_stop_received) {
473 Status error(exit_code, eErrorTypeWin32);
474 OnDebuggerError(error, type: 0);
475 }
476}
477
478void ProcessDebugger::OnDebuggerConnected(lldb::addr_t image_base) {}
479
480ExceptionResult
481ProcessDebugger::OnDebugException(bool first_chance,
482 const ExceptionRecord &record) {
483 Log *log = GetLog(mask: WindowsLog::Exception);
484 llvm::sys::ScopedLock lock(m_mutex);
485 // FIXME: Without this check, occasionally when running the test suite
486 // there is an issue where m_session_data can be null. It's not clear how
487 // this could happen but it only surfaces while running the test suite. In
488 // order to properly diagnose this, we probably need to first figure allow the
489 // test suite to print out full lldb logs, and then add logging to the process
490 // plugin.
491 if (!m_session_data) {
492 LLDB_LOG(log,
493 "Debugger thread reported exception {0:x} at address {1:x}, but "
494 "there is no session.",
495 record.GetExceptionCode(), record.GetExceptionAddress());
496 return ExceptionResult::SendToApplication;
497 }
498
499 ExceptionResult result = ExceptionResult::SendToApplication;
500 if ((record.GetExceptionCode() == EXCEPTION_BREAKPOINT ||
501 record.GetExceptionCode() ==
502 0x4000001FL /*WOW64 STATUS_WX86_BREAKPOINT*/) &&
503 !m_session_data->m_initial_stop_received) {
504 // Handle breakpoints at the first chance.
505 result = ExceptionResult::BreakInDebugger;
506 LLDB_LOG(
507 log,
508 "Hit loader breakpoint at address {0:x}, setting initial stop event.",
509 record.GetExceptionAddress());
510 m_session_data->m_initial_stop_received = true;
511 ::SetEvent(m_session_data->m_initial_stop_event);
512 }
513 return result;
514}
515
516void ProcessDebugger::OnCreateThread(const HostThread &thread) {
517 // Do nothing by default
518}
519
520void ProcessDebugger::OnExitThread(lldb::tid_t thread_id, uint32_t exit_code) {
521 // Do nothing by default
522}
523
524void ProcessDebugger::OnLoadDll(const ModuleSpec &module_spec,
525 lldb::addr_t module_addr) {
526 // Do nothing by default
527}
528
529void ProcessDebugger::OnUnloadDll(lldb::addr_t module_addr) {
530 // Do nothing by default
531}
532
533void ProcessDebugger::OnDebugString(const std::string &string) {}
534
535void ProcessDebugger::OnDebuggerError(const Status &error, uint32_t type) {
536 llvm::sys::ScopedLock lock(m_mutex);
537 Log *log = GetLog(mask: WindowsLog::Process);
538
539 if (m_session_data->m_initial_stop_received) {
540 // This happened while debugging. Do we shutdown the debugging session,
541 // try to continue, or do something else?
542 LLDB_LOG(log,
543 "Error {0} occurred during debugging. Unexpected behavior "
544 "may result. {1}",
545 error.GetError(), error);
546 } else {
547 // If we haven't actually launched the process yet, this was an error
548 // launching the process. Set the internal error and signal the initial
549 // stop event so that the DoLaunch method wakes up and returns a failure.
550 m_session_data->m_launch_error = error;
551 ::SetEvent(m_session_data->m_initial_stop_event);
552 LLDB_LOG(log,
553 "Error {0} occurred launching the process before the initial "
554 "stop. {1}",
555 error.GetError(), error);
556 return;
557 }
558}
559
560Status ProcessDebugger::WaitForDebuggerConnection(DebuggerThreadSP debugger,
561 HostProcess &process) {
562 Status result;
563 Log *log = GetLog(mask: WindowsLog::Process | WindowsLog::Breakpoints);
564 LLDB_LOG(log, "Waiting for loader breakpoint.");
565
566 // Block this function until we receive the initial stop from the process.
567 if (::WaitForSingleObject(m_session_data->m_initial_stop_event, INFINITE) ==
568 WAIT_OBJECT_0) {
569 LLDB_LOG(log, "hit loader breakpoint, returning.");
570
571 process = debugger->GetProcess();
572 return m_session_data->m_launch_error;
573 } else
574 return Status(::GetLastError(), eErrorTypeWin32);
575}
576
577} // namespace lldb_private
578

source code of lldb/source/Plugins/Process/Windows/Common/ProcessDebugger.cpp