documentation/winedbg

   1 I Introduction
   2 ==============
   3
   4 I.1 Processes and threads: in underlying OS and in Windows
   5 ----------------------------------------------------------
   6 Before going into the depths of debugging in Wine, here's a small
   7 overview of process and thread handling in Wine. It has to be clear
   8 that there are two different beasts: processes/threads from the Unix
   9 point of view and processes/threads from a Windows point of view.
  10
  11 Each Windows' thread is implemented as a Unix process (under Linux
  12 using the clone syscall), meaning that all threads of a same Windows'
  13 process share the same (unix) address space.
  14
  15 In the following:
  16 + W-process means a process in Windows' terminology
  17 + U-process means a process in Unix' terminology
  18 + W-thread means a thread in Windows' terminology
  19
  20 A W-process is made of one or several W-threads.
  21 Each W-thread is mapped to one and only one U-process. All U-processes
  22 of a same W-process share the same address space.
  23
  24 Each Unix process can be identified by two values:
  25 - the Unix process id (upid in the following)
  26 - the Windows's thread id (tid)
  27 Each Windows' process has also a Windows' process (wpid in the
  28 following). It must be clear that upid and wpid are different and
  29 shall not be used instead of the other.
  30
  31 Wpid and tid are defined (Windows) system wide. They must not be
  32 confused with process or thread handles which, as any handle, is an
  33 indirection to a system object (in this case process or thread). A
  34 same process can have several different handles on the same kernel
  35 object. The handles can be defined as local (the values is only valid
  36 in a process), or system wide (the same handle can be used by any
  37 W-process).
  38
  39
  40 I.2 Wine, debugging and WineDbg
  41 -------------------------------
  42 When talking of debugging in Wine, there are at least two levels to
  43 think of:
  44 + the Windows' debugging API.
  45 + the Wine integrated debugger, dubbed WineDbg.
  46
  47 Wine implements most the the Windows' debugging API (the part in
  48 KERNEL32, not the one in IMAGEHLP.DLL), and allows any program
  49 (emulated or WineLib) using that API to debug a W-process.
  50
  51 WineDbg is a WineLib application making use of this API to allow
  52 debugging both any Wine or WineLib applications as well as Wine itself
  53 (kernel and all DLLs).
  54
  55 II WineDbg's modes of invocation
  56 ================================
  57
  58 II.1 Starting a process
  59 -----------------------
  60 Any application (either a Windows' native executable, or a WineLib
  61 application) can be run through WineDbg. Command line options and
  62 tricks are the same than for wine:
  63
  64 winedbg telnet.exe
  65 winedbg "hl.exe -windowed"
  66
  67 II.2 Attaching
  68 --------------
  69 WineDbg can also launched without any command line argument:
  70 - WineDbg is started without any attached process. You can get a list
  71 of running W-processes (and their wpid:s) using 'walk process'
  72 command, and then, with the attach command, pick up the wpid of the
  73 W-process you want to debug.
  74
  75 This is (for now) a neat feature for the following reasons:
  76 * debug an already started application
  77
  78 II.3 On exception
  79 -----------------
  80 When something goes wrong, Windows track this as an
  81 exception. Exceptions exist for segmentation violation, stack
  82 overflow, division by zero...
  83
  84 When an exception occurs, Wine checks if the W-process is debugged. If
  85 so, the exception event is sent to the debugger, which takes care of
  86 it: end of the story. This mechanism is part of the standard Windows'
  87 debugging API.
  88
  89 If the W-process is not debugged, Wine tries to launch a
  90 debugger. This debugger (normally WineDbg, see III Configuration for
  91 more details), at startup, attaches to the W-process which generated
  92 the exception event. In this case, you are able to look at the causes
  93 of the exception, and either fix the causes (and continue further the
  94 execution) or dig deeper to understand what went wrong.
  95
  96 If WineDbg is the standard debugger, the 'pass' and 'cont' commands
  97 are the two ways to let the process go further for the handling of the
  98 exception event.
  99
 100 To be more precise on the way Wine (and Windows) generates exception
 101 events, when a fault occurs (segmentation violation, stack
 102 overflow...), the event is first sent to the debugger (this is know as
 103 a first chance exception). The debugger can give two answers:
 104 - continue: the debugger had the ability to correct what's generated
 105 the exception, and is now able to continue process execution.
 106 - pass: the debugger couldn't correct the cause of the (first chance
 107 exception). Wine will now try to walk the list of exception handlers
 108 to see if one of them can handle the exception. If no exception
 109 handler is found, the exception is sent once again to the debugger to
 110 indicate the failure of the exception handling.
 111
 112 Note: since some of Wine's code uses exceptions and try/catch blocks
 113 to provide some functionality, WineDbg can be entered in such cases
 114 with segv exceptions. This happens, for example, with IsBadReadPtr
 115 function. In that case, the pass command shall be used, to let the
 116 handling of the exception to be done by the catch block in
 117 IsBadReadPtr.
 118
 119 II.4 Quitting
 120 -------------
 121 Unfortunately, Windows' don't provide a detach kind of API, meaning
 122 that once you started debugging a process, you must do so until the
 123 process dies. Killing (or stopping/aborting) the debugger will also
 124 kill the debugged process.
 125 This will be true for any Windows' debugging API compliant debugger,
 126 starting with WineDbg.
 127
 128 III Configuration
 129 =================
 130
 131 III.1 Registry configuration
 132 ----------------------------
 133 The Windows' debugging API uses a registry entry to know with debugger
 134 to invoke when an unhandled exception occurs (see II.3 for some
 135 details).
 136 Two values in key
 137 "MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
 138 determine the behavior:
 139 + Debugger: this is the command line used to launch the debugger (it
 140 uses two printf formats (%ld) to pass context dependent information to
 141 the debugger). You should put here a complete path to your debugger
 142 (WineDbg can of course be used, but any other Windows' debugging API
 143 aware debugger will do).
 144 + Auto: if this value is zero, a message box will ask the user if
 145 he/she wishes to launch the debugger when an unhandled exception
 146 occurs. Otherwise, the debugger is automatically started.
 147
 148 A regular Wine registry looks like:
 149 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
 150 "Auto"=dword:00000001
 151 "Debugger"="/usr/local/bin/winedbg %ld %ld"
 152
 153 Note 1: creating this key is mandatory. Not doing so will not fire the
 154 debugger when an exception occurs.
 155
 156 Note 2: wineinstall sets up this correctly. However, due to some
 157 limitation of the registry installed, if a previous Wine installation
 158 exists, it's safer to remove the whole
 159 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
 160 key before running again wineinstall to regenerate this key.
 161
 162 III.2 WineDbg configuration
 163 ---------------------------
 164 WineDbg can be configured thru a number of options. Those options are
 165 stored in the registry, on a per user basis. The key is (in *my*
 166 registry) [eric\\Software\\Wine\\WineDbg]
 167 Those options can be read/written while inside WineDbg, as part of the
 168 debugger expressions. To refer to one of this option, its name must be
 169 prefixed by a $ sign.
 170 For example,
 171 set $BreakAllThreadsStartup = 1
 172 sets the option 'BreakAllThreadsStartup' to TRUE.
 173 All the options are read from the registry when WineDbg starts (if no
 174 corresponding value is found, a default value is used), and are
 175 written back to the registry when WineDbg exits (hence, all
 176 modifications to those options are automatically saved when WineDbg
 177 terminates).
 178
 179 Here's the list of all options:
 180
 181 III.2.1 Controling when the debugger is entered
 182
 183 BreakAllThreadsStartup  set to TRUE if at all threads start-up the
 184                         debugger stops
 185                         set to FALSE if only at the first thread
 186                         startup of a given process the debugger stops.
 187                         FALSE by default.
 188 BreakOnCritSectTimeOut  set to TRUE if the debugger stops when a
 189                         critical section times out (5 minutes);
 190                         TRUE by default.
 191 BreakOnAttach,          set to TRUE if when WineDbg attaches to an
 192                         existing process after an unhandled exception,
 193                         WineDbg shall be entered on the first attach
 194                         event.
 195                         Since the attach event is meaningless in the
 196                         context of an exception event (the next event
 197                         which is the exception event is of course
 198                         relevant), that option is likely to be FALSE.
 199 BreakOnDllLoad          When set to TRUE, allows the debugger to be
 200                         entered when a new DLL is loaded into the system.
 201                         FALSE by default.
 202 BreakOnFirstChance      an exception can generate two debug events.
 203                         The first one is passed to the debugger (known
 204                         as a first chance) just after the
 205                         exception. The debugger can then decides
 206                         either to resume execution (see winedbg's cont
 207                         command) or pass the exception up to the
 208                         exception handler chain in the program (if it
 209                         exists) (winedbg implements this thru the pass
 210                         command). If none of the exception handlers
 211                         takes care of the exception, the exception
 212                         event is sent again to the debugger (known as
 213                         last chance exception). You cannot pass on a
 214                         last exception. When the BreakOnFirstChance
 215                         exception is TRUE, then winedbg is entered for
 216                         both  first and last chance execptions (to
 217                         FALSE, it's only entered for last chance exceptions).
 218
 219 III.2.1 Output handling
 220
 221 ConChannelMask          mask of active debugger output channels on
 222                         console
 223 StdChannelMask          mask of active debugger output channels on
 224                         stderr
 225
 226 UseXTerm                set to TRUE if the debugger uses its own xterm
 227                         window for console input/output
 228                         set to FALSE is the debugger uses the current
 229                         Unix console for input/output
 230
 231 Those last 3 variables are jointly used in two generic ways:
 232 1/ default
 233         ConChannelMask = DBG_CHN_MESG (1)
 234         StdChannelMask = 0
 235         UseXTerm = 1
 236 In this case, all input/output goes into a specific xterm window (but
 237 all debug messages TRACE/WARN... still goes to tty where wine is run
 238 from).
 239
 240 2/ to have all input/output go into the tty where Wine was started
 241 from (to be used in a X11-free environment)
 242         ConChannelMask = 0
 243         StdChannelMask = DBG_CHN_MESG (1)
 244         UseXTerm = 1
 245
 246 Those variables also allow, for example for debugging purposes, to
 247 use:
 248         ConChannelMask = 0xfff
 249         StdChannelMask = 0xfff
 250         UseXTerm = 1
 251 This allows to redirect all WineDbg output to both tty Wine was
 252 started from, and xterm debugging window. If Wine (or WineDbg) was
 253 started with a redirection of stdout and/or stderr to a file (with for
 254 example >& shell redirect command), you'll get in that file both
 255 outputs. It may be interesting to look in the relay trace for specific
 256 values which the process segv:ed on.
 257
 258 III.2.3 Context information
 259
 260 ThreadId                ID of the W-thread currently examined by the
 261                         debugger
 262 ProcessId               ID of the W-thread currently examined by the
 263                         debugger
 264 <registers>             All CPU registers are also available
 265
 266 The ThreadId and ProcessId variables can be handy to set conditional
 267 breakpoints on a given thread or process.
 268
 269 IV WineDbg commands
 270 ===================
 271
 272 IV.1 Misc
 273 ---------
 274 abort           aborts the debugger
 275 quit            exits the debugger
 276
 277 attach N        attach to a W-process (N is its ID). IDs can be
 278                 obtained thru walk process command
 279
 280 help            prints some help on the commands
 281 help info       prints some help on info commands
 282
 283 mode 16         switch to 16 bit mode
 284 mode 32         switch to 32 bit mode
 285
 286 IV.2 Flow control
 287 -----------------
 288 cont            continue execution until next breakpoint or exception.
 289 pass            pass the exception event up to the filter chain.
 290 step            continue execution until next C line of code (enters
 291                 function call)
 292 next            continue execution until next C line of code (doesn't
 293                 enter function call)
 294 stepi           execute next assembly instruction (enters function
 295                 call)
 296 nexti           execute next assembly instruction (doesn't enter
 297                 function call)
 298 finish          do nexti commands until current function is exited
 299
 300 cont, step, next, stepi, nexti can be postfixed by a number (N),
 301 meaning that the command must be executed N times.
 302
 303 IV.3 Breakpoints, watch points
 304 ------------------------------
 305 enable N        enables (break|watch)point #N
 306 disable N       disables (break|watch)point #N
 307 delete N        deletes  (break|watch)point #N
 308 cond N          removes any a existing condition to (break|watch)point N
 309 cond N <expr>   adds condition <expr> to (break|watch)point N. <expr>
 310                 will be evaluated each time the breakpoint is hit. If
 311                 the result is a zero value, the breakpoint isn't
 312                 triggered
 313 break * N       adds a breakpoint at address N
 314 break <id>      adds a breakpoint at the address of symbol <id>
 315 break <id> N    adds a breakpoint at the address of symbol <id> (N ?)
 316 break N         adds a breakpoint at line N of current source file
 317 break           adds a breakpoint at current $pc address
 318 watch * N       adds a watch command (on write) at address N (on 4 bytes)
 319 watch <id>      adds a watch command (on write) at the address of
 320                 symbol <id>
 321 info break      lists all (break|watch)points (with state)
 322
 323 IV.4 Stack manipulation
 324 -----------------------
 325 bt              print calling stack of current thread
 326 up              goes up one frame in current thread's stack
 327 up N            goes up N frames in current thread's stack
 328 dn              goes down one frame in current thread's stack
 329 dn N            goes down N frames in current thread's stack
 330 frame N         set N as the current frame
 331 info local      prints information on local variables for current
 332                 function
 333
 334 IV.5 Directory & source file manipulation
 335 -----------------------------------------
 336 show dir
 337 dir <pathname>
 338 dir
 339 symbolfile <pathname>
 340
 341 list            lists 10 source lines from current position
 342 list -          lists 10 source lines before current position
 343 list N          lists 10 source lines from line N in current file
 344 list <path>:N   lists 10 source lines from line N in file <path>
 345 list <id>       lists 10 source lines of function <id>
 346 list * N        lists 10 source lines from address N
 347
 348 You can specify the end target (to change the 10 lines value) using
 349 the ','. For example:
 350 list 123, 234   lists source lines from line 123 up to line 234 in
 351                 current file
 352 list foo.c:1,56 lists source lines from line 1 up to 56 in file foo.c
 353
 354 IV.6 Displaying
 355 ---------------
 356 a display is an expression that's evaluated and printed after the
 357 execution of any WineDbg command
 358
 359 display         lists the active displays
 360 info display    (same as above command)
 361 display <expr>  adds a display for expression <expr>
 362 display /fmt <expr>     adds a display for expression <expr>. Printing
 363                 evaluated <expr> is done using the given format (see
 364                 print command for more on formats)
 365 del display N   deletes display #N
 366 undisplay N     (same as del display)
 367
 368 IV.7 Disassembly
 369 ----------------
 370 disas           disassemble from current position
 371 disas <expr>    disassemble from address <expr>
 372 disas <expr>,<expr>disassembles code between addresses specified by
 373                 the two <expr>
 374
 375 IV.8 Information on Wine's internals
 376 ------------------------------------
 377 info class <id> prints information on Windows's class <id>
 378 walk class      lists all Windows' class registered in Wine
 379 info share      lists all the dynamic libraries loaded the debugged
 380                 program (including .so files, NE and PE DLLs)
 381 info module N   prints information on module of handle N
 382 walk module     lists all modules loaded by debugged program
 383 info queue N    prints information on Wine's queue N
 384 walk queue      lists all queues allocated in Wine
 385 info regs       prints the value of CPU register
 386 info segment N  prints information on segment N
 387 info segment    lists all allocated segments
 388 info stack      prints the values on top of the stack
 389 info map        lists all virtual mappings used by the debugged
 390                 program
 391 info wnd N      prints information of Window of handle N
 392 walk wnd        lists all the window hierarchy starting from the
 393                 desktop window
 394 walk wnd N      lists all the window hierarchy starting from the
 395                 window of handle N
 396 walk process    lists all w-processes in Wine session
 397 walk thread     lists all w-threads in Wine session
 398 walk modref     (no longer avail)
 399
 400 IV.9 Memory (reading, writing, typing)
 401
 402 x <expr>        examines memory at <expr> address
 403 x /fmt <expr>   examines memory at <expr> address using format /fmt
 404 print <expr>    prints the value of <expr> (possibly using its type)
 405 print /fmt <expr>       prints the value of <expr> (possibly using its
 406                 type)
 407 set <lval>=<expr>       writes the value of <expr> in <lval>
 408 whatis <expr>   prints the C type of expression <expr>
 409
 410 /fmt is either /<letter> or /<count><letter>
 411 letter can be
 412                 s => an ASCII string
 413                 u => an Unicode UTF16 string
 414                 i => instructions (disassemble)
 415                 x => 32 bit unsigned hexadecimal integer
 416                 d => 32 bit signed decimal integer
 417                 w => 16 bit unsigned hexadecimal integer
 418                 c => character (only printable 0x20-0x7f are actually
 419                      printed)
 420                 b => 8 bit unsigned hexadecimal integer
 421
 422 V Other debuggers
 423 =================
 424
 425 V.1 Using other Unix debuggers
 426 ------------------------------
 427 You can also use other debuggers (like gdb), but you must be aware of
 428 a few items:
 429 - you need to attach the unix debugger to the correct unix process
 430 (representing the correct windows thread) (you can "guess" it from a
 431 'ps fax' for example: When running the emulator, usually the first
 432 two upids are for the Windows' application running the desktop, the
 433 first thread of the application is generally the third upid; when
 434 running a WineLib program, the first thread of the application is
 435 generally the first upid)
 436
 437 Note: even if latest gdb implements the notion of threads, it won't
 438 work with Wine because the thread abstraction used for implementing
 439 Windows' thread is not 100% mapped onto the linux posix threads
 440 implementation. It means that you'll have to spawn a different gdb
 441 session for each Windows' thread you wish to debug.
 442
 443 V.2 Using other Windows debuggers
 444 ---------------------------------
 445 You can use any Windows' debugging API compliant debugger with
 446 Wine. Some reports have been made of success with VisualStudio
 447 debugger (in remote mode, only the hub runs in Wine).
 448 GoVest fully runs in Wine.
 449
 450 V.3 Main differences between winedbg and regular Unix debuggers
 451 ---------------------------------------------------------------
 452
 453 +----------------------------------+---------------------------------+
 454 |             WineDbg              |                 gdb             |
 455 +----------------------------------+---------------------------------+
 456 |WineDbg debugs a Windows' process:|gdb debugs a Windows' thread:    |
 457 |+ the various threads will be     |+ a separate gdb session is      |
 458 |  handled by the same WineDbg     |  needed for each thread of      |
 459 | session                          |  Windows' process               |
 460 |+ a breakpoint will be triggered  |+ a breakpoint will be triggered |
 461 |  for any thread of the w-process |  only for the w-thread debugged |
 462 +----------------------------------+---------------------------------+
 463 |WineDbg supports debug information|gdb supports debug information   |
 464 |from:                             |from:                            |
 465 |+ stabs (standard Unix format)    |+ stabs (standard Unix format)   |
 466 |+ Microsoft's C, CodeView, .DBG   |                                 |
 467 +----------------------------------+---------------------------------+
 468
 469 VI Limitations
 470 ==============
 471
 472 + 16 bit processes are not supported (but calls to 16 bit code in 32
 473   bit applications is).
 474 + there are reports of debugger's freeze when loading large PDB files
 475
 476 Last updated: 6/14/2000 by ericP