gdb/nat/windows-nat.h

   1 /* Internal interfaces for the Windows code
   2    Copyright (C) 1995-2024 Free Software Foundation, Inc.
   3
   4    This file is part of GDB.
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  18
  19 #ifndef NAT_WINDOWS_NAT_H
  20 #define NAT_WINDOWS_NAT_H
  21
  22 #include <windows.h>
  23 #include <psapi.h>
  24 #include <vector>
  25
  26 #include <optional>
  27 #include "target/waitstatus.h"
  28
  29 #define STATUS_WX86_BREAKPOINT 0x4000001F
  30 #define STATUS_WX86_SINGLE_STEP 0x4000001E
  31
  32 namespace windows_nat
  33 {
  34
  35 /* Thread information structure used to track extra information about
  36    each thread.  */
  37 struct windows_thread_info
  38 {
  39   windows_thread_info (DWORD tid_, HANDLE h_, CORE_ADDR tlb)
  40     : tid (tid_),
  41       h (h_),
  42       thread_local_base (tlb)
  43   {
  44   }
  45
  46   DISABLE_COPY_AND_ASSIGN (windows_thread_info);
  47
  48   /* Ensure that this thread has been suspended.  */
  49   void suspend ();
  50
  51   /* Resume the thread if it has been suspended.  */
  52   void resume ();
  53
  54   /* Return the thread's name, or nullptr if not known.  The name is
  55      stored in this thread and is guaranteed to live until at least
  56      the next call.  */
  57   const char *thread_name ();
  58
  59   /* The Win32 thread identifier.  */
  60   DWORD tid;
  61
  62   /* The handle to the thread.  */
  63   HANDLE h;
  64
  65   /* Thread Information Block address.  */
  66   CORE_ADDR thread_local_base;
  67
  68   /* This keeps track of whether SuspendThread was called on this
  69      thread.  -1 means there was a failure or that the thread was
  70      explicitly not suspended, 1 means it was called, and 0 means it
  71      was not.  */
  72   int suspended = 0;
  73
  74   /* The context of the thread, including any manipulations.  */
  75   union
  76   {
  77     CONTEXT context {};
  78 #ifdef __x86_64__
  79     WOW64_CONTEXT wow64_context;
  80 #endif
  81   };
  82
  83   /* Whether debug registers changed since we last set CONTEXT back to
  84      the thread.  */
  85   bool debug_registers_changed = false;
  86
  87   /* Nonzero if CONTEXT is invalidated and must be re-read from the
  88      inferior thread.  */
  89   bool reload_context = false;
  90
  91   /* True if this thread is currently stopped at a software
  92      breakpoint.  This is used to offset the PC when needed.  */
  93   bool stopped_at_software_breakpoint = false;
  94
  95   /* True if we've adjusted the PC after hitting a software
  96      breakpoint, false otherwise.  This lets us avoid multiple
  97      adjustments if the registers are read multiple times.  */
  98   bool pc_adjusted = false;
  99
 100   /* The name of the thread.  */
 101   gdb::unique_xmalloc_ptr<char> name;
 102 };
 103
 104
 105 /* Possible values to pass to 'thread_rec'.  */
 106 enum thread_disposition_type
 107 {
 108   /* Do not invalidate the thread's context, and do not suspend the
 109      thread.  */
 110   DONT_INVALIDATE_CONTEXT,
 111   /* Invalidate the context, but do not suspend the thread.  */
 112   DONT_SUSPEND,
 113   /* Invalidate the context and suspend the thread.  */
 114   INVALIDATE_CONTEXT
 115 };
 116
 117 /* A single pending stop.  See "pending_stops" for more
 118    information.  */
 119 struct pending_stop
 120 {
 121   /* The thread id.  */
 122   DWORD thread_id;
 123
 124   /* The target waitstatus we computed.  */
 125   target_waitstatus status;
 126
 127   /* The event.  A few fields of this can be referenced after a stop,
 128      and it seemed simplest to store the entire event.  */
 129   DEBUG_EVENT event;
 130 };
 131
 132 enum handle_exception_result
 133 {
 134   HANDLE_EXCEPTION_UNHANDLED = 0,
 135   HANDLE_EXCEPTION_HANDLED,
 136   HANDLE_EXCEPTION_IGNORED
 137 };
 138
 139 /* A single Windows process.  An object of this type (or subclass) is
 140    created by the client.  Some methods must be provided by the client
 141    as well.  */
 142
 143 struct windows_process_info
 144 {
 145   /* The process handle */
 146   HANDLE handle = 0;
 147   DWORD main_thread_id = 0;
 148   enum gdb_signal last_sig = GDB_SIGNAL_0;
 149
 150   /* The current debug event from WaitForDebugEvent or from a pending
 151      stop.  */
 152   DEBUG_EVENT current_event {};
 153
 154   /* The ID of the thread for which we anticipate a stop event.
 155      Normally this is -1, meaning we'll accept an event in any
 156      thread.  */
 157   DWORD desired_stop_thread_id = -1;
 158
 159   /* A vector of pending stops.  Sometimes, Windows will report a stop
 160      on a thread that has been ostensibly suspended.  We believe what
 161      happens here is that two threads hit a breakpoint simultaneously,
 162      and the Windows kernel queues the stop events.  However, this can
 163      result in the strange effect of trying to single step thread A --
 164      leaving all other threads suspended -- and then seeing a stop in
 165      thread B.  To handle this scenario, we queue all such "pending"
 166      stops here, and then process them once the step has completed.  See
 167      PR gdb/22992.  */
 168   std::vector<pending_stop> pending_stops;
 169
 170   /* Contents of $_siginfo */
 171   EXCEPTION_RECORD siginfo_er {};
 172
 173 #ifdef __x86_64__
 174   /* The target is a WOW64 process */
 175   bool wow64_process = false;
 176   /* Ignore first breakpoint exception of WOW64 process */
 177   bool ignore_first_breakpoint = false;
 178 #endif
 179
 180
 181   /* Find a thread record given a thread id.  THREAD_DISPOSITION
 182      controls whether the thread is suspended, and whether the context
 183      is invalidated.
 184
 185      This function must be supplied by the embedding application.  */
 186   virtual windows_thread_info *thread_rec (ptid_t ptid,
 187                                            thread_disposition_type disposition) = 0;
 188
 189   /* Handle OUTPUT_DEBUG_STRING_EVENT from child process.  Updates
 190      OURSTATUS and returns the thread id if this represents a thread
 191      change (this is specific to Cygwin), otherwise 0.
 192
 193      Cygwin prepends its messages with a "cygwin:".  Interpret this as
 194      a Cygwin signal.  Otherwise just print the string as a warning.
 195
 196      This function must be supplied by the embedding application.  */
 197   virtual int handle_output_debug_string (struct target_waitstatus *ourstatus) = 0;
 198
 199   /* Handle a DLL load event.
 200
 201      This function assumes that the current event did not occur during
 202      inferior initialization.
 203
 204      DLL_NAME is the name of the library.  BASE is the base load
 205      address.
 206
 207      This function must be supplied by the embedding application.  */
 208
 209   virtual void handle_load_dll (const char *dll_name, LPVOID base) = 0;
 210
 211   /* Handle a DLL unload event.
 212
 213      This function assumes that this event did not occur during inferior
 214      initialization.
 215
 216      This function must be supplied by the embedding application.  */
 217
 218   virtual void handle_unload_dll () = 0;
 219
 220   /* When EXCEPTION_ACCESS_VIOLATION is processed, we give the embedding
 221      application a chance to change it to be considered "unhandled".
 222      This function must be supplied by the embedding application.  If it
 223      returns true, then the exception is "unhandled".  */
 224
 225   virtual bool handle_access_violation (const EXCEPTION_RECORD *rec) = 0;
 226
 227   handle_exception_result handle_exception
 228        (struct target_waitstatus *ourstatus, bool debug_exceptions);
 229
 230   /* Call to indicate that a DLL was loaded.  */
 231
 232   void dll_loaded_event ();
 233
 234   /* Iterate over all DLLs currently mapped by our inferior, and
 235      add them to our list of solibs.  */
 236
 237   void add_all_dlls ();
 238
 239   /* Return true if there is a pending stop matching
 240      desired_stop_thread_id.  If DEBUG_EVENTS is true, logging will be
 241      enabled.  */
 242
 243   bool matching_pending_stop (bool debug_events);
 244
 245   /* See if a pending stop matches DESIRED_STOP_THREAD_ID.  If so,
 246      remove it from the list of pending stops, set 'current_event', and
 247      return it.  Otherwise, return an empty optional.  */
 248
 249   std::optional<pending_stop> fetch_pending_stop (bool debug_events);
 250
 251   const char *pid_to_exec_file (int);
 252
 253 private:
 254
 255   /* Handle MS_VC_EXCEPTION when processing a stop.  MS_VC_EXCEPTION is
 256      somewhat undocumented but is used to tell the debugger the name of
 257      a thread.
 258
 259      Return true if the exception was handled; return false otherwise.  */
 260
 261   bool handle_ms_vc_exception (const EXCEPTION_RECORD *rec);
 262
 263   /* Iterate over all DLLs currently mapped by our inferior, looking for
 264      a DLL which is loaded at LOAD_ADDR.  If found, add the DLL to our
 265      list of solibs; otherwise do nothing.  LOAD_ADDR NULL means add all
 266      DLLs to the list of solibs; this is used when the inferior finishes
 267      its initialization, and all the DLLs it statically depends on are
 268      presumed loaded.  */
 269
 270   void add_dll (LPVOID load_addr);
 271
 272   /* Try to determine the executable filename.
 273
 274      EXE_NAME_RET is a pointer to a buffer whose size is EXE_NAME_MAX_LEN.
 275
 276      Upon success, the filename is stored inside EXE_NAME_RET, and
 277      this function returns nonzero.
 278
 279      Otherwise, this function returns zero and the contents of
 280      EXE_NAME_RET is undefined.  */
 281
 282   int get_exec_module_filename (char *exe_name_ret, size_t exe_name_max_len);
 283 };
 284
 285 /* A simple wrapper for ContinueDebugEvent that continues the last
 286    waited-for event.  If DEBUG_EVENTS is true, logging will be
 287    enabled.  */
 288
 289 extern BOOL continue_last_debug_event (DWORD continue_status,
 290                                        bool debug_events);
 291
 292 /* A simple wrapper for WaitForDebugEvent that also sets the internal
 293    'last_wait_event' on success.  */
 294
 295 extern BOOL wait_for_debug_event (DEBUG_EVENT *event, DWORD timeout);
 296
 297 /* Wrappers for CreateProcess.  These exist primarily so that the
 298    "disable randomization" feature can be implemented in a single
 299    place.  */
 300
 301 extern BOOL create_process (const char *image, char *command_line,
 302                             DWORD flags, void *environment,
 303                             const char *cur_dir,
 304                             bool no_randomization,
 305                             STARTUPINFOA *startup_info,
 306                             PROCESS_INFORMATION *process_info);
 307 #ifdef __CYGWIN__
 308 extern BOOL create_process (const wchar_t *image, wchar_t *command_line,
 309                             DWORD flags, void *environment,
 310                             const wchar_t *cur_dir,
 311                             bool no_randomization,
 312                             STARTUPINFOW *startup_info,
 313                             PROCESS_INFORMATION *process_info);
 314 #endif /* __CYGWIN__ */
 315
 316 #define AdjustTokenPrivileges           dyn_AdjustTokenPrivileges
 317 #define DebugActiveProcessStop          dyn_DebugActiveProcessStop
 318 #define DebugBreakProcess               dyn_DebugBreakProcess
 319 #define DebugSetProcessKillOnExit       dyn_DebugSetProcessKillOnExit
 320 #undef EnumProcessModules
 321 #define EnumProcessModules              dyn_EnumProcessModules
 322 #undef EnumProcessModulesEx
 323 #define EnumProcessModulesEx            dyn_EnumProcessModulesEx
 324 #undef GetModuleInformation
 325 #define GetModuleInformation            dyn_GetModuleInformation
 326 #undef GetModuleFileNameExA
 327 #define GetModuleFileNameExA            dyn_GetModuleFileNameExA
 328 #undef GetModuleFileNameExW
 329 #define GetModuleFileNameExW            dyn_GetModuleFileNameExW
 330 #define LookupPrivilegeValueA           dyn_LookupPrivilegeValueA
 331 #define OpenProcessToken                dyn_OpenProcessToken
 332 #define GetConsoleFontSize              dyn_GetConsoleFontSize
 333 #define GetCurrentConsoleFont           dyn_GetCurrentConsoleFont
 334 #define Wow64SuspendThread              dyn_Wow64SuspendThread
 335 #define Wow64GetThreadContext           dyn_Wow64GetThreadContext
 336 #define Wow64SetThreadContext           dyn_Wow64SetThreadContext
 337 #define Wow64GetThreadSelectorEntry     dyn_Wow64GetThreadSelectorEntry
 338 #define GenerateConsoleCtrlEvent        dyn_GenerateConsoleCtrlEvent
 339 #define InitializeProcThreadAttributeList dyn_InitializeProcThreadAttributeList
 340 #define UpdateProcThreadAttribute dyn_UpdateProcThreadAttribute
 341 #define DeleteProcThreadAttributeList dyn_DeleteProcThreadAttributeList
 342
 343 typedef BOOL WINAPI (AdjustTokenPrivileges_ftype) (HANDLE, BOOL,
 344                                                    PTOKEN_PRIVILEGES,
 345                                                    DWORD, PTOKEN_PRIVILEGES,
 346                                                    PDWORD);
 347 extern AdjustTokenPrivileges_ftype *AdjustTokenPrivileges;
 348
 349 typedef BOOL WINAPI (DebugActiveProcessStop_ftype) (DWORD);
 350 extern DebugActiveProcessStop_ftype *DebugActiveProcessStop;
 351
 352 typedef BOOL WINAPI (DebugBreakProcess_ftype) (HANDLE);
 353 extern DebugBreakProcess_ftype *DebugBreakProcess;
 354
 355 typedef BOOL WINAPI (DebugSetProcessKillOnExit_ftype) (BOOL);
 356 extern DebugSetProcessKillOnExit_ftype *DebugSetProcessKillOnExit;
 357
 358 typedef BOOL WINAPI (EnumProcessModules_ftype) (HANDLE, HMODULE *, DWORD,
 359                                                 LPDWORD);
 360 extern EnumProcessModules_ftype *EnumProcessModules;
 361
 362 #ifdef __x86_64__
 363 typedef BOOL WINAPI (EnumProcessModulesEx_ftype) (HANDLE, HMODULE *, DWORD,
 364                                                   LPDWORD, DWORD);
 365 extern EnumProcessModulesEx_ftype *EnumProcessModulesEx;
 366 #endif
 367
 368 typedef BOOL WINAPI (GetModuleInformation_ftype) (HANDLE, HMODULE,
 369                                                   LPMODULEINFO, DWORD);
 370 extern GetModuleInformation_ftype *GetModuleInformation;
 371
 372 typedef DWORD WINAPI (GetModuleFileNameExA_ftype) (HANDLE, HMODULE, LPSTR,
 373                                                   DWORD);
 374 extern GetModuleFileNameExA_ftype *GetModuleFileNameExA;
 375
 376 typedef DWORD WINAPI (GetModuleFileNameExW_ftype) (HANDLE, HMODULE,
 377                                                    LPWSTR, DWORD);
 378 extern GetModuleFileNameExW_ftype *GetModuleFileNameExW;
 379
 380 typedef BOOL WINAPI (LookupPrivilegeValueA_ftype) (LPCSTR, LPCSTR, PLUID);
 381 extern LookupPrivilegeValueA_ftype *LookupPrivilegeValueA;
 382
 383 typedef BOOL WINAPI (OpenProcessToken_ftype) (HANDLE, DWORD, PHANDLE);
 384 extern OpenProcessToken_ftype *OpenProcessToken;
 385
 386 typedef BOOL WINAPI (GetCurrentConsoleFont_ftype) (HANDLE, BOOL,
 387                                                    CONSOLE_FONT_INFO *);
 388 extern GetCurrentConsoleFont_ftype *GetCurrentConsoleFont;
 389
 390 typedef COORD WINAPI (GetConsoleFontSize_ftype) (HANDLE, DWORD);
 391 extern GetConsoleFontSize_ftype *GetConsoleFontSize;
 392
 393 #ifdef __x86_64__
 394 typedef DWORD WINAPI (Wow64SuspendThread_ftype) (HANDLE);
 395 extern Wow64SuspendThread_ftype *Wow64SuspendThread;
 396
 397 typedef BOOL WINAPI (Wow64GetThreadContext_ftype) (HANDLE, PWOW64_CONTEXT);
 398 extern Wow64GetThreadContext_ftype *Wow64GetThreadContext;
 399
 400 typedef BOOL WINAPI (Wow64SetThreadContext_ftype) (HANDLE,
 401                                                    const WOW64_CONTEXT *);
 402 extern Wow64SetThreadContext_ftype *Wow64SetThreadContext;
 403
 404 typedef BOOL WINAPI (Wow64GetThreadSelectorEntry_ftype) (HANDLE, DWORD,
 405                                                          PLDT_ENTRY);
 406 extern Wow64GetThreadSelectorEntry_ftype *Wow64GetThreadSelectorEntry;
 407 #endif
 408
 409 typedef BOOL WINAPI (GenerateConsoleCtrlEvent_ftype) (DWORD, DWORD);
 410 extern GenerateConsoleCtrlEvent_ftype *GenerateConsoleCtrlEvent;
 411
 412 /* We use a local typedef for this type to avoid depending on
 413    Windows 8.  */
 414 typedef void *gdb_lpproc_thread_attribute_list;
 415
 416 typedef BOOL WINAPI (InitializeProcThreadAttributeList_ftype)
 417      (gdb_lpproc_thread_attribute_list lpAttributeList,
 418       DWORD dwAttributeCount, DWORD dwFlags, PSIZE_T lpSize);
 419 extern InitializeProcThreadAttributeList_ftype *InitializeProcThreadAttributeList;
 420
 421 typedef BOOL WINAPI (UpdateProcThreadAttribute_ftype)
 422      (gdb_lpproc_thread_attribute_list lpAttributeList,
 423       DWORD dwFlags, DWORD_PTR Attribute, PVOID lpValue, SIZE_T cbSize,
 424       PVOID lpPreviousValue, PSIZE_T lpReturnSize);
 425 extern UpdateProcThreadAttribute_ftype *UpdateProcThreadAttribute;
 426
 427 typedef void WINAPI (DeleteProcThreadAttributeList_ftype)
 428      (gdb_lpproc_thread_attribute_list lpAttributeList);
 429 extern DeleteProcThreadAttributeList_ftype *DeleteProcThreadAttributeList;
 430
 431 /* Return true if it's possible to disable randomization on this
 432    host.  */
 433
 434 extern bool disable_randomization_available ();
 435
 436 /* Load any functions which may not be available in ancient versions
 437    of Windows.  */
 438
 439 extern bool initialize_loadable ();
 440
 441 }
 442
 443 #endif