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