1 Note: The new debugging interface can be considered to be stable,
2 with the exception of the in-memory message construction functions.
3 However, there is still a lot of work to be done to polish
4 things up and to convert the remaining fprintf. To make my life
5 easier, please follow the guidelines described in this document.
7 Read this document before writing new code.
8 Also, DO NOT USE fprintf (or printf) to output things. All these
9 will have to be translated to the new interface and there are already
10 about 1000 of them! Also, instead of writing FIXMEs in the source,
11 output a FIXME message if you can.
13 IMPORTANT: at the end of the document, there is a "Style Guide"
14 for debugging messages. Please read it.
16 28 Mar 1998, Dimitrie O. Paun <dimi@cs.toronto.edu>
22 There are 4 types (or classes) of debugging messages:
24 FIXME -- Messages in this class relate to behavior of Wine that does
25 not correspond to standard Windows behavior and that should
27 Examples: stubs, semi-implemented features, etc.
29 ERR -- Messages in this class relate to serious errors in Wine.
30 This sort of messages are close to asserts -- that is,
31 you should output an error message when the code detects a
32 condition which should not happen. In other words, important
33 things that are not warnings (see below), are errors.
34 Examples: unexpected change in internal state, etc.
36 WARN -- These are warning messages. You should report a warning when
37 something unwanted happen but the function behaves properly.
38 That is, output a warning when you encounter something
39 unexpected (ex: could not open a file) but the function deals
40 correctly with the situation (that is, according to the docs).
41 If you do not deal correctly with it, output a fixme.
42 Examples: fail to access a resource required by the app, etc.
44 TRACE -- These are detailed debugging messages that are mainly useful
45 to debug a component. These are usually turned off.
46 Examples: everything else that does not fall in one of the
47 above mentioned categories and the user does not
48 need to know about it.
51 The user has the capability to turn on or off messages of a particular
52 type. You can expect the following patterns of usage (but note that
53 any combination is possible):
54 -- when you debug a component, all types (TRACE,WARN,ERR,FIXME)
56 -- during the pre-alpha (maybe alpha) stage of Wine, most likely
57 the TRACE class will be disabled by default, but all others
58 (WARN,ERR,FIXME) will be enabled by default.
59 -- when Wine will become stable, most likely the TRACE and WARN
60 classes will be disabled by default, but all ERRs and FIXMEs
62 -- in some installations that want the smallest footprint
63 and where the debug information is of no interest,
64 all classes may be disabled by default.
66 Of course, the user will have the runtime ability to override these
67 defaults. However, this ability may be turned off and certain classes
68 of messages may be completely disabled at compile time to reduce the
74 Also, we divide the debugging messages on a component basis. Each
75 component is assigned a debugging channel. The identifier of the
76 channel must be a valid C identifier but note that it may also be a
77 reserve word like int or static.
79 Examples of debugging channels:
82 We will refer to a generic channel as xxx.
84 Note: for those who know the old interface, the channel/type is
85 what followed the _ in the dprintf_xxx statements.
86 For example, to output a message on the debugging channel
87 reg in the old interface you would had to write:
89 dprintf_reg(stddeb, "Could not access key!\n");
91 In the new interface, we drop the stddeb as it is implicit.
92 However, we add an orthogonal piece of information to the
93 message: its class. This is very important as it will allow
94 us to selectively turn on or off certain messages based on the
95 type of information they report. For this reason it is essential
96 to choose the right class for the message.
97 Anyhow, suppose we figured that this message should belong
98 in the WARN class, so in the new interface, you write:
100 WARN(reg, "Could not access key!\n");
106 So, to output a message (class YYY) on channel xxx, do:
112 YYY(xxx, "<message>", ...);
115 Some examples from the code:
121 TRACE(crtdll, "CRTDLL_setbuf(file %p buf %p)", file, buf);
123 WARN(aspi, "Error opening device errno=%d", save_error);
126 If you need to declare a new debugging channel, use it in your code
129 in the root directory of Wine.
131 Note that this will result in almost complete recompilation of Wine.
134 1. Please pay attention to which class you assign the message.
135 There are only 4 classes, so it is not hard. The reason
136 it is important to get it right is that too much information
137 is no information. For example, if you put things into the
138 WARN class that should really be in the TRACE class, the
139 output will be too big and this will force the user to
140 turn warnings off. But this way he will fail to see the important
141 ones. Also, if you put warnings into the TRACE class lets say,
142 he will most likely miss those because usually the TRACE class
143 is turned off. A similar argument can be made if you mix any
145 2. All lines should end with a newline.If you can NOT output
146 everything that you want in the line with only one statement,
147 then you need to build the string in memory.
148 Please read the section below "In-memory messages" on the
149 preferred way to do it. PLEASE USE THAT INTERFACE TO BUILD
150 MESSAGES IN MEMORY. The reason is that we are not sure that
151 we like it and having everything in one format will facilitate
152 the (automatic) translation to a better interface.
159 To test whether the debugging output of class yyy on channel xxx is
162 TRACE_ON to test if TRACE is enabled
163 WARN_ON to test if WARN is enabled
164 FIXME_ON to test if FIXME is enabled
165 ERR_ON to test if ERR is enabled
173 Note that you should normally need to test only if TRACE_ON. At present,
174 none of the other 3 tests (except for ERR_ON which is used only once!)
180 If you NEED to build the message from multiple calls, you need to
181 build it in memory. To do that, you should use the following
184 - declare a string (where you are allowed to declare C variables)
186 dbg_decl_str(name, len);
187 where name is the name of the string (you should use the channel
188 name on which you are going to output it)
191 dsprintf(name, "<message>", ...);
192 which is just like a sprintf function but instead of a C string as
193 first parameter it takes the name you used to declare it.
195 - obtain a pointer to the string with:
198 - reset the string (if you want to reuse it with):
201 Example (modified from the code):
206 LPINT16 p = (LPINT16)tabs;
207 dbg_decl_str(listbox, 256); /* declare the string */
209 for (i = 0; i < descr->nb_tabs; i++) {
210 descr->tabs[i] = *p++<<1;
211 if(TRACING(listbox)) /* write in it only if
212 dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
214 TRACE(listbox, "Listbox %04x: settabstops %s",
215 wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
218 If you need to use it two times in the same scope do like this:
223 LPINT16 p = (LPINT16)tabs;
224 dbg_decl_str(listbox, 256); /* declare the string */
226 for (i = 0; i < descr->nb_tabs; i++) {
227 descr->tabs[i] = *p++<<1;
228 if(TRACING(listbox)) /* write in it only if
229 dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
231 TRACE(listbox, "Listbox %04x: settabstops %s\n",
232 wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
234 dbg_reset_str(listbox); /* !!!reset the string!!! */
235 for (i = 0; i < descr->extrainfo_nr; i++) {
236 descr->extrainfo = *p+1;
237 if(TRACING(listbox)) /* write in it only if
238 dsprintf(listbox,"%3d ",descr->extrainfo); /* we are gonna output it */
241 TRACE(listbox, "Listbox %04x: extrainfo %s\n",
242 wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
247 As I already stated, I do not think this will be the ultimate interface
248 for building in-memory debugging messages. In fact, I do have better ideas
249 which I hope to have time to implement for the next release. For this
250 reason, please try not to use it. However, if you need to output a line
251 in more than one dprintf_xxx calls, then USE THIS INTERFACE. DO NOT use
252 other methods. This way, I will easily translate everything to the new
253 interface (when it will become available). So, if you need to use if,
254 then follow the following guidelines:
255 -- wrap calls to dsprintf with a
258 Of course, if the call to dsprintf is made from within a function
259 which you know is called only if YYY(xxx) is true
260 (say you call it only like this:
262 print_some_debug_info();
264 then you need not (and should not) wrap calls to dsprintf with
265 the before mentioned if.
266 -- name the string EXACTLY like the debugging channel on which
267 is going to be output. Please see the above example.
273 Resource identifiers can be either strings or numbers. To make life a bit
274 easier for outputting this beasts (and to help you avoid the need to build
275 the message in memory), I introduced a new function called:
279 The function is defined in debugstr.h
280 and has the following prototype:
282 LPSTR debugres(const void *id);
284 It takes a pointer to the resource id and returns a nicely formatted
285 string of the identifier.
287 It the high word of the pointer is 0, then it assumes that the
288 identifier is a number and thus returns a string of the form:
292 where xxxx are 4 hex-digits representing the low word of id.
294 It the high word of the pointer is not 0, then it assumes that the
295 identifier is a string and thus returns a string of the form:
299 Thus, to use it, do something on the following lines:
305 YYY(xxx, "resource is %s", debugres(myresource));
308 The -debugmsg command line option
309 ---------------------------------
311 So, the -debugmsg command line option has been changed as follows:
312 - the new syntax is: -debugmsg [yyy]#xxx[,[yyy1]#xxx1]*
313 where # is either + or -
315 - when the optional class argument (yyy) is not present,
316 then the statement will enable(+)/disable(-) all messages for
317 the given channel (xxx) on all classes. For example:
321 enables all messages on the reg channel and disables all
322 messages on the file channel.
323 This is same as the old semantics.
325 - when the optional class argument (yyy) is present,
326 then the statement will enable(+)/disable(-) messages for
327 the given channel (xxx) only on the given class. For example:
329 -debugmsg trace+reg,warn-file
331 enables trace messages on the reg channel and disables warning
332 messages on the file channel.
334 - also, the pseudo-channel all is also supported and it has the
337 -debugmsg +all -- enables all debug messages
338 -debugmsg -all -- disables all debug messages
339 -debugmsg yyy+all -- enables debug messages for class yyy on all
341 -debugmsg yyy-all -- disables debug messages for class yyy on all
346 -debugmsg warn-all -- disables all warning messages.
349 Also, note that at the moment:
350 - the fixme and err classes are enabled by default
351 - the trace and warn classes are disabled by default
352 - there is no way to compile out the messages. All are
353 runtime configurable. This will (hopefully) come next
360 This new scheme makes certain things more consistent but there is still
361 room for improvement by using a common style of debug messages. Before
362 I continue, let me note that the output format is the following:
364 yyy:xxx:fff <message>
367 yyy = the class (fixme, err, warn, trace)
368 xxx = the channel (atom, win, font, etc)
369 fff = the function name
370 these fields are output automatically. All you have to provide is
373 So here are some ideas:
375 * do NOT include the name of the function: it is included automatically
377 * if you want to output the parameters of the function, do it as the first
378 thing and include them in parenthesis, like this:
380 YYY(xxx, "(%d,%p,etc)...\n", par1, par2, ...);
382 * for stubs, you should output a FIXME message. I suggest this style:
384 FIXME(xxx, "(%x,%d...): stub\n", par1, par2, ...);
386 That is, you output the parameters, then a : and then a string
387 containing the word "stub". I've seen "empty stub", and others, but I
388 think that just "stub" suffices.
390 * output 1 and ONLY 1 line per message. That is, the format string should
391 contain only 1 \n and it should always appear at the end of the string.
392 (there are many reasons for this requirement, one of them is that each
393 debug macro adds things to the beginning of the line)
395 * if you want to name a value, use = and NOT :. That is, instead of
397 FIXME(xxx, "(fd: %d, file: %s): stub\n", fd, name);
399 FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);
401 use : to separate categories.
403 * try to avoid the style:
406 "(fd: %d, file: %s): stub\n", fd, name);
409 FIXME(xxx, "(fd: %d, file: %s): stub\n", fd, name);
411 The reason is that if you want to grep for things, you would search for
412 FIXME but in the first case there is no additional information available,
413 where in the second one, there is (e.g. the word stub)
415 * if you output a string s that might contain control characters,
416 or if s may be null, use debugstr_a (for ASCII strings, or
417 debugstr_w for Unicode strings) to convert s to a C string, like
420 HANDLE32 WINAPI YourFunc(LPCSTR s)
422 FIXME(xxx, "(%s): stub\n", debugstr_a(s));
425 * if you want to output a resource identifier, use debugres to
426 convert it to a string first, like this:
428 HANDLE32 WINAPI YourFunc(LPCSTR res)
430 FIXME(xxx, "(res=%s): stub\n", debugres(s));
433 if the resource identifier is a SEGPTR, use PTR_SEG_TO_LIN to get a
436 HRSRC16 WINAPI FindResource16( HMODULE16 hModule, SEGPTR name, SEGPTR type )
439 TRACE(resource, "module=%04x name=%s type=%s\n",
440 hModule, debugres(PTR_SEG_TO_LIN(name)),
441 debugres(PTR_SEG_TO_LIN(type)) );
445 * for messages intended for the user (specifically those that report
446 errors in wine.conf), use the MSG macro. Use it like a printf:
448 MSG( "Definition of drive %d is incorrect!\n", drive );
450 However, note that there are _very_ few valid uses of this macro.
451 Most messages are debugging messages, so chances are you will not
452 need to use this macro. Grep the source to get an idea where it
453 is appropriate to use it.
455 * for structure dumps, use the DUMP macro. Use it like a printf,
456 just like the MSG macro. Similarly, there are only a few valid
457 uses of this macro. Grep the source to see when to use it.