diff --git a/documentation/debugging.sgml b/documentation/debugging.sgml index f6655a0af75..1fd6c602395 100644 --- a/documentation/debugging.sgml +++ b/documentation/debugging.sgml @@ -1,33 +1,36 @@ Debug Logging - - Written by &name-dimitrie-paun; &email-dimitrie-paun;, 28 Mar 1998 - - - (Extracted from wine/documentation/debug-msgs) - - - - It is possible to turn on and of debugging output from - within the debugger using the set command. Please see the - WineDbg Command Reference section for how to do this. + To better manage the large volume of debugging messages that + Wine can generate, we divide the messages on a component basis, + and classify them based on the severity of the reported problem. + Therefore a message belongs to a channel + and a class respectively. + + + This section will describe the debugging classes, how you can + create a new debugging channel, what the debugging API is, + and how you can control the debugging output. A picture is + worth a thousand words, so here are a few examples of the + debugging API in action: + +ERR("lock_count == 0 ... please report\n"); +FIXME("Unsupported RTL style!\n"); +WARN(": file seems to be truncated!\n"); +TRACE("[%p]: new horz extent = %d\n", hwnd, extent ); +MESSAGE( "Could not create graphics driver '%s'\n", buffer ); + - - - - - At the end of the document, there is a "Style Guide" for - debugging messages. Please read it. - - Debugging classes - There are 4 types (or classes) of messages: + A debugging class categorizes a message based on the severity + of the reported problem. There is a fixed set of classes, and + you must carefuly choose the appropriate one for your messages. + There are five classes of messages: @@ -38,22 +41,15 @@ features, known bugs, etc. They serve as a constant and active reminder of what needs to be done. - - Examples: stubs, semi-implemented features, etc. - ERR - Messages in this class relate to serious errors in - Wine. This sort of messages signal an inconsistent - internal state, or more general, a condition which - should never happen by design. - - - Examples: unexpected change in internal state, etc. + Messages in this class indicate serious errors in + Wine, such as as conditions that should never happen + by design. @@ -62,15 +58,11 @@ These are warning messages. You should report a - warning when something unwanted happen but the - function behaves properly. That is, output a warning - 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. - - - Examples: fail to access a resource required by the app. + warning when something unwanted happens, and the + function can not deal with the condition. This + is seldomly used since proper functions can usually + report failures back to the caller. Think twice before + making the message a warning. @@ -79,13 +71,18 @@ These are detailed debugging messages that are mainly - useful to debug a component. These are usually turned - off. + useful to debug a component. These are turned off unless + explicitly enabled. + + + + MESSAGE + - Examples: everything else that does not fall in one of - the above mentioned categories and the user does not - need to know about it. + There messages are intended for the end user. They do not + belong to any channel. As with warnings, you will seldomly + need to output such messages. @@ -96,35 +93,18 @@ Debugging channels - To better manage the large volume of debugging messages that - Wine can generate, we divide them also on a component basis. Each component is assigned a debugging channel. The - identifier of the channel must be a valid C identifier but - note that it may also be a reserved word like - int or static. + identifier of the channel must be a valid C identifier + (reserved word like int or static + are premitted). To use a new channel, simply use it in + your code. It will be picked up automatically by the build process. - - Examples of debugging channels: - - reg - updown - string - - - - We will refer to a generic channel as xxx. - - - - - How to use it Typically, a file contains code pertaining to only one component, - and as such, there is only one channel to output to. To simplify - usage, you can declare that channel at the beginning of the file, - and simply write FIXMEs, ERRs, etc. as such: - + and as such, there is only one channel to output to. You can declare + a default chanel for the file using the + WINE_DEFAULT_DEBUG_CHANNEL() macro: #include "wine/debug.h" @@ -160,48 +140,29 @@ WINE_DECLARE_DEBUG_CHANNEL(zzz); - - If you need to declare a new debugging channel, simply use it in - your code. It will be picked up automatically by the build process. - - Are we debugging? - To test whether the debugging output of class - yyy on channel xxx is - enabled, use: - - -TRACE_ON to test if TRACE is enabled -WARN_ON to test if WARN is enabled -FIXME_ON to test if FIXME is enabled -ERR_ON to test if ERR is enabled - - - Examples: - + To test whether the debugging channel xxx is + enabled, use the TRACE_ON, WARN_ON, + FIXME_ON, or ERR_ON macros. For + example: if(TRACE_ON(atom)){ - ...blah... + ...blah... } - - - - You should normally need to test only if - TRACE_ON. At present, none of the other - 3 tests (except for ERR_ON which is - used only once!) are used in Wine. - - + You should normally need to test only if TRACE_ON, + all the others are very seldomly used. With careful coding, you + can avoid the use of these macros, which is generally desired. + - - Resource identifiers + + Helper functions Resource identifiers can be either strings or numbers. To @@ -241,10 +202,32 @@ LPSTR debugres(const void *id); TRACE("resource is %s", debugres(myresource)); + + + Many times strings need to be massaged before output: + they may be NULL, contain control + characters, or they may be too long. Similarly, Unicode + strings need to be converted to ASCII for usage with + the debugging API. For all this, you can use the + debugstr_[aw]n? familly of functions: + +HANDLE32 WINAPI YourFunc(LPCSTR s) +{ + FIXME("(%s): stub\n", debugstr_a(s)); +} + + + - - The <parameter>--debugmsg</parameter> command line option + + Controlling the debugging output + + + It is possible to turn on and off debugging output from + within the debugger using the set command. Please see the + WineDbg Command Reference section for how to do this. + The --debugmsg command line @@ -385,7 +368,7 @@ where: - do NOT include the name of the function: it is included automatically + do not include the name of the function: it is included automatically @@ -418,99 +401,10 @@ FIXME("(%x, %d, ...): stub\n", par1, par2, ...); - if you want to name a value, use = and - NOT :. That is, instead of saying: - -FIXME("(fd: %d, file: %s): stub\n", fd, name); - - say: + if you want to name a parameter, use = : FIXME("(fd=%d, file=%s): stub\n", fd, name); - use : to separate categories. - - - - - try to avoid the style: - -FIXME(xxx, "(fd=%d, file=%s)\n", fd, name); - - instead use: - -FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name); - - The reason is that if you want to grep - for things, you would search for FIXME - but in the first case there is no additional information - available, where in the second one, there is (e.g. the word - stub) - - - - - if you output a string s that might contain control - characters, or if s may be - NULL, use - debugstr_a (for ASCII strings, or - debugstr_w for Unicode strings) to - convert s to a C string, like this: - -HANDLE32 WINAPI YourFunc(LPCSTR s) -{ - FIXME("(%s): stub\n", debugstr_a(s)); -} - - - - - - if you want to output a resource identifier, use debugres to - convert it to a string first, like this: - -HANDLE32 WINAPI YourFunc(LPCSTR res) -{ - FIXME("(res=%s): stub\n", debugres(s)); -} - - if the resource identifier is a SEGPTR, use - PTR_SEG_TO_LIN to get a - liner pointer first: - -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)), - debugres(PTR_SEG_TO_LIN(type)) ); -[...] -} - - - - - - for messages intended for the user (specifically those that - report errors in the wine config file), use the - MSG macro. Use it like a - printf: - -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 - messages, so chances are you will not need to use this - macro. Grep the source to get an idea where it is - appropriate to use it. - - - - - For structure dumps, use the DUMP - macro. Use it like a printf, just like - the MSG macro. Similarly, there are only - a few valid uses of this macro. Grep the source to see when - to use it.