Sweden-Number/documentation/debug-msgs

Note: The new debugging interface is starting to take shape.
      In general, I think it can be considered to be stable,
      with the exception of the in-memory message construction functions.
      However, there is still a lot of work to be done to polish
      things up and to convert the remaining fprintf. To make my life 
      easier, please follow the guidelines described in this document. 

      Read this document before writing new code.
      Also, DO NOT USE fprintf (or printf) to output things. All these
      will have to be translated to the new interface and there are already
      about 3000 of them! Also, instead of writing FIXMEs in the source,
      output a FIXME message if you can. But read on...
14 Mar 1998, Dimitrie O. Paun <dimi@cs.toronto.edu>


Debugging classes
-----------------

There are 4 types (or classes) of debugging messages:

FIXME -- Messages in this class relate to behavior of Wine that does
         not correspond to standard Windows behavior and that should
         be fixed. 
         Examples: stubs, semi-implemented features, etc.

ERR   -- Messages in this class relate to serious errors in Wine.
         This sort of messages are close to asserts -- that is,
         you should output a error message when the code detects a
         condition which should not happen.
	 Examples: unexpected change in internal state, etc.

WARN  -- 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, etc.

TRACE -- These are detailed debugging messages that are mainly useful 
         to debug a component. These are usually turned off.
         Examples: everything else that does not fall in one of the
                   above mentioned categories and the user does not
                   need to know about it.

            
The user has the capability to turn on or off messages of a particular
type. You can expect the following patterns of usage (but note that 
any combination is possible):
  -- when you debug a component, all types (TRACE,WARN,ERR,FIXME)
     will be enabled.
  -- during the pre-alpha (maybe alpha) stage of Wine, most likely
     the TRACE class will be disabled by default, but all others
     (WARN,ERR,FIXME) will be enabled by default.
  -- when Wine will become stable, most likely the TRACE and WARN
     classes will be disabled by default, but all ERRs and FIXMEs 
     will be enabled.
  -- in some installations that want the smallest footprint
     and where the debug information is of no interest, 
     all classes may be disabled by default.

Of course, the user will have the runtime ability to override these
defaults. However, this ability may be turned off and certain classes
of messages may be completely disabled at compile time to reduce the 
size of Wine.

Debugging channels
------------------

Also, we divide the debugging messages per component. 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
reserve word like int or static.

Examples of debugging channels:
reg, updown, string

We will refer to a generic channel as xxx.

Note: for those who know the old interface, the channel/type is
      what followed the _ in the dprintf_xxx statements.
      For example, to output a message on the debugging channel
      reg in the old interface you would have to write:

      dprintf_reg(stddeb, "Could not access key!\n");

      In the new interface, we drop the stddeb as it is implicit.
      However, we add an orthogonal piece of information to the
      message: its class. This is very important as it will allow
      us to selectively turn on or off certain messages based on the
      type of information they report. For this reason it is VERY
      important to choose the right class for the message. 
      Anyhow, suppose we figured that this message should belong
      in the WARN class, so in the new interface, you write:

      WARN(reg, "Could not access key!");

      Notice the \n is no longer required.

---

How to use it
-------------

So, to output a message (class YYY) on channel xxx, do:

#include "debug.h"

....

YYY(xxx, "<message>", ...);


Some examples from the code:

#include "debug.h"

...

  TRACE(crtdll, "CRTDLL_setbuf(file %p buf %p)",
	       file, buf);

  WARN(aspi, "Error opening device errno=%d", save_error);


If you need to declare a new debugging channel, use it in your code
and then do:
%tools/make_debug
in the root directory of Wine.

Note that this will result in almost complete recompilation of Wine.

Notes:
   1. Please pay attention to which class you assign the message.
      There are only 4 classes, so it is not hard. The reason
      it is important to get it right is that too much information
      is no information. For example, if you put things into the 
      WARN class that should really be in the TRACE class, the 
      output will be too big and this will force the user to 
      turn warnings off. But this way he will fail to see the important
      ones. Also, if you put warnings into the TRACE class lets say,
      he will most likely miss those because usually the TRACE class
      is turned off. A similar argument can be made if you mix any
      other two classes.
   2. All lines end by default with a newline. So you should not
      add one more.  If you can NOT output everything that you want in 
      the line with only one statement, then you need to build the string
      in memory.
      Please read the section below "In-memory messages" on the
      preferred way to do it. PLEASE USE THAT INTERFACE TO BUILD
      MESSAGES IN MEMORY. The reason is that we are not sure that
      we like it and having everything in one format will facilitate
      the (automatic) translation to a better interface.



Are we debugging?
-----------------

To test whether the debugging output of class yyy on channel xxx is
enabled, use:

TRACING  to test if TRACE is enabled
WARNING  to test if WARN is enabled
FIXMING  to test if FIXME is enabled
ERRING   to test if ERR is enabled

Examples:

if(TRACING(atom)){
  ...blah...
}

Note that you should normaly need to test only if TRACING. At present,
none of the other 3 tests (except for ERRING which is used only once!)
are used in Wine.

In-memory messages
------------------

If you NEED to build the message from multiple calls, you need to 
build it in memory. To do that, you should use the following
interface:

 - declare a string (where you are allowed to declare C variables)
   as follows:
   dbg_decl_str(name, len);
   where name  is the name of the string (you should use the channel
   name on which you are going to output it)

 - print in it with:
   dsprintf(name, "<message>", ...);
   which is just like a sprintf function but instead of a C string as
   first parameter it takes the name you used to declare it.

 - obtain a pointer to the string with:
   dbg_str(name)

 - reset the string (if you want to reuse it with):
   dbg_reset_str(name);

Example (modified from the code):

void some_func(tabs)
{
  INT32 i;
  LPINT16 p = (LPINT16)tabs;
  dbg_decl_str(listbox, 256);                   /* declare the string */

  for (i = 0; i < descr->nb_tabs; i++) {
    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", 
	wnd->hwndSelf, dbg_str(listbox));        /* output the whole thing */
}

If you need to use it two times in the same scope do like this:

void some_func(tabs)
{
  INT32 i;
  LPINT16 p = (LPINT16)tabs;
  dbg_decl_str(listbox, 256);                   /* declare the string      */

  for (i = 0; i < descr->nb_tabs; i++) {
    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", 
	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; 
    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", 
	wnd->hwndSelf, dbg_str(listbox));        /* output the whole thing */

}

IMPORTANT NOTE:
  As I already stated, I do not think this will be the ultimate interface
  for building in-memory debugging messages. In fact, I do have better ideas
  which I hope to have time to implement for the next release. For this
  reason, please try not to use it. However, if you need to output a line
  in more than one dprintf_xxx calls, then USE THIS INTERFACE. DO NOT use
  other methods. This way, I will easily translate everything to the new
  interface (when it will become available). So, if you need to use if,
  then follow the following guidelines:
   -- wrap calls to dsprintf with a 
      if(YYY(xxx))
        dsprintf(xxx,...);
      Of course, if the call to dsprintf is made from within a function 
      which you know is called only if YYY(xxx) is true
      (say you call it only like this:
        if(YYY(xxx))
          print_some_debug_info();
      )
      then you need not (and should not) wrap calls to dsprintf with
      the before mentioned if.
   -- name the string EXACTLY like the debugging channel on which
      is going to be output. Please see the above example. 


Resource identifiers
--------------------

Resource identifiers can be either strings or numbers. To make life a bit
easier for outputting this beasts (and to help you avoid the need to build
the message in memory), I introduced a new function called:

debugres

The function is defined in debugstr.h
and has the following prototype:

LPSTR debugres(const void *id);

It takes a pointer to the resource id and returns a nicely formatted
string of the identifier.

It the high word of the pointer is 0, then it assumes that the
identifier is a number and thus returns a string of the form:

#xxxx

where xxxx are 4 hex-digits representing the low word of id.

It the high word of the pointer is not 0, then it assumes that the
identifier is a string and thus returns a string of the form:

'<identifier>'

Thus, to use it, do something on the following lines:

#include "debugstr.h"

...

   YYY(xxx, "resource is %s", debugres(myresource));


The -debugmsg command line option
---------------------------------

So, the -debugmsg command line option has been changed as follows:
  - the new syntax is: -debugmsg [yyy]#xxx[,[yyy1]#xxx1]*
    where # is either + or -

  - when the optional class argument (yyy) is not present, 
    then the statement will enable(+)/disable(-) all messages for
    the given channel (xxx) on all classes. For example:
   
    -debugmsg +reg,-file
   
    enables all messages on the reg channel and disables all
    messages on the file channel.
    This is same as the old semantics.

  - when the optional class argument (yyy) is present, 
    then the statement will enable(+)/disable(-) messages for
    the given channel (xxx) only on the given class. For example:
   
    -debugmsg trace+reg,warn-file
   
    enables trace messages on the reg channel and disables warning
    messages on the file channel.

  - also, the pseudo-channel all is also supported and it has the 
    intuitive semantics:

    -debugmsg +all      -- enables 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
                           channels.

    So, for example:

    -debugmsg warn-all  -- disables all warning messages.


Also, note that at the moment:
   - the fixme and err classes are enabled by default
   - the trace and warn  classes are disabled by default
   - there is no way to compile out the messages. All are 
     runtime configurable. This will come next release.