source: trunk/doc/Logging.txt@ 8001

/* $Id: Logging.txt,v 1.2 2001-11-22 11:48:55 phaller Exp $ */

                Odin Logging and Profiling
                ~~~~~~~~~~~~~~~~~~~~~~~~~~

1.0 Standard logging feature
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The alpha 5 binaries and daily build zipfiles can generate logfiles to show 
what a win32 application is doing. This can be very useful to determine
why certain applications don't run correctly.

The major disadvantage of loggging is the overhead. Therefor it has been 
disabled by default in the alpha 5 release and daily builds.
To enable logging set the environment variable WIN32LOG_ENABLED:
   SET WIN32LOG_ENABLED=1

To disable logging again, you must clear this variable:
   SET WIN32LOG_ENABLED=


2.0 Extended logging features (new as of February 16th)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Disabling or enabling logging for all the Odin dlls isn't always useful.
To make logging more flexible, you can now disable or enable separate
source files for each dll (NOTE: Only implemented in kernel32, user32 & gdi32
for now)

Each dll that supports this feature has a file called dbglocal.cpp in it's
source directory. It contains a listing of all the sources files for that dll
(DbgFileNames) and an array with boolean values for each of those files.
To add this feature to a dll, you must do the following:
        - Write a custom dbglocal.cpp & dbglocal.h.
        - Every source file must include dbglocal.h with the correct debug constant:
                #define DBG_LOCALLOG    DBG_directory
                #include "dbglocal.h"
        - Initterm.cpp must call ParseLogStatus when the dll is loaded

Each dprintf now first checks if logging is enabled for this sourefile before
calling WriteLog. (NOTE: dbglocal must be included *after* misc.h)

When building a debug version of a dll, logging is enabled for all source files
by default.

2.1 Examples of custom logging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Disable logging for kernel32, but enable it for profile.cpp & wprocess.cpp
        set dbg_kernel32=-dll +profile +wprocess


Enable logging for kernel32, but disable it for profile.cpp & wprocess.cpp
        set dbg_kernel32=+dll -profile -wprocess


3.0 ODIN Profiler
~~~~~~~~~~~~~~~~~

If the ODIN executables are compiled with IBM VisualAge C++ 3.08 and
the generation of profile hooks is enabled (/Gh+), the runtime library
ODINCRTP will reroute the _ProfileHook32 calls to the ODINPROF library.
This is done by some sophisticated stack trickery.
ODINPROF will be called upon each entry and exit of compiled C functions and
C++ member functions. The profiler will then try to load the symbolic debug
information file according to the module name (i. e. KERNEL32.sym) and
lookup the symbol name according to the function's entry address. C++ name
demangling is done automatically.
If this fails, the profiler will auto-generate symbolic names.
If a symbol table could be loaded, but the address looked for could not be
found exactly in the debug information, the profiler will revert to the 
closest symbol found and add the address difference as an offset suffix.
(i. e. _MyAPI@4+1234h)

Upon process termination the profiler will yield a file named '<pid>.prof'.
It will contain a number of sorted tables about the collected performance 
data.