/*++ Copyright (c) 1994 Microsoft Corporation All rights reserved. Module Name: Debug.h Abstract: New debug services for spooler. Author: Albert Ting (AlbertT) 15-Jan-1995 Revision History: --*/ #ifndef _DBGLOG_H #define _DBGLOG_H /******************************************************************** Setting up the debug support: ============================= Define a MODULE prefix string. Since this will be printed as a prefix to all debug output, it should be concise and unique. In your global header file: #define MODULE "prtlib:" Define a MODULE_DEBUG variable. This is the actual symbol that the library will use to indicate debugging level. This DWORD is broken into two bitfield WORDs: the low word indicates which levels to print to the debugger; the high word breaks into the debugger. The library takes the DebugLevel from a debug message, then ANDs it with the debug level. If the bit is on, the corresponding action (print or break) is taken. In your global header file: #define MODULE_DEBUG PrtlibDebug Finally, the actual debug variable must be defined and initialized to a default debug level. This must be done in exactly one *.c translation unit: In one of your source files: MODULE_DEBUG_LEVEL( {LevelsToPrint}, {LevelsToBreak} ); Adding logging to source code: ============================== The general format for debug message is: DBGMSG( {DebugLevel}, ( {args to printf} )); The DebugLevel dictates whether the level should print, break into the debugger, or just log to memory (logging always done). The args to printf must be placed in an extra set of parens, and should assume everything is ANSI. To print LPTSTRs, use the TSTR macro: DBGMSG( DBG_WARN, ( "LPTSTR "TSTR", LPSTR %s, LPWSTR %ws\n", TEXT("hello"), "hello", L"hello" )); Viewing DBGMSGs: ================ Messages will print to the debugger (usermode, or kernel debugger if no usermode debugger is available) for all printable levels. To change the level, you can edit the MODULE_DEBUG variable (PrtlibDebug in the above example). By default, DBG_ERROR and DBG_WARNING messages a logged to the error log (stored at gpbterrlog). All others are stored in the trace log (gpbttracelog). These currently log to memory in a circular buffer. Use the splx.dll extension to dump these logs. At compile time, you can switch these logs to go to file rather than memory. They will be stored as the PID + index number in the default directory of the process. ********************************************************************/ #ifdef __cplusplus extern "C" { #endif // // These values are strictly debug, but must be defined in the free // build because the TStatus error checking uses them as the first ctr // parameter. (During inlining they are discarded.) // #define DBG_NONE 0x0000 #define DBG_INFO 0x0001 #define DBG_WARN 0x0002 #define DBG_WARNING 0x0002 #define DBG_ERROR 0x0004 #define DBG_TRACE 0x0008 #define DBG_SECURITY 0x0010 #define DBG_EXEC 0x0020 #define DBG_PORT 0x0040 #define DBG_NOTIFY 0x0080 #define DBG_PAUSE 0x0100 #define DBG_THREADM 0x0400 #define DBG_MIN 0x0800 #define DBG_TIME 0x1000 #define DBG_FOLDER 0x2000 #define DBG_NOHEAD 0x8000 #if DBG BOOL SplLibInit( VOID ); extern DWORD MODULE_DEBUG; // // This should be used exactly once in a C file. It defines // the Debug variable, and also the DbgMsg function. // // If we are statically linking with SplLib (SplLib is a library, not // a Dll), then we will get the definition from SplLib, so don't define // it here. // #ifdef LINK_SPLLIB #define MODULE_DEBUG_INIT( print, break ) \ DWORD MODULE_DEBUG = (DBG_PRINT( print ) | DBG_BREAK( break )) #else #define MODULE_DEBUG_INIT( print, break ) \ VOID \ DbgMsg( \ LPCSTR pszMsgFormat, \ ... \ ) \ { \ CHAR szMsgText[1024]; \ va_list vargs; \ \ va_start( vargs, pszMsgFormat ); \ wvsprintfA( szMsgText, pszMsgFormat, vargs ); \ va_end( vargs ); \ \ if( szMsgText[0] && szMsgText[0] != ' ' ){ \ OutputDebugStringA( MODULE ); \ } \ OutputDebugStringA( szMsgText ); \ } \ DWORD MODULE_DEBUG = (DBG_PRINT( print ) | DBG_BREAK( break )) #endif #define DBGSTR( str ) \ ((str) ? (str) : TEXT("(NULL)")) #ifdef UNICODE #define TSTR "%ws" #else #define TSTR "%s" #endif #define DBG_PRINT_MASK 0xffff #define DBG_BREAK_SHIFT 16 #define DBG_PRINT(x) (x) #define DBG_BREAK(x) (((x) << DBG_BREAK_SHIFT)|(x)) #define SPLASSERT(expr) \ if (!(expr)) { \ DbgMsg( "Failed: %s\nLine %d, %s\n", \ #expr, \ __LINE__, \ __FILE__ ); \ DebugBreak(); \ } VOID vDbgSingleThreadReset( PDWORD pdwThreadId ); VOID vDbgSingleThread( PDWORD pdwThreadId ); VOID vDbgSingleThreadNot( PDWORD pdwThreadId ); VOID DbgMsg( LPCSTR pszMsgFormat, ... ); #ifdef DBGLOG #define DBGMSG( uDbgLevel, argsPrint ) \ vDbgLogError( MODULE_DEBUG, \ uDbgLevel, \ __LINE__, \ __FILE__, \ MODULE, \ pszDbgAllocMsgA argsPrint ) LPSTR pszDbgAllocMsgA( LPCSTR pszMsgFormatA, ... ); VOID vDbgLogError( UINT uDbg, UINT uDbgLevel, UINT uLine, LPCSTR pszFileA, LPCSTR pszModuleA, LPCSTR pszMsgA ); #else VOID DbgBreakPoint( VOID ); #define DBGMSG( Level, MsgAndArgs ) \ { \ if( ( (Level) & 0xFFFF ) & MODULE_DEBUG ){ \ DbgMsg MsgAndArgs; \ } \ if( ( (Level) << 16 ) & MODULE_DEBUG ) \ DbgBreakPoint(); \ } #endif #define SINGLETHREAD_VAR(var) \ DWORD dwSingleThread_##var #define SINGLETHREAD(var) \ vDbgSingleThread(&dwSingleThread_##var) #define SINGLETHREADNOT(var) \ vDbgSingleThreadNot(&dwSingleThread_##var) #define SINGLETHREADRESET(var) \ vDbgSingleThreadReset(&dwSingleThread_##var) #else #define MODULE_DEBUG_INIT( print, break ) #define DBGMSG( uDbgLevel, argsPrint ) #define SPLASSERT(exp) #define SINGLETHREAD_VAR(var) #define SINGLETHREAD(var) #define SINGLETHREADNOT(var) #define SINGLETHREADRESET(var) #endif // // Automatic checking if an object is valid. // #if DBG VOID vWarnInvalid( PVOID pvObject, UINT uDbg, UINT uLine, LPCSTR pszFileA, LPCSTR pszModuleA ); #define VALID_PTR(x) \ ((( x ) && (( x )->bValid( ))) ? \ TRUE : \ ( vWarnInvalid( (PVOID)(x), MODULE_DEBUG, __LINE__, __FILE__, MODULE ), FALSE )) #define VALID_OBJ(x) \ ((( x ).bValid( )) ? \ TRUE : \ ( vWarnInvalid( (PVOID)&(x), MODULE_DEBUG, __LINE__, __FILE__, MODULE ), FALSE )) #define VALID_BASE(x) \ (( x::bValid( )) ? \ TRUE : \ ( vWarnInvalid( (PVOID)this, MODULE_DEBUG, __LINE__, __FILE__, MODULE ), FALSE )) #else #define VALID_PTR(x) \ (( x ) && (( x )->bValid())) #define VALID_OBJ(x) \ (( x ).bValid()) #define VALID_BASE(x) \ ( x::bValid( )) #endif #ifdef __cplusplus } #endif #endif // _DBGLOG_H