documentation/debug-msgs

   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. To make my life easier, please follow the guidelines
   5       described in this document.
   6
   7       Read this document before writing new code. DO NOT USE fprintf
   8       (or printf) to output things. Also, instead of writing
   9       FIXMEs in the source, output a FIXME message if you can.
  10
  11       IMPORTANT: at the end of the document, there is a "Style Guide"
  12       for debugging messages. Please read it.
  13
  14 28 Mar 1998, Dimitrie O. Paun <dimi@cs.toronto.edu>
  15
  16
  17 Debugging classes
  18 -----------------
  19
  20 There are 4 types (or classes) of debugging messages:
  21
  22 FIXME -- Messages in this class relate to behavior of Wine that does
  23          not correspond to standard Windows behavior and that should
  24          be fixed.
  25          Examples: stubs, semi-implemented features, etc.
  26
  27 ERR   -- Messages in this class relate to serious errors in Wine.
  28          This sort of messages are close to asserts -- that is,
  29          you should output an error message when the code detects a
  30          condition which should not happen. In other words, important
  31          things that are not warnings (see below), are errors.
  32          Examples: unexpected change in internal state, etc.
  33
  34 WARN  -- These are warning messages. You should report a warning when
  35          something unwanted happen but the function behaves properly.
  36          That is, output a warning when you encounter something
  37          unexpected (ex: could not open a file) but the function deals
  38          correctly with the situation (that is, according to the docs).
  39          If you do not deal correctly with it, output a fixme.
  40          Examples: fail to access a resource required by the app, etc.
  41
  42 TRACE -- These are detailed debugging messages that are mainly useful
  43          to debug a component. These are usually turned off.
  44          Examples: everything else that does not fall in one of the
  45                    above mentioned categories and the user does not
  46                    need to know about it.
  47
  48
  49 The user has the capability to turn on or off messages of a particular
  50 type. You can expect the following patterns of usage (but note that
  51 any combination is possible):
  52   -- when you debug a component, all types (TRACE,WARN,ERR,FIXME)
  53      will be enabled.
  54   -- during the pre-alpha (maybe alpha) stage of Wine, most likely
  55      the TRACE class will be disabled by default, but all others
  56      (WARN,ERR,FIXME) will be enabled by default.
  57   -- when Wine will become stable, most likely the TRACE and WARN
  58      classes will be disabled by default, but all ERRs and FIXMEs
  59      will be enabled.
  60   -- in some installations that want the smallest footprint
  61      and where the debug information is of no interest,
  62      all classes may be disabled by default.
  63
  64 Of course, the user will have the runtime ability to override these
  65 defaults. However, this ability may be turned off and certain classes
  66 of messages may be completely disabled at compile time to reduce the
  67 size of Wine.
  68
  69 Debugging channels
  70 ------------------
  71
  72 Also, we divide the debugging messages on a component basis. Each
  73 component is assigned a debugging channel. The identifier of the
  74 channel must be a valid C identifier but note that it may also be a
  75 reserved word like int or static.
  76
  77 Examples of debugging channels:
  78 reg, updown, string
  79
  80 We will refer to a generic channel as xxx.
  81
  82 Note: for those who know the old interface, the channel/type is
  83       what followed the _ in the dprintf_xxx statements.
  84       For example, to output a message on the debugging channel
  85       reg in the old interface you would had to write:
  86
  87       dprintf_reg(stddeb, "Could not access key!\n");
  88
  89       In the new interface, we drop the stddeb as it is implicit.
  90       However, we add an orthogonal piece of information to the
  91       message: its class. This is very important as it will allow
  92       us to selectively turn on or off certain messages based on the
  93       type of information they report. For this reason it is essential
  94       to choose the right class for the message.
  95       Anyhow, suppose we figured that this message should belong
  96       in the WARN class, so in the new interface, you write:
  97
  98       WARN(reg, "Could not access key!\n");
  99 ---
 100
 101 How to use it
 102 -------------
 103
 104 So, to output a message (class YYY) on channel xxx, do:
 105
 106 #include "debug.h"
 107
 108 ....
 109
 110 YYY(xxx, "<message>", ...);
 111
 112
 113 Some examples from the code:
 114
 115 #include "debug.h"
 116
 117 ...
 118
 119   TRACE(crtdll, "CRTDLL_setbuf(file %p buf %p)", file, buf);
 120
 121   WARN(aspi, "Error opening device errno=%d", save_error);
 122
 123
 124 If you need to declare a new debugging channel, use it in your code
 125 and then do:
 126 %tools/make_debug
 127 in the root directory of Wine.
 128
 129 Note that this will result in almost complete recompilation of Wine.
 130
 131 Notes:
 132    1. Please pay attention to which class you assign the message.
 133       There are only 4 classes, so it is not hard. The reason
 134       it is important to get it right is that too much information
 135       is no information. For example, if you put things into the
 136       WARN class that should really be in the TRACE class, the
 137       output will be too big and this will force the user to
 138       turn warnings off. But this way he will fail to see the important
 139       ones. Also, if you put warnings into the TRACE class lets say,
 140       he will most likely miss those because usually the TRACE class
 141       is turned off. A similar argument can be made if you mix any
 142       other two classes.
 143    2. All lines should end with a newline.If you can NOT output
 144       everything that you want in the line with only one statement,
 145       then you need to build the string in memory.
 146       Please read the section below "In-memory messages" on the
 147       preferred way to do it. PLEASE USE THAT INTERFACE TO BUILD
 148       MESSAGES IN MEMORY. The reason is that we are not sure that
 149       we like it and having everything in one format will facilitate
 150       the (automatic) translation to a better interface.
 151
 152
 153
 154 Are we debugging?
 155 -----------------
 156
 157 To test whether the debugging output of class yyy on channel xxx is
 158 enabled, use:
 159
 160 TRACE_ON  to test if TRACE is enabled
 161 WARN_ON   to test if WARN is enabled
 162 FIXME_ON  to test if FIXME is enabled
 163 ERR_ON    to test if ERR is enabled
 164
 165 Examples:
 166
 167 if(TRACE_ON(atom)){
 168   ...blah...
 169 }
 170
 171 Note that you should normally need to test only if TRACE_ON. At present,
 172 none of the other 3 tests (except for ERR_ON which is used only once!)
 173 are used in Wine.
 174
 175 In-memory messages
 176 ------------------
 177
 178 If you NEED to build the message from multiple calls, you need to
 179 build it in memory. To do that, you should use the following
 180 interface:
 181
 182  - declare a string (where you are allowed to declare C variables)
 183    as follows:
 184    dbg_decl_str(name, len);
 185    where name  is the name of the string (you should use the channel
 186    name on which you are going to output it)
 187
 188  - print in it with:
 189    dsprintf(name, "<message>", ...);
 190    which is just like a sprintf function but instead of a C string as
 191    first parameter it takes the name you used to declare it.
 192
 193  - obtain a pointer to the string with:
 194    dbg_str(name)
 195
 196  - reset the string (if you want to reuse it with):
 197    dbg_reset_str(name);
 198
 199 Example (modified from the code):
 200
 201 void some_func(tabs)
 202 {
 203   INT32 i;
 204   LPINT16 p = (LPINT16)tabs;
 205   dbg_decl_str(listbox, 256);                   /* declare the string */
 206
 207   for (i = 0; i < descr->nb_tabs; i++) {
 208     descr->tabs[i] = *p++<<1;
 209     if(TRACING(listbox))                         /* write in it only if
 210       dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
 211   }
 212   TRACE(listbox, "Listbox %04x: settabstops %s",
 213         wnd->hwndSelf, dbg_str(listbox));        /* output the whole thing */
 214 }
 215
 216 If you need to use it two times in the same scope do like this:
 217
 218 void some_func(tabs)
 219 {
 220   INT32 i;
 221   LPINT16 p = (LPINT16)tabs;
 222   dbg_decl_str(listbox, 256);                   /* declare the string      */
 223
 224   for (i = 0; i < descr->nb_tabs; i++) {
 225     descr->tabs[i] = *p++<<1;
 226     if(TRACING(listbox))                         /* write in it only if
 227       dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
 228   }
 229   TRACE(listbox, "Listbox %04x: settabstops %s\n",
 230         wnd->hwndSelf, dbg_str(listbox));        /* output the whole thing */
 231
 232   dbg_reset_str(listbox);                        /* !!!reset the string!!! */
 233   for (i = 0; i < descr->extrainfo_nr; i++) {
 234     descr->extrainfo = *p+1;
 235     if(TRACING(listbox))                         /* write in it only if
 236       dsprintf(listbox,"%3d ",descr->extrainfo); /* we are gonna output it */
 237   }
 238
 239   TRACE(listbox, "Listbox %04x: extrainfo %s\n",
 240         wnd->hwndSelf, dbg_str(listbox));        /* output the whole thing */
 241
 242 }
 243
 244 IMPORTANT NOTE:
 245   As I already stated, I do not think this will be the ultimate interface
 246   for building in-memory debugging messages. In fact, I do have better ideas
 247   which I hope to have time to implement for the next release. For this
 248   reason, please try not to use it. However, if you need to output a line
 249   in more than one dprintf_xxx calls, then USE THIS INTERFACE. DO NOT use
 250   other methods. This way, I will easily translate everything to the new
 251   interface (when it will become available). So, if you need to use it,
 252   then follow the following guidelines:
 253    -- wrap calls to dsprintf with a
 254       if(YYY(xxx))
 255         dsprintf(xxx,...);
 256       Of course, if the call to dsprintf is made from within a function
 257       which you know is called only if YYY(xxx) is true
 258       (say you call it only like this:
 259         if(YYY(xxx))
 260           print_some_debug_info();
 261       )
 262       then you need not (and should not) wrap calls to dsprintf with
 263       the before mentioned if.
 264    -- name the string EXACTLY like the debugging channel on which
 265       is going to be output. Please see the above example.
 266
 267
 268 Resource identifiers
 269 --------------------
 270
 271 Resource identifiers can be either strings or numbers. To make life a bit
 272 easier for outputting this beasts (and to help you avoid the need to build
 273 the message in memory), I introduced a new function called:
 274
 275 debugres
 276
 277 The function is defined in debugstr.h
 278 and has the following prototype:
 279
 280 LPSTR debugres(const void *id);
 281
 282 It takes a pointer to the resource id and returns a nicely formatted
 283 string of the identifier.
 284
 285 It the high word of the pointer is 0, then it assumes that the
 286 identifier is a number and thus returns a string of the form:
 287
 288 #xxxx
 289
 290 where xxxx are 4 hex-digits representing the low word of id.
 291
 292 It the high word of the pointer is not 0, then it assumes that the
 293 identifier is a string and thus returns a string of the form:
 294
 295 '<identifier>'
 296
 297 Thus, to use it, do something on the following lines:
 298
 299 #include "debug.h"
 300
 301 ...
 302
 303    YYY(xxx, "resource is %s", debugres(myresource));
 304
 305
 306 The -debugmsg command line option
 307 ---------------------------------
 308
 309 So, the -debugmsg command line option has been changed as follows:
 310   - the new syntax is: -debugmsg [yyy]#xxx[,[yyy1]#xxx1]*
 311     where # is either + or -
 312
 313   - when the optional class argument (yyy) is not present,
 314     then the statement will enable(+)/disable(-) all messages for
 315     the given channel (xxx) on all classes. For example:
 316
 317     -debugmsg +reg,-file
 318
 319     enables all messages on the reg channel and disables all
 320     messages on the file channel.
 321     This is same as the old semantics.
 322
 323   - when the optional class argument (yyy) is present,
 324     then the statement will enable(+)/disable(-) messages for
 325     the given channel (xxx) only on the given class. For example:
 326
 327     -debugmsg trace+reg,warn-file
 328
 329     enables trace messages on the reg channel and disables warning
 330     messages on the file channel.
 331
 332   - also, the pseudo-channel all is also supported and it has the
 333     intuitive semantics:
 334
 335     -debugmsg +all      -- enables all debug messages
 336     -debugmsg -all      -- disables all debug messages
 337     -debugmsg yyy+all   -- enables debug messages for class yyy on all
 338                            channels.
 339     -debugmsg yyy-all   -- disables debug messages for class yyy on all
 340                            channels.
 341
 342     So, for example:
 343
 344     -debugmsg warn-all  -- disables all warning messages.
 345
 346
 347 Also, note that at the moment:
 348    - the fixme and err classes are enabled by default
 349    - the trace and warn  classes are disabled by default
 350
 351
 352 Compiling Out Debugging Messages
 353 --------------------------------
 354
 355 To compile out the debugging messages, provide configure with the
 356 following options:
 357
 358 --disable-debug      -- turns off TRACE, WARN, and FIXME (and DUMP).
 359
 360 --disable-trace      -- turns off TRACE only.
 361
 362 This will result in an executable that, when stripped, is about 15%-20%
 363 smaller.  Note, however, that you will not be able to effectively debug
 364 Wine without these messages.
 365
 366 This feature has not been extensively tested--it may subtly break some
 367 things.
 368
 369
 370 A Few Notes on Style
 371 --------------------
 372
 373 This new scheme makes certain things more consistent but there is still
 374 room for improvement by using a common style of debug messages. Before
 375 I continue, let me note that the output format is the following:
 376
 377 yyy:xxx:fff <message>
 378
 379 where:
 380   yyy = the class (fixme, err, warn, trace)
 381   xxx = the channel (atom, win, font, etc)
 382   fff = the function name
 383 these fields are output automatically. All you have to provide is
 384 the <message> part.
 385
 386 So here are some ideas:
 387
 388 * do NOT include the name of the function: it is included automatically
 389
 390 * if you want to output the parameters of the function, do it as the first
 391 thing and include them in parenthesis, like this:
 392
 393    YYY(xxx, "(%d,%p,etc)...\n", par1, par2, ...);
 394
 395 * for stubs, you should output a FIXME message. I suggest this style:
 396
 397    FIXME(xxx, "(%x,%d...): stub\n", par1, par2, ...);
 398
 399   That is, you output the parameters, then a : and then a string
 400 containing the word "stub". I've seen "empty stub", and others, but I
 401 think that just "stub" suffices.
 402
 403 * output 1 and ONLY 1 line per message. That is, the format string should
 404 contain only 1 \n and it should always appear at the end of the string.
 405 (there are many reasons  for this requirement, one of them is that each
 406 debug macro adds things to the beginning of the line)
 407
 408 * if you want to name a value, use = and NOT :. That is, instead of
 409 saying:
 410   FIXME(xxx, "(fd: %d, file: %s): stub\n", fd, name);
 411 say:
 412   FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);
 413
 414 use : to separate categories.
 415
 416 * try to avoid the style:
 417
 418    FIXME(xxx,
 419          "(fd=%d, file=%s): stub\n", fd, name);
 420 but use:
 421
 422   FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);
 423
 424 The reason is that if you want to grep for things, you would search for
 425 FIXME but in the first case there is no additional information available,
 426 where in the second one, there is (e.g. the word stub)
 427
 428 * if you output a string s that might contain control characters,
 429   or if s may be null, use debugstr_a (for ASCII strings, or
 430   debugstr_w for Unicode strings) to convert s to a C string, like
 431   this:
 432
 433    HANDLE32 WINAPI YourFunc(LPCSTR s)
 434 {
 435    FIXME(xxx, "(%s): stub\n", debugstr_a(s));
 436 }
 437
 438 * if you want to output a resource identifier, use debugres to
 439   convert it to a string first, like this:
 440
 441    HANDLE32 WINAPI YourFunc(LPCSTR res)
 442 {
 443    FIXME(xxx, "(res=%s): stub\n", debugres(s));
 444 }
 445
 446 if the resource identifier is a SEGPTR, use PTR_SEG_TO_LIN to get a
 447 liner pointer first:
 448
 449 HRSRC16 WINAPI FindResource16( HMODULE16 hModule, SEGPTR name, SEGPTR type )
 450 {
 451 [...]
 452     TRACE(resource, "module=%04x name=%s type=%s\n",
 453                  hModule, debugres(PTR_SEG_TO_LIN(name)),
 454                  debugres(PTR_SEG_TO_LIN(type)) );
 455 [...]
 456 }
 457
 458 * for messages intended for the user (specifically those that report
 459   errors in wine.conf), use the MSG macro. Use it like a printf:
 460
 461            MSG( "Definition of drive %d is incorrect!\n", drive );
 462
 463   However, note that there are _very_ few valid uses of this macro.
 464   Most messages are debugging messages, so chances are you will not
 465   need to use this macro. Grep the source to get an idea where it
 466   is appropriate to use it.
 467
 468 * for structure dumps, use the DUMP macro. Use it like a printf,
 469   just like the MSG macro. Similarly, there are only a few valid
 470   uses of this macro. Grep the source to see when to use it.