documentation/debugger.sgml

   1   <chapter id="debugger">
   2     <title>Debugging Wine</title>
   3
   4     <sect1 id="dbg-intro">
   5       <title>Introduction</title>
   6
   7       <sect2>
   8         <title>Processes and threads: in underlying OS and in Windows</title>
   9
  10         <para>
  11           Before going into the depths of debugging in Wine, here's
  12           a small overview of process and thread handling in Wine.
  13           It has to be clear that there are two different beasts:
  14           processes/threads from the Unix point of view and
  15           processes/threads from a Windows point of view.
  16         </para>
  17         <para>
  18           Each Windows' thread is implemented as a Unix process (under
  19           Linux using the <function>clone</function> syscall), meaning
  20           that all threads of a same Windows' process share the same
  21           (unix) address space.
  22         </para>
  23         <para>
  24           In the following:
  25         </para>
  26         <itemizedlist>
  27           <listitem>
  28             <para>
  29               <varname>W-process</varname> means a process in Windows' terminology
  30             </para>
  31           </listitem>
  32           <listitem>
  33             <para>
  34               <varname>U-process</varname> means a process in Unix' terminology
  35             </para>
  36           </listitem>
  37           <listitem>
  38             <para>
  39               <varname>W-thread</varname> means a thread in Windows' terminology
  40             </para>
  41           </listitem>
  42         </itemizedlist>
  43         <para>
  44           A <varname>W-process</varname> is made of one or several
  45           <varname>W-threads</varname>. Each
  46           <varname>W-thread</varname> is mapped to one and only one
  47           <varname>U-process</varname>. All
  48           <varname>U-processes</varname> of a same
  49           <varname>W-process</varname> share the same address space.
  50         </para>
  51         <para>
  52           Each Unix process can be identified by two values:
  53         </para>
  54         <itemizedlist>
  55           <listitem>
  56             <para>
  57               the Unix process id (<varname>upid</varname> in the following)
  58             </para>
  59           </listitem>
  60           <listitem>
  61             <para>
  62               the Windows's thread id (<varname>tid</varname>)
  63             </para>
  64           </listitem>
  65         </itemizedlist>
  66         <para>
  67           Each Windows' process has also a Windows' process id
  68           (<varname>wpid</varname> in the following). It must be clear
  69           that <varname>upid</varname> and <varname>wpid</varname> are
  70           different and shall not be used instead of the other.
  71         </para>
  72         <para>
  73           <varname>Wpid</varname> and <varname>tid</varname> are
  74           defined (Windows) system wide. They must not be confused
  75           with process or thread handles which, as any handle, is an
  76           indirection to a system object (in this case process or
  77           thread). A same process can have several different handles
  78           on the same kernel object. The handles can be defined as
  79           local (the values is only valid in a process), or system
  80           wide (the same handle can be used by any
  81           <varname>W-process</varname>).
  82         </para>
  83       </sect2>
  84
  85       <sect2>
  86         <title>Wine, debugging and WineDbg</title>
  87
  88         <para>
  89           When talking of debugging in Wine, there are at least two
  90           levels to think of:
  91         </para>
  92         <itemizedlist>
  93           <listitem>
  94             <para>
  95               the Windows' debugging API.
  96             </para>
  97           </listitem>
  98           <listitem>
  99             <para>
 100               the Wine integrated debugger, dubbed <command>WineDbg</command>.
 101             </para>
 102           </listitem>
 103         </itemizedlist>
 104         <para>
 105           Wine implements most of the Windows' debugging API (the
 106           part in <filename>KERNEL32.DLL</filename>, not the one in
 107           <filename>IMAGEHLP.DLL</filename>), and allows any program
 108           (emulated or Winelib) using that API to debug a
 109           <varname>W-process</varname>.
 110         </para>
 111         <para>
 112           <command>WineDbg</command> is a Winelib application making
 113           use of this API to allow debugging both any Wine or Winelib
 114           applications as well as Wine itself (kernel and all DLLs).
 115         </para>
 116       </sect2>
 117     </sect1>
 118
 119
 120     <sect1 id="dbg-modes">
 121       <title>WineDbg's modes of invocation</title>
 122
 123       <sect2>
 124         <title>Starting a process</title>
 125
 126         <para>
 127           Any application (either a Windows' native executable, or a
 128           Winelib application) can be run through
 129           <command>WineDbg</command>. Command line options and tricks
 130           are the same as for wine:
 131         </para>
 132         <screen>
 133 winedbg telnet.exe
 134 winedbg "hl.exe -windowed"
 135         </screen>
 136       </sect2>
 137
 138       <sect2>
 139         <title>Attaching</title>
 140
 141         <para>
 142           <command>WineDbg</command> can also be launched without any
 143           command line argument: <command>WineDbg</command> is started
 144           without any attached process. You can get a list of running
 145           <varname>W-processes</varname> (and their
 146           <varname>wpid</varname>'s) using the <command>walk
 147             process</command> command, and then, with the
 148           <command>attach</command> command, pick up the
 149           <varname>wpid</varname> of the <varname>W-process</varname>
 150           you want to debug. This is a neat feature as it allows you
 151           to debug an already started application.
 152          </para>
 153       </sect2>
 154
 155       <sect2 id="dbg-on-exception">
 156         <title id="dbg-exception-title">On exceptions</title>
 157
 158         <para>
 159           When something goes wrong, Windows tracks this as an
 160           exception. Exceptions exist for segmentation violation,
 161           stack overflow, division by zero, etc.
 162         </para>
 163         <para>
 164           When an exception occurs, Wine checks if the <varname>W-process</varname> is
 165           debugged. If so, the exception event is sent to the
 166           debugger, which takes care of it: end of the story. This
 167           mechanism is part of the standard Windows' debugging API.
 168         </para>
 169         <para>
 170           If the <varname>W-process</varname> is not debugged, Wine
 171           tries to launch a debugger. This debugger (normally
 172           <command>WineDbg</command>, see III Configuration for more
 173           details), at startup, attaches to the
 174           <varname>W-process</varname> which generated the exception
 175           event. In this case, you are able to look at the causes of
 176           the exception, and either fix the causes (and continue
 177           further the execution) or dig deeper to understand what went
 178           wrong.
 179         </para>
 180         <para>
 181           If <command>WineDbg</command> is the standard debugger, the
 182           <command>pass</command> and <command>cont</command> commands
 183           are the two ways to let the process go further for the
 184           handling of the  exception event.
 185         </para>
 186         <para>
 187           To be more precise on the way Wine (and Windows) generates
 188           exception events, when a fault occurs (segmentation
 189           violation, stack overflow...), the event is first sent to
 190           the debugger (this is known as a first chance exception).
 191           The debugger can give two answers:
 192         </para>
 193
 194         <variablelist>
 195           <varlistentry>
 196             <term>continue:</term>
 197             <listitem>
 198               <para>
 199                 the debugger had the ability to correct what's
 200                 generated the exception, and is now able to continue
 201                 process execution.
 202               </para>
 203             </listitem>
 204           </varlistentry>
 205           <varlistentry>
 206             <term>pass:</term>
 207             <listitem>
 208               <para>
 209                 the debugger couldn't correct the cause of the
 210                 first chance exception. Wine will now try to walk
 211                 the list of exception handlers to see if one of them
 212                 can handle the exception. If no exception handler is
 213                 found, the exception is sent once again to the
 214                 debugger to indicate the failure of the exception
 215                 handling.
 216               </para>
 217             </listitem>
 218           </varlistentry>
 219         </variablelist>
 220         <note>
 221           <para>
 222             since some of Wine's code uses exceptions and
 223             <function>try/catch</function> blocks to provide some
 224             functionality, <command>WineDbg</command> can be entered
 225             in such cases with segv exceptions. This happens, for
 226             example, with <function>IsBadReadPtr</function> function.
 227             In that case, the <command>pass</command> command shall be
 228             used, to let the handling of the exception to be done by
 229             the <function>catch</function> block in
 230             <function>IsBadReadPtr</function>.
 231           </para>
 232         </note>
 233       </sect2>
 234
 235       <sect2 id="interrupt">
 236         <title>Interrupting</title>
 237
 238         <para>
 239           You can stop the debugger while it's running by hitting
 240           Ctrl-C in its window. This will stop the debugged process,
 241           and let you manipulate the current context.
 242         </para>
 243       </sect2>
 244
 245       <sect2>
 246         <title>Quitting</title>
 247
 248         <para>
 249           Wine supports the new XP APIs, allowing for a debugger to
 250           detach from a program being debugged (see
 251           <command>detach</command> command). Unfortunately, as the
 252           debugger cannot, for now, neither clear its internal
 253           information, nor restart a new process, the debugger, after
 254           detaching itself, cannot do much except being quitted.
 255         </para>
 256       </sect2>
 257     </sect1>
 258
 259
 260     <sect1 id="wine-debugger">
 261       <title>Using the Wine Debugger</title>
 262
 263       <para>
 264         This section describes where to start debugging Wine. If at any
 265         point you get stuck and want to ask for help, please read the
 266         <emphasis>How to Report A Bug</emphasis> section of the
 267         <emphasis>Wine Users Guide</emphasis> for information on how to write
 268         useful bug reports.
 269       </para>
 270
 271       <sect2>
 272         <title>Crashes</title>
 273
 274         <para>
 275           These usually show up like this:
 276         </para>
 277         <screen>
 278 |Unexpected Windows program segfault - opcode = 8b
 279 |Segmentation fault in Windows program 1b7:c41.
 280 |Loading symbols from ELF file /root/wine/wine...
 281 |....more Loading symbols from ...
 282 |In 16 bit mode.
 283 |Register dump:
 284 | CS:01b7 SS:016f DS:0287 ES:0000
 285 | IP:0c41 SP:878a BP:8796 FLAGS:0246
 286 | AX:811e BX:0000 CX:0000 DX:0000 SI:0001 DI:ffff
 287 |Stack dump:
 288 |0x016f:0x878a:  0001 016f ffed 0000 0000 0287 890b 1e5b
 289 |0x016f:0x879a:  01b7 0001 000d 1050 08b7 016f 0001 000d
 290 |0x016f:0x87aa:  000a 0003 0004 0000 0007 0007 0190 0000
 291 |0x016f:0x87ba:
 292 |
 293 |0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
 294 |Backtrace:
 295 |0 0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c)
 296 |1 0x01b7:0x1e5b (PXSRV_FONPUTCATFONT+0x2cd)
 297 |2 0x01a7:0x05aa
 298 |3 0x01b7:0x0768 (PXSRV_FONINITFONTS+0x81)
 299 |4 0x014f:0x03ed (PDOXWIN_@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
 300 |5 0x013f:0x00ac
 301 |
 302 |0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c):  movw        %es:0x38(%bx),%dx
 303         </screen>
 304         <para>
 305           Steps to debug a crash. You may stop at any step, but please
 306           report the bug and provide as much of the information
 307           gathered to the bug report as feasible.
 308         </para>
 309
 310         <orderedlist>
 311           <listitem>
 312             <para>
 313               Get the reason for the crash. This is usually an access to
 314               an invalid selector, an access to an out of range address
 315               in a valid selector, popping a segment register from the
 316               stack or the like. When reporting a crash, report this
 317               <emphasis>whole</emphasis> crashdump even if it doesn't
 318               make sense to you.
 319             </para>
 320             <para>
 321               (In this case it is access to an invalid selector, for
 322               <systemitem>%es</systemitem> is <literal>0000</literal>, as
 323               seen in the register dump).
 324             </para>
 325           </listitem>
 326           <listitem>
 327             <para>
 328               Determine the cause of the crash. Since this is usually
 329               a primary/secondary reaction to a failed or misbehaving
 330               Wine function, rerun Wine with <parameter>-debugmsg
 331                 +relay</parameter> added to the commandline. This will
 332               generate quite a lot of output, but usually the reason is
 333               located in the last call(s).  Those lines usually look like
 334               this:
 335             </para>
 336             <screen>
 337 |Call KERNEL.90: LSTRLEN(0227:0692 "text") ret=01e7:2ce7 ds=0227
 338       ^^^^^^^^^  ^       ^^^^^^^^^ ^^^^^^      ^^^^^^^^^    ^^^^
 339       |          |       |         |           |            |Datasegment
 340       |          |       |         |           |Return address
 341       |          |       |         |textual parameter
 342       |          |       |
 343       |          |       |Argument(s). This one is a win16 segmented pointer.
 344       |          |Function called.
 345       |The module, the function is called in. In this case it is KERNEL.
 346
 347 |Ret  KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
 348                                   ^^^^^^
 349                                   |Returnvalue is 16 bit and has the value 4.
 350             </screen>
 351           </listitem>
 352           <listitem>
 353             <para>
 354               If you have found a misbehaving function, try to find out
 355               why it misbehaves. Find the function in the source code.
 356               Try to make sense of the arguments passed. Usually there is
 357               a <function>WINE_DEFAULT_DEBUG_CHANNEL(&lt;channel>);</function>
 358               at the beginning of the file. Rerun wine with
 359               <parameter>-debugmsg +xyz,+relay</parameter> added to the
 360               commandline.
 361             </para>
 362             <para>
 363               Occasionally there are additional debug channels defined at the
 364               beginning of the file in the form.
 365               <function>WINE_DECLARE_DEBUG_CHANNEL(&lt;channel>);</function>
 366               If so the offending function may also uses one of these alternate
 367               channels. Look through the the function for
 368              <function>TRACE_(&lt;channel>)(" ... /n");</function> and add any
 369              additional channels to the commandline.
 370             </para>
 371           </listitem>
 372           <listitem>
 373             <para>
 374               Additional information on how to debug using the internal
 375               debugger can be  found in
 376               <filename>programs/winedbg/README</filename>.
 377             </para>
 378           </listitem>
 379           <listitem>
 380             <para>
 381               If this information isn't clear enough or if you want to
 382               know more about what's happening in the function itself,
 383               try running wine with <parameter>-debugmsg
 384                 +all</parameter>, which dumps ALL included debug
 385               information in wine.
 386             </para>
 387           </listitem>
 388           <listitem>
 389             <para>
 390               If even that isn't enough, add more debug output for yourself
 391               into the functions you find relevant. See The section on Debug
 392               Logging in this guide for more information. You might
 393               also try to run the program in <command>gdb</command>
 394               instead of using the Wine debugger. If you do that, use
 395               <parameter>handle SIGSEGV nostop noprint</parameter> to
 396               disable the handling of seg faults inside
 397               <command>gdb</command> (needed for Win16).
 398             </para>
 399           </listitem>
 400           <listitem>
 401             <para>
 402               You can also set a breakpoint for that function. Start wine
 403               useing <command>winedbg</command> instead of
 404               <command>wine</command>. Once the debugger is is running enter
 405               <command>break</command> <parameter>KERNEL_LSTRLEN</parameter>
 406               (replace by function you want to debug, CASE IS RELEVANT)
 407               to set a breakpoint.  Then
 408               use <command>continue</command> to start normal
 409               program-execution. Wine will stop if it reaches the
 410               breakpoint. If the program isn't yet at the crashing call
 411               of that function, use <command>continue</command> again
 412               until you are about to enter that function. You may now
 413               proceed with single-stepping the function until you reach
 414               the point of crash. Use the other debugger commands to
 415               print registers and the like.
 416             </para>
 417           </listitem>
 418         </orderedlist>
 419       </sect2>
 420
 421       <sect2>
 422         <title>Program hangs, nothing happens</title>
 423
 424         <para>
 425           Start the program with <command>winedbg</command> instead of
 426           <command>wine</command>. When the program locks up switch to the
 427           winedbg terminal and press
 428           <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>. this
 429           will stop the program and let you debug the program as you would for
 430           a crash.
 431         </para>
 432       </sect2>
 433
 434       <sect2>
 435         <title>Program reports an error with a Messagebox</title>
 436
 437         <para>
 438           Sometimes programs are reporting failure using more or
 439           less nondescript messageboxes. We can debug this using the
 440           same method as Crashes, but there is one problem... For
 441           setting up a message box the program also calls Wine
 442           producing huge chunks of debug code.
 443         </para>
 444         <para>
 445           Since the failure happens usually directly before setting up
 446           the Messagebox you can start winedbg and set a
 447           breakpoint at <function>MessageBoxA</function> (called by win16
 448           and win32 programs) and proceed with
 449           <command>continue</command>. With <parameter>--debugmsg
 450             +all</parameter> Wine will now stop directly before setting
 451           up the Messagebox. Proceed as explained above.
 452         </para>
 453         <para>
 454           You can also run wine using <command>wine -debugmsg +relay
 455             program.exe 2>&1 | less -i</command> and in
 456           <command>less</command> search for <quote>MessageBox</quote>.
 457         </para>
 458       </sect2>
 459
 460       <sect2>
 461         <title>Disassembling programs:</title>
 462
 463         <para>
 464           You may also try to disassemble the offending program to
 465           check for undocumented features and/or use of them.
 466         </para>
 467         <para>
 468           The best, freely available, disassembler for Win16 programs is
 469           <application>Windows Codeback</application>, archive name
 470           <filename>wcbxxx.zip</> (e.g. <filename>wcb105a.zip</>), which
 471           usually can be found in the <filename>Cica-Mirror</filename>
 472           subdirectory on the Wine ftp sites. (See <filename>ANNOUNCE</>).
 473         </para>
 474         <para>
 475           Disassembling win32 programs is possible using
 476           <application>Windows Disassembler 32</>. Look for
 477           a file called <filename>w32dsm87.zip</> (or similar)
 478           on <ulink url="http://www.winsite.com/">http://www.winsite.com</>
 479           and mirrors.  The shareware version does not allow saving of
 480           disassembly listings. You can also use the newer (and in the
 481           full version better) <application>Interactive
 482             Disassembler</application> (IDA) from the ftp sites mentioned
 483           at the end of the document. Understanding disassembled code is
 484           mostly a question of exercise.
 485         </para>
 486         <para>
 487           Most code out there uses standard C function entries (for it
 488           is usually  written in C). Win16 function entries usually
 489           look like that:
 490         </para>
 491         <programlisting>
 492 push bp
 493 mov bp, sp
 494 ... function code ..
 495 retf XXXX       &lt;--------- XXXX is number of bytes of arguments
 496         </programlisting>
 497         <para>
 498           This is a <function>FAR</function> function with no local
 499           storage. The arguments usually start at
 500           <literal>[bp+6]</literal> with increasing offsets. Note, that
 501           <literal>[bp+6]</literal> belongs to the
 502           <emphasis>rightmost</emphasis> argument, for exported win16
 503           functions use the PASCAL calling convention. So, if we use
 504           <function>strcmp(a,b)</function> with <parameter>a</parameter>
 505           and <parameter>b</parameter> both 32 bit variables
 506           <parameter>b</parameter> would be at <literal>[bp+6]</literal>
 507           and <parameter>a</parameter> at <literal>[bp+10]</literal>.
 508         </para>
 509         <para>
 510           Most functions make also use of local storage in the stackframe:
 511         </para>
 512         <programlisting>
 513 enter 0086, 00
 514 ... function code ...
 515 leave
 516 retf XXXX
 517         </programlisting>
 518         <para>
 519           This does mostly the same as above, but also adds
 520           <literal>0x86</literal> bytes of stackstorage, which is
 521           accessed using <literal>[bp-xx]</literal>. Before calling a
 522           function, arguments are pushed on the stack using something
 523           like this:
 524         </para>
 525         <programlisting>
 526 push word ptr [bp-02]   &lt;- will be at [bp+8]
 527 push di                 &lt;- will be at [bp+6]
 528 call KERNEL.LSTRLEN
 529         </programlisting>
 530         <para>
 531           Here first the selector and then the offset to the passed
 532           string are pushed.
 533         </para>
 534       </sect2>
 535
 536       <sect2>
 537         <title>Sample debugging session:</title>
 538
 539         <para>
 540           Let's debug the infamous Word <filename>SHARE.EXE</filename>
 541           messagebox:
 542         </para>
 543         <screen>
 544 |marcus@jet $ wine winword.exe
 545 |            +---------------------------------------------+
 546 |            | !  You must leave Windows and load SHARE.EXE|
 547 |            |    before starting Word.                    |
 548 |            +---------------------------------------------+
 549         </screen>
 550         <screen>
 551 |marcus@jet $ wine winword.exe -debugmsg +relay -debug
 552 |CallTo32(wndproc=0x40065bc0,hwnd=000001ac,msg=00000081,wp=00000000,lp=00000000)
 553 |Win16 task 'winword': Breakpoint 1 at 0x01d7:0x001a
 554 |CallTo16(func=0127:0070,ds=0927)
 555 |Call WPROCS.24: TASK_RESCHEDULE() ret=00b7:1456 ds=0927
 556 |Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x8672 ret=00b7:1456 ds=0927
 557 |CallTo16(func=01d7:001a,ds=0927)
 558 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=0927 BP=0000 ES=11f7
 559 |Loading symbols: /home/marcus/wine/wine...
 560 |Stopped on breakpoint 1 at 0x01d7:0x001a
 561 |In 16 bit mode.
 562 |Wine-dbg>break MessageBoxA                          &lt;---- Set Breakpoint
 563 |Breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
 564 |Wine-dbg>c                                            &lt;---- Continue
 565 |Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
 566 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
 567 |CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
 568 |...                                                   &lt;----- Much debugoutput
 569 |Call KERNEL.136: GETDRIVETYPE(0x0000) ret=060f:097b ds=0927
 570                                ^^^^^^ Drive 0 (A:)
 571 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0002 ret=060f:097b ds=0927
 572                                         ^^^^^^  DRIVE_REMOVEABLE
 573                                                 (It is a floppy diskdrive.)
 574
 575 |Call KERNEL.136: GETDRIVETYPE(0x0001) ret=060f:097b ds=0927
 576                                ^^^^^^ Drive 1 (B:)
 577 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0000 ret=060f:097b ds=0927
 578                                         ^^^^^^  DRIVE_CANNOTDETERMINE
 579                                                 (I don't have drive B: assigned)
 580
 581 |Call KERNEL.136: GETDRIVETYPE(0x0002) ret=060f:097b ds=0927
 582                                ^^^^^^^ Drive 2 (C:)
 583 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0003 ret=060f:097b ds=0927
 584                                         ^^^^^^ DRIVE_FIXED
 585                                                (specified as a harddisk)
 586
 587 |Call KERNEL.97: GETTEMPFILENAME(0x00c3,0x09278364"doc",0x0000,0927:8248) ret=060f:09b1 ds=0927
 588                                  ^^^^^^           ^^^^^        ^^^^^^^^^
 589                                  |                |            |buffer for fname
 590                                  |                |temporary name ~docXXXX.tmp
 591                                  |Force use of Drive C:.
 592
 593 |Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writeable.
 594 |Please check your configuration file if this generates a failure.
 595         </screen>
 596         <para>
 597           Whoops, it even detects that something is wrong!
 598         </para>
 599         <screen>
 600 |Ret  KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
 601                                           ^^^^^^ Temporary storage ID
 602
 603 |Call KERNEL.74: OPENFILE(0x09278248"C:~doc9281.tmp",0927:82da,0x1012) ret=060f:09d8 ds=0927
 604                                     ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
 605                                     |filename        |OFSTRUCT |open mode:
 606
 607                                        OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
 608         </screen>
 609         <para>
 610           This fails, since my <medialabel>C:</medialabel> drive is in
 611           this case mounted readonly.
 612         </para>
 613         <screen>
 614 |Ret  KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
 615                                    ^^^^^^ HFILE_ERROR16, yes, it failed.
 616
 617 |Call USER.1: MESSAGEBOX(0x0000,0x09278376"You must close Windows and load SHARE.EXE before you start Word.",0x00000000,0x1030) ret=060f:084f ds=0927
 618         </screen>
 619         <para>
 620           And MessageBox'ed.
 621         </para>
 622         <screen>
 623 |Stopped on breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
 624 |190     {              &lt;- the sourceline
 625 In 32 bit mode.
 626 Wine-dbg>
 627         </screen>
 628         <para>
 629           The code seems to find a writeable harddisk and tries to create
 630           a file there. To work around this bug, you can define
 631           <medialabel>C:</medialabel> as a networkdrive, which is ignored
 632           by the code above.
 633         </para>
 634       </sect2>
 635
 636       <sect2>
 637         <title>Debugging Tips</title>
 638
 639         <para>
 640           Here are some additional debugging tips:
 641         </para>
 642
 643         <itemizedlist>
 644           <listitem>
 645             <para>
 646               If you have a program crashing at such an early loader phase that you can't
 647               use the Wine debugger normally, but Wine already executes the program's
 648               start code, then you may use a special trick. You should do a
 649               <programlisting>
 650 wine --debugmsg +relay program
 651               </programlisting>
 652               to get a listing of the functions the program calls in its start function.
 653               Now you do a
 654               <programlisting>
 655 winedbg winfile.exe
 656               </programlisting>
 657             </para>
 658             <para>
 659               This way, you get into <command>winedbg</command>. Now you
 660               can set a breakpoint on any function the program calls in
 661               the start function and just type <userinput>c</userinput>
 662               to bypass the eventual calls of Winfile to this function
 663               until you are finally at the place where this function gets
 664               called by the crashing start function. Now you can proceed
 665               with your debugging as usual.
 666             </para>
 667           </listitem>
 668           <listitem>
 669             <para>
 670               If you try to run a program and it quits after showing an error messagebox,
 671               the problem can usually be identified in the return value of one of the
 672               functions executed before <function>MessageBox()</function>.
 673               That's why you should re-run the program with e.g.
 674               <programlisting>
 675 wine --debugmsg +relay &lt;program name> &>relmsg
 676               </programlisting>
 677               Then do a <command>more relmsg</command> and search for the
 678               last occurrence of a call to the string "MESSAGEBOX". This is a line like
 679               <programlisting>
 680 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
 681               </programlisting>
 682               In my example the lines before the call to
 683               <function>MessageBox()</function> look like that:
 684               <programlisting>
 685 Call KERNEL.96: FREELIBRARY(0x0347) ret=01cf:1033 ds=01ff
 686 CallTo16(func=033f:0072,ds=01ff,0x0000)
 687 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1033 ds=01ff
 688 Call KERNEL.96: FREELIBRARY(0x036f) ret=01cf:1043 ds=01ff
 689 CallTo16(func=0367:0072,ds=01ff,0x0000)
 690 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1043 ds=01ff
 691 Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
 692 CallTo16(func=0317:0072,ds=01ff,0x0000)
 693 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:105c ds=01ff
 694 Call USER.171: WINHELP(0x02ac,0x01ff05b4 "COMET.HLP",0x0002,0x00000000) ret=01cf:1070 ds=01ff
 695 CallTo16(func=0117:0080,ds=01ff)
 696 Call WPROCS.24: TASK_RESCHEDULE() ret=00a7:0a2d ds=002b
 697 Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x0000 ret=00a7:0a2d ds=002b
 698 Ret  USER.171: WINHELP() retval=0x0001 ret=01cf:1070 ds=01ff
 699 Call KERNEL.96: FREELIBRARY(0x01be) ret=01df:3e29 ds=01ff
 700 Ret  KERNEL.96: FREELIBRARY() retval=0x0000 ret=01df:3e29 ds=01ff
 701 Call KERNEL.52: FREEPROCINSTANCE(0x02cf00ba) ret=01f7:1460 ds=01ff
 702 Ret  KERNEL.52: FREEPROCINSTANCE() retval=0x0001 ret=01f7:1460 ds=01ff
 703 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
 704               </programlisting>
 705             </para>
 706             <para>
 707               I think that the call to <function>MessageBox()</function>
 708               in this example is <emphasis>not</emphasis> caused by a
 709               wrong result value of some previously executed function
 710               (it's happening quite often like that), but instead the
 711               messagebox complains about a runtime error at
 712               <literal>0x0004:0x1056</literal>.
 713             </para>
 714             <para>
 715               As the segment value of the address is only
 716               <literal>4</literal>, I think that that is only an internal
 717               program value. But the offset address reveals something
 718               quite interesting: Offset <literal>1056</literal> is
 719               <emphasis>very</emphasis> close to the return address of
 720               <function>FREELIBRARY()</function>:
 721               <programlisting>
 722 Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
 723                                              ^^^^
 724               </programlisting>
 725             </para>
 726             <para>
 727               Provided that segment <literal>0x0004</literal> is indeed segment
 728               <literal>0x1cf</literal>, we now we can use IDA                 (available at
 729               <ulink url="http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip">
 730                http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip</ulink>) to
 731               disassemble the part that caused the error. We just have to find the address of
 732               the call to <function>FreeLibrary()</function>. Some lines before that the
 733               runtime error occurred. But be careful! In some cases you don't have to
 734               disassemble the main program, but instead some DLL called by it in order to find
 735               the correct place where the runtime error occurred. That can be determined by
 736               finding the origin of the segment value (in this case <literal>0x1cf</literal>).
 737             </para>
 738           </listitem>
 739           <listitem>
 740             <para>
 741               If you have created a relay file of some crashing
 742               program and want to set a breakpoint at a certain
 743               location which is not yet available as the program loads
 744               the breakpoint's segment during execution, you may set a
 745               breakpoint to <function>GetVersion16/32</function> as
 746               those functions are called very often.
 747             </para>
 748             <para>
 749               Then do a <userinput>c</userinput> until you are able to
 750               set this breakpoint without error message.
 751             </para>
 752           </listitem>
 753           <listitem>
 754             <para>
 755               Some useful programs:
 756             </para>
 757             <variablelist>
 758               <varlistentry>
 759                 <term>
 760                   <application>IDA</application>:
 761                   <filename>
 762                     <ulink url="http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip">
 763                      http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip</ulink>
 764                   </filename>
 765                 </term>
 766                 <listitem>
 767                   <para>
 768                     <emphasis>Very</emphasis> good DOS disassembler ! It's badly needed
 769                     for debugging Wine sometimes.
 770                   </para>
 771                 </listitem>
 772               </varlistentry>
 773               <varlistentry>
 774                 <term>
 775                   <application>XRAY</application>:
 776                   <filename>
 777                     <ulink url="http://garbo.uwasa.fi/pub/pc/sysinfo/xray15.zip">
 778                      http://garbo.uwasa.fi/pub/pc/sysinfo/xray15.zip</ulink>
 779                   </filename>
 780                 </term>
 781                 <listitem>
 782                   <para>
 783                     Traces DOS calls (Int 21h, DPMI, ...). Use it with
 784                     Windows to correct file management problems etc.
 785                   </para>
 786                 </listitem>
 787               </varlistentry>
 788               <varlistentry>
 789                 <term>
 790                   <application>pedump</application>:
 791                   <filename>
 792                     <ulink url="ftp://ftp.simtel.net/pub/simtelnet/win95/prog/pedump.zip">
 793                      ftp://ftp.simtel.net/pub/simtelnet/win95/prog/pedump.zip</ulink>
 794                   </filename>
 795                 </term>
 796                 <listitem>
 797                   <para>
 798                     Dumps the imports and exports of a PE (Portable
 799                     Executable) DLL.
 800                   </para>
 801                 </listitem>
 802               </varlistentry>
 803               <varlistentry>
 804                 <term>
 805                   <application>winedump</application>:
 806                 </term>
 807                 <listitem>
 808                   <para>
 809                     Dumps the imports and exports of a PE (Portable
 810                     Executable) DLL (included in wine tree).
 811                   </para>
 812                 </listitem>
 813               </varlistentry>
 814             </variablelist>
 815           </listitem>
 816         </itemizedlist>
 817       </sect2>
 818
 819       <sect2>
 820         <title>Some basic debugger usages:</title>
 821
 822         <para>
 823           After starting your program with
 824         </para>
 825         <screen>
 826 wine -debug myprog.exe
 827         </screen>
 828         <para>
 829           the program loads and you get a prompt at the program
 830           starting point. Then you can set breakpoints:
 831         </para>
 832         <screen>
 833   b RoutineName      (by outine name) OR
 834   b *0x812575        (by address)
 835         </screen>
 836         <para>
 837           Then you hit <command>c</command> (continue) to run the
 838           program. It stops at the breakpoint. You can type
 839         </para>
 840         <screen>
 841   step               (to step one line) OR
 842   stepi              (to step one machine instruction at a time;
 843                       here, it helps to know the basic 386
 844                       instruction set)
 845   info reg           (to see registers)
 846   info stack         (to see hex values in the stack)
 847   info local         (to see local variables)
 848   list &lt;line number&gt; (to list source code)
 849   x &lt;variable name&gt;  (to examine a variable; only works if code
 850                       is not compiled with optimization)
 851   x 0x4269978        (to examine a memory location)
 852   ?                  (help)
 853   q                  (quit)
 854         </screen>
 855         <para>
 856           By hitting <keycap>Enter</keycap>, you repeat the last
 857           command.
 858         </para>
 859       </sect2>
 860     </sect1>
 861
 862
 863     <sect1 id="memory-addresses">
 864       <title>Useful memory addresses</title>
 865       <para>
 866         Wine uses several different kinds of memory addresses.
 867       </para>
 868       <variablelist>
 869         <varlistentry>
 870           <term>
 871             Win32/"normal" Wine addresses/Linux: linear addresses.
 872           </term>
 873           <listitem>
 874             <para>
 875               Linear addresses can be everything from 0x0 up to
 876               0xffffffff.  In Wine on Linux they are often around
 877               e.g. 0x08000000, 0x00400000 (std. Win32 program load
 878               address), 0x40000000.  Every Win32 process has its own
 879               private 4GB address space (that is, from 0x0 up to
 880               0xffffffff).
 881             </para>
 882           </listitem>
 883         </varlistentry>
 884         <varlistentry>
 885           <term>
 886             Win16 "enhanced mode": segmented addresses.
 887           </term>
 888           <listitem>
 889             <para>
 890               These are the "normal" Win16 addresses, called SEGPTR.
 891               They have a segment:offset notation, e.g. 0x01d7:0x0012.
 892               The segment part usually is a "selector", which
 893               <emphasis>always</emphasis>
 894               has the lowest 3 bits set.  Some sample selectors are
 895               0x1f7, 0x16f, 0x8f.  If these bits are set except for
 896               the lowest bit, as e.g. with 0x1f6,xi then it might be a
 897               handle to global memory. Just set the lowest bit to get
 898               the selector in these cases.  A selector kind of
 899               "points" to a certain linear (see above) base address.
 900               It has more or less three important attributes: segment
 901               base address, segment limit, segment access rights.
 902             </para>
 903             <para>
 904               Example:
 905             </para>
 906             <para>
 907               Selector 0x1f7 (0x40320000, 0x0000ffff, r-x) So 0x1f7
 908               has a base address of 0x40320000, the segment's last
 909               address is 0x4032ffff (limit 0xffff), and it's readable
 910               and executable.  So an address of 0x1f7:0x2300 would be
 911               the linear address of 0x40322300.
 912             </para>
 913           </listitem>
 914         </varlistentry>
 915         <varlistentry>
 916           <term>
 917             DOS/Win16 "standard mode"
 918           </term>
 919           <listitem>
 920             <para>
 921               They, too, have a segment:offset notation.  But they are
 922               completely different from "normal" Win16 addresses, as
 923               they just represent at most 1MB of memory: The segment
 924               part can be anything from 0 to 0xffff, and it's the same
 925               with the offset part.
 926             </para>
 927             <para>
 928               Now the strange thing is the calculation that's behind
 929               these addresses: Just calculate segment*16 + offset in
 930               order to get a "linear DOS" address.  So
 931               e.g. 0x0f04:0x3628 results in 0xf040 + 0x3628 = 0x12668.
 932               And the highest address you can get is 0xfffff (1MB), of
 933               course.  In Wine, this "linear DOS" address of 0x12668
 934               has to be added to the linear base address of the
 935               corresponding DOS memory allocated for dosmod in order
 936               to get the true linear address of a DOS seg:offs
 937               address.  And make sure that you're doing this in the
 938               correct process with the correct linear address space,
 939               of course ;-)
 940             </para>
 941           </listitem>
 942         </varlistentry>
 943       </variablelist>
 944     </sect1>
 945
 946     <sect1 id="dbg-config">
 947       <title>Configuration</title>
 948
 949       <sect2>
 950         <title>Registry configuration</title>
 951
 952         <para>
 953           The Windows' debugging API uses a registry entry to know
 954           which debugger to invoke when an unhandled exception occurs
 955           (see <link endterm="dbg-exception-title"
 956           linkend="dbg-on-exception"></link> for some details). Two
 957           values in key
 958         </para>
 959         <programlisting>
 960 "MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
 961         </programlisting>
 962         <para>
 963           Determine the behavior:
 964         </para>
 965         <variablelist>
 966           <varlistentry>
 967             <term>Debugger:</term>
 968             <listitem>
 969               <para>
 970                 this is the command line used to launch the debugger
 971                 (it uses two <function>printf</function> formats
 972                 (<literal>%ld</literal>) to pass context dependent
 973                 information to  the debugger). You should put here a
 974                 complete path to your debugger
 975                 (<command>WineDbg</command> can of course be used, but
 976                 any other Windows' debugging API aware debugger will
 977                 do).
 978                 The path to the debugger you chose to use must be reachable
 979                 via a DOS drive in the Wine config file !
 980               </para>
 981             </listitem>
 982           </varlistentry>
 983           <varlistentry>
 984             <term>Auto:</term>
 985             <listitem>
 986               <para>
 987                 if this value is zero, a message box will ask the
 988                 user if he/she wishes to launch the debugger when an
 989                 unhandled exception occurs. Otherwise, the debugger
 990                 is automatically started.
 991               </para>
 992             </listitem>
 993           </varlistentry>
 994         </variablelist>
 995
 996         <para>
 997           A regular Wine registry looks like:
 998         </para>
 999         <programlisting>
1000 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
1001 "Auto"=dword:00000001
1002 "Debugger"="winedbg --debugmsg -all %ld %ld"
1003         </programlisting>
1004
1005         <note>
1006           <title>Note 1</title>
1007           <para>
1008             creating this key is mandatory. Not doing so will not
1009             fire the debugger when an exception occurs.
1010           </para>
1011         </note>
1012         <note>
1013           <title>Note 2</title>
1014           <para>
1015             <command>wineinstall</command> (available in Wine source)
1016             sets up this correctly.
1017             However, due to some limitation of the registry installed,
1018             if a previous Wine installation exists, it's safer to
1019             remove the whole
1020           </para>
1021           <programlisting>
1022 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
1023           </programlisting>
1024           <para>
1025             key before running again <command>wineinstall</command> to
1026             regenerate this key.
1027           </para>
1028         </note>
1029       </sect2>
1030
1031       <sect2>
1032         <title>WineDbg configuration</title>
1033
1034         <para>
1035           <command>WineDbg</command> can be configured through a number
1036           of options. Those options are stored in the registry, on a
1037           per user basis. The key is (in <emphasis>my</emphasis> registry)
1038         </para>
1039         <programlisting>
1040 [eric\\Software\\Wine\\WineDbg]
1041         </programlisting>
1042         <para>
1043           Those options can be read/written while inside
1044           <command>WineDbg</command>, as part of the debugger
1045           expressions. To refer to one of these options, its name must
1046           be  prefixed by a <literal>$</literal> sign. For example,
1047         </para>
1048         <programlisting>
1049 set $BreakAllThreadsStartup = 1
1050         </programlisting>
1051         <para>
1052           sets the option <varname>BreakAllThreadsStartup</varname> to
1053           <literal>TRUE</literal>.
1054         </para>
1055         <para>
1056           All the options are read from the registry when
1057           <command>WineDbg</command> starts (if no corresponding value
1058           is found, a default value is used), and are written back to
1059           the registry when <command>WineDbg</command> exits (hence,
1060           all modifications to those options are automatically saved
1061           when <command>WineDbg</command> terminates).
1062         </para>
1063         <para>
1064           Here's the list of all options:
1065         </para>
1066
1067         <sect3>
1068           <title>Controlling when the debugger is entered</title>
1069
1070           <variablelist>
1071             <varlistentry>
1072               <term><varname>BreakAllThreadsStartup</varname></term>
1073               <listitem>
1074                 <para>
1075                   Set to <literal>TRUE</literal> if at all threads
1076                   start-up the debugger stops  set to
1077                   <literal>FALSE</literal> if only at the first thread
1078                   startup of a given process the debugger stops.
1079                   <literal>FALSE</literal> by default.
1080                 </para>
1081               </listitem>
1082             </varlistentry>
1083             <varlistentry>
1084               <term><varname>BreakOnCritSectTimeOut</varname></term>
1085               <listitem>
1086                 <para>
1087                   Set to <literal>TRUE</literal> if the debugger stops
1088                   when a critical section times out (5 minutes);
1089                   <literal>TRUE</literal> by default.
1090                 </para>
1091               </listitem>
1092             </varlistentry>
1093             <varlistentry>
1094               <term><varname>BreakOnAttach</varname></term>
1095               <listitem>
1096                 <para>
1097                   Set to <literal>TRUE</literal> if when
1098                   <command>WineDbg</command> attaches to an existing
1099                   process after an unhandled exception,
1100                   <command>WineDbg</command> shall be entered on the
1101                   first attach event. Since the attach event is
1102                   meaningless in the context of an exception event
1103                   (the next event  which is the exception event is of
1104                   course relevant), that option is likely to be
1105                   <literal>FALSE</literal>.
1106                 </para>
1107               </listitem>
1108             </varlistentry>
1109             <varlistentry>
1110               <term><varname>BreakOnFirstChance</varname></term>
1111               <listitem>
1112                 <para>
1113                   An exception can generate two debug events. The
1114                   first one is passed to the debugger (known as a
1115                   first chance) just after the exception. The debugger
1116                   can then decides either to resume execution (see
1117                   <command>WineDbg</command>'s <command>cont</command>
1118                   command) or pass the exception up to the exception
1119                   handler chain in the program (if it exists)
1120                   (<command>WineDbg</command> implements this through the
1121                   <command>pass</command> command). If none of the
1122                   exception handlers takes care of the exception, the
1123                   exception event is sent again to the debugger (known
1124                   as last chance exception). You cannot pass on a last
1125                   exception. When the
1126                   <varname>BreakOnFirstChance</varname> exception is
1127                   <literal>TRUE</literal>, then winedbg is entered for
1128                   both first and last chance execptions (to
1129                   <literal>FALSE</literal>, it's only entered for last
1130                   chance exceptions).
1131                 </para>
1132               </listitem>
1133             </varlistentry>
1134             <varlistentry>
1135               <term><varname>BreakOnDllLoad</varname></term>
1136               <listitem>
1137                 <para>
1138                   Set to <literal>TRUE</literal> if the debugger stops
1139                   when a DLL is loaded into memory; when the debugger
1140                   is invoked after a crash, the DLLs already mapped in
1141                   memory will not trigger this break.
1142                   <literal>FALSE</literal> by default.
1143                 </para>
1144               </listitem>
1145             </varlistentry>
1146           </variablelist>
1147         </sect3>
1148
1149         <sect3>
1150           <title>Output handling</title>
1151
1152           <variablelist>
1153             <varlistentry>
1154               <term><varname>ConChannelMask</varname></term>
1155               <listitem>
1156                 <para>
1157                   Mask of active debugger output channels on console
1158                 </para>
1159               </listitem>
1160             </varlistentry>
1161             <varlistentry>
1162               <term><varname>StdChannelMask</varname></term>
1163               <listitem>
1164                 <para>
1165                   Mask of active debugger output channels on <filename>stderr</filename>
1166                 </para>
1167               </listitem>
1168             </varlistentry>
1169           </variablelist>
1170
1171           <para>
1172             Those last 2 variables are jointly used in two generic ways:
1173           </para>
1174
1175           <orderedlist>
1176             <listitem>
1177               <para>
1178                 default
1179               </para>
1180               <programlisting>
1181 ConChannelMask = DBG_CHN_MESG (1)
1182 StdChannelMask = 0
1183               </programlisting>
1184               <para>
1185                 In this case, all input/output goes into the
1186                 debugger's console (either the standard unix console
1187                 if winedbg is started from the command line, or a
1188                 specific windowed-console if the debugger is started
1189                 upon an exception in a running program. All debug
1190                 messages <function>TRACE</function>,
1191                 <function>WARN</function>... still goes to tty where
1192                 wine is run from).
1193               </para>
1194             </listitem>
1195             <listitem>
1196               <para>
1197                 To have all input/output go into the tty where Wine
1198                 was started from (to be used in a X11-free
1199                 environment)
1200               </para>
1201               <screen>
1202 ConChannelMask = 0
1203 StdChannelMask = DBG_CHN_MESG (1)
1204               </screen>
1205             </listitem>
1206           </orderedlist>
1207         </sect3>
1208
1209         <sect3>
1210           <title>Context information</title>
1211
1212           <variablelist>
1213             <varlistentry>
1214               <term><varname>ThreadId</varname></term>
1215               <listitem>
1216                 <para>
1217                   ID of the <varname>W-thread</varname> currently
1218                   examined by the debugger
1219                 </para>
1220               </listitem>
1221             </varlistentry>
1222             <varlistentry>
1223               <term><varname>ProcessId</varname></term>
1224               <listitem>
1225                 <para>
1226                   ID of the <varname>W-thread</varname> currently
1227                   examined by the debugger
1228                 </para>
1229               </listitem>
1230             </varlistentry>
1231             <varlistentry>
1232               <term>&lt;registers></term>
1233               <listitem>
1234                 <para>
1235                   All CPU registers are also available
1236                 </para>
1237               </listitem>
1238             </varlistentry>
1239           </variablelist>
1240
1241           <para>
1242             The <varname>ThreadId</varname> and
1243             <varname>ProcessId</varname> variables can be handy to set
1244             conditional breakpoints on a given thread or process.
1245           </para>
1246         </sect3>
1247       </sect2>
1248     </sect1>
1249
1250
1251     <sect1 id="dbg-commands">
1252       <title>WineDbg Command Reference</title>
1253
1254       <sect2>
1255         <title>Misc</title>
1256
1257         <screen>
1258 abort           aborts the debugger
1259 quit            exits the debugger
1260
1261 attach N        attach to a W-process (N is its ID). IDs can be
1262                 obtained using the walk process command
1263 detach          detach from a W-process. WineDbg will exit (this may
1264                 be changed later on)
1265         </screen>
1266         <screen>
1267 help            prints some help on the commands
1268 help info       prints some help on info commands
1269         </screen>
1270         <screen>
1271 mode 16         switch to 16 bit mode
1272 mode 32         switch to 32 bit mode
1273         </screen>
1274       </sect2>
1275
1276       <sect2>
1277         <title>Flow control</title>
1278
1279         <screen>
1280 cont            continue execution until next breakpoint or exception.
1281 pass            pass the exception event up to the filter chain.
1282 step            continue execution until next C line of code (enters
1283                 function call)
1284 next            continue execution until next C line of code (doesn't
1285                 enter function call)
1286 stepi           execute next assembly instruction (enters function
1287                 call)
1288 nexti           execute next assembly instruction (doesn't enter
1289                 function call)
1290 finish          do nexti commands until current function is exited
1291         </screen>
1292         <para>
1293           cont, step, next, stepi, nexti can be postfixed by a
1294           number (N), meaning that the command must be executed N
1295           times.
1296         </para>
1297       </sect2>
1298
1299       <sect2>
1300         <title>Breakpoints, watch points</title>
1301
1302         <screen>
1303 enable N        enables (break|watch)point #N
1304 disable N       disables (break|watch)point #N
1305 delete N        deletes  (break|watch)point #N
1306 cond N          removes any a existing condition to (break|watch)point N
1307 cond N &lt;expr&gt;     adds condition &lt;expr&gt; to (break|watch)point N. &lt;expr&gt;
1308                 will be evaluated each time the breakpoint is hit. If
1309                 the result is a zero value, the breakpoint isn't
1310                 triggered
1311 break * N       adds a breakpoint at address N
1312 break &lt;id&gt;        adds a breakpoint at the address of symbol &lt;id&gt;
1313 break &lt;id&gt; N      adds a breakpoint at the address of symbol &lt;id&gt; (N ?)
1314 break N         adds a breakpoint at line N of current source file
1315 break           adds a breakpoint at current $pc address
1316 watch * N       adds a watch command (on write) at address N (on 4 bytes)
1317 watch &lt;id&gt;        adds a watch command (on write) at the address of
1318                 symbol &lt;id&gt;
1319 info break      lists all (break|watch)points (with state)
1320         </screen>
1321         <para>
1322           When setting a breakpoint on an &lt;id&gt;, if several symbols with this
1323           &lt;id&gt; exist, the debugger will prompt for the symbol you want to use.
1324           Pick up the one you want from its number.
1325         </para>
1326         <para>
1327           Alternatively you can specify a DLL in the &lt;id&gt; (for example
1328           MYDLL.DLL.myFunc for function myFunc of
1329           <filename>G:\AnyPath\MyDll.dll)</filename>.
1330         </para>
1331         <para>
1332           You can use the symbol <emphasis>EntryPoint</emphasis> to stand for
1333           the entry point of the Dll.
1334         </para>
1335         <para>
1336           When setting a break/watch-point by &lt;id&gt;, if the symbol cannot be found (for example, the symbol is contained in a not yet loaded module), winedbg will
1337           recall the name of the symbol and will try to set the breakpoint each time a new module is loaded (until it succeeds).
1338         </para>
1339       </sect2>
1340
1341       <sect2>
1342         <title>Stack manipulation</title>
1343
1344         <screen>
1345 bt              print calling stack of current thread
1346 bt N            print calling stack of thread of ID N (note: this
1347                 doesn't change the position of the current frame as
1348                 manipulated by the up & dn commands)
1349 up              goes up one frame in current thread's stack
1350 up N            goes up N frames in current thread's stack
1351 dn              goes down one frame in current thread's stack
1352 dn N            goes down N frames in current thread's stack
1353 frame N         set N as the current frame for current thread's stack
1354 info local      prints information on local variables for current
1355                 function
1356         </screen>
1357       </sect2>
1358
1359       <sect2>
1360         <title>Directory & source file manipulation</title>
1361
1362         <screen>
1363 show dir
1364 dir &lt;pathname&gt;
1365 dir
1366 symbolfile &lt;pathname&gt;   loads external symbol definition
1367 symbolfile &lt;pathname&gt; N loads external symbol definition
1368                            (applying an offset of N to addresses)
1369         </screen>
1370         <screen>
1371 list            lists 10 source lines from current position
1372 list -          lists 10 source lines before current position
1373 list N          lists 10 source lines from line N in current file
1374 list &lt;path&gt;:N     lists 10 source lines from line N in file &lt;path&gt;
1375 list &lt;id&gt; lists 10 source lines of function &lt;id&gt;
1376 list * N        lists 10 source lines from address N
1377         </screen>
1378         <para>
1379           You can specify the end target (to change the 10 lines
1380           value) using the ','. For example:
1381         </para>
1382         <screen>
1383 list 123, 234   lists source lines from line 123 up to line 234 in
1384                 current file
1385 list foo.c:1,56 lists source lines from line 1 up to 56 in file foo.c
1386         </screen>
1387       </sect2>
1388
1389       <sect2>
1390         <title>Displaying</title>
1391
1392         <para>
1393           A display is an expression that's evaluated and printed
1394           after the execution of any <command>WineDbg</command>
1395           command.
1396         </para>
1397         <screen>
1398 display         lists the active displays
1399 info display    (same as above command)
1400 display &lt;expr&gt;    adds a display for expression &lt;expr&gt;
1401 display /fmt &lt;expr&gt;       adds a display for expression &lt;expr&gt;. Printing
1402                 evaluated &lt;expr&gt; is done using the given format (see
1403                 print command for more on formats)
1404 del display N   deletes display #N
1405 undisplay N     (same as del display)
1406         </screen>
1407       </sect2>
1408
1409       <sect2>
1410         <title>Disassembly</title>
1411
1412         <screen>
1413 disas           disassemble from current position
1414 disas &lt;expr&gt;      disassemble from address &lt;expr&gt;
1415 disas &lt;expr&gt;,&lt;expr&gt;disassembles code between addresses specified by
1416                 the two &lt;expr&gt;
1417         </screen>
1418       </sect2>
1419
1420       <sect2>
1421         <title>Information on Wine's internals</title>
1422
1423         <screen>
1424 info class &lt;id&gt; prints information on Windows's class &lt;id&gt;
1425 walk class      lists all Windows' class registered in Wine
1426 info share      lists all the dynamic libraries loaded the debugged
1427                 program (including .so files, NE and PE DLLs)
1428 info module &lt;N&gt; prints information on module of handle &lt;N&gt;
1429 walk module     lists all modules loaded by debugged program
1430 info regs       prints the value of CPU register
1431 info segment &lt;N&gt;prints information on segment &lt;N&gt;
1432 info segment    lists all allocated segments
1433 info stack      prints the values on top of the stack
1434 walk map        lists all virtual mappings used by the debugged
1435                 program
1436 walk map &lt;N&gt;    lists all virtual mappings used by the program of pid &lt;N&gt;
1437 info wnd &lt;N&gt;    prints information of Window of handle &lt;N&gt;
1438 walk wnd        lists all the window hierarchy starting from the
1439                 desktop window
1440 walk wnd &lt;N&gt;    lists all the window hierarchy starting from the
1441                 window of handle &lt;N&gt;
1442 walk process    lists all w-processes in Wine session
1443 walk thread     lists all w-threads in Wine session
1444 walk exception  lists the exception frames (starting from current
1445                 stack frame)
1446         </screen>
1447       </sect2>
1448
1449       <sect2>
1450         <title>Memory (reading, writing, typing)</title>
1451
1452         <screen>
1453 x &lt;expr&gt;  examines memory at &lt;expr&gt; address
1454 x /fmt &lt;expr&gt;     examines memory at &lt;expr&gt; address using format /fmt
1455 print &lt;expr&gt;      prints the value of &lt;expr&gt; (possibly using its type)
1456 print /fmt &lt;expr&gt; prints the value of &lt;expr&gt; (possibly using its
1457                 type)
1458 set &lt;lval&gt;=&lt;expr&gt;   writes the value of &lt;expr&gt; in &lt;lval&gt;
1459 whatis &lt;expr&gt;     prints the C type of expression &lt;expr&gt;
1460         </screen>
1461         <para>
1462           <filename>/fmt</filename> is either <filename>/&lt;letter&gt;</filename> or
1463           <filename>/&lt;count&gt;&lt;letter&gt;</filename> letter can be
1464         </para>
1465         <screen>
1466 s =&gt; an ASCII string
1467 u =&gt; an Unicode UTF16 string
1468 i =&gt; instructions (disassemble)
1469 x =&gt; 32 bit unsigned hexadecimal integer
1470 d =&gt; 32 bit signed decimal integer
1471 w =&gt; 16 bit unsigned hexadecimal integer
1472 c =&gt; character (only printable 0x20-0x7f are actually printed)
1473 b =&gt; 8 bit unsigned hexadecimal integer
1474 g =&gt; GUID
1475         </screen>
1476       </sect2>
1477
1478       <sect2>
1479         <title>Expressions</title>
1480
1481         <para>
1482           Expressions in Wine Debugger are mostly written in a C form. However, there
1483           are a few discrepancies:
1484           <itemizedlist>
1485             <listitem>
1486               <para>
1487                 Identifiers can take a '.' in their names. This allow
1488                 mainly to access symbols from different DLLs like
1489                 <function>USER32.DLL.CreateWindowA</function>.
1490               </para>
1491             </listitem>
1492             <listitem>
1493               <para>
1494                 The debugger will try to distinguish this writing with structure operations.
1495                 Therefore, you can only use the previous writing in operations manipulating
1496                 symbols ({break|watch}points, type information command...).
1497               </para>
1498             </listitem>
1499           </itemizedlist>
1500         </para>
1501       </sect2>
1502       <sect2>
1503           <title>Debug channels</title>
1504               <para>
1505                It is possible to turn on and off debug messages as you are debugging using
1506                the set command.
1507               </para>
1508             <screen>
1509 set + warn win  =&gt; turn on warn on 'win' channel
1510 set + win       =&gt; turn on warn/fixme/err/trace on 'win' channel
1511 set - win       =&gt; turn off warn/fixme/err/trace on 'win' channel
1512 set - fixme     =&gt; turn off the 'fixme' class
1513             </screen>
1514       </sect2>
1515
1516     </sect1>
1517
1518     <sect1 id="dbg-others">
1519       <title>Other debuggers</title>
1520
1521       <sect2>
1522         <title>GDB mode</title>
1523
1524         <para>
1525           WineDbg can act as a remote monitor for GDB. This allows to
1526           use all the power of GDB, but while debugging wine and/or
1527           any Win32 application. To enable this mode, just add
1528           <parameter>--gdb</parameter> to winedbg command line. You'll
1529           end up on a GDB prompt. You'll have to use the GDB commands
1530           (not the wine nes).
1531         </para>
1532
1533         <para>
1534           However, some limitation in GDB while debugging wine (see
1535           below) don't appear in this mode:
1536           <itemizedlist>
1537             <listitem>
1538               <para>
1539                 GDB will correctly present Win32 thread
1540                 information and breakpoint behavior
1541               </para>
1542             </listitem>
1543             <listitem>
1544               <para>
1545                 Moreover, it also provides support for the Dwarf II
1546                 debug format (which became the default format (instead
1547                 of stabs) in gcc 3.1).
1548               </para>
1549             </listitem>
1550           </itemizedlist>
1551         </para>
1552
1553         <para>
1554           A few wine extensions available through the monitor command.
1555 <screen>
1556 monitor wnd           lists all window in the Wine session
1557 monitor proc          lists all processes in the Wine session
1558 monitor mem           displays memory mapping of debugged process
1559                       (doesn't work)
1560 </screen>
1561         </para>
1562       </sect2>
1563
1564       <sect2>
1565         <title>Graphical frontends to gdb</title>
1566
1567         <para>
1568           This section will describe how you can debug wine using the
1569           GDB mode of winedbg and some graphical front ends to GDB for
1570           those of you who really like graphical debuggers.
1571         </para>
1572
1573         <sect3>
1574           <title>DDD</title>
1575
1576           <para>
1577             Use the following steps, in this order:
1578 <orderedlist>
1579               <listitem>
1580                 <para>
1581 Start the wine debugger with a command line
1582 like:
1583 <screen>
1584         winedbg -- --gdb --no-start &lt;name_of_exe_to_debug.exe&gt;
1585 </screen>
1586 </para>
1587               </listitem>
1588               <listitem>
1589                 <para>
1590                   Start ddd
1591                 </para>
1592               </listitem>
1593               <listitem>
1594                 <para>
1595                   In ddd, use the 'Open File' or 'Open Program' to
1596                   point to the wine executable
1597                 </para>
1598               </listitem>
1599               <listitem>
1600                 <para>
1601 In the output of 1/, there's a line like
1602 <screen>
1603         target remote localhost:32878
1604 </screen>
1605 copy that line and paste into ddd command pane (the one with the (gdb)
1606 prompt)
1607 </para>
1608               </listitem>
1609             </orderedlist>
1610 The program should now be loaded and up and running. If you want, you
1611 can also add in 1/ after the name of the exec all the needed
1612 parameters
1613           </para>
1614         </sect3>
1615         <sect3>
1616           <title>kdbg</title>
1617
1618           <para>
1619             Use the following steps, in this order:
1620             <orderedlist>
1621               <listitem>
1622                 <para>
1623                   Start the wine debugger with a command line like:
1624 <screen>
1625         winedbg -- --gdb --no-start &lt;name_of_exe_to_debug.exe&gt;
1626 </screen>
1627 </para>
1628               </listitem>
1629               <listitem>
1630                 <para>
1631                   In the output of 1/, there's a line like
1632 <screen>
1633         target remote localhost:32878
1634 </screen>
1635 Start kdbg with
1636 <screen>
1637 kdbg -r localhost:32878 wine
1638 </screen>
1639 localhost:32878 is not a fixed value, but has been printed in step
1640 1/. 'wine' should also be the full path to the wine executable.
1641 </para>
1642               </listitem>
1643             </orderedlist>
1644 The program should now be loaded and up and running. If you want, you
1645 can also add in 1/ after the name of the exec all the needed
1646 parameters
1647           </para>
1648         </sect3>
1649       </sect2>
1650
1651       <sect2>
1652         <title>Using other Unix debuggers</title>
1653
1654         <para>
1655           You can also use other debuggers (like
1656           <command>gdb</command>), but you must be aware of a few
1657           items:
1658         </para>
1659         <para>
1660           You need to attach the unix debugger to the correct unix
1661           process (representing the correct windows thread) (you can
1662           "guess" it from a <command>ps fax</command> for example:
1663           When running the emulator, usually the first two
1664           <varname>upids</varname> are for the Windows' application
1665           running the desktop, the first thread of the application is
1666           generally the third <varname>upid</varname>; when running a
1667           Winelib program, the first thread of the application is
1668           generally the first <varname>upid</varname>)
1669         </para>
1670         <note>
1671           <para>
1672             Even if latest <command>gdb</command> implements the
1673             notion of threads, it won't work with Wine because the
1674             thread abstraction used for implementing Windows' thread
1675             is not 100% mapped onto the Linux POSIX threads
1676             implementation. It means that you'll have to spawn a
1677             different <command>gdb</command> session for each Windows'
1678             thread you wish to debug.
1679           </para>
1680         </note>
1681
1682         <para>
1683           Here's how to get info about the current execution status of a
1684           certain Wine process:
1685         </para>
1686         <para>
1687           Change into your Wine source dir and enter:
1688         </para>
1689         <screen>
1690 $ gdb wine
1691         </screen>
1692         <para>
1693           Switch to another console and enter <command>ps ax | grep
1694             wine</command> to find all wine processes. Inside
1695           <command>gdb</command>, repeat for all Wine processes:
1696         </para>
1697         <screen>
1698 (gdb) attach <userinput>PID</userinput>
1699         </screen>
1700         <para>
1701           with <userinput>PID</userinput> being the process ID of one of
1702           the Wine processes.  Use
1703         </para>
1704         <screen>
1705 (gdb) bt
1706         </screen>
1707         <para>
1708           to get the backtrace of the current Wine process, i.e. the
1709           function call history.  That way you can find out what the
1710           current process is doing right now.  And then you can use
1711           several times:
1712         </para>
1713         <screen>
1714 (gdb) n
1715         </screen>
1716         <para>
1717           or maybe even
1718         </para>
1719         <screen>
1720 (gdb) b <userinput>SomeFunction</userinput>
1721         </screen>
1722         <para>
1723           and
1724         </para>
1725         <screen>
1726 (gdb) c
1727         </screen>
1728         <para>
1729           to set a breakpoint at a certain function and continue up to
1730           that function.  Finally you can enter
1731         </para>
1732         <screen>
1733 (gdb) detach
1734         </screen>
1735         <para>
1736           to detach from the Wine process.
1737         </para>
1738         <!-- *** End of xtra content *** -->
1739       </sect2>
1740
1741       <sect2>
1742         <title>Using other Windows debuggers</title>
1743
1744         <para>
1745           You can use any Windows' debugging API compliant debugger
1746           with Wine. Some reports have been made of success with
1747           VisualStudio debugger (in remote mode, only the hub runs
1748           in Wine). GoVest fully runs in Wine.
1749         </para>
1750       </sect2>
1751
1752       <sect2>
1753         <title>Main differences between winedbg and regular Unix debuggers</title>
1754         <table><title>Debuggers comparison</title>
1755           <tgroup cols=2 align="left">
1756             <tbody>
1757               <row>
1758                 <entry>WineDbg</entry><entry>gdb</entry>
1759               </row>
1760               <row>
1761                 <entry>
1762                   WineDbg debugs a Windows' process: the various
1763                   threads will be handled by the same WineDbg session,
1764                   and a breakpoint will be triggered for any thread of
1765                   the W-process
1766                 </entry>
1767                 <entry>
1768                   gdb debugs a Windows' thread: a separate gdb session
1769                   is needed for each thread of a Windows' process and
1770                   a breakpoint will be triggered only for the w-thread
1771                   debugged
1772                 </entry>
1773               </row>
1774               <row>
1775                 <entry>
1776                   WineDbg supports debug information from stabs
1777                   (standard Unix format) and Microsoft's C, CodeView,
1778                   .DBG
1779                 </entry>
1780                 <entry>
1781                   GDB supports debug information from stabs (standard
1782                   Unix format) and Dwarf II.
1783                 </entry>
1784               </row>
1785             </tbody>
1786           </tgroup>
1787         </table>
1788       </sect2>
1789     </sect1>
1790
1791
1792     <sect1 id="dbg-limits">
1793       <title>Limitations</title>
1794
1795       <itemizedlist>
1796         <listitem>
1797           <para>
1798             16 bit processes are not supported (but calls to 16 bit
1799             code in 32 bit  applications are).
1800           </para>
1801         </listitem>
1802         <listitem>
1803           <para>
1804             Function call in expression is no longer supported
1805           </para>
1806         </listitem>
1807       </itemizedlist>
1808     </sect1>
1809   </chapter>
1810
1811 <!-- Keep this comment at the end of the file
1812 Local variables:
1813 mode: sgml
1814 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
1815 End:
1816 -->