WineHQ

Wine Developer's Guide: Difference between revisions

(add the wip banner.)
 
(43 intermediate revisions by 2 users not shown)
Line 1: Line 1:
__NUMBEREDHEADINGS__
__NOTOC__
== Debugging Wine ==
{{wip}}
== Table of Contents ==
=== I. Developing Wine ===
#[[Building Wine|Building Wine]]
#[[Wine User's Guide|Running Wine]]
#[[Wine Developer's Guide/Debugging Wine|Debugging Wine]]
#[[Wine Developer's Guide/Debug Logging|Debug Logging]]
#[[Wine Developer's Guide/Other Debugging Techniques|Other Debugging Techniques]]
#[[Wine Developer's Guide/Coding Practice|Coding Practice]]
#[[Wine_Developer's_Guide/Writing_Conformance_Tests|Writing Conformance Tests]]
#[[Submitting Patches|Submitting Patches]]
#[[Wine Developer's Guide/Documenting Wine|Documenting Wine]]


=== Introduction ===
=== II. Wine Architecture ===
#[[Wine Developer's Guide/Architecture Overview|Overview]]
#[[Wine Developer's Guide/Kernel modules|Kernel modules]]
#[[Wine Developer's Guide/Windowing system|Windowing system]]
#[[Wine Developer's Guide/COM in Wine|COM in Wine]]
#[[Wine Developer's Guide/Wine and OpenGL|Wine and OpenGL]]
#[[Wine Developer's Guide/Outline of DirectDraw Architecture|Outline of DirectDraw Architecture]]
#[[Wine Developer's Guide/Wine and Multimedia|Wine and Multimedia]]


==== Processes and threads: in underlying OS and in Windows ====
=== III. Miscellaneous references ===
# [[Vim Tips|Tips for Vim users]]
#[[Wine and Valgrind|Running Wine under Valgrind]]
#[[List Of Windows Messages|A list of windows messages, by value]]
#[[Ternary Raster Ops|The format of a ternary raster operation code]]
#[http://books.google.com/books?id=-O92IIF1Bj4C Windows Graphics Programming: Win32 GDI and DirectDraw] by [http://www.fengyuan.com Feng Yuan] (Working at HP for Printer Drivers; Now at Microsoft for WPF and XPS)
#[[:Category:Development|All Development Wiki pages]]


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.
===List of Tables===
:[[Wine_Developer's_Guide/Debugging_Wine#1-1|1-1. WineDbg misc commands]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-2|1-2. WineDbg flow control commands]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-3|1-3. WineDbg break & watch points]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-4|1-4. WineDbg stack manipulation]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-5|1-5. WineDbg directory & source file manipulation]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-6|1-6. WineDbg list command examples]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-7|1-7. WineDbg displays]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-8|1-8. WineDbg disassembly]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-9|1-9. WineDbg memory management]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-10|1-10. WineDbg Win32 objects management]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-11|1-11. WineDbg debug channels management]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-12|1-12. WineDbg debug channels management]]
:[[Wine_Developer's_Guide/Debugging_Wine#1-13|1-13. Debuggers comparison]]
:[[Wine Developer's Guide/Architecture Overview#7-1|7-1. Wine executables]]
:[[Wine Developer's Guide/Architecture Overview#7-2|7-2. Memory layout (Windows and Wine)]]
:[[Wine_Developer's_Guide/Kernel_modules#8-1|8-1. DOS, Win32 and NT paths equivalences]]
:[[Wine_Developer's_Guide/Kernel_modules#8-2|8-2. File systems' properties]]
:[[Wine_Developer's_Guide/Kernel_modules#8-3|8-3. Mapping of Windows device names into Unix device names]]
:[[Wine_Developer's_Guide/Kernel_modules#8-4|8-4. Function consoles implementation comparison]]
:[[Wine_Developer's_Guide/Kernel_modules#8-5|8-5. Console registry settings]]
:[[Wine Developer's Guide/Wine and Multimedia#13-1|13-1. Wine MCI drivers]]
:[[Wine Developer's Guide/Wine and Multimedia#13-2|13-2. Wine ACM drivers]]
:[[Wine Developer's Guide/Wine and Multimedia#13-3|13-3. Wine VIDC drivers]]
:[[Wine Developer's Guide/Wine and Multimedia#13-4|13-4. Wine multimedia configuration scheme]]


Each Windows thread is implemented as a Unix thread, meaning that all threads of a same Windows process share the same (unix) address space.
== Authors ==
Uwe Bonnes; Jonathan Buzzard; Zoran Dzelajlija; Klaas van Gend; Francois Gouget; Jon Griffiths; Albert den Haan; Mike Hearn; André Hentschel; Ove Kaaven; Tony Lambregts; Marcus Meissner; Gerard Patel; Dimitrie Paun; Michele Petrovski; Eric Pouech; Douglas Ridgway; John Sheets; Lionel Ulmer; Ulrich Weigand; Morten Welinder; Jeremy White


In the following:


* <code>W-process</code> means a process in Windows terminology
[[Category:Documentation]] [[Category:Development]]
* <code>U-process</code> means a process in Unix terminology
* <code>W-thread</code> means a thread in Windows terminology
 
A <code>W-process</code> is made of one or several <code>W-threads</code>. Each <code>W-thread</code> is mapped to one and only one <code>U-process</code>. All <code>U-processes</code> of a same <code>W-process</code> share the same address space.
 
Each Unix process can be identified by two values:
 
* the Unix process id (<code>upid</code> in the following)
* the Windows thread id (<code>tid</code>)
 
Each Windows process has also a Windows process id (<code>wpid</code> in the following). It must be clear that <code>upid</code> and <code>wpid</code> are different and shall not be used instead of the other.
 
<code>Wpid</code> and <code>tid</code> are defined (Windows) system wide. They must not be confused with process or thread handles which, as any handle, are indirections to system objects (in this case processes or threads). 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 <code>W-process</code>).
 
==== Wine, debugging and WineDbg ====
 
When talking of debugging in Wine, there are at least two levels to think of:
 
* the Windows debugging API.
* the Wine integrated debugger, dubbed <b>winedbg</b>.
 
Wine implements most of the Windows debugging API. The first part of the debugging APIs (in <tt>KERNEL32.DLL</tt>) allows a W-process, called the debugger, to control the execution of another W-process, the debuggee. To control means stopping/resuming execution, enabling/disabling single stepping, setting breakpoints, reading/writing debuggee memory... Another part of the debugging APIs resides in <tt>DBGHELP.DLL</tt> (and its ancestor <tt>IMAGEHLP.DLL</tt>) and lets a debugger look into symbols and types from any module (if the module has been compiled with the proper options).
 
<b>winedbg</b> is a Winelib application making use of these APIs (<tt>KERNEL32.DLL</tt> debugging API and <tt> class=&quot;libraryfile&quot;DBGHELP.DLL</tt>) to allow debugging both any Wine or Winelib application as well as Wine itself (kernel and all DLLs).
 
=== WineDbg modes of invocation ===
 
==== Starting a process ====
 
Any application (either a Windows native executable, or a Winelib application) can be run through <b>winedbg</b>. Command line options and tricks are the same as for wine:
 
<pre>winedbg telnet.exe
winedbg hl.exe -windowed</pre>
 
==== Attaching ====
 
<b>winedbg</b> can also be launched without any command line argument: <b>winedbg</b> is started without any attached process. You can get a list of running <code>W-processes</code> (and their <code>wpid</code>) using the <b>info process</b> command, and then, with the <b>attach</b> command, pick up the <code>wpid</code> of the <code>W-process</code> you want to debug. This is a neat feature as it allows you to debug an already started application.
 
==== On exceptions ====
 
When something goes wrong, Windows tracks this as an exception. Exceptions exist for segmentation violation, stack overflow, division by zero, etc.
 
When an exception occurs, Wine checks if the <code>W-process</code> 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.
 
If the <code>W-process</code> is not debugged, Wine tries to launch a debugger. This debugger (normally <b>winedbg</b>, see III Configuration for more details), at startup, attaches to the <code>W-process</code> 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.
 
If <b>winedbg</b> is the standard debugger, the <b>pass</b> and <b>cont</b> commands are the two ways to let the process go further for the handling of the exception event.
 
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:
 
; <tt>continue</tt>
: the debugger had the ability to correct what's generated the exception, and is now able to continue process execution.
; <tt>pass</tt>
: 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.
 
<blockquote style="font-size:100%">'''Note''': since some of Wine code uses exceptions and <code>try/catch</code> blocks to provide some functionality, <b>winedbg</b> can be entered in such cases with segv exceptions. This happens, for example, with <code>IsBadReadPtr</code> function. In that case, the <b>pass</b> command shall be used, to let the handling of the exception to be done by the <code>catch</code> block in <code>IsBadReadPtr</code>.
</blockquote>
 
==== Interrupting ====
 
You can stop the debugger while it's running by hitting <b>Ctrl+C</b> in its window. This will stop the debugged process, and let you manipulate the current context.
 
==== Quitting ====
 
Wine supports the new XP APIs, allowing for a debugger to detach from a program being debugged (see <b>detach</b> command).
 
=== Using the Wine Debugger ===
 
This section describes where to start debugging Wine. If at any point you get stuck and want to ask for help, please read the ''How to Report A Bug'' section of the ''Wine Users Guide'' for information on how to write useful bug reports.
 
==== Crashes ====
 
These usually show up like this:
 
<pre>Unhandled exception: page fault on write access to 0x00000000 in 32-bit code (0x0043369e).
Register dump:
CS:0023 SS:002b DS:002b ES:002b FS:0063 GS:006b
EIP:0043369e ESP:0b3ee90c EBP:0b3ee938 EFLAGS:00010246(  R- --  I  Z- -P- )
EAX:00000072 EBX:7b8acff4 ECX:00000000 EDX:6f727265
ESI:7ba3b37c EDI:7ffa0000
Stack dump:
0x0b3ee90c:  7b82ced8 00000000 7ba3b348 7b884401
0x0b3ee91c:  7b883cdc 00000008 00000000 7bc36e7b
0x0b3ee92c:  7b8acff4 7b82ceb9 7b8acff4 0b3eea18
0x0b3ee93c:  7b82ce82 00000000 00000000 00000000
0x0b3ee94c:  00000000 0b3ee968 70d7ed7b 70c50000
0x0b3ee95c:  00000000 0b3eea40 7b87fd40 7b82d0d0
Backtrace:
=&gt;0 0x0043369e in elementclient (+0x3369e) (0x0b3ee938)
  1 0x7b82ce82 CONSOLE_SendEventThread+0xe1(pmt=0x0(nil)) [/usr/src/debug/wine-1.5.14/dlls/kernel32/console.c:1989] in kernel32 (0x0b3eea18)
  2 0x7bc76320 call_thread_func_wrapper+0xb() in ntdll (0x0b3eea28)
  3 0x7bc7916e call_thread_func+0x7d(entry=0x7b82cda0, arg=0x0(nil), frame=0xb3eeb18) [/usr/src/debug/wine-1.5.14/dlls/ntdll/signal_i386.c:2522] in ntdll (0x0b3eeaf8)
  4 0x7bc762fe RtlRaiseException+0x21() in ntdll (0x0b3eeb18)
  5 0x7bc7f3da start_thread+0xe9(info=0x7ffa0fb8) [/usr/src/debug/wine-1.5.14/dlls/ntdll/thread.c:408] in ntdll (0x0b3ef368)
  6 0xf7597adf start_thread+0xce() in libpthread.so.0 (0x0b3ef468)
0x0043369e: movl    %edx,0x0(%ecx)
Modules:
Module  Address        Debug info  Name (143 modules)
PE    340000-  3af000  Deferred        speedtreert
PE    3b0000-  3d6000  Deferred        ftdriver
PE    3e0000-  3e6000  Deferred        immwrapper
PE    400000-  b87000  Export          elementclient
PE    b90000-  e04000  Deferred        elementskill
PE    e10000-  e42000  Deferred        ifc22
PE  10000000-10016000  Deferred        zlibwapi
ELF 41f75000-41f7e000  Deferred        librt.so.1
ELF 41ff9000-42012000  Deferred        libresolv.so.2
PE  48080000-480a8000  Deferred        msls31
PE  65340000-653d2000  Deferred        oleaut32
PE  70200000-70294000  Deferred        wininet
PE  702b0000-70328000  Deferred        urlmon
PE  70440000-704cf000  Deferred        mlang
PE  70bd0000-70c34000  Deferred        shlwapi
PE  70c50000-70ef3000  Deferred        mshtml
PE  71930000-719b8000  Deferred        shdoclc
PE  78130000-781cb000  Deferred        msvcr80
ELF 79afb000-7b800000  Deferred        libnvidia-glcore.so.304.51
ELF 7b800000-7ba3d000  Dwarf          kernel32&lt;elf&gt;
  \-PE  7b810000-7ba3d000  \              kernel32
ELF 7bc00000-7bcd5000  Dwarf          ntdll&lt;elf&gt;
  \-PE  7bc10000-7bcd5000  \              ntdll
ELF 7bf00000-7bf04000  Deferred        &lt;wine-loader&gt;
ELF 7c288000-7c400000  Deferred        libvorbisenc.so.2
PE  7c420000-7c4a7000  Deferred        msvcp80
ELF 7c56d000-7c5b6000  Deferred        dinput&lt;elf&gt;
  \-PE  7c570000-7c5b6000  \              dinput
ELF 7c5b6000-7c600000  Deferred        libdbus-1.so.3
ELF 7c70e000-7c715000  Deferred        libasyncns.so.0
ELF 7c715000-7c77e000  Deferred        libsndfile.so.1
ELF 7c77e000-7c7e5000  Deferred        libpulsecommon-1.1.so
ELF 7c7e5000-7c890000  Deferred        krnl386.exe16.so
PE  7c7f0000-7c890000  Deferred        krnl386.exe16
ELF 7c890000-7c900000  Deferred        ieframe&lt;elf&gt;
  \-PE  7c8a0000-7c900000  \              ieframe
ELF 7ca00000-7ca1a000  Deferred        rasapi32&lt;elf&gt;
  \-PE  7ca10000-7ca1a000  \              rasapi32
ELF 7ca1a000-7ca21000  Deferred        libnss_dns.so.2
ELF 7ca21000-7ca25000  Deferred        libnss_mdns4_minimal.so.2
ELF 7ca25000-7ca2d000  Deferred        libogg.so.0
ELF 7ca2d000-7ca5a000  Deferred        libvorbis.so.0
ELF 7cd5d000-7cd9c000  Deferred        libflac.so.8
ELF 7cd9c000-7cdea000  Deferred        libpulse.so.0
ELF 7cdfe000-7ce23000  Deferred        iphlpapi&lt;elf&gt;
  \-PE  7ce00000-7ce23000  \              iphlpapi
ELF 7cff1000-7cffd000  Deferred        libnss_nis.so.2
ELF 7d60d000-7d629000  Deferred        wsock32&lt;elf&gt;
  \-PE  7d610000-7d629000  \              wsock32
ELF 7d80d000-7d828000  Deferred        libnsl.so.1
ELF 7d8cf000-7d8db000  Deferred        libgsm.so.1
ELF 7d8db000-7d903000  Deferred        winepulse&lt;elf&gt;
  \-PE  7d8e0000-7d903000  \              winepulse
ELF 7d95c000-7d966000  Deferred        libwrap.so.0
ELF 7d966000-7d96d000  Deferred        libxtst.so.6
ELF 7d96d000-7d992000  Deferred        mmdevapi&lt;elf&gt;
  \-PE  7d970000-7d992000  \              mmdevapi
ELF 7d9b3000-7d9d0000  Deferred        msimtf&lt;elf&gt;
  \-PE  7d9c0000-7d9d0000  \              msimtf
ELF 7d9d0000-7d9e5000  Deferred        comm.drv16.so
PE  7d9e0000-7d9e5000  Deferred        comm.drv16
ELF 7da83000-7db5f000  Deferred        libgl.so.1
ELF 7db60000-7db63000  Deferred        libx11-xcb.so.1
ELF 7db63000-7db78000  Deferred        system.drv16.so
PE  7db70000-7db78000  Deferred        system.drv16
ELF 7db98000-7dca1000  Deferred        opengl32&lt;elf&gt;
  \-PE  7dbb0000-7dca1000  \              opengl32
ELF 7dca1000-7dcb6000  Deferred        vdmdbg&lt;elf&gt;
  \-PE  7dcb0000-7dcb6000  \              vdmdbg
ELF 7dcce000-7dd04000  Deferred        uxtheme&lt;elf&gt;
  \-PE  7dcd0000-7dd04000  \              uxtheme
ELF 7dd04000-7dd0a000  Deferred        libxfixes.so.3
ELF 7dd0a000-7dd15000  Deferred        libxcursor.so.1
ELF 7dd16000-7dd1f000  Deferred        libjson.so.0
ELF 7dd24000-7dd38000  Deferred        psapi&lt;elf&gt;
  \-PE  7dd30000-7dd38000  \              psapi
ELF 7dd78000-7dda1000  Deferred        libexpat.so.1
ELF 7dda1000-7ddd6000  Deferred        libfontconfig.so.1
ELF 7ddd6000-7dde6000  Deferred        libxi.so.6
ELF 7dde6000-7ddef000  Deferred        libxrandr.so.2
ELF 7ddef000-7de11000  Deferred        libxcb.so.1
ELF 7de11000-7df49000  Deferred        libx11.so.6
ELF 7df49000-7df5b000  Deferred        libxext.so.6
ELF 7df5b000-7df75000  Deferred        libice.so.6
ELF 7df75000-7e005000  Deferred        winex11&lt;elf&gt;
  \-PE  7df80000-7e005000  \              winex11
ELF 7e005000-7e0a5000  Deferred        libfreetype.so.6
ELF 7e0a5000-7e0c5000  Deferred        libtinfo.so.5
ELF 7e0c5000-7e0ea000  Deferred        libncurses.so.5
ELF 7e123000-7e1eb000  Deferred        crypt32&lt;elf&gt;
  \-PE  7e130000-7e1eb000  \              crypt32
ELF 7e1eb000-7e235000  Deferred        dsound&lt;elf&gt;
  \-PE  7e1f0000-7e235000  \              dsound
ELF 7e235000-7e2a7000  Deferred        ddraw&lt;elf&gt;
  \-PE  7e240000-7e2a7000  \              ddraw
ELF 7e2a7000-7e3e3000  Deferred        wined3d&lt;elf&gt;
  \-PE  7e2b0000-7e3e3000  \              wined3d
ELF 7e3e3000-7e417000  Deferred        d3d8&lt;elf&gt;
  \-PE  7e3f0000-7e417000  \              d3d8
ELF 7e417000-7e43b000  Deferred        imm32&lt;elf&gt;
  \-PE  7e420000-7e43b000  \              imm32
ELF 7e43b000-7e46f000  Deferred        ws2_32&lt;elf&gt;
  \-PE  7e440000-7e46f000  \              ws2_32
ELF 7e46f000-7e49a000  Deferred        msacm32&lt;elf&gt;
  \-PE  7e470000-7e49a000  \              msacm32
ELF 7e49a000-7e519000  Deferred        rpcrt4&lt;elf&gt;
  \-PE  7e4b0000-7e519000  \              rpcrt4
ELF 7e519000-7e644000  Deferred        ole32&lt;elf&gt;
  \-PE  7e530000-7e644000  \              ole32
ELF 7e644000-7e6f7000  Deferred        winmm&lt;elf&gt;
  \-PE  7e650000-7e6f7000  \              winmm
ELF 7e6f7000-7e7fa000  Deferred        comctl32&lt;elf&gt;
  \-PE  7e700000-7e7fa000  \              comctl32
ELF 7e7fa000-7ea23000  Deferred        shell32&lt;elf&gt;
  \-PE  7e810000-7ea23000  \              shell32
ELF 7ea23000-7eaf9000  Deferred        gdi32&lt;elf&gt;
  \-PE  7ea30000-7eaf9000  \              gdi32
ELF 7eafb000-7eaff000  Deferred        libnvidia-tls.so.304.51
ELF 7eaff000-7eb09000  Deferred        libxrender.so.1
ELF 7eb09000-7eb0f000  Deferred        libxxf86vm.so.1
ELF 7eb0f000-7eb18000  Deferred        libsm.so.6
ELF 7eb18000-7eb32000  Deferred        version&lt;elf&gt;
  \-PE  7eb20000-7eb32000  \              version
ELF 7eb32000-7ec87000  Deferred        user32&lt;elf&gt;
  \-PE  7eb40000-7ec87000  \              user32
ELF 7ec87000-7ecf1000  Deferred        advapi32&lt;elf&gt;
  \-PE  7ec90000-7ecf1000  \              advapi32
ELF 7ecf1000-7ed8f000  Deferred        msvcrt&lt;elf&gt;
  \-PE  7ed00000-7ed8f000  \              msvcrt
ELF 7ef8f000-7ef9c000  Deferred        libnss_files.so.2
ELF 7ef9c000-7efc7000  Deferred        libm.so.6
ELF 7efc8000-7efe5000  Deferred        libgcc_s.so.1
ELF 7efe5000-7f000000  Deferred        crtdll&lt;elf&gt;
  \-PE  7eff0000-7f000000  \              crtdll
ELF f73d0000-f73d4000  Deferred        libxinerama.so.1
ELF f73d4000-f73d8000  Deferred        libxau.so.6
ELF f73da000-f73df000  Deferred        libdl.so.2
ELF f73df000-f7591000  Dwarf          libc.so.6
ELF f7591000-f75ab000  Dwarf          libpthread.so.0
ELF f75ab000-f76ef000  Dwarf          libwine.so.1
ELF f7722000-f7728000  Deferred        libuuid.so.1
ELF f7729000-f774a000  Deferred        ld-linux.so.2
ELF f774a000-f774b000  Deferred        [vdso].so
Threads:
process  tid      prio (all id:s are in hex)
00000008 (D) C:\Perfect World Entertainment\Perfect World International\element\elementclient.exe
    00000031    0 &lt;==
    00000035  15
    00000012    0
    00000021    0
    00000045    0
    00000044    0
    00000043    0
    00000038  15
    00000037    0
    00000036  15
    00000034    0
    00000033    0
    00000032    0
    00000027    0
    00000009    0
0000000e services.exe
    0000000b    0
    00000020    0
    00000017    0
    00000010    0
    0000000f    0
00000014 winedevice.exe
    0000001e    0
    0000001b    0
    00000016    0
    00000015    0
0000001c plugplay.exe
    00000022    0
    0000001f    0
    0000001d    0
00000023 explorer.exe
    00000024    0</pre>
Steps to debug a crash. You may stop at any step, but please report the bug and provide as much of the information gathered to the bug report as feasible.
 
<ol style="list-style-type: decimal;">
<li><p>Get the reason for the crash. This is usually a page fault, an unimplemented function in Wine, or the like. When reporting a crash, report this ''whole'' crashdump even if it doesn't make sense to you.</p>
<p>(In this case it is page fault on write access to 0x00000000. Most likely Wine passed NULL to the application or the like.)</p></li>
<li><p>Determine the cause of the crash. Since this is usually a primary/secondary reaction to a failed or misbehaving Wine function, rerun Wine with the <code>WINEDEBUG=+relay</code> environment variable set. This will generate quite a lot of output, but usually the reason is located in the last calls. Those lines usually look like this:</p>
<pre>000d:Call advapi32.RegOpenKeyExW(00000090,7eb94da0 L&quot;Patterns&quot;,00000000,00020019,0033f968) ret=7eb39af8
^^^^      ^^^^^^^^ ^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^
|        |        |            |                |          |                          |Return address.
|        |        |            |                |          |More arguments.
|        |        |            |                |Textual parameter.
|        |        |            |Arguments.
|        |        |Function called.
|        |The module of the called function.
|The thread in which the call was made.
 
000d:Ret  advapi32.RegOpenKeyExW() retval=00000000 ret=7eb39af8
                                  ^^^^^^^^^^^^^^^
                                  |Return value is 32-bit and has the value 0.</pre></li>
<li><p>If you have found a misbehaving Wine 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 a <code>WINE_DEFAULT_DEBUG_CHANNEL(channel);</code> at the beginning of the source file. Rerun wine with the <code>WINEDEBUG=+xyz,+relay</code> environment variable set.</p>
<p>Occasionally there are additional debug channels defined at the beginning of the source file in the form <code>WINE_DECLARE_DEBUG_CHANNEL(channel);</code> if so the offending function may also use one of these alternate channels. Look through the the function for <code>TRACE_(channel)(&quot;... /n&quot;);</code> and add any additional channels to the command line.</p></li>
<li><p>Additional information on how to debug using the internal debugger can be found in <tt>programs/winedbg/README</tt>.</p></li>
<li><p>If this information isn't clear enough or if you want to know more about what's happening in the function itself, try running wine with <code>WINEDEBUG=+all</code>, which dumps ALL included debug information in wine. It is often necessary to limit the debug output produced. That can be done by piping the output through <b>grep</b>, or alternatively with registry keys. See [[#Configuring +relay behaviour|Section 1.5.3]] for more information.</p></li>
<li><p>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 also try to run the program in <b>gdb</b> instead of using the Wine debugger. If you do that, use <code>handle SIGSEGV nostop noprint</code> to disable the handling of seg faults inside <b>gdb</b> (needed for Win16).</p></li>
<li><p>You can also set a breakpoint for that function. Start wine using <b>winedbg</b> instead of <b>wine</b>. Once the debugger is running enter <code>break RegOpenKeyExW</code> (replace by function you want to debug, '''case is relevant''') to set a breakpoint. Then use <b>continue</b> to start normal program-execution. Wine will stop if it reaches the breakpoint. If the program isn't yet at the crashing call of that function, use <b>continue</b> 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.</p></li></ol>
 
==== Program hangs, nothing happens ====
 
Start the program with <b>winedbg</b> instead of <b>wine</b>. When the program locks up switch to the winedbg terminal and press <b>Ctrl+C</b>. This will stop the program and let you debug the program as you would for a crash.
 
==== Program reports an error with a message box ====
 
Sometimes programs are reporting failure using more or less nondescript message boxes. 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.
 
Since the failure happens usually directly before setting up the message box you can start winedbg and set a breakpoint at <code>MessageBoxA</code> (called by win16 and win32 programs) and proceed with <b>continue</b>. With <code>WINEDEBUG=+all</code> Wine will now stop directly before setting up the message box. Proceed as explained above.
 
You can also run wine using <code>WINEDEBUG=+relay wine program.exe 2&gt;&amp;1 | less -i</code> and in <b>less</b> search for “MessageBox”.
 
==== Disassembling programs ====
 
You may also try to disassemble the offending program to check for undocumented features and/or use of them.
 
The best, freely available, disassembler for Win16 programs is Windows Codeback, archive name <tt>wcbxxx.zip</tt> (e.g. <tt>wcb105a.zip</tt>).
 
Disassembling win32 programs is possible using e.g. GoVest by Ansgar Trimborn. It can be found [http://www.oocities.com/govest/ here].
 
You can also use the newer and better Interactive Disassembler (IDA) from DataRescue. Take a look in the [http://appdb.winehq.org/appview.php?appId=565 AppDB] for links to various versions of IDA.
 
Another popular disassembler is Windows Disassembler 32 from URSoft. Look for a file called <tt>w32dsm87.zip</tt> (or similar) on [http://www.winsite.com/ winsite.com] or [http://www.softpedia.com/ softpedia.com]. It seems that Windows Disassembler 32 currently has problems working correctly under Wine, so use IDA or GoVest.
 
Also of considerable fame amongst disassemblers is SoftIce from NuMega. That software has since been acquired by [http://www.compuware.com/ CompuWare] and made part of their Windows driver development suite. Newer versions of SoftIce needs to run as a Windows Service and therefore won't currently work under Wine.
 
If nothing works for you, you might try one of the disassemblers found in [http://directory.google.com/Top/Computers/Programming/Disassemblers/DOS_and_Windows/ Google directory].
 
Understanding disassembled code is mostly a question of exercise. Most code out there uses standard C function entries (for it is usually written in C). Win16 function entries usually look like that:
 
<source lang="asm">push bp
mov bp, sp
... function code ..
retf XXXX  <--------- XXXX is number of bytes of arguments</source>
This is a <tt>FAR</tt> function with no local storage. The arguments usually start at <tt>[bp+6]</tt> with increasing offsets. Note, that <tt>[bp+6]</tt> belongs to the ''rightmost'' argument, for exported win16 functions use the <tt>PASCAL</tt> calling convention. So, if we use <code>strcmp(a,b)</code> with <code>a</code> and <code>b</code> both 32-bit variables <code>b</code> would be at <tt>[bp+6]</tt> and <code>a</code> at <tt>[bp+10]</tt>.
 
Most functions make also use of local storage in the stackframe:
 
<source lang="asm">enter 0086, 00
... function code ...
leave
retf XXXX</source>
This does mostly the same as above, but also adds <tt>0x86</tt> bytes of stackstorage, which is accessed using <tt>[bp-xx]</tt>. Before calling a function, arguments are pushed on the stack using something like this:
 
<source lang="asm">push word ptr [bp-02]  <- will be at [bp+8]
push di                <- will be at [bp+6]
call KERNEL.LSTRLEN</source>
Here first the selector and then the offset to the passed string are pushed.
 
==== Sample debugging session ====
 
Let's debug the infamous Word <b>SHARE.EXE</b> message box:
 
<pre>|marcus@jet $ wine winword.exe
|            +---------------------------------------------+
|            | !  You must leave Windows and load SHARE.EXE|
|            |    before starting Word.                    |
|            +---------------------------------------------+</pre>
<pre>|marcus@jet $ WINEDEBUG=+relay,-debug wine winword.exe
|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&gt;break MessageBoxA                          &lt;---- Set Breakpoint
|Breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|Wine-dbg&gt;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 debug output
|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 hard disk)
 
|Call KERNEL.97: GETTEMPFILENAME(0x00c3,0x09278364&quot;doc&quot;,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 writable.
|Please check your configuration file if this generates a failure.</pre>
Whoops, it even detects that something is wrong!
 
<pre>|Ret  KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
                                          ^^^^^^ Temporary storage ID
 
|Call KERNEL.74: OPENFILE(0x09278248&quot;C:~doc9281.tmp&quot;,0927:82da,0x1012) ret=060f:09d8 ds=0927
                                    ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
                                    |filename        |OFSTRUCT |open mode:
 
                                      OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE</pre>
This fails, since my <tt>C:</tt> drive is in this case mounted readonly.
 
<pre>|Ret  KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
                                  ^^^^^^ HFILE_ERROR16, yes, it failed.
 
|Call USER.1: MESSAGEBOX(0x0000,0x09278376&quot;You must close Windows and load SHARE.EXE before you start Word.&quot;,0x00000000,0x1030) ret=060f:084f ds=0927</pre>
And MessageBox'ed.
 
<pre>|Stopped on breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|190    {      &lt;- the sourceline
In 32 bit mode.
Wine-dbg&gt;</pre>
The code seems to find a writable harddisk and tries to create a file there. To work around this bug, you can define <tt>C:</tt> as a network drive, which is ignored by the code above.
 
==== Debugging Tips ====
 
Here are some additional debugging tips:
 
<ul>
<li><p>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</p>
<pre>WINEDEBUG=+relay wine program</pre>
<p>to get a listing of the functions the program calls in its start function. Now you do a</p>
<pre>winedbg winfile.exe</pre>
<p>This way, you get into <b>winedbg</b>. Now you can set a breakpoint on any function the program calls in the <code>start</code> function and just type <b>c</b> 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.</p></li>
<li><p>If you try to run a program and it quits after showing an error message box, the problem can usually be identified in the return value of one of the functions executed before <code>MessageBox()</code>. That's why you should re-run the program with e.g.</p>
<pre>WINEDEBUG=+relay wine program_name &amp;&gt;relmsg</pre>
<p>Then do a <b>more relmsg</b> and search for the last occurrence of a call to the string &quot;MESSAGEBOX&quot;. This is a line like</p>
<pre>Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 &quot;Runtime error 219 at 0004:1056.&quot;,0x00000000,0x1010) ret=01f7:2160 ds=01ff</pre>
<p>In my example the lines before the call to <code>MessageBox()</code> look like that:</p>
<pre>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 &quot;COMET.HLP&quot;,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 &quot;Runtime error 219 at 0004:1056.&quot;,0x00000000,0x1010) ret=01f7:2160 ds=01ff</pre>
<p>I think that the call to <code>MessageBox()</code> in this example is ''not'' caused by a wrong result value of some previously executed function (it's happening quite often like that), but instead the message box complains about a runtime error at <tt>0x0004:0x1056</tt>.</p>
<p>As the segment value of the address is only <tt>4</tt>, I think that that is only an internal program value. But the offset address reveals something quite interesting: offset <tt>1056</tt> is ''very'' close to the return address of <code>FREELIBRARY()</code>:</p>
<pre>Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
                                            ^^^^</pre>
<p>Provided that segment <tt>0x0004</tt> is indeed segment <code>0x1cf</code>, we now we can use IDA to disassemble the part that caused the error. We just have to find the address of the call to <code>FreeLibrary()</code>. 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 <tt>0x1cf</tt>).</p></li>
<li><p>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 segment during execution, you may set a breakpoint to <code>GetVersion16/32</code> as those functions are called very often.</p>
<p>Then do a <b>c</b> until you are able to set this breakpoint without error message.</p></li></ul>
 
==== Some basic debugger usages ====
 
After starting your program with
 
<pre>winedbg myprog.exe</pre>
the program loads and you get a prompt at the program starting point. Then you can set breakpoints:
 
<pre>b RoutineName      (by routine name) OR
b *0x812575        (by address)</pre>
Then you hit <b>c</b> (continue) to run the program. It stops at the breakpoint. You can type
 
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)
list ''line number''  (to list source code)
x ''variable name''    (to examine a variable; only works if code
                    is not compiled with optimization)
x ''0x4269978''        (to examine a memory location)
?                  (help)
q                  (quit)
 
By hitting '''Enter''', you repeat the last command.
 
==== Useful programs ====
 
Some useful programs:
 
<dl>
<dt>GoVest: <b>govest.zip</b> is available from http://www.oocities.com/govest/.</dt>
<dd><p>Simple win32 disassembler that works well with Wine.</p></dd>
<dt>IDA:</dt>
<dd><p>IDA Pro is highly recommended, but is not free. DataRescue does however make trial versions available.</p>
<p>Take a look in the [http://appdb.winehq.org/appview.php?appId=565 AppDB] for links to various versions of IDA.</p></dd>
<dt>XRAY: http://garbo.uwasa.fi/pub/pc/sysinfo/xray15.zip </dt>
<dd><p>Traces DOS calls (Int 21h, DPMI, ...). Use it with Windows to correct file management problems etc.</p></dd>
<dt>pedump: ftp://ftp.simtel.net/pub/simtelnet/win95/prog/pedump.zip</dt>
<dd><p>Dumps the imports and exports of a PE (Portable Executable) DLL.</p></dd>
<dt>winedump: (included in wine tree)</dt>
<dd><p>Dumps the imports and exports of a PE (Portable Executable) DLL.</p></dd></dl>
 
=== Useful memory addresses ===
 
Wine uses several different kinds of memory addresses.
 
<dl>
<dt>Win32/“normal” Wine addresses/Linux: linear addresses.</dt>
<dd><p>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).</p></dd>
<dt>Win16 “enhanced mode”: segmented addresses.</dt>
<dd><p>These are the “normal” Win16 addresses, called SEGPTR. They have a segment:offset notation, e.g. 0x01d7:0x0012. The segment part usually is a “selector”, which ''always'' 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.</p>
<p>Example:</p>
<p>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.</p></dd>
<dt>DOS/Win16 “standard mode”</dt>
<dd><p>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.</p>
<p>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.</p></dd></dl>
 
=== Configuration ===
 
==== Windows Debugging configuration ====
 
The Windows debugging API uses a registry entry to know which debugger to invoke when an unhandled exception occurs (see [[#On exceptions|''On exceptions'']] for some details). Two values in key
 
<pre>[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]</pre>
determine the behavior:
 
; Debugger
: This is the command line used to launch the debugger (it uses two <code>printf</code> formats (<tt>%ld</tt>) to pass context dependent information to the debugger). You should put here a complete path to your debugger (<b>winedbg</b> can of course be used, but any other Windows debugging API aware debugger will do). The path to the debugger you choose to use must be reachable via one of the DOS drives configured under <tt>/dosdevices</tt> in your WINEPREFIX or <tt>~/.wine</tt> folder.
; Auto
: 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.
 
A regular Wine registry looks like:
 
<pre>[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
&quot;Auto&quot;=dword:00000001
&quot;Debugger&quot;=&quot;winedbg %ld %ld&quot;</pre>
<blockquote style="font-size:100%">'''Note 1''': Creating this key is mandatory. Not doing so will not fire the debugger when an exception occurs.
</blockquote>
<blockquote style="font-size:100%">'''Note 2''': <b>wineinstall</b> (available in Wine source) sets up this correctly. However, due to some limitation of the registry installed, if a previous Wine installation exists, it's safer to remove the whole
 
 
<pre>[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]</pre>
key before running again <b>wineinstall</b> to regenerate this key.
</blockquote>
 
==== WineDbg configuration ====
 
<b>winedbg</b> can be configured through a number of options. Those options are stored in the registry, on a per user basis. The key is (in ''my'' registry)
 
<pre>[HKCU\\Software\\Wine\\WineDbg]</pre>
Those options can be read/written while inside <b>winedbg</b>, as part of the debugger expressions. To refer to one of these options, its name must be prefixed by a <tt>$</tt> sign. For example,
 
<pre>set $BreakAllThreadsStartup = 1</pre>
sets the option <code>BreakAllThreadsStartup</code> to <tt>TRUE</tt>.
 
All the options are read from the registry when <b>winedbg</b> starts (if no corresponding value is found, a default value is used), and are written back to the registry when <b>winedbg</b> exits (hence, all modifications to those options are automatically saved when <b>winedbg</b> terminates).
 
Here's the list of all options:
 
; <code>BreakAllThreadsStartup</code>
: Set to <tt>TRUE</tt> if at all threads start-up the debugger stops set to <tt>FALSE</tt> if only at the first thread startup of a given process the debugger stops. <tt>FALSE</tt> by default.
; <code>BreakOnCritSectTimeOut</code>
: Set to <tt>TRUE</tt> if the debugger stops when a critical section times out (5 minutes); <tt>TRUE</tt> by default.
; <code>BreakOnAttach</code>
: Set to <tt>TRUE</tt> if when <b>winedbg</b> attaches to an existing process after an unhandled exception, <b>winedbg</b> 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 <tt>FALSE</tt>.
; <code>BreakOnFirstChance</code>
: 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 <b>winedbg</b>'s <b>cont</b> command) or pass the exception up to the exception handler chain in the program (if it exists) (<b>winedbg</b> implements this through the <b>pass</b> 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 <code>BreakOnFirstChance</code> exception is <tt>TRUE</tt>, then winedbg is entered for both first and last chance exceptions (to <tt>FALSE</tt>, it's only entered for last chance exceptions).
; <code>AlwaysShowThunk</code>
: Set to <tt>TRUE</tt> if the debugger, when looking up for a symbol from its name, displays all the thunks with that name. The default value (<tt>FALSE</tt>) allows not to have to choose between a symbol and all the import thunks from all the DLLs using that symbols.
 
==== Configuring +relay behaviour ====
 
When setting <code>WINEDEBUG</code> to <tt>+relay</tt> and debugging, you might get a lot of output. You can limit the output by configuring the value <tt>RelayExclude</tt> in the registry, located under the key <tt>[HKCU\\Software\\Wine\\Debug]</tt>
 
Set the value of <tt>RelayExclude</tt> to a semicolon-separated list of calls to exclude, e.g. &quot;RtlEnterCriticalSection;RtlLeaveCriticalSection;kernel32.97;kernel32.98&quot;.
 
<tt>RelayInclude</tt> is an option similar to <tt>RelayExclude</tt>, except that functions listed here will be the only ones included in the output.
 
If your application runs too slow with <tt>+relay</tt> to get meaningful output and you're stuck with multi-GB relay log files, but you're not sure what to exclude, here's a trick to get you started. First, run your application for a minute or so, piping its output to a file on disk:
 
<pre>WINEDEBUG=+relay wine appname.exe &amp;&gt;relay.log</pre>
Then run this command to see which calls are performed the most:
 
<pre>awk -F'(' '{print $1}' &lt; relay.log | awk '{print $2}' | sort | uniq -c | sort</pre>
Exclude the bottom-most calls with <tt>RelayExclude</tt> after making sure that they are irrelevant, then run your application again.
 
=== WineDbg Expressions and Variables ===
 
==== Expressions ====
 
Expressions in Wine Debugger are mostly written in a C form. However, there are a few discrepancies:
 
* Identifiers can take a '!' in their names. This allow mainly to access symbols from different DLLs like <code>USER32!CreateWindowExA</code>.
* In cast operation, when specifying a structure or an union, you must use the <tt>struct</tt> or <tt>union</tt> keyword (even if your program uses a <tt>typedef</tt>).
 
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.
 
In lots of cases, you can also use regular expressions for looking for a symbol.
 
<b>winedbg</b> defines its own set of variables. The configuration variables from above are part of them. Some others include:
 
; <code>$ThreadId</code>
: ID of the <code>W-thread</code> currently examined by the debugger
; <code>$ProcessId</code>
: ID of the <code>W-thread</code> currently examined by the debugger
; ''registers''
: All CPU registers are also available, using '$' as a prefix. You can use <b>info regs</b> to get a list of available CPU registers.
 
The <code>$ThreadId</code> and <code>$ProcessId</code> variables can be handy to set conditional breakpoints on a given thread or process.
 
=== WineDbg Command Reference ===
 
==== Misc ====
 
{|class="wikitable"
|+<b>Table 1-1. WineDbg misc. commands</b>
|-
| <b>abort</b>
| aborts the debugger
|-
| <b>quit</b>
| exits the debugger
|-
| <b>attach</b> ''N''
| attach to a W-process (''N'' is its ID, numeric or hexadecimal (<tt>0x</tt>''N'')). IDs can be obtained using the <b>info process</b> command. Note the <b>info process</b> command returns hexadecimal values.
|-
| <b>detach</b>
| detach from a W-process.
|-
| <b>help</b>
| prints some help on the commands
|-
| <b>help info</b>
| prints some help on info commands
|}
 
==== Flow control ====
 
{|class="wikitable"
|+ Table 1-2. '''WineDbg flow control commands'''
| <b>cont</b>, <b>c</b>
| continue execution until next breakpoint or exception.
|-
| <b>pass</b>
| pass the exception event up to the filter chain.
|-
| <b>step</b>, <b>s</b>
| continue execution until next “C” line of code (enters function call)
|-
| <b>next</b>, <b>n</b>
| continue execution until next “C” line of code (doesn't enter function call)
|-
| <b>stepi</b>, <b>si</b>
| execute next assembly instruction (enters function call)
|-
| <b>nexti</b>, <b>ni</b>
| execute next assembly instruction (doesn't enter function call)
|-
| <b>finish</b>, <b>f</b>
| execute until current function is exited
|}
 
<b>cont</b>, <b>step</b>, <b>next</b>, <b>stepi</b>, <b>nexti</b> can be postfixed by a number (''N''), meaning that the command must be executed ''N'' times.
 
==== Breakpoints, watch points ====
 
{|class="wikitable"
|+ '''Table 1-3. WineDbg break &amp; watch points'''
| <b>enable</b> ''N''
| enables (break|watch)point ''N''
|-
| <b>disable</b> ''N''
| disables (break|watch)point ''N''
|-
| <b>delete</b> ''N''
| deletes (break|watch)point ''N''
|-
| <b>cond</b> ''N''
| removes any existing condition to (break|watch)point ''N''
|-
| <b>cond</b> ''N expr''
| adds condition ''expr'' to (break|watch)point ''N. expr'' will be evaluated each time the breakpoint is hit. If the result is a zero value, the breakpoint isn't triggered.
|-
| <b>break *</b> ''N''
| adds a breakpoint at address ''N''
|-
| <b>break</b> ''id''
| adds a breakpoint at the address of symbol ''id''
|-
| <b>break</b> ''id N''
| adds a breakpoint at line ''N'' inside symbol ''id''
|-
| <b>break</b> ''N''
| adds a breakpoint at line ''N'' of current source file
|-
| <b>break</b>
| adds a breakpoint at current $PC address
|-
| <b>watch *</b> ''N''
| adds a watch command (on write) at address ''N'' (on 4 bytes)
|-
| <b>watch</b> ''id''
| adds a watch command (on write) at the address of symbol ''id''
|-
| <b>info break</b>
| lists all (break|watch)points (with state)
|}
 
You can use the symbol <tt>EntryPoint</tt> to stand for the entry point of the DLL.
 
When setting a break/watch-point by ''id'', if the symbol cannot be found (for example, the symbol is contained in a not yet loaded module), <b>winedbg</b> will recall the name of the symbol and will try to set the breakpoint each time a new module is loaded (until it succeeds).
 
==== Stack manipulation ====
 
{|class="wikitable"
|+ '''Table 1-4. WineDbg stack manipulation'''
| <b>bt</b>
| print calling stack of current thread
|-
| <b>bt</b> N
| print calling stack of thread of ID ''N'' (note: this doesn't change the position of the current frame as manipulated by the <b>up</b> and <b>dn</b> commands)
|-
| <b>up</b>
| goes up one frame in current thread's stack
|-
| <b>up</b> ''N''
| goes up ''N'' frames in current thread's stack
|-
| <b>dn</b>
| goes down one frame in current thread's stack
|-
| <b>dn</b> ''N''
| goes down ''N'' frames in current thread's stack
|-
| <b>frame</b> ''N''
| set ''N'' as the current frame for current thread's stack
|-
| <b>info local</b>
| prints information on local variables for current function frame
|}
 
==== Directory &amp; source file manipulation ====
 
{|class="wikitable"
|+ '''Table 1-5. WineDbg directory &amp; source file manipulation'''
| <b>show dir</b>
| prints the list of dirs where source files are looked for
|-
| <b>dir</b> ''pathname''
| adds ''pathname'' to the list of dirs where to look for source files
|-
| <b>dir</b>
| deletes the list of dirs where to look for source files
|-
| <b>symbolfile</b> ''pathname''
| loads external symbol definition
|-
| <b>symbolfile</b> ''pathname N''
| loads external symbol definition (applying an offset of ''N'' to addresses)
|-
| <b>list</b>
| lists 10 source lines forwards from current position
|-
| <b>list -</b>
| lists 10 source lines backwards from current position
|-
| <b>list</b> ''N''
| lists 10 source lines from line ''N'' in current file
|-
| <b>list</b> ''path<b>:</b>N''
| lists 10 source lines from line ''N'' in file ''path''
|-
| <b>list</b> ''id''
| lists 10 source lines of function ''id''
|-
| <b>list *</b> ''N''
| lists 10 source lines from address ''N''
|}
 
You can specify the end target (to change the 10 lines value) using the ','. For example:
 
{|class="wikitable"
|+ '''Table 1-6. WineDbg list command examples'''
| <code>list 123, 234</code>
| lists source lines from line 123 up to line 234 in current file
|-
| <code>list foo.c:1, 56</code>
| lists source lines from line 1 up to 56 in file <tt>foo.c</tt>
|}
 
==== Displaying ====
 
A display is an expression that's evaluated and printed after the execution of any <code>winedbg</code> command.
 
<code>winedbg</code> will automatically detect if the expression you entered contains a local variable. If so, display will only be shown if the context is still in the same function as the one the debugger was in when the display expression was entered.
 
{|
|+ WineDbg displays
| <code>info display</code>
| lists the active displays
|-
| <code>display</code>
| print the active displays' values (as done each time the debugger stops)
|-
| <code>display</code> expr
| adds a display for expression expr
|-
| <code>display /</code>fmt expr
| adds a display for expression expr. Printing evaluated expr is done using the given format (see <code>print</code> command for more on formats)
|-
| <code>del display</code> N, <code>undisplay</code> N
| deletes display N
|}
 
==== Disassembly ====
 
{|
|+ WineDbg dissassembly
| <code>disas</code>
| disassemble from current position
|-
| <code>disas</code> expr
| disassemble from address expr
|-
| <code>disas</code> expr, expr
| disassembles code between addresses specified by the two exprs
|}
 
==== Memory (reading, writing, typing) ====
 
{|
|+ WineDbg memory management
| <code>x</code> expr
| examines memory at expr address
|-
| <code>x /</code>fmt expr
| examines memory at expr address using format fmt
|-
| <code>print</code> expr
| prints the value of expr (possibly using its type)
|-
| <code>print /</code>fmt expr
| prints the value of expr using format fmt
|-
| <code>set</code> lval<code>=</code>expr
| writes the value of expr in lval
|-
| <code>whatis</code> expr
| prints the C type of expression expr
|-
| <code>
              set ! symbol_picker interactive
            </code>
| when printing a value, if several symbols are found, ask the user which one to pick (default)
|-
| <code>
              set ! symbol_picker scoped
            </code>
| when printing a value, give precedence to local symbols over global symbols
|}
 
fmt is either letter or count letter (without a space between count and letter), where letter can be <code>s</code>, an ASCII string, <code>u</code>, a Unicode UTF16 string, <code>i</code>, instructions (disassemble), <code>x</code>, 32-bit unsigned hexadecimal integer, <code>d</code>, 32-bit signed decimal integer, <code>w</code>, 16-bit unsigned hexadecimal integer, <code>c</code>, character (only printable 0x20-0x7f are actually printed), <code>b</code>, 8-bit unsigned hexadecimal integer, <code>g</code>, GUID
 
==== Information on Wine internals ====
 
{|
|+ WineDbg Win32 objects management
| <code>info class</code>
| lists all Windows classes registered in Wine
|-
| <code>info class</code> id
| prints information on Windows class id
|-
| <code>info share</code>
| lists all the dynamic libraries loaded in the debugged program (including <code>.so</code> files, NE and PE DLLs)
|-
| <code>info share</code> N
| prints information on module at address N
|-
| <code>info regs</code>
| prints the value of the CPU registers
|-
| <code>info all-regs</code>
| prints the value of the CPU and Floating Point registers
|-
| <code>info segment</code> N
| prints information on segment N (i386 only)
|-
| <code>info segment</code>
| lists all allocated segments (i386 only)
|-
| <code>info stack</code>
| prints the values on top of the stack
|-
| <code>info map</code>
| lists all virtual mappings used by the debugged program
|-
| <code>info map</code> N
| lists all virtual mappings used by the program of wpid N
|-
| <code>info wnd</code> N
| prints information of Window of handle N
|-
| <code>info wnd</code>
| lists all the window hierarchy starting from the desktop window
|-
| <code>info process</code>
| lists all w-processes in Wine session
|-
| <code>info thread</code>
| lists all w-threads in Wine session
|-
| <code>info exception</code>
| lists the exception frames (starting from current stack frame)
|}
 
==== Debug channels ====
 
It is possible to turn on and off debug messages as you are debugging using the set command (only for debug channels specified in WINEDEBUG environment variable). See [[#debugging|???]]
 
{|
|+ WineDbg debug channels management
| <code>set + warn</code> channel
| turn on warn on channel
|-
| <code>set +</code> channel
| turn on warn/fixme/err/trace on channel
|-
| <code>set -</code> channel
| turn off warn/fixme/err/trace on channel
|-
| <code>set - fixme</code>
| turn off the “fixme” class
|}
 
=== Other debuggers ===
 
==== GDB mode ====
 
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 <code>--gdb</code> to <code>winedbg</code> command line. You'll end up on a GDB prompt. You'll have to use the GDB commands (not WineDbg ones).
 
However, some limitation in GDB while debugging wine (see below) don't appear in this mode:
 
* GDB will correctly present Win32 thread information and breakpoint behavior
* Moreover, it also provides support for the Dwarf II debug format (which became the default format (instead of <code>stabs</code>) in gcc 3.1).
 
A few Wine extensions available through the monitor command.
 
{|
|+ WineDbg debug channels management
| <code>monitor wnd</code>
| lists all window in the Wine session
|-
| <code>monitor proc</code>
| lists all processes in the Wine session
|-
| <code>monitor mem</code>
| displays memory mapping of debugged process
|}
 
==== Graphical frontends to <code>gdb</code> ====
 
This section will describe how you can debug Wine using the GDB mode of winedbg and some graphical front ends to GDB for those of you who really like graphical debuggers.
 
===== DDD =====
 
Use the following steps, in this order:
 
<ol style="list-style-type: decimal;">
<li><p>Start the Wine debugger with a command line like:</p>
<pre>winedbg --gdb --no-start name_of_exe_to_debug.exe optional parameters</pre></li>
<li><p>Start ddd</p></li>
<li><p>In <code>ddd</code>, use Open File or Open Program to point to the Wine executable.</p></li>
<li><p>In the output of above command, there's a line like</p>
<pre>target remote localhost:12345</pre>
<p>Copy that line and paste into <code>ddd</code> command pane (the one with the <code>(gdb)</code> prompt)</p></li></ol>
 
The program should now be loaded and up and running.
 
===== kdbg =====
 
Use the following steps, in this order:
 
<ol style="list-style-type: decimal;">
<li><p>Start the Wine debugger with a command line like:</p>
<pre>winedbg --gdb --no-start name_of_exe_to_debug.exe optional parameters</pre></li>
<li><p>In the output of above command, there's a line like</p>
<pre>target remote localhost:12345</pre>
<p>Start kdbg with</p>
<pre>kdbg -r localhost:12345 wine</pre>
<p><code>localhost:12345</code> is not a fixed value, but has been printed in first step. “wine” should also be the full path to the Wine executable.</p></li></ol>
 
The program should now be loaded and up and running.
 
==== Using other Unix debuggers ====
 
You can also use other debuggers (like <code>gdb</code>), but you must be aware of a few items:
 
You need to attach the unix debugger to the correct unix process (representing the correct windows thread) (you can “guess” it from a <code>ps fax</code> command for example. When running the emulator, usually the first two <code>upid</code>s are for the Windows application running the desktop, the first thread of the application is generally the third <code>upid</code>; when running a Winelib program, the first thread of the application is generally the first <code>upid</code>)
 
<blockquote>'''Note'''
 
If you plan to used <code>gdb</code> for a multi-threaded Wine application (native or Winelib), then <code>gdb</code> will be able to handle the multiple threads directly only if:
 
* Wine is running on the pthread model (it won't work in the kthread one). See the Wine architecture documentation for further details.
* <code>gdb</code> supports the multi-threading (you need at least version 5.0 for that).
 
In the unfortunate case (no direct thread support in <code>gdb</code> because one of the above conditions is false), you'll have to spawn a different <code>gdb</code> session for each Windows thread you wish to debug (which means no synchronization for debugging purposes between the various threads).
</blockquote>
Here's how to get info about the current execution status of a certain Wine process:
 
Change into your Wine source dir and enter:
 
<pre>$ gdb wine</pre>
Switch to another console and enter <code>ps ax | grep
          wine</code> to find all wine processes. Inside <code>gdb</code>, repeat for all Wine processes:
 
<pre>(gdb) attach wpid</pre>
with wpid being the process ID of one of the Wine processes. Use
 
<pre>(gdb) bt</pre>
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:
 
<pre>(gdb) n</pre>
or maybe even
 
<pre>(gdb) b SomeFunction</pre>
and
 
<pre>(gdb) c</pre>
to set a breakpoint at a certain function and continue up to that function. Finally you can enter
 
<pre>(gdb) detach</pre>
to detach from the Wine process.
 
==== Using other Windows debuggers ====
 
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.
 
==== Main differences between winedbg and regular Unix debuggers ====
 
{|
|+ Debuggers comparison
| WineDbg
| gdb
|-
| 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
| 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
|-
| WineDbg supports debug information from <code>stabs</code> (standard Unix format) and C, CodeView, <code>.DBG</code> (Microsoft)
| GDB supports debug information from <code>stabs</code> (standard Unix format) and Dwarf II.
|}

Latest revision as of 16:36, 15 January 2019

Work in progress: This page is currently undergoing extensive revision. External links to specific parts of this page may now be broken due to the section having been edited, moved, merged with another section, or removed altogether. Consult the table of contents to find the section you are looking for. There may be related discussion on the talk page.

Table of Contents

I. Developing Wine

  1. Building Wine
  2. Running Wine
  3. Debugging Wine
  4. Debug Logging
  5. Other Debugging Techniques
  6. Coding Practice
  7. Writing Conformance Tests
  8. Submitting Patches
  9. Documenting Wine

II. Wine Architecture

  1. Overview
  2. Kernel modules
  3. Windowing system
  4. COM in Wine
  5. Wine and OpenGL
  6. Outline of DirectDraw Architecture
  7. Wine and Multimedia

III. Miscellaneous references

  1. Tips for Vim users
  2. Running Wine under Valgrind
  3. A list of windows messages, by value
  4. The format of a ternary raster operation code
  5. Windows Graphics Programming: Win32 GDI and DirectDraw by Feng Yuan (Working at HP for Printer Drivers; Now at Microsoft for WPF and XPS)
  6. All Development Wiki pages

List of Tables

1-1. WineDbg misc commands
1-2. WineDbg flow control commands
1-3. WineDbg break & watch points
1-4. WineDbg stack manipulation
1-5. WineDbg directory & source file manipulation
1-6. WineDbg list command examples
1-7. WineDbg displays
1-8. WineDbg disassembly
1-9. WineDbg memory management
1-10. WineDbg Win32 objects management
1-11. WineDbg debug channels management
1-12. WineDbg debug channels management
1-13. Debuggers comparison
7-1. Wine executables
7-2. Memory layout (Windows and Wine)
8-1. DOS, Win32 and NT paths equivalences
8-2. File systems' properties
8-3. Mapping of Windows device names into Unix device names
8-4. Function consoles implementation comparison
8-5. Console registry settings
13-1. Wine MCI drivers
13-2. Wine ACM drivers
13-3. Wine VIDC drivers
13-4. Wine multimedia configuration scheme

Authors

Uwe Bonnes; Jonathan Buzzard; Zoran Dzelajlija; Klaas van Gend; Francois Gouget; Jon Griffiths; Albert den Haan; Mike Hearn; André Hentschel; Ove Kaaven; Tony Lambregts; Marcus Meissner; Gerard Patel; Dimitrie Paun; Michele Petrovski; Eric Pouech; Douglas Ridgway; John Sheets; Lionel Ulmer; Ulrich Weigand; Morten Welinder; Jeremy White

This page was last edited on 15 January 2019, at 16:36.