mirror of
https://github.com/reactos/wine.git
synced 2024-11-24 20:30:01 +00:00
Document the new trace-related winedbg commands.
This commit is contained in:
Tony Lambregts
Alexandre Julliard
parent
2e38a17021
commit
019c591da8
@ -143,7 +143,7 @@ winedbg "hl.exe -windowed"
|
||||
<command>attach</command> command, pick up the
|
||||
<varname>wpid</varname> of the <varname>W-process</varname>
|
||||
you want to debug. This is (for now) a neat feature for the
|
||||
following reasons:
|
||||
following reasons:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
@ -164,7 +164,7 @@ winedbg "hl.exe -windowed"
|
||||
When an exception occurs, Wine checks if the <varname>W-process</varname> is
|
||||
debugged. If so, the exception event is sent to the
|
||||
debugger, which takes care of it: end of the story. This
|
||||
mechanism is part of the standard Windows' debugging API.
|
||||
mechanism is part of the standard Windows' debugging API.
|
||||
</para>
|
||||
<para>
|
||||
If the <varname>W-process</varname> is not debugged, Wine
|
||||
@ -341,7 +341,7 @@ winedbg "hl.exe -windowed"
|
||||
| | |Argument(s). This one is a win16 segmented pointer.
|
||||
| |Function called.
|
||||
|The module, the function is called in. In this case it is KERNEL.
|
||||
|
||||
|
||||
|Ret KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
|
||||
^^^^^^
|
||||
|Returnvalue is 16 bit and has the value 4.
|
||||
@ -421,7 +421,7 @@ winedbg "hl.exe -windowed"
|
||||
then enter its internal debugger and you can proceed as
|
||||
explained above. Also, you can use
|
||||
<parameter>--debug</parameter> switch and then you can get into
|
||||
internal debugger by pressing
|
||||
internal debugger by pressing
|
||||
<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> in
|
||||
the terminal where you run Wine.
|
||||
</para>
|
||||
@ -535,7 +535,7 @@ call KERNEL.LSTRLEN
|
||||
|
||||
<para>
|
||||
Let's debug the infamous Word <filename>SHARE.EXE</filename>
|
||||
messagebox:
|
||||
messagebox:
|
||||
</para>
|
||||
<screen>
|
||||
|marcus@jet $ wine winword.exe
|
||||
@ -612,7 +612,7 @@ call KERNEL.LSTRLEN
|
||||
^^^^^^ HFILE_ERROR16, yes, it failed.
|
||||
|
||||
|Call USER.1: MESSAGEBOX(0x0000,0x09278376"Sie mussen Windows verlassen und SHARE.EXE laden bevor Sie Word starten.",0x00000000,0x1030) ret=060f:084f ds=0927
|
||||
</screen>
|
||||
</screen>
|
||||
<para>
|
||||
And MessageBox'ed.
|
||||
</para>
|
||||
@ -754,7 +754,7 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<application>IDA</application>:
|
||||
<application>IDA</application>:
|
||||
<filename>
|
||||
<ulink url="ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip">
|
||||
ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip</ulink>
|
||||
@ -1041,7 +1041,7 @@ wine -debug myprog.exe
|
||||
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,
|
||||
be prefixed by a <literal>$</literal> sign. For example,
|
||||
</para>
|
||||
<programlisting>
|
||||
set $BreakAllThreadsStartup = 1
|
||||
@ -1134,8 +1134,8 @@ set $BreakAllThreadsStartup = 1
|
||||
<listitem>
|
||||
<para>
|
||||
Set to <literal>TRUE</literal> if the debugger stops
|
||||
when a DLL is loaded into memory; when the debugger
|
||||
is invoked after a crash, the DLLs already mapped in
|
||||
when a DLL is loaded into memory; when the debugger
|
||||
is invoked after a crash, the DLLs already mapped in
|
||||
memory will not trigger this break.
|
||||
<literal>FALSE</literal> by default.
|
||||
</para>
|
||||
@ -1152,7 +1152,7 @@ set $BreakAllThreadsStartup = 1
|
||||
<term><varname>ConChannelMask</varname></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Mask of active debugger output channels on console
|
||||
Mask of active debugger output channels on console
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@ -1213,7 +1213,7 @@ UseXTerm = 1
|
||||
</orderedlist>
|
||||
<para>
|
||||
Those variables also allow, for example for debugging
|
||||
purposes, to use:
|
||||
purposes, to use:
|
||||
</para>
|
||||
<screen>
|
||||
ConChannelMask = 0xfff
|
||||
@ -1233,7 +1233,7 @@ UseXTerm = 1
|
||||
on.
|
||||
</para>
|
||||
</sect3>
|
||||
|
||||
|
||||
<sect3>
|
||||
<title>Context information</title>
|
||||
|
||||
@ -1300,11 +1300,11 @@ mode 32 switch to 32 bit mode
|
||||
|
||||
<screen>
|
||||
cont continue execution until next breakpoint or exception.
|
||||
pass pass the exception event up to the filter chain.
|
||||
pass pass the exception event up to the filter chain.
|
||||
step continue execution until next C line of code (enters
|
||||
function call)
|
||||
next continue execution until next C line of code (doesn't
|
||||
enter function call)
|
||||
enter function call)
|
||||
stepi execute next assembly instruction (enters function
|
||||
call)
|
||||
nexti execute next assembly instruction (doesn't enter
|
||||
@ -1329,7 +1329,7 @@ cond N removes any a existing condition to (break|watch)point N
|
||||
cond 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
|
||||
triggered
|
||||
break * N adds a breakpoint at address N
|
||||
break <id> adds a breakpoint at the address of symbol <id>
|
||||
break <id> N adds a breakpoint at the address of symbol <id> (N ?)
|
||||
@ -1341,17 +1341,17 @@ watch <id> adds a watch command (on write) at the address of
|
||||
info break lists all (break|watch)points (with state)
|
||||
</screen>
|
||||
<para>
|
||||
When setting a breakpoint on an <id>, if several symbols with this
|
||||
<id> exist, the debugger will prompt for the symbol you want to use.
|
||||
When setting a breakpoint on an <id>, if several symbols with this
|
||||
<id> exist, the debugger will prompt for the symbol you want to use.
|
||||
Pick up the one you want from its number.
|
||||
</para>
|
||||
<para>
|
||||
Alternatively you can specify a DLL in the <id> (for example
|
||||
Alternatively you can specify a DLL in the <id> (for example
|
||||
MYDLL.DLL.myFunc for function myFunc of
|
||||
<filename>G:\AnyPath\MyDll.dll)</filename>.
|
||||
</para>
|
||||
<para>
|
||||
You can use the symbol <emphasis>EntryPoint</emphasis> to stand for
|
||||
You can use the symbol <emphasis>EntryPoint</emphasis> to stand for
|
||||
the entry point of the Dll.
|
||||
</para>
|
||||
</sect2>
|
||||
@ -1370,7 +1370,7 @@ dn goes down one frame in current thread's stack
|
||||
dn N goes down N frames in current thread's stack
|
||||
frame N set N as the current frame for current thread's stack
|
||||
info local prints information on local variables for current
|
||||
function
|
||||
function
|
||||
</screen>
|
||||
</sect2>
|
||||
|
||||
@ -1414,7 +1414,7 @@ list foo.c:1,56 lists source lines from line 1 up to 56 in file foo.c
|
||||
display lists the active displays
|
||||
info display (same as above command)
|
||||
display <expr> adds a display for expression <expr>
|
||||
display /fmt <expr> adds a display for expression <expr>. Printing
|
||||
display /fmt <expr> adds a display for expression <expr>. Printing
|
||||
evaluated <expr> is done using the given format (see
|
||||
print command for more on formats)
|
||||
del display N deletes display #N
|
||||
@ -1450,7 +1450,7 @@ info segment N prints information on segment N
|
||||
info segment lists all allocated segments
|
||||
info stack prints the values on top of the stack
|
||||
info map lists all virtual mappings used by the debugged
|
||||
program
|
||||
program
|
||||
info wnd N prints information of Window of handle N
|
||||
walk wnd lists all the window hierarchy starting from the
|
||||
desktop window
|
||||
@ -1470,13 +1470,13 @@ x <expr> examines memory at <expr> address
|
||||
x /fmt <expr> examines memory at <expr> address using format /fmt
|
||||
print <expr> prints the value of <expr> (possibly using its type)
|
||||
print /fmt <expr> prints the value of <expr> (possibly using its
|
||||
type)
|
||||
set <lval>=<expr> writes the value of <expr> in <lval>
|
||||
type)
|
||||
set <lval>=<expr> writes the value of <expr> in <lval>
|
||||
whatis <expr> prints the C type of expression <expr>
|
||||
</screen>
|
||||
<para>
|
||||
<filename>/fmt</filename> is either <filename>/<letter></filename> or
|
||||
<filename>/<count><letter></filename> letter can be
|
||||
<filename>/<count><letter></filename> letter can be
|
||||
</para>
|
||||
<screen>
|
||||
s => an ASCII string
|
||||
@ -1486,14 +1486,14 @@ x => 32 bit unsigned hexadecimal integer
|
||||
d => 32 bit signed decimal integer
|
||||
w => 16 bit unsigned hexadecimal integer
|
||||
c => character (only printable 0x20-0x7f are actually
|
||||
printed)
|
||||
printed)
|
||||
b => 8 bit unsigned hexadecimal integer
|
||||
</screen>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Expressions</title>
|
||||
|
||||
|
||||
<para>
|
||||
Expressions in Wine Debugger are mostly written in a C form. However, there
|
||||
are a few discrepancies:
|
||||
@ -1506,7 +1506,7 @@ b => 8 bit unsigned hexadecimal integer
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
The debugger will try to distinguish this writing with structure operations.
|
||||
The debugger will try to distinguish this writing with structure operations.
|
||||
Therefore, you can only use the previous writing in operations manipulating
|
||||
symbols ({break|watch}points, type information command...).
|
||||
</para>
|
||||
@ -1514,10 +1514,22 @@ b => 8 bit unsigned hexadecimal integer
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>debug messages</title>
|
||||
<para>
|
||||
It is possible to turn on and off debug messages as you are debuging using
|
||||
the set command.
|
||||
</para>
|
||||
<screen>
|
||||
set + warn win => turn on warn on 'win' channel
|
||||
set + win => turn on warn/fixme/err/trace on 'win' channel
|
||||
set - win => turn off warn/fixme/err/trace on 'win' channel
|
||||
set - fixme => turn off the 'fixme' class
|
||||
</screen>
|
||||
</sect2>
|
||||
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="dbg-others">
|
||||
<title>Other debuggers</title>
|
||||
|
||||
|
||||
@ -15,7 +15,13 @@
|
||||
construction functions. However, there is still a lot of
|
||||
work to be done to polish things up. To make my life
|
||||
easier, please follow the guidelines described in this
|
||||
document.
|
||||
document.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is possible to turn on and of debugging output from
|
||||
within the debuger using the set command. Please see the
|
||||
WineDbg Command Reference section for how to do this.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -25,7 +31,7 @@
|
||||
<function>fprintf</function> (or
|
||||
<function>printf</function>) to output things. Also, instead
|
||||
of writing FIXMEs in the source, output a FIXME message if
|
||||
you can.
|
||||
you can.
|
||||
</para>
|
||||
<para>
|
||||
At the end of the document, there is a "Style Guide" for
|
||||
@ -46,7 +52,7 @@
|
||||
<para>
|
||||
Messages in this class relate to behavior of Wine that
|
||||
does not correspond to standard Windows behavior and
|
||||
that should be fixed.
|
||||
that should be fixed.
|
||||
</para>
|
||||
<para>Examples: stubs, semi-implemented features, etc.</para>
|
||||
</listitem>
|
||||
@ -60,7 +66,7 @@
|
||||
that is, you should output an error message when the
|
||||
code detects a condition which should not happen. In
|
||||
other words, important things that are not warnings
|
||||
(see below), are errors.
|
||||
(see below), are errors.
|
||||
</para>
|
||||
<para>
|
||||
Examples: unexpected change in internal state, etc.
|
||||
@ -77,7 +83,7 @@
|
||||
when you encounter something unexpected (ex: could not
|
||||
open a file) but the function deals correctly with the
|
||||
situation (that is, according to the docs). If you do
|
||||
not deal correctly with it, output a fixme.
|
||||
not deal correctly with it, output a fixme.
|
||||
</para>
|
||||
<para>
|
||||
Examples: fail to access a resource required by the
|
||||
@ -368,11 +374,11 @@ void some_func(tabs)
|
||||
dbg_decl_str(listbox, 256); /* declare the string */
|
||||
|
||||
for (i = 0; i < descr->nb_tabs; i++) {
|
||||
descr->tabs[i] = *p++<<1;
|
||||
descr->tabs[i] = *p++<<1;
|
||||
if(TRACING(listbox)) /* write in it only if
|
||||
dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
|
||||
}
|
||||
TRACE(listbox, "Listbox %04x: settabstops %s",
|
||||
TRACE(listbox, "Listbox %04x: settabstops %s",
|
||||
wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
|
||||
}
|
||||
</programlisting>
|
||||
@ -388,21 +394,21 @@ void some_func(tabs)
|
||||
dbg_decl_str(listbox, 256); /* declare the string */
|
||||
|
||||
for (i = 0; i < descr->nb_tabs; i++) {
|
||||
descr->tabs[i] = *p++<<1;
|
||||
descr->tabs[i] = *p++<<1;
|
||||
if(TRACING(listbox)) /* write in it only if
|
||||
dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
|
||||
}
|
||||
TRACE(listbox, "Listbox %04x: settabstops %s\n",
|
||||
TRACE(listbox, "Listbox %04x: settabstops %s\n",
|
||||
wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
|
||||
|
||||
dbg_reset_str(listbox); /* !!!reset the string!!! */
|
||||
for (i = 0; i < descr->extrainfo_nr; i++) {
|
||||
descr->extrainfo = *p+1;
|
||||
descr->extrainfo = *p+1;
|
||||
if(TRACING(listbox)) /* write in it only if
|
||||
dsprintf(listbox,"%3d ",descr->extrainfo); /* we are gonna output it */
|
||||
}
|
||||
|
||||
TRACE(listbox, "Listbox %04x: extrainfo %s\n",
|
||||
TRACE(listbox, "Listbox %04x: extrainfo %s\n",
|
||||
wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
|
||||
|
||||
}
|
||||
@ -451,7 +457,7 @@ if(YYY(xxx))
|
||||
<para>
|
||||
name the string EXACTLY like the debugging channel on
|
||||
which is going to be output. Please see the above
|
||||
example.
|
||||
example.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
@ -566,7 +572,7 @@ LPSTR debugres(const void *id);
|
||||
</para>
|
||||
<screen>
|
||||
--debugmsg +all -- enables all debug messages
|
||||
--debugmsg -all -- disables all debug messages
|
||||
--debugmsg -all -- disables all debug messages
|
||||
--debugmsg yyy+all -- enables debug messages for class yyy on all
|
||||
channels.
|
||||
--debugmsg yyy-all -- disables debug messages for class yyy on all
|
||||
@ -611,7 +617,7 @@ LPSTR debugres(const void *id);
|
||||
<para>
|
||||
This will result in an executable that, when stripped, is
|
||||
about 15%-20% smaller. Note, however, that you will not be
|
||||
able to effectively debug Wine without these messages.
|
||||
able to effectively debug Wine without these messages.
|
||||
</para>
|
||||
<para>
|
||||
This feature has not been extensively tested--it may subtly
|
||||
@ -631,7 +637,7 @@ LPSTR debugres(const void *id);
|
||||
<screen>
|
||||
yyy:xxx:fff <message>
|
||||
|
||||
where:
|
||||
where:
|
||||
yyy = the class (fixme, err, warn, trace)
|
||||
xxx = the channel (atom, win, font, etc)
|
||||
fff = the function name
|
||||
@ -652,7 +658,7 @@ where:
|
||||
<para>
|
||||
if you want to output the parameters of the function, do
|
||||
it as the first thing and include them in parentheses,
|
||||
like this:
|
||||
like this:
|
||||
<programlisting>
|
||||
YYY(xxx, "(%d,%p,etc)...\n", par1, par2, ...);
|
||||
</programlisting>
|
||||
@ -721,7 +727,7 @@ FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);
|
||||
<programlisting>
|
||||
HANDLE32 WINAPI YourFunc(LPCSTR s)
|
||||
{
|
||||
FIXME(xxx, "(%s): stub\n", debugstr_a(s));
|
||||
FIXME(xxx, "(%s): stub\n", debugstr_a(s));
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
@ -743,8 +749,8 @@ HANDLE32 WINAPI YourFunc(LPCSTR res)
|
||||
HRSRC16 WINAPI FindResource16( HMODULE16 hModule, SEGPTR name, SEGPTR type )
|
||||
{
|
||||
[...]
|
||||
TRACE(resource, "module=%04x name=%s type=%s\n",
|
||||
hModule, debugres(PTR_SEG_TO_LIN(name)),
|
||||
TRACE(resource, "module=%04x name=%s type=%s\n",
|
||||
hModule, debugres(PTR_SEG_TO_LIN(name)),
|
||||
debugres(PTR_SEG_TO_LIN(type)) );
|
||||
[...]
|
||||
}
|
||||
@ -758,7 +764,7 @@ HRSRC16 WINAPI FindResource16( HMODULE16 hModule, SEGPTR name, SEGPTR type )
|
||||
<literal>MSG</literal> macro. Use it like a
|
||||
<function>printf</function>:
|
||||
<programlisting>
|
||||
MSG( "Definition of drive %d is incorrect!\n", drive );
|
||||
MSG( "Definition of drive %d is incorrect!\n", drive );
|
||||
</programlisting>
|
||||
However, note that there are <emphasis>very</emphasis> few
|
||||
valid uses of this macro. Most messages are debugging
|
||||
|
||||
Loading…
Reference in New Issue
Block a user