documentation/debug-msgs

   1 Note: the debugging interface is under development. Please do not make
   2       changes to it yet as I will do major changes in the next few weeks.
   3       To make my life easier, PLEASE follow the guidelines described in
   4       this document. If you have some ideas that you would like to
   5       incorporate, please contact me first.
   6       Please read the document before writing new code.
   7       Also, DO NOT USE fprintf (or printf) to output things. All these
   8       will have to be translated to dprintf_ calls and there are already
   9       about 3000 of them! Also, instead of writing FIXMEs in the source,
  10       output a dprintf_fixme message. But read on...
  11 25 Feb 1998, Dimitrie O. Paun <dimi@cs.toronto.edu>
  12
  13
  14 Debugging classes
  15 -----------------
  16
  17 The debugging messages are divided into 4 classes:
  18
  19 fixme -- Messages in this class relate to behavior of Wine that does
  20          not correspond to standard Windows behavior and that should
  21          be fixed.
  22          Examples: stubs, semi-implemented features, etc.
  23
  24 err   -- Messages in this class relate to serious errors in Wine.
  25          This sort of messages are close to asserts -- that is,
  26          you should output a 'err' message when the code detects a
  27          condition which should not happen.
  28          Examples: unexpected change in internal state, etc.
  29
  30 warn  -- This are warning messages. You should report a warning when
  31          something unwanted happen but the function behaves properly.
  32          That is, output a warning when you encounter something
  33          unexpected (ex: could not open a file) but the function deals
  34          correctly with the situation (that is, according to the docs).
  35          If you do not deal correctly with it, output a fixme.
  36          Examples: fail to access a resource required by the app, etc.
  37
  38 info  -- This are detailed debugging messages that are mainly useful
  39          to debug a component. This are usually turned off.
  40          Examples: everything else that does not fall in one of the
  41                    above mentioned categories and the user does not
  42                    need to know about it. This sort of messages simply
  43                    outputs something about the state of some component
  44                    that is of interest mainly to the developer of that
  45                    component.
  46
  47 We will refer to a generic class as yyy.
  48
  49 The user has the capability to turn on or off messages in a particular
  50 class. You can expect the following patters of usage (but note that
  51 any combination is possible):
  52   -- when you debug a component, all classes (info,warn,err,fixme)
  53      will be enabled.
  54   -- during the pre-alpha (maybe alpha) stage of Wine, most likely
  55      the info 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 info and warn
  58      classes will be disabled by default, but all err and fixme
  59      will be enabled by default.
  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 per component. Each component
  73 is assigned a debugging channel (or type). The identifier of the
  74 channel must be a valid C identifier but note that it may also be a
  75 reserve word like int or static.
  76
  77 Examples of debugging channels/types:
  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 have 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
  93       type of information they report. For this reason it is VERY
  94       important 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       dprintf_warn(reg, "Could not access key!\n");
  99
 100 ---
 101
 102 How to use it
 103 -------------
 104
 105 So, to output a message (class yyy) on channel xxx, do:
 106
 107 #include "debug.h"
 108
 109 ....
 110
 111 dprintf_yyy(xxx, "<message>", ...);
 112
 113
 114 Some examples from the code:
 115
 116 #include "debug.h"
 117
 118 ...
 119
 120   dprintf_info(crtdll,
 121                "CRTDLL_setbuf(file %p buf %p)\n",
 122                file, buf);
 123
 124   dprintf_warn(aspi, "Error opening device errno=%d\n", save_error);
 125
 126
 127 If you need to declare a new debugging channel, do:
 128 %tools/make_debug
 129 in the root directory of Wine.
 130
 131 Note that this will result in almost complete recompilation of Wine.
 132
 133 Notes:
 134    1. Please pay attention to which class you assign the message.
 135       It is very, Very, VERY important to get the class right.
 136       There are only 4 classes, so it is not hard. The reason
 137       it is important to get it right is that too much information
 138       is no information. For example, if you put things into the
 139       warn class that should really be in the info class, the
 140       output will be too big and this will force the user to
 141       turn of warnings. But this way he will fail to see the important
 142       ones. Also, if you put warnings into the info class lets say,
 143       he will most likely miss those because usually the info class
 144       is turned off. A similar argument can be made if you mix any
 145       other two classes.
 146    2. ALL LINES MUST END WITH A NEWLINE!!! If you can NOT output
 147       everything that you want in the line with only one dprintf_xxx
 148       statement, then you need to build the string in memory.
 149       Please read the section below "In-memory messages" on the
 150       preferred way to do it. PLEASE USE THAT INTERFACE TO BUILD
 151       MESSAGES IN MEMORY. The reason is that we are not sure that
 152       we like it and having everything in one format will facilitate
 153       the (automatic) translation to a better interface.
 154
 155
 156
 157 Are we debugging?
 158 -----------------
 159
 160 To test whether the debugging output of class yyy on channel xxx is
 161 enabled, do:
 162
 163 debugging_yyy(xxx)
 164
 165 Examples:
 166
 167 if(debugging_info(atom)){
 168   ...blah...
 169 }
 170
 171
 172
 173 In-memory messages
 174 ------------------
 175
 176 If you NEED to build the message from multiple calls, you need to
 177 build it in memory. To do that, you should use the following
 178 interface:
 179
 180  - declare a string (where you are allowed to declare C variables)
 181    as follows:
 182    dbg_decl_str(name, len);
 183    where name  is the name of the string (you should use the channel
 184    name on which you are going to output it)
 185
 186  - print in it with:
 187    dsprintf(name, "<message>", ...);
 188    which is just like a sprintf function but instead of a C string as
 189    first parameter it takes the name you used to declare it.
 190
 191  - obtain a pointer to the string with:
 192    dbg_str(name)
 193
 194  - reset the string (if you want to reuse it with):
 195    dbg_reset_str(name);
 196
 197 Example (modified from the code):
 198
 199 void some_func(tabs)
 200 {
 201   INT32 i;
 202   LPINT16 p = (LPINT16)tabs;
 203   dbg_decl_str(listbox, 256);                   /* declare the string */
 204
 205   for (i = 0; i < descr->nb_tabs; i++) {
 206     descr->tabs[i] = *p++<<1;
 207     if(debugging_info(listbox))                  /* write in it only if
 208       dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
 209   }
 210   dprintf_info(listbox, "Listbox %04x: settabstops %s\n",
 211                wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
 212 }
 213
 214 If you need to use it two times in the same scope do like this:
 215
 216 void some_func(tabs)
 217 {
 218   INT32 i;
 219   LPINT16 p = (LPINT16)tabs;
 220   dbg_decl_str(listbox, 256);                   /* declare the string      */
 221
 222   for (i = 0; i < descr->nb_tabs; i++) {
 223     descr->tabs[i] = *p++<<1;
 224     if(debugging_info(listbox))                  /* write in it only if
 225       dsprintf(listbox, "%hd ", descr->tabs[i]); /* we are gonna output it */
 226   }
 227   dprintf_info(listbox, "Listbox %04x: settabstops %s\n",
 228                wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
 229
 230   dbg_reset_str(listbox);                        /* !!!reset the string!!! */
 231   for (i = 0; i < descr->extrainfo_nr; i++) {
 232     descr->extrainfo = *p+1;
 233     if(debugging_info(listbox))                  /* write in it only if
 234       dsprintf(listbox,"%3d ",descr->extrainfo); /* we are gonna output it */
 235   }
 236
 237   dprintf_info(listbox, "Listbox %04x: extrainfo %s\n",
 238                wnd->hwndSelf, dbg_str(listbox)); /* output the whole thing */
 239
 240 }
 241
 242 IMPORTANT NOTE:
 243   As I already stated, I do not think this will be the ultimate interface
 244   for building in-memory debugging messages. In fact, I do have better ideas
 245   which I hope to have time to implement for the next release. For this
 246   reason, please try not to use it. However, if you need to output a line
 247   in more than one dprintf_xxx calls, then USE THIS INTERFACE. DO NOT use
 248   other methods. This way, I will easily translate everything to the new
 249   interface (when it will become available). So, if you need to use if,
 250   then follow the following guidelines:
 251    -- wrap calls to dsprintf with a
 252       if(debugging_yyy(xxx))
 253         dsprintf(xxx,...);
 254       Of course, if the call to dsprintf is made from within a function
 255       which you know is called only if debugging_yyy(xxx) is true
 256       (say you call it only like this:
 257         if(debugging_yyy(xxx))
 258           print_some_debug_info();
 259       )
 260       then you need not (and should not) wrap calls to dsprintf with
 261       the before mentioned if.
 262    -- name the string EXACTLY like the debugging channel on which
 263       is going to be output. Please see the above example.
 264
 265
 266 Resource identifiers
 267 --------------------
 268
 269 Resource identifiers can be either strings or numbers. To make life a bit
 270 easier for outputting this beasts (and to help you avoid the need to build
 271 the message in memory), I introduced a new function called:
 272
 273 debugres
 274
 275 The function is defined in debugstr.h
 276 and has the following prototype:
 277
 278 LPSTR debugres(const void *id);
 279
 280 It takes a pointer to the resource id and returns a nicely formatted
 281 string of the identifier.
 282
 283 It the high word of the pointer is 0, then it assumes that the
 284 identifier is a number and thus returns a string of the form:
 285
 286 #xxxx
 287
 288 where xxxx are 4 hex-digits representing the low word of id.
 289
 290 It the high word of the pointer is not 0, then it assumes that the
 291 identifier is a string and thus returns a string of the form:
 292
 293 '<identifier>'
 294
 295 Thus, to use it, do something on the following lines:
 296
 297 #include "debugstr.h"
 298
 299 ...
 300
 301    dprintf_yyy(xxx, "resource is %s", debugres(myresource));
 302
 303
 304 The -debugmsg command line option
 305 ---------------------------------
 306
 307 So, the -debugmsg command line option has been changed as follows:
 308   - the new syntax is: -debugmsg [yyy]#xxx[,[yyy1]#xxx1]*
 309     where # is either + or -
 310
 311   - when the optional class argument (yyy) is not present,
 312     then the statement will enable(+)/disable(-) all messages for
 313     the given channel (xxx) on all classes. For example:
 314
 315     -debugmsg +reg,-file
 316
 317     enables all messages on the reg channel and disables all
 318     messages on the file channel.
 319     This is very close (actually identical) to the old semantics.
 320
 321   - when the optional class argument (yyy) is present,
 322     then the statement will enable(+)/disable(-) messages for
 323     the given channel (xxx) only on the given class. For example:
 324
 325     -debugmsg info+reg,warn-file
 326
 327     enables info messages on the reg channel and disables warning
 328     messages on the file channel.
 329
 330   - also, the pseudo-channel all is also supported and it has the
 331     intuitive semantics:
 332
 333     -debugmsg +all      -- enables all debug messages
 334     -debugmsg -all      -- disables all debug messages
 335     -debugmsg yyy+all   -- enables debug messages for class yyy on all
 336                            channels.
 337     -debugmsg yyy-all   -- disables debug messages for class yyy on all
 338                            channels.
 339
 340     So, for example:
 341
 342     -debugmsg warn-all  -- disables all warning messages.
 343
 344
 345 Also, note that at the moment:
 346    - the fixme, err, warn classes are all enabled by default
 347    - the info class is disabled by default
 348    - there is no way to compile out the messages. All are
 349      runtime configurable. This will come next release.
 350
 351