docs/en winedev-debugger.sgml
Dimi Paun
dimi at users.sourceforge.net
Mon Oct 3 20:52:04 CDT 2005
ChangeSet ID: 1128390724281499355406599
CVSROOT: /cvsroot/wine
Module name: docs
Changes by: dimi at sc8-pr-cvs1.sourceforge.net 2005/10/03 18:52:04
Modified files:
en : winedev-debugger.sgml
Log message:
Molle Bestefich <molle.bestefich at gmail.com>
Fix up winedev-debugger doc to match 0.9.
Remove 404s, remove config file references, mention disassemblers
that actually installs, etc.
Old revision New revision Changes Path
1.2 1.3 +240 -149 docs/en/winedev-debugger.sgml
Index: docs/en/winedev-debugger.sgml
diff -u -p docs/en/winedev-debugger.sgml:1.2 docs/en/winedev-debugger.sgml:1.3
--- docs/en/winedev-debugger.sgml 4 Oct 2005 1:52: 4 -0000
+++ /dev/null 4 Oct 2005 1:52: 4 -0000
@@ -41,9 +41,9 @@
</itemizedlist>
<para>
A <varname>W-process</varname> is made of one or several
- <varname>W-threads</varname>. Each
+ <varname>W-threads</varname>. Each
<varname>W-thread</varname> is mapped to one and only one
- <varname>U-process</varname>. All
+ <varname>U-process</varname>. All
<varname>U-processes</varname> of a same
<varname>W-process</varname> share the same address space.
</para>
@@ -64,17 +64,17 @@
</itemizedlist>
<para>
Each Windows' process has also a Windows' process id
- (<varname>wpid</varname> in the following). It must be clear
+ (<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
+ 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
+ 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>).
@@ -101,17 +101,17 @@
</listitem>
</itemizedlist>
<para>
- Wine implements most of the Windows' debugging API. The
+ Wine implements most of the Windows' debugging API. The
first part of the debugging APIs (in
<filename>KERNEL32.DLL</filename>) allows a W-process, called
the debugger, to control the execution of another W-process,
- the debuggee. To control means stopping/resuming execution,
+ the debuggee. To control means stopping/resuming execution,
enabling/disabling single stepping, setting breakpoints,
- reading/writing debuggee memory... Another part of the
+ reading/writing debuggee memory... Another part of the
debugging APIs resides in <filename>DBGHELP.DLL</filename>
(and its ancestor <filename>IMAGEHLP.DLL</filename>) and lets
a debugger look into symbols and types from any module (if
- the module has been compiled with the proper options).
+ the module has been compiled with the proper options).
</para>
<para>
<command>winedbg</command> is a Winelib application making
@@ -133,7 +133,7 @@
<para>
Any application (either a Windows' native executable, or a
Winelib application) can be run through
- <command>winedbg</command>. Command line options and tricks
+ <command>winedbg</command>. Command line options and tricks
are the same as for wine:
</para>
<screen>
@@ -148,13 +148,13 @@ winedbg hl.exe -windowed
<para>
<command>winedbg</command> can also be launched without any
command line argument: <command>winedbg</command> is started
- without any attached process. You can get a list of running
+ without any attached process. You can get a list of running
<varname>W-processes</varname> (and their
<varname>wpid</varname>'s) using the <command>info
process</command> command, and then, with the
<command>attach</command> command, pick up the
<varname>wpid</varname> of the <varname>W-process</varname>
- you want to debug. This is a neat feature as it allows you
+ you want to debug. This is a neat feature as it allows you
to debug an already started application.
</para>
</sect2>
@@ -164,23 +164,23 @@ winedbg hl.exe -windowed
<para>
When something goes wrong, Windows tracks this as an
- exception. Exceptions exist for segmentation violation,
+ exception. Exceptions exist for segmentation violation,
stack overflow, division by zero, etc.
</para>
<para>
When an exception occurs, Wine checks if the
- <varname>W-process</varname> is debugged. If so, 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
+ it: end of the story. This mechanism is part of the standard
Windows' debugging API.
</para>
<para>
If the <varname>W-process</varname> is not debugged, Wine
- tries to launch a debugger. This debugger (normally
+ tries to launch a debugger. This debugger (normally
<command>winedbg</command>, see III Configuration for more
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
+ 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.
@@ -215,9 +215,9 @@ winedbg hl.exe -windowed
<listitem>
<para>
the debugger couldn't correct the cause of the
- first chance exception. Wine will now try to walk
+ 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
+ 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.
@@ -230,7 +230,7 @@ winedbg hl.exe -windowed
since some of Wine's code uses exceptions and
<function>try/catch</function> blocks to provide some
functionality, <command>winedbg</command> can be entered
- in such cases with segv exceptions. This happens, for
+ 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
@@ -245,7 +245,7 @@ winedbg hl.exe -windowed
<para>
You can stop the debugger while it's running by hitting
- Ctrl-C in its window. This will stop the debugged process,
+ Ctrl-C in its window. This will stop the debugged process,
and let you manipulate the current context.
</para>
</sect2>
@@ -266,7 +266,7 @@ winedbg hl.exe -windowed
<title>Using the Wine Debugger</title>
<para>
- This section describes where to start debugging Wine. If at any
+ This section describes where to start debugging Wine. If at any
point you get stuck and want to ask for help, please read the
<emphasis>How to Report A Bug</emphasis> section of the
<emphasis>Wine Users Guide</emphasis> for information on how to write
@@ -307,7 +307,7 @@ winedbg hl.exe -windowed
|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
+ 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.
</para>
@@ -315,10 +315,10 @@ winedbg hl.exe -windowed
<orderedlist>
<listitem>
<para>
- Get the reason for the crash. This is usually an access to
+ Get the reason for the crash. This is usually an access to
an invalid selector, an access to an out of range address
in a valid selector, popping a segment register from the
- stack or the like. When reporting a crash, report this
+ stack or the like. When reporting a crash, report this
<emphasis>whole</emphasis> crashdump even if it doesn't
make sense to you.
</para>
@@ -330,10 +330,10 @@ winedbg hl.exe -windowed
</listitem>
<listitem>
<para>
- Determine the cause of the crash. Since this is usually
+ 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<parameter>WINEDEBUG=+relay</parameter>
- environment variable set. This will
+ Wine function, rerun Wine with the <parameter>WINEDEBUG=+relay</parameter>
+ environment variable set. This will
generate quite a lot of output, but usually the reason is
located in the last call(s). Those lines usually look like
this:
@@ -345,9 +345,9 @@ winedbg hl.exe -windowed
| | | | |Return address
| | | |textual parameter
| | |
- | | |Argument(s). This one is a win16 segmented pointer.
+ | | |Argument(s). This one is a win16 segmented pointer.
| |Function called.
- |The module, the function is called in. In this case it is KERNEL.
+ |The module, the function is called in. In this case it is KERNEL.
|Ret KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
^^^^^^
@@ -356,19 +356,19 @@ winedbg hl.exe -windowed
</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
+ 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 <function>WINE_DEFAULT_DEBUG_CHANNEL(<channel>);</function>
- at the beginning of the file. Rerun wine with the
+ at the beginning of the source file. Rerun wine with the
<parameter>WINEDEBUG=+xyz,+relay</parameter> environment variable set.
</para>
<para>
Occasionally there are additional debug channels defined at the
- beginning of the file in the form.
+ beginning of the source file in the form
<function>WINE_DECLARE_DEBUG_CHANNEL(<channel>);</function>
If so the offending function may also uses one of these alternate
- channels. Look through the the function for
+ channels. Look through the the function for
<function>TRACE_(<channel>)(" ... /n");</function> and add any
additional channels to the commandline.
</para>
@@ -385,37 +385,41 @@ winedbg hl.exe -windowed
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 <parameter>WINEDEBUG=+all</parameter>,
- which dumps ALL included debug
- information in wine.
+ 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 <command>grep</command>,
+ or alternatively with the registry value RelayExclude located
+ under
+ <programlisting>HKCU\\Software\\Wine\\Debug</programlisting>.
</para>
</listitem>
<listitem>
<para>
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
+ 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 <command>gdb</command>
- instead of using the Wine debugger. If you do that, use
+ instead of using the Wine debugger. If you do that, use
<parameter>handle SIGSEGV nostop noprint</parameter> to
disable the handling of seg faults inside
- <command>gdb</command> (needed for Win16).
+ <command>gdb</command> (needed for Win16).
</para>
</listitem>
<listitem>
<para>
- 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
+ You can also set a breakpoint for that function. Start wine
+ using <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
- program-execution. Wine will stop if it reaches the
- breakpoint. If the program isn't yet at the crashing call
+ 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
+ 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
+ the point of crash. Use the other debugger commands to
print registers and the like.
</para>
</listitem>
@@ -427,11 +431,11 @@ winedbg hl.exe -windowed
<para>
Start the program with <command>winedbg</command> instead of
- <command>wine</command>. When the program locks up switch to the
+ <command>wine</command>. When the program locks up switch to the
winedbg's terminal and press
- <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>. this
+ <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.
+ a crash.
</para>
</sect2>
@@ -440,8 +444,8 @@ winedbg hl.exe -windowed
<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
+ 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>
@@ -450,9 +454,9 @@ winedbg hl.exe -windowed
the Messagebox you can start winedbg and set a
breakpoint at <function>MessageBoxA</function> (called by win16
and win32 programs) and proceed with
- <command>continue</command>. With <parameter>WINEDEBUG=+all</parameter>
+ <command>continue</command>. With <parameter>WINEDEBUG=+all</parameter>
Wine will now stop directly before setting
- up the Messagebox. Proceed as explained above.
+ up the Messagebox. Proceed as explained above.
</para>
<para>
You can also run wine using <command>WINEDEBUG=+relay wine
@@ -471,25 +475,45 @@ winedbg hl.exe -windowed
<para>
The best, freely available, disassembler for Win16 programs is
<application>Windows Codeback</application>, archive name
- <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</>).
+ <filename>wcbxxx.zip</> (e.g. <filename>wcb105a.zip</>).
</para>
<para>
Disassembling win32 programs is possible using
- <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</>
- 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.
+ eg. <application>GoVest</> by Ansgar Trimborn. It can be found
+ <ulink url="http://www.geocities.com/GoVest/">here</>.
</para>
<para>
+ Another popular disassembler is
+ <application>Windows Disassembler 32</> from URSoft.
+ Look for a file called <filename>w32dsm87.zip</> (or similar) on
+ <ulink url="http://www.winsite.com/">winsite.com</> or
+ <ulink url="http://www.softpedia.com/">softpedia.com</>.
+ </para>
+ <para>
+ You can also use the newer (and in the full version better)
+ <application>Interactive Disassembler</> (IDA) from
+ DataRescue. The version of IDA that has been most actively used by
+ Wine project enthusiasts is named <filename>ida35bx.zip</filename>,
+ although that version now seems impossible to locate. Take a look
+ in the 'useful programs' section later on for links to working
+ versions of IDA.
+ </para>
+ <para>
+ Also of considerable fame amongst disassemblers is
+ <application>SoftIce</> from NuMega. That software has since been
+ acquired by CompuWare (http://www.compuware.com/) 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.
+ </para>
+ <para>
+ If nothing works for you, try one of the disassemblers found in
+ <ulink url="http://directory.google.com/Top/Computers/Programming/Disassemblers/DOS_and_Windows/">Google's directory</>.
+ </para>
+ <para>
+ 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
+ is usually written in C). Win16 function entries usually
look like that:
</para>
<programlisting>
@@ -500,11 +524,11 @@ retf XXXX <--------- XXXX is number
</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
+ 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
+ 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>
@@ -522,7 +546,7 @@ retf XXXX
<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
+ accessed using <literal>[bp-xx]</literal>. Before calling a
function, arguments are pushed on the stack using something
like this:
</para>
@@ -631,7 +655,7 @@ 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
+ 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>
@@ -649,7 +673,7 @@ Wine-dbg>
<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
+ start code, then you may use a special trick. You should do a
<programlisting>
WINEDEBUG=+relay wine program
</programlisting>
@@ -660,12 +684,12 @@ winedbg winfile.exe
</programlisting>
</para>
<para>
- This way, you get into <command>winedbg</command>. Now you
+ This way, you get into <command>winedbg</command>. Now you
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
+ called by the crashing start function. Now you can proceed
with your debugging as usual.
</para>
</listitem>
@@ -679,7 +703,7 @@ winedbg winfile.exe
WINEDEBUG=+relay wine <program name> &>relmsg
</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
+ 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>
@@ -718,7 +742,7 @@ Call USER.1: MESSAGEBOX(0x0000,0x01ff124
<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
+ 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>:
@@ -729,15 +753,15 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret=
</para>
<para>
Provided that segment <literal>0x0004</literal> is indeed segment
- <literal>0x1cf</literal>, we now we can use IDA (available at
- <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
- 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>).
+ <literal>0x1cf</literal>, 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 <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>
@@ -761,15 +785,39 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret=
<variablelist>
<varlistentry>
<term>
+ <application>GoVest</application>:
+ <filename>govest.zip</filename> is available from
+ <ulink url="http://www.geocities.com/GoVest/">http://www.geocities.com/GoVest/</>.
+ </term>
+ <listitem>
+ <para>
+ The win32 disassembler that currently works
+ the best with Wine.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
<application>IDA</application>:
- <filename>
- <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>
- </filename>
+ <filename>ida35bx.zip</filename> is near impossible to
+ locate, but you might try a trial version of the new IDA Pro
+ from
+ <ulink url="http://www.datarescue.com/">http://www.datarescue.com</ulink>
+ or try locating the free version of IDA Pro 4.3 by
+ <ulink url="http://www.google.com/search?q=%22IDA+Pro+freeware%22+4.3">Googling</>.
+ The newer versions mentioned above currently has problems
+ installing under Wine. In the mean time, you can use the
+ free version of IDA Pro 3.85b, which you can also find by
+ <ulink url="http://www.google.com/search?q=IDA+Pro+freeware+3.85b">Googling</>.
+ Version 3.85b does not have a GUI. It does have a textual
+ interface, which currently has problems launching under
+ Wine. To get it to launch correctly, start it with
+ <application>winedbg</> instead of <application>wine</>.
+ Remember to 'c'ontinue the program after starting it.
</term>
<listitem>
<para>
- <emphasis>Very</emphasis> good DOS disassembler ! It's badly needed
+ <emphasis>Very</emphasis> good DOS disassembler! It's badly needed
for debugging Wine sometimes.
</para>
</listitem>
@@ -784,7 +832,7 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret=
</term>
<listitem>
<para>
- Traces DOS calls (Int 21h, DPMI, ...). Use it with
+ Traces DOS calls (Int 21h, DPMI, ...). Use it with
Windows to correct file management problems etc.
</para>
</listitem>
@@ -827,11 +875,11 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret=
After starting your program with
</para>
<screen>
-wine -debug myprog.exe
+winedbg myprog.exe
</screen>
<para>
the program loads and you get a prompt at the program
- starting point. Then you can set breakpoints:
+ starting point. Then you can set breakpoints:
</para>
<screen>
b RoutineName (by routine name) OR
@@ -839,7 +887,7 @@ wine -debug myprog.exe
</screen>
<para>
Then you hit <command>c</command> (continue) to run the
- program. It stops at the breakpoint. You can type
+ program. It stops at the breakpoint. You can type
</para>
<screen>
step (to step one line) OR
@@ -898,7 +946,7 @@ wine -debug myprog.exe
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
+ 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
@@ -951,17 +999,17 @@ wine -debug myprog.exe
<title>Configuration</title>
<sect2>
- <title>Registry configuration</title>
+ <title>Windows Debugging configuration</title>
<para>
The Windows' debugging API uses a registry entry to know
which debugger to invoke when an unhandled exception occurs
(see <link endterm="dbg-exception-title"
- linkend="dbg-on-exception"></link> for some details). Two
+ linkend="dbg-on-exception"></link> for some details). Two
values in key
</para>
<programlisting>
-"MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
+[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
</programlisting>
<para>
Determine the behavior:
@@ -971,16 +1019,16 @@ wine -debug myprog.exe
<term>Debugger</term>
<listitem>
<para>
- this is the command line used to launch the debugger
+ 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
+ information to the debugger). You should put here a
complete path to your debugger
(<command>winedbg</command> can of course be used, but
- any other Windows' debugging API aware debugger will
- do).
- The path to the debugger you chose to use must be reachable
- via a DOS drive in the Wine config file !
+ 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 /dosdevices in
+ your $WINEPREFIX or ~/.wine folder.
</para>
</listitem>
</varlistentry>
@@ -990,7 +1038,7 @@ wine -debug myprog.exe
<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
+ unhandled exception occurs. Otherwise, the debugger
is automatically started.
</para>
</listitem>
@@ -1009,7 +1057,7 @@ wine -debug myprog.exe
<note>
<title>Note 1</title>
<para>
- creating this key is mandatory. Not doing so will not
+ creating this key is mandatory. Not doing so will not
fire the debugger when an exception occurs.
</para>
</note>
@@ -1037,8 +1085,8 @@ wine -debug myprog.exe
<para>
<command>winedbg</command> can be configured through a number
- of options. Those options are stored in the registry, on a
- per user basis. The key is (in <emphasis>my</emphasis> registry)
+ of options. Those options are stored in the registry, on a
+ per user basis. The key is (in <emphasis>my</emphasis> registry)
</para>
<programlisting>
[HKCU\\Software\\Wine\\WineDbg]
@@ -1046,8 +1094,8 @@ wine -debug myprog.exe
<para>
Those options can be read/written while inside
<command>winedbg</command>, as part of the debugger
- expressions. To refer to one of these options, its name must
- be prefixed by a <literal>$</literal> sign. For example,
+ expressions. To refer to one of these options, its name must
+ be prefixed by a <literal>$</literal> sign. For example,
</para>
<programlisting>
set $BreakAllThreadsStartup = 1
@@ -1077,7 +1125,7 @@ set $BreakAllThreadsStartup = 1
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.
+ stops. <literal>FALSE</literal> by default.
</para>
</listitem>
</varlistentry>
@@ -1099,7 +1147,7 @@ set $BreakAllThreadsStartup = 1
<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
+ 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
@@ -1111,19 +1159,19 @@ set $BreakAllThreadsStartup = 1
<term><varname>BreakOnFirstChance</varname></term>
<listitem>
<para>
- An exception can generate two debug events. The first
+ 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
+ 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
+ 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
+ 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
@@ -1138,7 +1186,7 @@ set $BreakAllThreadsStartup = 1
<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
+ 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.
@@ -1147,6 +1195,49 @@ set $BreakAllThreadsStartup = 1
</varlistentry>
</variablelist>
</sect2>
+
+ <sect2>
+ <title>Configuring +relay behaviour</title>
+ <para>
+ When setting <parameter>WINEDEBUG</> to +relay and debugging,
+ you might get a lot of output. You can limit the output by
+ configuring the value RelayExclude in the registry, located
+ under the key:
+ </para>
+ <programlisting>
+ [HKCU\\Software\\Wine\\Debug]
+ </programlisting>
+ <para>
+ Set the value of RelayExclude to a semicolon-separated list of
+ calls to exclude. Example:
+ "RtlEnterCriticalSection;RtlLeaveCriticalSection;kernel32.97;kernel32.98".
+ </para>
+ <para>
+ RelayInclude is an option similar to RelayExclude, except that
+ functions listed here will be the only ones included in the output.
+ Also see section 3.4.3.5 for more options.
+ </para>
+ <para>
+ If your application runs too slow with +relay 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 it's output
+ to a file on disk:
+ </para>
+ <programlisting>
+ WINEDEBUG=+relay wine <appname.exe> &>relay.log
+ </programlisting>
+ <para>
+ Then run this command to see which calls are performed the most:
+ </para>
+ <programlisting>
+ awk -F'(' '{print $1}' < relay.log | awk '{print $2}' | sort | uniq -c | sort
+ </programlisting>
+ <para>
+ Exclude the bottom-most calls with RelayExclude after making
+ sure that they are irrelevant and run your application again.
+ </para>
+ </sect2>
</sect1>
<sect1 id="dbg-expr">
@@ -1156,11 +1247,11 @@ set $BreakAllThreadsStartup = 1
<para>
Expressions in Wine Debugger are mostly written in a C
- form. However, there are a few discrepancies:
+ form. However, there are a few discrepancies:
<itemizedlist>
<listitem>
<para>
- Identifiers can take a '!' in their names. This allow
+ Identifiers can take a '!' in their names. This allow
mainly to access symbols from different DLLs like
<function>USER32!CreateWindowExA</function>.
</para>
@@ -1169,7 +1260,7 @@ set $BreakAllThreadsStartup = 1
<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).
+ <type>union</type> keyword (even if your program uses a typedef).
</para>
</listitem>
</itemizedlist>
@@ -1177,7 +1268,7 @@ set $BreakAllThreadsStartup = 1
<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
+ for the symbol you want to use. Pick up the one you want
from its number.
</para>
<para>
@@ -1186,8 +1277,8 @@ set $BreakAllThreadsStartup = 1
</para>
<para>
<command>winedbg</command> defines its own set of
- variables. The configuration variables from above are part
- of them. Some others include:
+ variables. The configuration variables from above are part
+ of them. Some others include:
<variablelist>
<varlistentry>
<term><varname>$ThreadId</varname></term>
@@ -1212,7 +1303,7 @@ set $BreakAllThreadsStartup = 1
<listitem>
<para>
All CPU registers are also available, using $ as a
- prefix. You can use <command>info regs</command> to
+ prefix. You can use <command>info regs</command> to
get a list of avaible CPU registers
</para>
</listitem>
@@ -1250,8 +1341,8 @@ set $BreakAllThreadsStartup = 1
<entry><command>attach 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
+ or hexadecimal (0xN)). IDs can be obtained using
+ the info process command. Note the info process
command returns hexadecimal values.
</entry>
</row>
@@ -1373,7 +1464,7 @@ set $BreakAllThreadsStartup = 1
<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.
+ meaning that the command must be executed N times.
</para>
</sect2>
@@ -1410,8 +1501,8 @@ set $BreakAllThreadsStartup = 1
</entry>
<entry>
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,
+ N. <expr> will be evaluated each time the
+ breakpoint is hit. If the result is a zero value,
the breakpoint isn't triggered
</entry>
</row>
@@ -1478,7 +1569,7 @@ set $BreakAllThreadsStartup = 1
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).
+ new module is loaded (until it succeeds).
</para>
</sect2>
@@ -1643,7 +1734,7 @@ set $BreakAllThreadsStartup = 1
<para>
You can specify the end target (to change the 10 lines
- value) using the ','. For example:
+ value) using the ','. For example:
<table>
<title>WineDbg's list command examples</title>
<tgroup cols="2" align="left">
@@ -1678,7 +1769,7 @@ set $BreakAllThreadsStartup = 1
</para>
<para>
<command>winedbg</command> will automatically detect if the
- expression you entered contains a local variable. If so,
+ 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.
@@ -1719,7 +1810,7 @@ set $BreakAllThreadsStartup = 1
</entry>
<entry>
adds a display for expression
- <expr>. Printing evaluated <expr> is
+ <expr>. Printing evaluated <expr> is
done using the given format (see
<command>print</command> command for more on
formats)
@@ -2054,11 +2145,11 @@ set $BreakAllThreadsStartup = 1
<title>GDB mode</title>
<para>
- WineDbg can act as a remote monitor for GDB. This allows to
+ 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
+ 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
(not WineDbg's).
</para>
@@ -2076,7 +2167,7 @@ set $BreakAllThreadsStartup = 1
<para>
Moreover, it also provides support for the Dwarf II
debug format (which became the default format (instead
- of stabs) in gcc 3.1).
+ of stabs) in gcc 3.1).
</para>
</listitem>
</itemizedlist>
@@ -2157,7 +2248,7 @@ set $BreakAllThreadsStartup = 1
</para>
</listitem>
</orderedlist>
- The program should now be loaded and up and running. If
+ 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
</para>
@@ -2193,7 +2284,7 @@ kdbg -r localhost:32878 wine
</para>
</listitem>
</orderedlist>
- The program should now be loaded and up and running. If
+ 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
</para>
@@ -2229,7 +2320,7 @@ kdbg -r localhost:32878 wine
<listitem>
<para>
Wine is running on the pthread model (it won't work
- in the kthread one). See the Wine architecture
+ in the kthread one). See the Wine architecture
documentation for further details.
</para>
</listitem>
@@ -2261,7 +2352,7 @@ $ gdb wine
</screen>
<para>
Switch to another console and enter <command>ps ax | grep
- wine</command> to find all wine processes. Inside
+ wine</command> to find all wine processes. Inside
<command>gdb</command>, repeat for all Wine processes:
</para>
<screen>
@@ -2313,9 +2404,9 @@ $ gdb wine
<para>
You can use any Windows' debugging API compliant debugger
- with Wine. Some reports have been made of success with
+ 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.
+ in Wine). GoVest fully runs in Wine.
</para>
</sect2>
More information about the wine-cvs
mailing list