home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 8 Other / 08-Other.zip / odin0501.zip / Logging.txt < prev    next >
Text File  |  2001-11-22  |  3KB  |  80 lines
  1. /* $Id: Logging.txt,v 1.2 2001/11/22 11:48:55 phaller Exp $ */
  2.  
  3.                 Odin Logging and Profiling
  4.                 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  5.  
  6. 1.0 Standard logging feature
  7. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  8.  
  9. The alpha 5 binaries and daily build zipfiles can generate logfiles to show 
  10. what a win32 application is doing. This can be very useful to determine
  11. why certain applications don't run correctly.
  12.  
  13. The major disadvantage of loggging is the overhead. Therefor it has been 
  14. disabled by default in the alpha 5 release and daily builds.
  15. To enable logging set the environment variable WIN32LOG_ENABLED:
  16.    SET WIN32LOG_ENABLED=1
  17.  
  18. To disable logging again, you must clear this variable:
  19.    SET WIN32LOG_ENABLED=
  20.  
  21.  
  22. 2.0 Extended logging features (new as of February 16th)
  23. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  24.  
  25. Disabling or enabling logging for all the Odin dlls isn't always useful.
  26. To make logging more flexible, you can now disable or enable separate
  27. source files for each dll (NOTE: Only implemented in kernel32, user32 & gdi32
  28. for now)
  29.  
  30. Each dll that supports this feature has a file called dbglocal.cpp in it's
  31. source directory. It contains a listing of all the sources files for that dll
  32. (DbgFileNames) and an array with boolean values for each of those files.
  33. To add this feature to a dll, you must do the following:
  34.     - Write a custom dbglocal.cpp & dbglocal.h.
  35.     - Every source file must include dbglocal.h with the correct debug constant:
  36.         #define DBG_LOCALLOG    DBG_directory
  37.         #include "dbglocal.h"
  38.     - Initterm.cpp must call ParseLogStatus when the dll is loaded
  39.  
  40. Each dprintf now first checks if logging is enabled for this sourefile before
  41. calling WriteLog. (NOTE: dbglocal must be included *after* misc.h)
  42.  
  43. When building a debug version of a dll, logging is enabled for all source files
  44. by default.
  45.  
  46. 2.1 Examples of custom logging
  47. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  48.  
  49. Disable logging for kernel32, but enable it for profile.cpp & wprocess.cpp
  50.     set dbg_kernel32=-dll +profile +wprocess
  51.  
  52.  
  53. Enable logging for kernel32, but disable it for profile.cpp & wprocess.cpp
  54.     set dbg_kernel32=+dll -profile -wprocess
  55.  
  56.  
  57. 3.0 ODIN Profiler
  58. ~~~~~~~~~~~~~~~~~
  59.  
  60. If the ODIN executables are compiled with IBM VisualAge C++ 3.08 and
  61. the generation of profile hooks is enabled (/Gh+), the runtime library
  62. ODINCRTP will reroute the _ProfileHook32 calls to the ODINPROF library.
  63. This is done by some sophisticated stack trickery.
  64. ODINPROF will be called upon each entry and exit of compiled C functions and
  65. C++ member functions. The profiler will then try to load the symbolic debug
  66. information file according to the module name (i. e. KERNEL32.sym) and
  67. lookup the symbol name according to the function's entry address. C++ name
  68. demangling is done automatically.
  69. If this fails, the profiler will auto-generate symbolic names.
  70. If a symbol table could be loaded, but the address looked for could not be
  71. found exactly in the debug information, the profiler will revert to the 
  72. closest symbol found and add the address difference as an offset suffix.
  73. (i. e. _MyAPI@4+1234h)
  74.  
  75. Upon process termination the profiler will yield a file named '<pid>.prof'.
  76. It will contain a number of sorted tables about the collected performance 
  77. data.
  78.  
  79.  
  80.