debugger.sgml 75.7 KB
Newer Older
1
  <chapter id="debugger">
John R. Sheets's avatar
John R. Sheets committed
2
    <title>Debugging Wine</title>
3 4

    <sect1 id="dbg-intro">
John R. Sheets's avatar
John R. Sheets committed
5
      <title>Introduction</title>
6 7

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
8
        <title>Processes and threads: in underlying OS and in Windows</title>
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

        <para>
          Before going into the depths of debugging in Wine, here's
          a small overview of process and thread handling in Wine.
          It has to be clear that there are two different beasts:
          processes/threads from the Unix point of view and
          processes/threads from a Windows point of view.
        </para>
        <para>
          Each Windows' thread is implemented as a Unix process (under
          Linux using the <function>clone</function> syscall), meaning
          that all threads of a same Windows' process share the same
          (unix) address space.
        </para>
        <para>
          In the following:
        </para>
        <itemizedlist>
          <listitem>
28 29 30
            <para>
              <varname>W-process</varname> means a process in Windows' terminology
            </para>
31 32
          </listitem>
          <listitem>
33 34 35
            <para>
              <varname>U-process</varname> means a process in Unix' terminology
            </para>
36 37
          </listitem>
          <listitem>
38 39 40
            <para>
              <varname>W-thread</varname> means a thread in Windows' terminology
            </para>
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
          </listitem>
        </itemizedlist>
        <para>
          A <varname>W-process</varname> is made of one or several
          <varname>W-threads</varname>. Each
          <varname>W-thread</varname> is mapped to one and only one
          <varname>U-process</varname>. All
          <varname>U-processes</varname> of a same
          <varname>W-process</varname> share the same address space.
        </para>
        <para>
          Each Unix process can be identified by two values:
        </para>
        <itemizedlist>
          <listitem>
56 57 58
            <para>
              the Unix process id (<varname>upid</varname> in the following)
            </para>
59 60
          </listitem>
          <listitem>
61 62 63
            <para>
              the Windows's thread id (<varname>tid</varname>)
            </para>
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
          </listitem>
        </itemizedlist>
        <para>
          Each Windows' process has also a Windows' process id
          (<varname>wpid</varname> in the following). It must be clear
          that <varname>upid</varname> and <varname>wpid</varname> are
          different and shall not be used instead of the other.
        </para>
        <para>
          <varname>Wpid</varname> and <varname>tid</varname> are
          defined (Windows) system wide. They must not be confused
          with process or thread handles which, as any handle, is an
          indirection to a system object (in this case process or
          thread). A same process can have several different handles
          on the same kernel object. The handles can be defined as
          local (the values is only valid in a process), or system
          wide (the same handle can be used by any
          <varname>W-process</varname>).
        </para>
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
86
        <title>Wine, debugging and WineDbg</title>
87 88 89 90 91 92 93

        <para>
          When talking of debugging in Wine, there are at least two
          levels to think of:
        </para>
        <itemizedlist>
          <listitem>
94 95 96
            <para>
              the Windows' debugging API.
            </para>
97 98
          </listitem>
          <listitem>
99
            <para>
100
              the Wine integrated debugger, dubbed <command>winedbg</command>.
101
            </para>
102 103 104
          </listitem>
        </itemizedlist>
        <para>
John R. Sheets's avatar
John R. Sheets committed
105
          Wine implements most of the Windows' debugging API (the
106
          part in <filename>KERNEL32.DLL</filename>, not the one in
107
          <filename>IMAGEHLP.DLL</filename>), and allows any program
John R. Sheets's avatar
John R. Sheets committed
108
          (emulated or Winelib) using that API to debug a
109 110 111
          <varname>W-process</varname>.
        </para>
        <para>
112 113 114 115 116 117 118 119 120 121
	  Wine also implements <filename>DBGHELP.DLL</filename> which
	  allows to look into symbols and types from any module (if
	  the module has been compiled with the proper options). 
        </para>
        <para>
          <command>winedbg</command> is a Winelib application making
          use of these APIs (<filename>KERNEL32.DLL</filename>'s
	  debugging API and <filename>DBGHELP.DLL</filename>) to allow
	  debugging both any Wine or Winelib applications as well as
	  Wine itself (kernel and all DLLs).
122 123 124 125
        </para>
      </sect2>
    </sect1>

John R. Sheets's avatar
John R. Sheets committed
126

127
    <sect1 id="dbg-modes">
John R. Sheets's avatar
John R. Sheets committed
128
      <title>WineDbg's modes of invocation</title>
129 130

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
131
        <title>Starting a process</title>
132 133 134

        <para>
          Any application (either a Windows' native executable, or a
John R. Sheets's avatar
John R. Sheets committed
135
          Winelib application) can be run through
136
          <command>winedbg</command>. Command line options and tricks
137 138 139 140 141 142 143 144 145
          are the same as for wine:
        </para>
        <screen>
winedbg telnet.exe
winedbg "hl.exe -windowed"
        </screen>
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
146
        <title>Attaching</title>
147 148

        <para>
149 150
          <command>winedbg</command> can also be launched without any
          command line argument: <command>winedbg</command> is started
151 152
          without any attached process. You can get a list of running
          <varname>W-processes</varname> (and their
153
          <varname>wpid</varname>'s) using the <command>info
154 155 156
            process</command> command, and then, with the
          <command>attach</command> command, pick up the
          <varname>wpid</varname> of the <varname>W-process</varname>
157 158 159
          you want to debug. This is a neat feature as it allows you
	  to debug an already started application.
	 </para>
160 161
      </sect2>

John R. Sheets's avatar
John R. Sheets committed
162
      <sect2 id="dbg-on-exception">
163
        <title id="dbg-exception-title">On exceptions</title>
164 165 166 167

        <para>
          When something goes wrong, Windows tracks this as an
          exception. Exceptions exist for segmentation violation,
168
          stack overflow, division by zero, etc.
169 170
        </para>
        <para>
171 172 173 174 175
          When an exception occurs, Wine checks if the
	  <varname>W-process</varname> is debugged. If so, the
	  exception event is sent to the debugger, which takes care of
	  it: end of the story. This mechanism is part of the standard
	  Windows' debugging API.
176 177 178 179
        </para>
        <para>
          If the <varname>W-process</varname> is not debugged, Wine
          tries to launch a debugger. This debugger (normally
180
          <command>winedbg</command>, see III Configuration for more
181 182 183 184 185 186 187 188
          details), at startup, attaches to the
          <varname>W-process</varname> which generated the exception
          event. In this case, you are able to look at the causes of
          the exception, and either fix the causes (and continue
          further the execution) or dig deeper to understand what went
          wrong.
        </para>
        <para>
189
          If <command>winedbg</command> is the standard debugger, the
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
          <command>pass</command> and <command>cont</command> commands
          are the two ways to let the process go further for the
          handling of the  exception event.
        </para>
        <para>
          To be more precise on the way Wine (and Windows) generates
          exception events, when a fault occurs (segmentation
          violation, stack overflow...), the event is first sent to
          the debugger (this is known as a first chance exception).
          The debugger can give two answers:
        </para>

        <variablelist>
          <varlistentry>
            <term>continue:</term>
            <listitem>
              <para>
                the debugger had the ability to correct what's
                generated the exception, and is now able to continue
                process execution.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>pass:</term>
            <listitem>
              <para>
                the debugger couldn't correct the cause of the
                first chance exception. Wine will now try to walk
                the list of exception handlers to see if one of them
                can handle the exception. If no exception handler is
                found, the exception is sent once again to the
                debugger to indicate the failure of the exception
                handling.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
        <note>
          <para>
            since some of Wine's code uses exceptions and
            <function>try/catch</function> blocks to provide some
232
            functionality, <command>winedbg</command> can be entered
233 234 235 236 237 238 239 240 241 242
            in such cases with segv exceptions. This happens, for
            example, with <function>IsBadReadPtr</function> function.
            In that case, the <command>pass</command> command shall be
            used, to let the handling of the exception to be done by
            the <function>catch</function> block in
            <function>IsBadReadPtr</function>.
          </para>
        </note>
      </sect2>

243 244 245 246 247 248
      <sect2 id="interrupt">
        <title>Interrupting</title>

	<para>
	  You can stop the debugger while it's running by hitting
	  Ctrl-C in its window. This will stop the debugged process,
249
	  and let you manipulate the current context.
250 251 252
	</para>
      </sect2>

253
      <sect2>
John R. Sheets's avatar
John R. Sheets committed
254
        <title>Quitting</title>
255 256

        <para>
257 258
	  Wine supports the new XP APIs, allowing for a debugger to
	  detach from a program being debugged (see
259
	  <command>detach</command> command).
260 261 262 263
        </para>
      </sect2>
    </sect1>

John R. Sheets's avatar
John R. Sheets committed
264 265 266 267 268

    <sect1 id="wine-debugger">
      <title>Using the Wine Debugger</title>

      <para>
269
        This section describes where to start debugging Wine. If at any
John R. Sheets's avatar
John R. Sheets committed
270
        point you get stuck and want to ask for help, please read the
271 272 273
        <emphasis>How to Report A Bug</emphasis> section of the 
        <emphasis>Wine Users Guide</emphasis> for information on how to write
        useful bug reports.
John R. Sheets's avatar
John R. Sheets committed
274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311
      </para>

      <sect2>
        <title>Crashes</title>

        <para>
          These usually show up like this:
        </para>
        <screen>
|Unexpected Windows program segfault - opcode = 8b
|Segmentation fault in Windows program 1b7:c41.
|Loading symbols from ELF file /root/wine/wine...
|....more Loading symbols from ...
|In 16 bit mode.
|Register dump:
| CS:01b7 SS:016f DS:0287 ES:0000
| IP:0c41 SP:878a BP:8796 FLAGS:0246
| AX:811e BX:0000 CX:0000 DX:0000 SI:0001 DI:ffff
|Stack dump:
|0x016f:0x878a:  0001 016f ffed 0000 0000 0287 890b 1e5b
|0x016f:0x879a:  01b7 0001 000d 1050 08b7 016f 0001 000d
|0x016f:0x87aa:  000a 0003 0004 0000 0007 0007 0190 0000
|0x016f:0x87ba:
|
|0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
|Backtrace:
|0 0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c)
|1 0x01b7:0x1e5b (PXSRV_FONPUTCATFONT+0x2cd)
|2 0x01a7:0x05aa
|3 0x01b7:0x0768 (PXSRV_FONINITFONTS+0x81)
|4 0x014f:0x03ed (PDOXWIN_@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
|5 0x013f:0x00ac
|
|0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c):  movw        %es:0x38(%bx),%dx
        </screen>
        <para>
          Steps to debug a crash. You may stop at any step, but please
          report the bug and provide as much of the information
312
          gathered to the bug report as feasible.
John R. Sheets's avatar
John R. Sheets committed
313 314 315 316 317 318 319
        </para>

        <orderedlist>
          <listitem>
            <para>
              Get the reason for the crash. This is usually an access to
              an invalid selector, an access to an out of range address
Tom Wickline's avatar
Tom Wickline committed
320
              in a valid selector, popping a segment register from the
John R. Sheets's avatar
John R. Sheets committed
321 322 323 324 325 326 327 328 329 330 331 332 333 334
              stack or the like. When reporting a crash, report this
              <emphasis>whole</emphasis> crashdump even if it doesn't
              make sense to you.
            </para>
            <para>
              (In this case it is access to an invalid selector, for
              <systemitem>%es</systemitem> is <literal>0000</literal>, as
              seen in the register dump).
            </para>
          </listitem>
          <listitem>
            <para>
              Determine the cause of the crash. Since this is usually
              a primary/secondary reaction to a failed or misbehaving
335 336
              Wine function, rerun Wine with the<parameter>WINEDEBUG=+relay</parameter>
              environment variable set. This will
John R. Sheets's avatar
John R. Sheets committed
337 338 339 340 341 342 343 344 345 346 347 348 349 350
              generate quite a lot of output, but usually the reason is
              located in the last call(s).  Those lines usually look like
              this:
            </para>
            <screen>
|Call KERNEL.90: LSTRLEN(0227:0692 "text") ret=01e7:2ce7 ds=0227
      ^^^^^^^^^  ^       ^^^^^^^^^ ^^^^^^      ^^^^^^^^^    ^^^^
      |          |       |         |           |            |Datasegment
      |          |       |         |           |Return address
      |          |       |         |textual parameter
      |          |       |
      |          |       |Argument(s). This one is a win16 segmented pointer.
      |          |Function called.
      |The module, the function is called in. In this case it is KERNEL.
351

John R. Sheets's avatar
John R. Sheets committed
352 353 354 355 356 357 358 359 360 361
|Ret  KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
                                  ^^^^^^
				  |Returnvalue is 16 bit and has the value 4.
            </screen>
          </listitem>
          <listitem>
            <para>
              If you have found a misbehaving function, try to find out
              why it misbehaves. Find the function in the source code.
              Try to make sense of the arguments passed. Usually there is
362
              a <function>WINE_DEFAULT_DEBUG_CHANNEL(&lt;channel>);</function>
363 364
              at the beginning of the file. Rerun wine with the
              <parameter>WINEDEBUG=+xyz,+relay</parameter> environment variable set.
John R. Sheets's avatar
John R. Sheets committed
365
            </para>
366 367
            <para>
              Occasionally there are additional debug channels defined at the 
Tom Wickline's avatar
Tom Wickline committed
368
              beginning of the file in the form.
369
              <function>WINE_DECLARE_DEBUG_CHANNEL(&lt;channel>);</function>
Tom Wickline's avatar
Tom Wickline committed
370
              If so the offending function may also uses one of these alternate
371 372 373 374
              channels. Look through the the function for  
             <function>TRACE_(&lt;channel>)(" ... /n");</function> and add any
             additional channels to the commandline.
            </para>
John R. Sheets's avatar
John R. Sheets committed
375 376 377 378 379
          </listitem>
          <listitem>
            <para>
              Additional information on how to debug using the internal
              debugger can be  found in
380
              <filename>programs/winedbg/README</filename>.
John R. Sheets's avatar
John R. Sheets committed
381 382 383 384 385 386
            </para>
          </listitem>
          <listitem>
            <para>
              If this information isn't clear enough or if you want to
              know more about what's happening in the function itself,
387 388
              try running wine with <parameter>WINEDEBUG=+all</parameter>,
              which dumps ALL included debug
John R. Sheets's avatar
John R. Sheets committed
389 390 391 392 393
              information in wine.
            </para>
          </listitem>
          <listitem>
            <para>
394 395 396
              If even that isn't enough, add more debug output for yourself 
              into the functions you find relevant. See The section on Debug 
              Logging in this guide for more information. You might
John R. Sheets's avatar
John R. Sheets committed
397
              also try to run the program in <command>gdb</command>
398
              instead of using the Wine debugger. If you do that, use
John R. Sheets's avatar
John R. Sheets committed
399 400
              <parameter>handle SIGSEGV nostop noprint</parameter> to
              disable the handling of seg faults inside
401
              <command>gdb</command> (needed for Win16). 
John R. Sheets's avatar
John R. Sheets committed
402 403 404 405
            </para>
          </listitem>
          <listitem>
            <para>
406 407 408 409 410 411 412
              You can also set a breakpoint for that function. Start wine 
              useing <command>winedbg</command> instead of 
              <command>wine</command>. Once the debugger is is running enter 
              <command>break</command> <parameter>KERNEL_LSTRLEN</parameter>
              (replace by function you want to debug, CASE IS RELEVANT) 
              to set a breakpoint.  Then
              use <command>continue</command> to start normal
John R. Sheets's avatar
John R. Sheets committed
413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428
              program-execution. Wine will stop if it reaches the
              breakpoint. If the program isn't yet at the crashing call
              of that function, use <command>continue</command> again
              until you are about to enter that function. You may now
              proceed with single-stepping the function until you reach
              the point of crash. Use the other debugger commands to
              print registers and the like.
            </para>
          </listitem>
        </orderedlist>
      </sect2>

      <sect2>
        <title>Program hangs, nothing happens</title>

        <para>
429 430
          Start the program with <command>winedbg</command> instead of
          <command>wine</command>. When the program locks up switch to the 
431
          winedbg's terminal and press 
432 433 434
          <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>. this
          will stop the program and let you debug the program as you would for
          a crash. 
John R. Sheets's avatar
John R. Sheets committed
435 436 437 438 439 440 441 442 443 444 445 446 447 448 449
        </para>
      </sect2>

      <sect2>
        <title>Program reports an error with a Messagebox</title>

        <para>
          Sometimes programs are reporting failure using more or
          less nondescript messageboxes. We can debug this using the
          same method as Crashes, but there is one problem... For
          setting up a message box the program also calls Wine
          producing huge chunks of debug code.
        </para>
        <para>
          Since the failure happens usually directly before setting up
450
          the Messagebox you can start winedbg and set a
John R. Sheets's avatar
John R. Sheets committed
451 452
          breakpoint at <function>MessageBoxA</function> (called by win16
          and win32 programs) and proceed with
453 454
          <command>continue</command>. With <parameter>WINEDEBUG=+all</parameter>
          Wine will now stop directly before setting
John R. Sheets's avatar
John R. Sheets committed
455 456 457
          up the Messagebox. Proceed as explained above.
        </para>
        <para>
458
          You can also run wine using <command>WINEDEBUG=+relay wine
John R. Sheets's avatar
John R. Sheets committed
459 460 461 462 463 464 465 466 467 468 469 470 471 472
            program.exe 2>&1 | less -i</command> and in
          <command>less</command> search for <quote>MessageBox</quote>.
        </para>
      </sect2>

      <sect2>
        <title>Disassembling programs:</title>

        <para>
          You may also try to disassemble the offending program to
          check for undocumented features and/or use of them.
        </para>
        <para>
          The best, freely available, disassembler for Win16 programs is
473
          <application>Windows Codeback</application>, archive name
474 475 476
          <filename>wcbxxx.zip</> (e.g. <filename>wcb105a.zip</>), which
          usually can be found in the <filename>Cica-Mirror</filename>
          subdirectory on the Wine ftp sites. (See <filename>ANNOUNCE</>).
John R. Sheets's avatar
John R. Sheets committed
477 478 479
        </para>
        <para>
          Disassembling win32 programs is possible using
480 481 482
          <application>Windows Disassembler 32</>. Look for
          a file called <filename>w32dsm87.zip</> (or similar)
          on <ulink url="http://www.winsite.com/">http://www.winsite.com</>
John R. Sheets's avatar
John R. Sheets committed
483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544
          and mirrors.  The shareware version does not allow saving of
          disassembly listings. You can also use the newer (and in the
          full version better) <application>Interactive
            Disassembler</application> (IDA) from the ftp sites mentioned
          at the end of the document. Understanding disassembled code is
          mostly a question of exercise.
        </para>
        <para>
          Most code out there uses standard C function entries (for it
          is usually  written in C). Win16 function entries usually
          look like that:
        </para>
        <programlisting>
push bp
mov bp, sp
... function code ..
retf XXXX 	&lt;--------- XXXX is number of bytes of arguments
        </programlisting>
        <para>
          This is a <function>FAR</function> function with no local
          storage. The arguments usually start at
          <literal>[bp+6]</literal> with increasing offsets. Note, that
          <literal>[bp+6]</literal> belongs to the
          <emphasis>rightmost</emphasis> argument, for exported win16
          functions use the PASCAL calling convention. So, if we use
          <function>strcmp(a,b)</function> with <parameter>a</parameter>
          and <parameter>b</parameter> both 32 bit variables
          <parameter>b</parameter> would be at <literal>[bp+6]</literal>
          and <parameter>a</parameter> at <literal>[bp+10]</literal>.
        </para>
        <para>
          Most functions make also use of local storage in the stackframe:
        </para>
        <programlisting>
enter 0086, 00
... function code ...
leave
retf XXXX
        </programlisting>
        <para>
          This does mostly the same as above, but also adds
          <literal>0x86</literal> bytes of stackstorage, which is
          accessed using <literal>[bp-xx]</literal>. Before calling a
          function, arguments are pushed on the stack using something
          like this:
        </para>
        <programlisting>
push word ptr [bp-02]	&lt;- will be at [bp+8]
push di			&lt;- will be at [bp+6]
call KERNEL.LSTRLEN
        </programlisting>
        <para>
          Here first the selector and then the offset to the passed
          string are pushed.
        </para>
      </sect2>

      <sect2>
        <title>Sample debugging session:</title>

        <para>
          Let's debug the infamous Word <filename>SHARE.EXE</filename>
545
          messagebox:
John R. Sheets's avatar
John R. Sheets committed
546 547 548 549 550 551 552 553 554
        </para>
        <screen>
|marcus@jet $ wine winword.exe
|            +---------------------------------------------+
|            | !  You must leave Windows and load SHARE.EXE|
|            |    before starting Word.                    |
|            +---------------------------------------------+
        </screen>
        <screen>
555
|marcus@jet $ WINEDEBUG=+relay,-debug wine winword.exe
John R. Sheets's avatar
John R. Sheets committed
556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620
|CallTo32(wndproc=0x40065bc0,hwnd=000001ac,msg=00000081,wp=00000000,lp=00000000)
|Win16 task 'winword': Breakpoint 1 at 0x01d7:0x001a
|CallTo16(func=0127:0070,ds=0927)
|Call WPROCS.24: TASK_RESCHEDULE() ret=00b7:1456 ds=0927
|Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x8672 ret=00b7:1456 ds=0927
|CallTo16(func=01d7:001a,ds=0927)
|     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=0927 BP=0000 ES=11f7
|Loading symbols: /home/marcus/wine/wine...
|Stopped on breakpoint 1 at 0x01d7:0x001a
|In 16 bit mode.
|Wine-dbg>break MessageBoxA                          &lt;---- Set Breakpoint
|Breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|Wine-dbg>c                                            &lt;---- Continue
|Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
|     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
|CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
|...                                                   &lt;----- Much debugoutput
|Call KERNEL.136: GETDRIVETYPE(0x0000) ret=060f:097b ds=0927
                               ^^^^^^ Drive 0 (A:)
|Ret  KERNEL.136: GETDRIVETYPE() retval=0x0002 ret=060f:097b ds=0927
                                        ^^^^^^  DRIVE_REMOVEABLE
						(It is a floppy diskdrive.)

|Call KERNEL.136: GETDRIVETYPE(0x0001) ret=060f:097b ds=0927
                               ^^^^^^ Drive 1 (B:)
|Ret  KERNEL.136: GETDRIVETYPE() retval=0x0000 ret=060f:097b ds=0927
                                        ^^^^^^  DRIVE_CANNOTDETERMINE
						(I don't have drive B: assigned)

|Call KERNEL.136: GETDRIVETYPE(0x0002) ret=060f:097b ds=0927
                               ^^^^^^^ Drive 2 (C:)
|Ret  KERNEL.136: GETDRIVETYPE() retval=0x0003 ret=060f:097b ds=0927
                                        ^^^^^^ DRIVE_FIXED
                                               (specified as a harddisk)

|Call KERNEL.97: GETTEMPFILENAME(0x00c3,0x09278364"doc",0x0000,0927:8248) ret=060f:09b1 ds=0927
                                 ^^^^^^           ^^^^^        ^^^^^^^^^
                                 |                |            |buffer for fname
                                 |                |temporary name ~docXXXX.tmp
                                 |Force use of Drive C:.

|Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writeable.
|Please check your configuration file if this generates a failure.
        </screen>
        <para>
          Whoops, it even detects that something is wrong!
        </para>
        <screen>
|Ret  KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
                                          ^^^^^^ Temporary storage ID

|Call KERNEL.74: OPENFILE(0x09278248"C:~doc9281.tmp",0927:82da,0x1012) ret=060f:09d8 ds=0927
                                    ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
                                    |filename        |OFSTRUCT |open mode:

                                       OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
        </screen>
        <para>
          This fails, since my <medialabel>C:</medialabel> drive is in
          this case mounted readonly.
        </para>
        <screen>
|Ret  KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
                                   ^^^^^^ HFILE_ERROR16, yes, it failed.

Tom Wickline's avatar
Tom Wickline committed
621
|Call USER.1: MESSAGEBOX(0x0000,0x09278376"You must close Windows and load SHARE.EXE before you start Word.",0x00000000,0x1030) ret=060f:084f ds=0927
622
        </screen>
John R. Sheets's avatar
John R. Sheets committed
623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643
        <para>
          And MessageBox'ed.
        </para>
        <screen>
|Stopped on breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|190     {		&lt;- the sourceline
In 32 bit mode.
Wine-dbg>
        </screen>
        <para>
          The code seems to find a writeable harddisk and tries to create
          a file there. To work around this bug, you can define
          <medialabel>C:</medialabel> as a networkdrive, which is ignored
          by the code above.
        </para>
      </sect2>

      <sect2>
        <title>Debugging Tips</title>

        <para>
644
          Here are some additional debugging tips:
John R. Sheets's avatar
John R. Sheets committed
645 646 647 648 649 650 651 652 653
        </para>

        <itemizedlist>
          <listitem>
            <para>
              If you have a program crashing at such an early loader phase that you can't
              use the Wine debugger normally, but Wine already executes the program's
              start code, then you may use a special trick. You should do a
              <programlisting>
654
WINEDEBUG=+relay wine program
John R. Sheets's avatar
John R. Sheets committed
655 656 657 658
              </programlisting>
              to get a listing of the functions the program calls in its start function.
              Now you do a
              <programlisting>
659
winedbg winfile.exe
John R. Sheets's avatar
John R. Sheets committed
660 661 662
              </programlisting>
            </para>
            <para>
663
              This way, you get into <command>winedbg</command>. Now you
John R. Sheets's avatar
John R. Sheets committed
664 665 666 667 668 669 670 671 672 673 674 675 676 677 678
              can set a breakpoint on any function the program calls in
              the start function and just type <userinput>c</userinput>
              to bypass the eventual calls of Winfile to this function
              until you are finally at the place where this function gets
              called by the crashing start function. Now you can proceed
              with your debugging as usual.
            </para>
          </listitem>
          <listitem>
            <para>
              If you try to run a program and it quits after showing an error messagebox,
              the problem can usually be identified in the return value of one of the
              functions executed before <function>MessageBox()</function>.
              That's why you should re-run the program with e.g.
              <programlisting>
679
WINEDEBUG=+relay wine  &lt;program name> &>relmsg
John R. Sheets's avatar
John R. Sheets committed
680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732
              </programlisting>
              Then do a <command>more relmsg</command> and search for the
              last occurrence of a call to the string "MESSAGEBOX". This is a line like
              <programlisting>
Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
              </programlisting>
              In my example the lines before the call to
              <function>MessageBox()</function> look like that:
              <programlisting>
Call KERNEL.96: FREELIBRARY(0x0347) ret=01cf:1033 ds=01ff
CallTo16(func=033f:0072,ds=01ff,0x0000)
Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1033 ds=01ff
Call KERNEL.96: FREELIBRARY(0x036f) ret=01cf:1043 ds=01ff
CallTo16(func=0367:0072,ds=01ff,0x0000)
Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1043 ds=01ff
Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
CallTo16(func=0317:0072,ds=01ff,0x0000)
Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:105c ds=01ff
Call USER.171: WINHELP(0x02ac,0x01ff05b4 "COMET.HLP",0x0002,0x00000000) ret=01cf:1070 ds=01ff
CallTo16(func=0117:0080,ds=01ff)
Call WPROCS.24: TASK_RESCHEDULE() ret=00a7:0a2d ds=002b
Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x0000 ret=00a7:0a2d ds=002b
Ret  USER.171: WINHELP() retval=0x0001 ret=01cf:1070 ds=01ff
Call KERNEL.96: FREELIBRARY(0x01be) ret=01df:3e29 ds=01ff
Ret  KERNEL.96: FREELIBRARY() retval=0x0000 ret=01df:3e29 ds=01ff
Call KERNEL.52: FREEPROCINSTANCE(0x02cf00ba) ret=01f7:1460 ds=01ff
Ret  KERNEL.52: FREEPROCINSTANCE() retval=0x0001 ret=01f7:1460 ds=01ff
Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
              </programlisting>
            </para>
            <para>
              I think that the call to <function>MessageBox()</function>
              in this example is <emphasis>not</emphasis> caused by a
              wrong result value of some previously executed function
              (it's happening quite often like that), but instead the
              messagebox complains about a runtime error at
              <literal>0x0004:0x1056</literal>.
            </para>
            <para>
              As the segment value of the address is only
              <literal>4</literal>, I think that that is only an internal
              program value. But the offset address reveals something
              quite interesting: Offset <literal>1056</literal> is
              <emphasis>very</emphasis> close to the return address of
              <function>FREELIBRARY()</function>:
              <programlisting>
Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
                                             ^^^^
              </programlisting>
            </para>
            <para>
              Provided that segment <literal>0x0004</literal> is indeed segment
              <literal>0x1cf</literal>, we now we can use IDA                 (available at
Tom Wickline's avatar
Tom Wickline committed
733 734
              <ulink url="http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip">
               http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip</ulink>) to
John R. Sheets's avatar
John R. Sheets committed
735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763
              disassemble the part that caused the error. We just have to find the address of
              the call to <function>FreeLibrary()</function>. Some lines before that the
              runtime error occurred. But be careful! In some cases you don't have to
              disassemble the main program, but instead some DLL called by it in order to find
              the correct place where the runtime error occurred. That can be determined by
              finding the origin of the segment value (in this case <literal>0x1cf</literal>).
            </para>
          </listitem>
          <listitem>
            <para>
              If you have created a relay file of some crashing
              program and want to set a breakpoint at a certain
              location which is not yet available as the program loads
              the breakpoint's segment during execution, you may set a
              breakpoint to <function>GetVersion16/32</function> as
              those functions are called very often.
            </para>
            <para>
              Then do a <userinput>c</userinput> until you are able to
              set this breakpoint without error message.
            </para>
          </listitem>
          <listitem>
            <para>
              Some useful programs:
            </para>
            <variablelist>
              <varlistentry>
                <term>
764
                  <application>IDA</application>:
John R. Sheets's avatar
John R. Sheets committed
765
                  <filename>
Tom Wickline's avatar
Tom Wickline committed
766 767
                    <ulink url="http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip">
                     http://www.filelibrary.com:8080/cgi-bin/freedownload/DOS/h/72/ida35bx.zip</ulink>
John R. Sheets's avatar
John R. Sheets committed
768 769 770 771 772 773 774 775 776 777 778 779 780
                  </filename>
                </term>
                <listitem>
                  <para>
                    <emphasis>Very</emphasis> good DOS disassembler ! It's badly needed
                    for debugging Wine sometimes.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <application>XRAY</application>:
                  <filename>
Tom Wickline's avatar
Tom Wickline committed
781 782
                    <ulink url="http://garbo.uwasa.fi/pub/pc/sysinfo/xray15.zip">
                     http://garbo.uwasa.fi/pub/pc/sysinfo/xray15.zip</ulink>
John R. Sheets's avatar
John R. Sheets committed
783 784 785 786 787 788 789 790 791 792 793 794 795
                  </filename>
                </term>
                <listitem>
                  <para>
                    Traces DOS calls (Int 21h, DPMI, ...). Use it with
                    Windows to correct file management problems etc.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <application>pedump</application>:
                  <filename>
Tom Wickline's avatar
Tom Wickline committed
796 797
                    <ulink url="ftp://ftp.simtel.net/pub/simtelnet/win95/prog/pedump.zip">
                     ftp://ftp.simtel.net/pub/simtelnet/win95/prog/pedump.zip</ulink>
John R. Sheets's avatar
John R. Sheets committed
798 799 800 801 802 803 804 805 806
                  </filename>
                </term>
                <listitem>
                  <para>
                    Dumps the imports and exports of a PE (Portable
                    Executable) DLL.
                  </para>
                </listitem>
              </varlistentry>
807 808 809 810 811 812 813 814 815 816 817
              <varlistentry>
                <term>
                  <application>winedump</application>:
                </term>
                <listitem>
                  <para>
                    Dumps the imports and exports of a PE (Portable
                    Executable) DLL (included in wine tree).
                  </para>
                </listitem>
              </varlistentry>
John R. Sheets's avatar
John R. Sheets committed
818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836
            </variablelist>
          </listitem>
        </itemizedlist>
      </sect2>

      <sect2>
        <title>Some basic debugger usages:</title>

        <para>
          After starting your program with
        </para>
        <screen>
wine -debug myprog.exe
        </screen>
        <para>
          the program loads and you get a prompt at the program
          starting point. Then you can set breakpoints:
        </para>
        <screen>
837
  b RoutineName      (by routine name) OR
John R. Sheets's avatar
John R. Sheets committed
838 839 840 841 842 843 844 845 846 847 848 849 850 851
  b *0x812575        (by address)
        </screen>
        <para>
          Then you hit <command>c</command> (continue) to run the
          program. It stops at the breakpoint. You can type
        </para>
        <screen>
  step               (to step one line) OR
  stepi              (to step one machine instruction at a time;
                      here, it helps to know the basic 386
                      instruction set)
  info reg           (to see registers)
  info stack         (to see hex values in the stack)
  info local         (to see local variables)
852 853
  list &lt;line number&gt; (to list source code)
  x &lt;variable name&gt;  (to examine a variable; only works if code
John R. Sheets's avatar
John R. Sheets committed
854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895
                      is not compiled with optimization)
  x 0x4269978        (to examine a memory location)
  ?                  (help)
  q                  (quit)
        </screen>
        <para>
          By hitting <keycap>Enter</keycap>, you repeat the last
          command.
        </para>
      </sect2>
    </sect1>


    <sect1 id="memory-addresses">
      <title>Useful memory addresses</title>
      <para>
        Wine uses several different kinds of memory addresses.
      </para>
      <variablelist>
        <varlistentry>
          <term>
            Win32/"normal" Wine addresses/Linux: linear addresses.
          </term>
          <listitem>
            <para>
              Linear addresses can be everything from 0x0 up to
              0xffffffff.  In Wine on Linux they are often around
              e.g. 0x08000000, 0x00400000 (std. Win32 program load
              address), 0x40000000.  Every Win32 process has its own
              private 4GB address space (that is, from 0x0 up to
              0xffffffff).
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            Win16 "enhanced mode": segmented addresses.
          </term>
          <listitem>
            <para>
              These are the "normal" Win16 addresses, called SEGPTR.
              They have a segment:offset notation, e.g. 0x01d7:0x0012.
896 897
              The segment part usually is a "selector", which
	      <emphasis>always</emphasis>
John R. Sheets's avatar
John R. Sheets committed
898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949
              has the lowest 3 bits set.  Some sample selectors are
              0x1f7, 0x16f, 0x8f.  If these bits are set except for
              the lowest bit, as e.g. with 0x1f6,xi then it might be a
              handle to global memory. Just set the lowest bit to get
              the selector in these cases.  A selector kind of
              "points" to a certain linear (see above) base address.
              It has more or less three important attributes: segment
              base address, segment limit, segment access rights.
            </para>
            <para>
              Example:
            </para>
            <para>
              Selector 0x1f7 (0x40320000, 0x0000ffff, r-x) So 0x1f7
              has a base address of 0x40320000, the segment's last
              address is 0x4032ffff (limit 0xffff), and it's readable
              and executable.  So an address of 0x1f7:0x2300 would be
              the linear address of 0x40322300.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>
            DOS/Win16 "standard mode"
          </term>
          <listitem>
            <para>
              They, too, have a segment:offset notation.  But they are
              completely different from "normal" Win16 addresses, as
              they just represent at most 1MB of memory: The segment
              part can be anything from 0 to 0xffff, and it's the same
              with the offset part.
            </para>
            <para>
              Now the strange thing is the calculation that's behind
              these addresses: Just calculate segment*16 + offset in
              order to get a "linear DOS" address.  So
              e.g. 0x0f04:0x3628 results in 0xf040 + 0x3628 = 0x12668.
              And the highest address you can get is 0xfffff (1MB), of
              course.  In Wine, this "linear DOS" address of 0x12668
              has to be added to the linear base address of the
              corresponding DOS memory allocated for dosmod in order
              to get the true linear address of a DOS seg:offs
              address.  And make sure that you're doing this in the
              correct process with the correct linear address space,
              of course ;-)
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect1>

950
    <sect1 id="dbg-config">
John R. Sheets's avatar
John R. Sheets committed
951
      <title>Configuration</title>
952 953

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
954
        <title>Registry configuration</title>
955 956 957

        <para>
          The Windows' debugging API uses a registry entry to know
John R. Sheets's avatar
John R. Sheets committed
958 959 960 961
          which debugger to invoke when an unhandled exception occurs
          (see <link endterm="dbg-exception-title"
          linkend="dbg-on-exception"></link> for some details). Two
          values in key
962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978
        </para>
        <programlisting>
"MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
        </programlisting>
        <para>
          Determine the behavior:
        </para>
        <variablelist>
          <varlistentry>
            <term>Debugger:</term>
            <listitem>
              <para>
                this is the command line used to launch the debugger
                (it uses two <function>printf</function> formats
                (<literal>%ld</literal>) to pass context dependent
                information to  the debugger). You should put here a
                complete path to your debugger
979
                (<command>winedbg</command> can of course be used, but
980 981
                any other Windows' debugging API aware debugger will
                do).
John R. Sheets's avatar
John R. Sheets committed
982 983
		The path to the debugger you chose to use must be reachable
		via a DOS drive in the Wine config file !
984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>Auto:</term>
            <listitem>
              <para>
                if this value is zero, a message box will ask the
                user if he/she wishes to launch the debugger when an
                unhandled exception occurs. Otherwise, the debugger
                is automatically started.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>
          A regular Wine registry looks like:
        </para>
        <programlisting>
[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
"Auto"=dword:00000001
1006
"Debugger"="winedbg %ld %ld"
1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018
        </programlisting>

        <note>
          <title>Note 1</title>
          <para>
            creating this key is mandatory. Not doing so will not
            fire the debugger when an exception occurs.
          </para>
        </note>
        <note>
          <title>Note 2</title>
          <para>
1019 1020
            <command>wineinstall</command> (available in Wine source)
	    sets up this correctly.
1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035
            However, due to some limitation of the registry installed,
            if a previous Wine installation exists, it's safer to
            remove the whole
          </para>
          <programlisting>
[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
          </programlisting>
          <para>
            key before running again <command>wineinstall</command> to
            regenerate this key.
          </para>
        </note>
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
1036
        <title>WineDbg configuration</title>
1037 1038

        <para>
1039
          <command>winedbg</command> can be configured through a number
1040
          of options. Those options are stored in the registry, on a
John R. Sheets's avatar
John R. Sheets committed
1041
          per user basis. The key is (in <emphasis>my</emphasis> registry)
1042 1043 1044 1045 1046 1047
        </para>
        <programlisting>
[eric\\Software\\Wine\\WineDbg]
        </programlisting>
        <para>
          Those options can be read/written while inside
1048
          <command>winedbg</command>, as part of the debugger
John R. Sheets's avatar
John R. Sheets committed
1049
          expressions. To refer to one of these options, its name must
1050
          be  prefixed by a <literal>$</literal> sign. For example,
1051 1052 1053 1054 1055 1056 1057 1058 1059 1060
        </para>
        <programlisting>
set $BreakAllThreadsStartup = 1
        </programlisting>
        <para>
          sets the option <varname>BreakAllThreadsStartup</varname> to
          <literal>TRUE</literal>.
        </para>
        <para>
          All the options are read from the registry when
1061
          <command>winedbg</command> starts (if no corresponding value
1062
          is found, a default value is used), and are written back to
1063
          the registry when <command>winedbg</command> exits (hence,
1064
          all modifications to those options are automatically saved
1065
          when <command>winedbg</command> terminates).
1066 1067 1068 1069 1070
        </para>
        <para>
          Here's the list of all options:
        </para>

1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150
	<variablelist>
	  <varlistentry>
	    <term><varname>BreakAllThreadsStartup</varname></term>
	    <listitem>
	      <para>
		Set to <literal>TRUE</literal> if at all threads
		start-up the debugger stops  set to
		<literal>FALSE</literal> if only at the first thread
		startup of a given process the debugger
		stops. <literal>FALSE</literal> by default.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><varname>BreakOnCritSectTimeOut</varname></term>
	    <listitem>
	      <para>
		Set to <literal>TRUE</literal> if the debugger stops
		when a critical section times out (5 minutes);
		<literal>TRUE</literal> by default.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><varname>BreakOnAttach</varname></term>
	    <listitem>
	      <para>
		Set to <literal>TRUE</literal> if when
		<command>winedbg</command> attaches to an existing
		process after an unhandled exception,
		<command>winedbg</command> shall be entered on the
		first attach event. Since the attach event is
		meaningless in the context of an exception event (the
		next event  which is the exception event is of course
		relevant), that option is likely to be
		<literal>FALSE</literal>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><varname>BreakOnFirstChance</varname></term>
	    <listitem>
	      <para>
		An exception can generate two debug events. The first
		one is passed to the debugger (known as a first
		chance) just after the exception. The debugger can
		then decide either to resume execution (see
		<command>winedbg</command>'s <command>cont</command>
		command) or pass the exception up to the exception
		handler chain in the program (if it exists)
		(<command>winedbg</command> implements this through
		the <command>pass</command> command). If none of the
		exception handlers takes care of the exception, the
		exception event is sent again to the debugger (known
		as last chance exception). You cannot pass on a last
		exception. When the
		<varname>BreakOnFirstChance</varname> exception is
		<literal>TRUE</literal>, then winedbg is entered for
		both first and last chance execptions (to
		<literal>FALSE</literal>, it's only entered for last
		chance exceptions).
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><varname>AlwaysShowThunk</varname></term>
	    <listitem>
	      <para>
		Set to <literal>TRUE</literal> if the debugger, when
		looking up for a symbol from its name, displays all
		the thunks with that name. The default value
		(<literal>FALSE</literal>) allows not to have to
		choose between a symbol and all the import thunks
		from all the DLLs using that symbols.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>
    </sect1>
1151

1152 1153 1154 1155
    <sect1 id="dbg-expr">
      <title>WineDbg Expressions and Variables</title>
      <sect2>
	<title>Expressions</title>
1156

1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190
	<para>
	  Expressions in Wine Debugger are mostly written in a C
	  form. However, there are a few discrepancies:
	  <itemizedlist>
	    <listitem>
	      <para>
		Identifiers can take a '!' in their names. This allow
		mainly to access symbols from different DLLs like
		<function>USER32!CreateWindowExA</function>.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
	        In cast operation, when specifying a structure or an
		union, you must use the <type>struct</type> or
		<type>union</type> keyword (even if your program uses a typedef). 
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>
	<para>
	  When specifying an identifier by its name, if several
	  symbols with the same name exist, the debugger will prompt
	  for the symbol you want to use. Pick up the one you want
	  from its number.
	</para>
	<para>
	  In lots of cases, you can also use regular expressions for
	  looking for a symbol.
	</para>
	<para>
	  <command>winedbg</command> defines its own set of
	  variables. The configuration variables from above are part
	  of them. Some others include:
1191 1192
          <variablelist>
            <varlistentry>
1193
              <term><varname>$ThreadId</varname></term>
1194
              <listitem>
1195 1196 1197 1198
                <para>
                  ID of the <varname>W-thread</varname> currently
                  examined by the debugger
                </para>
1199 1200 1201
              </listitem>
            </varlistentry>
            <varlistentry>
1202
              <term><varname>$ProcessId</varname></term>
1203
              <listitem>
1204 1205 1206 1207
                <para>
                  ID of the <varname>W-thread</varname> currently
                  examined by the debugger
                </para>
1208 1209 1210 1211 1212
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>&lt;registers></term>
              <listitem>
1213
                <para>
1214 1215 1216
                  All CPU registers are also available, using $ as a
		  prefix. You can use <command>info regs</command> to
		  get a list of avaible CPU registers
1217
                </para>
1218 1219 1220
              </listitem>
            </varlistentry>
          </variablelist>
1221 1222 1223 1224 1225 1226
	</para>
	<para>
	  The <varname>$ThreadId</varname> and
	  <varname>$ProcessId</varname> variables can be handy to set
	  conditional breakpoints on a given thread or process.
	</para>
1227 1228 1229 1230
      </sect2>
    </sect1>

    <sect1 id="dbg-commands">
John R. Sheets's avatar
John R. Sheets committed
1231
      <title>WineDbg Command Reference</title>
1232 1233

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
1234
        <title>Misc</title>
1235

1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273
	<para>
	  <table>
	    <title>WineDbg's misc. commands</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry><command>abort</command></entry>
		  <entry>aborts the debugger</entry>
		</row>
		<row>
		  <entry><command>quit</command></entry>
		  <entry>exits the debugger</entry>
		</row>
		<row>
		  <entry><command>attach&nbsp;N</command></entry>
		  <entry>
		    attach to a W-process (N is its ID, numeric
		    or hexadecimal (0xN)). IDs can be obtained using
		    the info process command. Note the info process
		    command returns hexadecimal values.
		  </entry>
		</row>
		<row>
		  <entry><command>detach</command></entry>
		  <entry>detach from a W-process.</entry>
		</row>
		<row>
		  <entry><command>help</command></entry>
		  <entry>prints some help on the commands</entry>
		</row>
		<row>
		  <entry><command>help info</command></entry>
		  <entry>prints some help on info commands</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>
1274 1275 1276
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
1277
        <title>Flow control</title>
1278

1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371
	<para>
	  <table>
	    <title>WineDbg's flow control commands</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry>
		    <msgtext>
		      <simplelist type="inline">
			<member><command>cont</command></member>
			<member><command>c</command></member>
		      </simplelist>
		    </msgtext>
		  </entry>
		  <entry>continue execution until next breakpoint or
		    exception.</entry>
		</row>
		<row>
		  <entry><command>pass</command></entry>
		  <entry>pass the exception event up to the filter
		    chain.</entry>
		</row>
		<row>
		  <entry>
		    <msgtext>
		      <simplelist type="inline">
			<member><command>step</command></member>
			<member><command>s</command></member>
		      </simplelist>
		    </msgtext>
		  </entry>
		  <entry>
		    continue execution until next 'C' line of code
		    (enters function call)
		  </entry>
		</row>
		<row>
		  <entry>
		    <msgtext>
		      <simplelist type="inline">
			<member><command>next</command></member>
			<member><command>n</command></member>
		      </simplelist>
		    </msgtext>
		  </entry>
		  <entry>
		    continue execution until next 'C' line of code
		    (doesn't enter function call)
		  </entry>
		</row>
		<row>
		  <entry>
		    <msgtext>
		      <simplelist type="inline">
			<member><command>stepi</command></member>
			<member><command>si</command></member>
		      </simplelist>
		    </msgtext>
		  </entry>
		  <entry>
		    execute next assembly instruction (enters function
		    call)
		  </entry>
		</row>
		<row>
		  <entry>
		    <msgtext>
		      <simplelist type="inline">
			<member><command>nexti</command></member>
			<member><command>ni</command></member>
		      </simplelist>
		    </msgtext>
		  </entry>
		  <entry>
		    execute next assembly instruction (doesn't enter
		    function call)
		  </entry>
		</row>
		<row>
		  <entry>
		    <msgtext>
		      <simplelist type="inline">
			<member><command>finish</command></member>
			<member><command>f</command></member>
		      </simplelist>
		    </msgtext>
		  </entry>
		  <entry>execute until current function is exited</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>
1372
        <para>
1373 1374 1375 1376
          <command>cont</command>, <command>step</command>,
	  <command>next</command>, <command>stepi</command>,
	  <command>nexti</command> can be postfixed by a number (N),
	  meaning that the command must be executed N times. 
1377 1378 1379 1380
        </para>
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
1381
        <title>Breakpoints, watch points</title>
1382

1383
	<para>
1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470
	  <table>
	    <title>WineDbg's break & watch points</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry><command>enable&nbsp;N</command></entry>
		  <entry>enables (break|watch)point #N</entry>
		</row>
		<row>
		  <entry><command>disable&nbsp;N</command></entry>
		  <entry>disables (break|watch)point #N</entry>
		</row>
		<row>
		  <entry><command>delete&nbsp;N</command></entry>
		  <entry>deletes (break|watch)point #N</entry>
		</row>
		<row>
		  <entry><command>cond&nbsp;N</command></entry>
		  <entry>
		    removes any existing condition to
		    (break|watch)point N
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>cond&nbsp;N &lt;expr&gt;</command>
		  </entry>
		  <entry>
		    adds condition &lt;expr&gt; to (break|watch)point
		    N. &lt;expr&gt; will be evaluated each time the
		    breakpoint is hit. If the result is a zero value,
		    the breakpoint isn't triggered
		  </entry>
		</row>
		<row>
		  <entry><command>break&nbsp;*&nbsp;N</command></entry>
		  <entry>adds a breakpoint at address N</entry>
		</row>
		<row>
		  <entry><command>break &lt;id&gt;</command></entry>
		  <entry>
		    adds a breakpoint at the address of symbol
		    &lt;id&gt;
		  </entry>
		</row>
		<row>
		  <entry><command>break &lt;id&gt;&nbsp;N</command></entry>
		  <entry>
		    adds a breakpoint at the address of symbol
		    &lt;id&gt; (N ?)
		  </entry>
		</row>
		<row>
		  <entry><command>break&nbsp;N</command></entry>
		  <entry>
		    adds a breakpoint at line N of current source file
		  </entry>
		</row>
		<row>
		  <entry><command>break</command></entry>
		  <entry>
		    adds a breakpoint at current $PC address
		  </entry>
		</row>
		<row>
		  <entry><command>watch&nbsp;*&nbsp;N</command></entry>
		  <entry>
		    adds a watch command (on write) at address N (on 4
		    bytes)
		  </entry>
		</row>
		<row>
		  <entry><command>watch &lt;id&gt;</command></entry>
		  <entry>
		    adds a watch command (on write) at the address of
		    symbol &lt;id&gt;
		  </entry>
		</row>
		<row>
		  <entry><command>info break</command></entry>
		  <entry>
		    lists all (break|watch)points (with state)
		  </entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
1471
	</para>
1472
        <para>
1473
          You can use the symbol <emphasis>EntryPoint</emphasis> to stand for
1474 1475
          the entry point of the Dll.
        </para>
1476
	<para>
1477 1478 1479 1480 1481
          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 recall the name of
	  the symbol and will try to set the breakpoint each time a
	  new module is loaded (until it succeeds). 
1482
        </para>
1483 1484 1485
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
1486
        <title>Stack manipulation</title>
1487

1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547
	<para>
	  <table>
	    <title>WineDbg's stack manipulation</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry><command>bt</command></entry>
		  <entry>print calling stack of current thread</entry>
		</row>
		<row>
		  <entry><command>bt&nbsp;N</command></entry>
		  <entry>
		    print calling stack of thread of ID N (note: this
		    doesn't change the position of the current frame
		    as manipulated by the <command>up</command> and
		    <command>dn</command> commands)
		  </entry>
		</row>
		<row>
		  <entry><command>up</command></entry>
		  <entry>
		    goes up one frame in current thread's stack
		  </entry> 
		</row>
		<row>
		  <entry><command>up&nbsp;N</command></entry>
		  <entry>
		    goes up N frames in current thread's stack
		  </entry>
		</row>
		<row>
		  <entry><command>dn</command></entry>
		  <entry>
		    goes down one frame in current thread's stack
		  </entry>
		</row>
		<row>
		  <entry><command>dn&nbsp;N</command></entry>
		  <entry>
		    goes down N frames in current thread's stack
		  </entry>
		</row>
		<row>
		  <entry><command>frame&nbsp;N</command></entry>
		  <entry>
		    set N as the current frame for current thread's
		    stack
		  </entry>
		</row>
		<row>
		  <entry><command>info&nbsp;local</command></entry>
		  <entry>
		    prints information on local variables for current
		    function frame
		  </entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>
1548 1549 1550
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
1551
        <title>Directory & source file manipulation</title>
1552

1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643
	<para>
	  <table>
	    <title>WineDbg's directory & source file manipulation</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry><command>show&nbsp;dir</command></entry>
		  <entry>
		    prints the list of dir:s where source files are
		    looked for
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>dir&nbsp;&lt;pathname&gt;</command>
		  </entry>
		  <entry>
		    adds &lt;pathname&gt; to the list of dir:s
		    where to look for source files
		  </entry>
		</row>
		<row>
		  <entry><command>dir</command></entry>
		  <entry>
		    deletes the list of dir:s where to look for source
		    files
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>
		      symbolfile&nbsp;&lt;pathname&gt;
		    </command>
		  </entry>
		  <entry>loads external symbol definition</entry>
		</row>
		<row>
		  <entry>
		    <command>
		      symbolfile&nbsp;&lt;pathname&gt;&nbsp;N
		    </command>
		  </entry>
		  <entry>
		    loads external symbol definition (applying an
		    offset of N to addresses)
		  </entry>
		</row>
		<row>
		  <entry><command>list</command></entry>
		  <entry>
		    lists 10 source lines forwards from current
		    position
		  </entry>
		</row>
		<row>
		  <entry><command>list&nbsp;-</command></entry>
		  <entry>
		    lists 10 source lines backwards from current
		    position
		  </entry>
		</row>
		<row>
		  <entry><command>list&nbsp;N</command></entry>
		  <entry>
		    lists 10 source lines from line N in current file
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>list&nbsp;&lt;path&gt;:N</command>
		  </entry>
		  <entry>
		    lists 10 source lines from line N in file
		    &lt;path&gt;
		  </entry>
		</row>
		<row>
		  <entry><command>list &lt;id&gt;</command></entry>
		  <entry>
		    lists 10 source lines of function &lt;id&gt;
		  </entry>
		</row>
		<row>
		  <entry><command>list&nbsp;*&nbsp;N</command></entry>
		  <entry>lists 10 source lines from address N</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>

1644 1645 1646
        <para>
          You can specify the end target (to change the 10 lines
          value) using the ','. For example:
1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668
	  <table>
	    <title>WineDbg's list command examples</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry><command>list 123, 234</command></entry>
		  <entry>
		    lists source lines from line 123 up to line 234 in
		    current file
		  </entry>
		</row>
		<row>
		  <entry><command>list foo.c:1,&nbsp;56</command></entry>
		  <entry>
		    lists source lines from line 1 up to 56 in file
		    foo.c
		  </entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>
1669 1670 1671
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
1672
        <title>Displaying</title>
1673 1674 1675

        <para>
          A display is an expression that's evaluated and printed
1676
          after the execution of any <command>winedbg</command>
1677 1678
          command.
        </para>
1679 1680 1681 1682 1683 1684 1685
	<para>
	  <table>
	    <title>WineDbg's displays</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry>
1686
		    <command>info&nbsp;display</command>
1687 1688 1689
		  </entry>
		  <entry>lists the active displays</entry>
		</row>
1690 1691 1692 1693 1694 1695 1696 1697 1698
		<row>
		  <entry>
		    <command>display</command>
		  </entry>
		  <entry>
		    print the active displays' values (as done each
		    time the debugger stops)
		  </entry>
		</row>
1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739
		<row>
		  <entry>
		    <command>display&nbsp;&lt;expr&gt;</command>
		  </entry>
		  <entry>
		    adds a display for expression &lt;expr&gt;
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>
		      display&nbsp;/fmt&nbsp;&lt;expr&gt;
		    </command>
		  </entry>
		  <entry>
		    adds a display for expression
		    &lt;expr&gt;. Printing evaluated &lt;expr&gt; is
		    done using the given format (see
		    <command>print</command> command for more on
		    formats)
		  </entry> 
		</row>
		<row>
		  <entry>
		    <msgtext>
		      <simplelist type="inline">
			<member>
			  <command>del&nbsp;display&nbsp;N</command>
			</member>
			<member>
			  <command>undisplay&nbsp;N</command>
			</member>
		      </simplelist>
		    </msgtext>
		  </entry>
		  <entry>deletes display #N</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>
1740 1741 1742
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
1743
        <title>Disassembly</title>
1744

1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776
	<para>
	  <table>
	    <title>WineDbg's dissassembly</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry><command>disas</command></entry>
		  <entry>disassemble from current position</entry>
		</row>
		<row>
		  <entry>
		    <command>disas&nbsp;&lt;expr&gt;</command>
		  </entry>
		  <entry>
		    disassemble from address &lt;expr&gt;
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>
		      disas&nbsp;&lt;expr&gt;,&lt;expr&gt;
		    </command>
		  </entry>
		  <entry>
		    disassembles code between addresses specified by
		    the two &lt;expr&gt;
		  </entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>
1777 1778 1779
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
1780
        <title>Memory (reading, writing, typing)</title>
1781

1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850
	<para>
	  <table>
	    <title>WineDbg's memory management</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry>
		    <command>x&nbsp;&lt;expr&gt;</command>
		  </entry>
		  <entry>
		    examines memory at &lt;expr&gt; address
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>
		      x&nbsp;/fmt&nbsp;&lt;expr&gt;
		    </command>
		  </entry>
		  <entry>
		    examines memory at &lt;expr&gt; address using
		    format /fmt
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>
		      print&nbsp;&lt;expr&gt;
		    </command>
		  </entry>
		  <entry>
		    prints the value of &lt;expr&gt; (possibly using
		    its type)
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>
		      print&nbsp;/fmt&nbsp;&lt;expr&gt;
		    </command>
		  </entry>
		  <entry>prints the value of &lt;expr&gt; (possibly
		    using its type)
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>
		      set&nbsp;&lt;lval&gt;&nbsp;=&nbsp;&lt;expr&gt;
		    </command>
		  </entry>
		  <entry>
		    writes the value of &lt;expr&gt; in &lt;lval&gt;
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>
		      whatis&nbsp;&lt;expr&gt;
		    </command>
		  </entry>
		  <entry>
		    prints the C type of expression &lt;expr&gt;
		  </entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>
1851 1852
        <para>
          <filename>/fmt</filename> is either <filename>/&lt;letter&gt;</filename> or
1853
          <filename>/&lt;count&gt;&lt;letter&gt;</filename> letter can be
1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865
	  <simplelist type="horiz" columns="2">
	    <member>s</member><member>an ASCII string</member>
	    <member>u</member><member>an Unicode UTF16 string</member>
	    <member>i</member><member>instructions (disassemble)</member>
	    <member>x</member><member>32 bit unsigned hexadecimal integer</member>
	    <member>d</member><member>32 bit signed decimal integer</member>
	    <member>w</member><member>16 bit unsigned hexadecimal integer</member>
	    <member>c</member><member>character (only printable 0x20-0x7f are actually printed)</member>
	    <member>b</member><member>8 bit unsigned hexadecimal integer</member>
	    <member>g</member><member>GUID</member>
	  </simplelist>
	</para>
1866
      </sect2>
1867 1868

      <sect2>
1869
        <title>Information on Wine's internals</title>
1870

1871
	<para>
1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989
	  <table>
	    <title>WineDbg's Win32 objects management</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry><command>info&nbsp;class</command></entry>
		  <entry>
		    lists all Windows' classes registered in Wine
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>
		      info&nbsp;class&nbsp;&lt;id&gt;
		    </command>
		  </entry>
		  <entry>
		    prints information on Windows's class &lt;id&gt;
		  </entry>
		</row>
		<row>
		  <entry><command>info&nbsp;share;</command></entry>
		  <entry>
		    lists all the dynamic libraries loaded in the
		    debugged program (including .so files, NE and PE
		    DLLs)
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>
		      info&nbsp;share&nbsp;&lt;N&gt;;
		    </command>
		  </entry>
		  <entry>
		    prints information on module at address &lt;N&gt;
		  </entry>
		</row>
		<row>
		  <entry><command>info regs;</command></entry>
		  <entry>
		    prints the value of the CPU registers
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>info segment &lt;N&gt;;</command>
		  </entry>
		  <entry>
		    prints information on segment &lt;N&gt; (i386
		    only)
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>info&nbsp;segment;</command>
		  </entry>
		  <entry>
		    lists all allocated segments (i386 only)
		  </entry>
		</row>
		<row>
		  <entry><command>info&nbsp;stack;</command></entry>
		  <entry>
		    prints the values on top of the stack
		  </entry>
		</row>
		<row>
		  <entry><command>info&nbsp;map;</command></entry>
		  <entry>
		    lists all virtual mappings used by the debugged
		    program
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>info&nbsp;map&nbsp;&lt;N&gt;</command>
		  </entry>
		  <entry>
		    lists all virtual mappings used by the program of
		    pid &lt;N&gt;
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>info&nbsp;wnd&nbsp;&lt;N&gt;</command>
		  </entry>
		  <entry>
		    prints information of Window of handle &lt;N&gt;
		  </entry>
		</row>
		<row>
		  <entry><command>info&nbsp;wnd</command></entry>
		  <entry>
		    lists all the window hierarchy starting from the
		    desktop window
		  </entry>
		</row>
		<row>
		  <entry><command>info process</command></entry>
		  <entry>
		    lists all w-processes in Wine session
		  </entry>
		</row>
		<row>
		  <entry><command>info&nbsp;thread</command></entry>
		  <entry>lists all w-threads in Wine session</entry>
		</row>
		<row>
		  <entry><command>info&nbsp;exception</command></entry>
		  <entry>
		    lists the exception frames (starting from current
		    stack frame)
		  </entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
1990 1991
	</para>
      </sect2>
1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038

      <sect2 id="winedbg-dbg-chan">
	<title>Debug channels</title>
	<para>
	  It is possible to turn on and off debug messages as you
	  are debugging using the set command.
	  See <xref linkend="debugging"> for more details on debug
	  channels.
	</para>

	<para>
	  <table>
	    <title>WineDbg's debug channels' management</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry>
		    <command>set&nbsp;+&nbsp;warn&nbsp;win</command>
		  </entry>
		  <entry>turn on warn on 'win' channel</entry>	
		</row>
		<row>
		  <entry>
		    <command>set&nbsp;+&nbsp;win</command>
		  </entry>
		  <entry>
		    turn on warn/fixme/err/trace on 'win' channel
		  </entry> 
		</row>
		<row>
		  <entry>
		    <command>set&nbsp;-&nbsp;win</command>
		  </entry>
		  <entry>
		    turn off warn/fixme/err/trace on 'win' channel
		  </entry>
		</row>
		<row>
		  <entry>
		    <command>set&nbsp;-&nbsp;fixme</command>
		  </entry>
		  <entry>turn off the 'fixme' class</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>
2039
      </sect2>
2040

2041 2042 2043
    </sect1>

    <sect1 id="dbg-others">
John R. Sheets's avatar
John R. Sheets committed
2044
      <title>Other debuggers</title>
2045

2046 2047 2048 2049 2050 2051 2052 2053 2054
      <sect2>
        <title>GDB mode</title>

        <para>
	  WineDbg can act as a remote monitor for GDB. This allows to
	  use all the power of GDB, but while debugging wine and/or
	  any Win32 application. To enable this mode, just add
	  <parameter>--gdb</parameter> to winedbg command line. You'll
	  end up on a GDB prompt. You'll have to use the GDB commands
2055
	  (not WineDbg's).
2056 2057 2058 2059
	</para>

	<para>
	  However, some limitation in GDB while debugging wine (see
Tom Wickline's avatar
Tom Wickline committed
2060
	  below) don't appear in this mode:
2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078
	  <itemizedlist>
	    <listitem>
	      <para>
		GDB will correctly present Win32 thread
		information and breakpoint behavior
	      </para> 
	    </listitem>
	    <listitem>
	      <para>
		Moreover, it also provides support for the Dwarf II
		debug format (which became the default format (instead
		of stabs) in gcc 3.1). 
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>

	<para>
2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102
	  A few Wine extensions available through the monitor command.
	  <table>
	    <title>WineDbg's debug channels' management</title>
	    <tgroup cols="2" align="left">
	      <tbody>
		<row>
		  <entry><command>monitor&nbsp;wnd</command></entry>
		  <entry>lists all window in the Wine session</entry>
		</row>
		<row>
		  <entry><command>monitor&nbsp;proc</command></entry>
		  <entry>
		    lists all processes in the Wine session
		  </entry>
		</row>
		<row>
		  <entry><command>monitor&nbsp;mem</command></entry>
		  <entry>
		    displays memory mapping of debugged process
		  </entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
2103 2104 2105
	</para>
      </sect2>

2106 2107 2108 2109
      <sect2>
	<title>Graphical frontends to gdb</title>

	<para>
2110
          This section will describe how you can debug Wine using the
2111 2112 2113 2114 2115 2116 2117 2118 2119
          GDB mode of winedbg and some graphical front ends to GDB for
          those of you who really like graphical debuggers.
        </para>

	<sect3>
	  <title>DDD</title>
	  
	  <para>
            Use the following steps, in this order:
2120
	    <orderedlist>
2121 2122
	      <listitem>
		<para>
2123
		  Start the Wine debugger with a command line like:
2124
<screen>
2125
	winedbg --gdb --no-start &lt;name_of_exe_to_debug.exe&gt;
2126
</screen>
2127
		</para>
2128 2129
	      </listitem>
	      <listitem>
2130 2131 2132
		<para>
                  Start ddd
                </para>
2133 2134
	      </listitem>
	      <listitem>
2135 2136
		<para>
		  In ddd, use the 'Open File' or 'Open Program' to
2137 2138 2139
                  point to the Wine executable (which is either
		  wine-pthread or wine-kthread depending on your
		  settings).
2140
		</para>
2141 2142
	      </listitem>
	      <listitem>
2143
		<para>
2144
		  In the output of 1/, there's a line like 
2145 2146 2147
<screen>
	target remote localhost:32878
</screen>
2148 2149 2150
		  copy that line and paste into ddd command pane (the
		  one with the (gdb) prompt)
		</para>
2151 2152
	      </listitem>
	    </orderedlist>
2153 2154 2155
	    The program should now be loaded and up and running. If
	    you want, you can also add in 1/ after the name of the
	    exec all the needed parameters
2156 2157 2158 2159 2160 2161 2162 2163 2164 2165
          </para>
	</sect3>
	<sect3>
	  <title>kdbg</title>
	  
	  <para>
            Use the following steps, in this order:
            <orderedlist>
	      <listitem>
		<para>
2166
                  Start the Wine debugger with a command line like:
2167
<screen>
2168
	winedbg --gdb --no-start &lt;name_of_exe_to_debug.exe&gt;
2169 2170 2171 2172
</screen>
</para>
	      </listitem>
	      <listitem>
2173 2174
		<para>
		  In the output of 1/, there's a line like 
2175 2176 2177
<screen>
	target remote localhost:32878
</screen>
2178
		  Start kdbg with
2179 2180 2181
<screen>
kdbg -r localhost:32878 wine
</screen>
2182 2183 2184 2185 2186
		  localhost:32878 is not a fixed value, but has been
		  printed in step 1/. 'wine' should also be the full
		  path to the Wine executable (which is either
		  wine-pthread or wine-kthread depending on your settings).
		</para>
2187 2188
	      </listitem>
	    </orderedlist>
2189 2190 2191
	    The program should now be loaded and up and running. If
	    you want, you can also add in 1/ after the name of the
	    exec all the needed parameters
2192 2193 2194 2195
          </para>
	</sect3>
      </sect2>
	
2196
      <sect2>
John R. Sheets's avatar
John R. Sheets committed
2197
        <title>Using other Unix debuggers</title>
2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211

        <para>
          You can also use other debuggers (like
          <command>gdb</command>), but you must be aware of a few
          items:
        </para>
        <para>
          You need to attach the unix debugger to the correct unix
          process (representing the correct windows thread) (you can
          "guess" it from a <command>ps fax</command> for example:
          When running the emulator, usually the first two
          <varname>upids</varname> are for the Windows' application
          running the desktop, the first thread of the application is
          generally the third <varname>upid</varname>; when running a
John R. Sheets's avatar
John R. Sheets committed
2212
          Winelib program, the first thread of the application is
2213 2214 2215 2216 2217 2218 2219
          generally the first <varname>upid</varname>)
        </para>
        <note>
          <para>
            Even if latest <command>gdb</command> implements the
            notion of threads, it won't work with Wine because the
            thread abstraction used for implementing Windows' thread
2220
            is not 100% mapped onto the Linux POSIX threads
2221 2222 2223 2224 2225
            implementation. It means that you'll have to spawn a
            different <command>gdb</command> session for each Windows'
            thread you wish to debug.
          </para>
        </note>
John R. Sheets's avatar
John R. Sheets committed
2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283

        <para>
          Here's how to get info about the current execution status of a
          certain Wine process:
        </para>
        <para>
          Change into your Wine source dir and enter:
        </para>
        <screen>
$ gdb wine
        </screen>
        <para>
          Switch to another console and enter <command>ps ax | grep
            wine</command> to find all wine processes. Inside
          <command>gdb</command>, repeat for all Wine processes:
        </para>
        <screen>
(gdb) attach <userinput>PID</userinput>
        </screen>
        <para>
          with <userinput>PID</userinput> being the process ID of one of
          the Wine processes.  Use
        </para>
        <screen>
(gdb) bt
        </screen>
        <para>
          to get the backtrace of the current Wine process, i.e. the
          function call history.  That way you can find out what the
          current process is doing right now.  And then you can use
          several times:
        </para>
        <screen>
(gdb) n
        </screen>
        <para>
          or maybe even
        </para>
        <screen>
(gdb) b <userinput>SomeFunction</userinput>
        </screen>
        <para>
          and
        </para>
        <screen>
(gdb) c
        </screen>
        <para>
          to set a breakpoint at a certain function and continue up to
          that function.  Finally you can enter
        </para>
        <screen>
(gdb) detach
        </screen>
        <para>
          to detach from the Wine process.
        </para>
        <!-- *** End of xtra content *** -->
2284 2285 2286
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
2287
        <title>Using other Windows debuggers</title>
2288 2289 2290 2291 2292 2293 2294 2295 2296 2297

        <para>
          You can use any Windows' debugging API compliant debugger
          with Wine. Some reports have been made of success with
          VisualStudio debugger (in remote mode, only the hub runs
          in Wine). GoVest fully runs in Wine.
        </para>
      </sect2>

      <sect2>
John R. Sheets's avatar
John R. Sheets committed
2298
        <title>Main differences between winedbg and regular Unix debuggers</title>
2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332
	<table><title>Debuggers comparison</title>
	  <tgroup cols=2 align="left">
	    <tbody>
	      <row>
		<entry>WineDbg</entry><entry>gdb</entry>
	      </row>
	      <row>
		<entry>
		  WineDbg debugs a Windows' process: the various
		  threads will be handled by the same WineDbg session,
		  and a breakpoint will be triggered for any thread of
		  the W-process 
                </entry>
	        <entry>
		  gdb debugs a Windows' thread: a separate gdb session
		  is needed for each thread of a Windows' process and
		  a breakpoint will be triggered only for the w-thread
		  debugged 
                </entry>
	      </row>
	      <row>
		<entry>
		  WineDbg supports debug information from stabs
		  (standard Unix format) and Microsoft's C, CodeView,
		  .DBG
                </entry>
		<entry>
		  GDB supports debug information from stabs (standard
		  Unix format) and Dwarf II.
                </entry>
	      </row>
            </tbody>
          </tgroup>
        </table>
2333 2334 2335
      </sect2>
    </sect1>

John R. Sheets's avatar
John R. Sheets committed
2336

2337
    <sect1 id="dbg-limits">
John R. Sheets's avatar
John R. Sheets committed
2338
      <title>Limitations</title>
2339

2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352
      <itemizedlist>
	<listitem>
	  <para>
	    16 bit processes are not supported (but calls to 16 bit
	    code in 32 bit  applications are).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Function call in expression is no longer supported
	  </para>
	</listitem>
      </itemizedlist>
2353 2354 2355 2356 2357 2358
    </sect1>
  </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
2359
sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
2360 2361
End:
-->