From 019c591da8c4248ec82b772e966869f2569bfe42 Mon Sep 17 00:00:00 2001 From: Tony Lambregts Date: Wed, 3 Jul 2002 01:20:46 +0000 Subject: [PATCH] Document the new trace-related winedbg commands. --- documentation/debugger.sgml | 72 +++++++++++++++++++++--------------- documentation/debugging.sgml | 46 +++++++++++++---------- 2 files changed, 68 insertions(+), 50 deletions(-) diff --git a/documentation/debugger.sgml b/documentation/debugger.sgml index 5c0e48031a1..607227326cb 100644 --- a/documentation/debugger.sgml +++ b/documentation/debugger.sgml @@ -143,7 +143,7 @@ winedbg "hl.exe -windowed" attach command, pick up the wpid of the W-process you want to debug. This is (for now) a neat feature for the - following reasons: + following reasons: @@ -164,7 +164,7 @@ winedbg "hl.exe -windowed" When an exception occurs, Wine checks if the W-process 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. If the W-process 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 --debug switch and then you can get into - internal debugger by pressing + internal debugger by pressing CtrlC in the terminal where you run Wine. @@ -535,7 +535,7 @@ call KERNEL.LSTRLEN Let's debug the infamous Word SHARE.EXE - messagebox: + messagebox: |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 - + And MessageBox'ed. @@ -754,7 +754,7 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff - IDA: + IDA: ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip @@ -1041,7 +1041,7 @@ wine -debug myprog.exe Those options can be read/written while inside WineDbg, as part of the debugger expressions. To refer to one of these options, its name must - be prefixed by a $ sign. For example, + be prefixed by a $ sign. For example, set $BreakAllThreadsStartup = 1 @@ -1134,8 +1134,8 @@ set $BreakAllThreadsStartup = 1 Set to TRUE 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. FALSE by default. @@ -1152,7 +1152,7 @@ set $BreakAllThreadsStartup = 1 ConChannelMask - Mask of active debugger output channels on console + Mask of active debugger output channels on console @@ -1213,7 +1213,7 @@ UseXTerm = 1 Those variables also allow, for example for debugging - purposes, to use: + purposes, to use: ConChannelMask = 0xfff @@ -1233,7 +1233,7 @@ UseXTerm = 1 on. - + Context information @@ -1300,11 +1300,11 @@ mode 32 switch to 32 bit mode 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) - 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. - 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 G:\AnyPath\MyDll.dll). - You can use the symbol EntryPoint to stand for + You can use the symbol EntryPoint to stand for the entry point of the Dll. @@ -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 @@ -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> /fmt is either /<letter> or - /<count><letter> letter can be + /<count><letter> letter can be 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 Expressions - + 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 - 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...). @@ -1514,10 +1514,22 @@ b => 8 bit unsigned hexadecimal integer + + debug messages + + It is possible to turn on and off debug messages as you are debuging using + the set command. + + +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 + + - Other debuggers diff --git a/documentation/debugging.sgml b/documentation/debugging.sgml index 5868bcccc91..32db007cf6e 100644 --- a/documentation/debugging.sgml +++ b/documentation/debugging.sgml @@ -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. + + + + 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. @@ -25,7 +31,7 @@ fprintf (or printf) to output things. Also, instead of writing FIXMEs in the source, output a FIXME message if - you can. + you can. At the end of the document, there is a "Style Guide" for @@ -46,7 +52,7 @@ 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. Examples: stubs, semi-implemented features, etc. @@ -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. 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. 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 */ } @@ -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)) name the string EXACTLY like the debugging channel on which is going to be output. Please see the above - example. + example. @@ -566,7 +572,7 @@ LPSTR debugres(const void *id); --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); 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. This feature has not been extensively tested--it may subtly @@ -631,7 +637,7 @@ LPSTR debugres(const void *id); 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: 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: YYY(xxx, "(%d,%p,etc)...\n", par1, par2, ...); @@ -721,7 +727,7 @@ FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name); HANDLE32 WINAPI YourFunc(LPCSTR s) { - FIXME(xxx, "(%s): stub\n", debugstr_a(s)); + FIXME(xxx, "(%s): stub\n", debugstr_a(s)); } @@ -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 ) MSG macro. Use it like a printf: -MSG( "Definition of drive %d is incorrect!\n", drive ); +MSG( "Definition of drive %d is incorrect!\n", drive ); However, note that there are very few valid uses of this macro. Most messages are debugging