documentation/debugger.sgml

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