A template for debug messages

In all the drivers and applications we develop here at GuruCE, we always take the time to add plenty of logging because we know good logging will save us loads of time debugging our code (not that we ever have to debug code here of course... ;)).

Windows CE has a really great mechanism for debug logging called Debug Zones. This mechanism allows you to divide your debug messages into 16 zones and each of these zones can be turned on or off at run-time. This allows you to control the verbosity of your debug output and helps prevent cluttering of messages. Read this excellent blog post by Travis first before reading on: http://blogs.msdn.com/ce_base/archive/2006/12/18/debug-messages-and-debu...

To add debug logging using Debug Zones to your application or driver do the following:

1. Define your zones using the DEBUGZONE macro
1. Define a DBGPARAM structure and fill it
2. Call either DEBUGREGISTER or RETAILREGISTERZONES from your DllMain (driver) or WinMain (application)
3. Log messages using either DEBUGMSG or RETAILMSG

Sounds easy (and actually it is) but to make it more easy (and because we found ourselves doing the same thing over and over) we created a template we now use in all our driver and application code, even on projects targeted for Desktop Windows. Even though "Big" Windows doesn't have a "Debug Zone" mechanism you can still use the template. The big benefit of course being that your code is completely portable between desktop PC's and CE devices (and also MBS/UNICODE)! The only thing you can't do is switch debug zones at run-time, but you can still select which zones should be on or off at compile-time.

We have released these templates under GPL for the greater good.

Let us explain the template by walking through it; we'll start with DebugZones.cpp (the line numbers reflect the actual line numbers in the template files):

The first and most important thing to note is that you should not change anything in this file. You configure the template all through the header file, which we'll will be discussing later.

In this first part of DebugZones.cpp we simply define a global variable dpCurSettings of type DBGPARAM and fill the structure with defines from DebugZones.h. The __WMODULE__ corresponds to the "lpszName" member, the ZONEx_TEXT defines fill the "rglpszZones" array and finally RETAILZONES or DEBUGZONES (depending on whether you build a "debug" or "release" version of the code) corresponds to the "ulZoneMask" member of the DBGPARAM structure. The CE debug system uses this structure to get Debug Zone information from the module and to set or clear debug zones during execution of the module. When you use the template for code targeted at Desktop Windows this structure will only be used by the DEBUGMSG/RETAILMSG macros (they use the ulZoneMask member as a display condition).

This code is only used when you target Desktop Windows. Only Windows CE defines NKDbgPrintf so for Desktop Windows we had to create our own implementation of this function to make the Debug Zones system portable. This function simply takes a format string followed by a variable number of parameters and transforms that into a formatted string and outputs it to the debug output window of Visual Studio. Note that the maximum length of the formatted string is BUFFER_SIZE characters.

This next bit of code is a helper function that solves a problem when you want your code to be portable between MBS and UNICODE. MBS is multi-byte string, also called ANSI string, and UNICODE is, well, UNICODE strings. Let's say you are compiling for UNICODE but want to display a multi-byte string using a function that uses a format string. The way to do that is to use %S instead of %s in the format string. When you use %s in code compiled for UNICODE the variable indicated by %s should be in UNICODE. When you compile for MBS the variable indicated by %s should be MBS. In other words, %s indicates the "native" string format. If you want to display a multi-byte string in code compiled for UNICODE you'd use %S, and if you want to display a UNICODE string in code compiled for MBS you'd use %S as well. In other words, %S indicates the "opposite" string format. And here lies the problem: What if you want to display a multi-byte string regardless of whether the code is compiled for MBS or UNICODE?

Take a look at the following code:

Note that the _T macro is defined as L in UNICODE (making the following string a UNICODE string) and as nothing in MBS (leaving the following string a multi-byte string).

When compiled for UNICODE the above code works perfectly:

But now see what happens when you compile the above code for MBS:

You only get the output of the first line! So what just happened? Well, the _vstprintf_s function in NKDbgPrintf expected the first argument to be of the opposite string format. Since you compiled for MBS this means it expects a UNICODE string. The _vstprintf_s function detects it is not and bails out, setting szBuffer to an empty string.

The to_T function solves this problem:

When compiled for MBS the output is:

I can hear you say: So why don't you just use _T() in that 2nd call to NkDbgPrintf? And yes, you are right, in the above code that would work, but what if it's a variable pointing to a multi-byte string? You can't use _T() around a variable:

Line 67 defines the maximum number of times you can call this function before it will start overwriting its internal buffers. Increase this value if you want to use more than 4 parameters that need to be converted in one call. To understand this, see the following code and its output:

Output:

Let's move on to the real core of the template; DebugZones.h:

This is the part of the template you should change to match your driver or application. First, in line 33, change the __MODULE__ define to the name of your driver or application. If you are creating a flash driver you'd set this to "FLASH" for instance.

Uncomment line 36 and/or 37 to generate a DEBUGCHK whenever you use ERRMSG and/or WRNMSG. You'd usually only uncomment these lines when you are in the development stage (when you're still actively debugging your code).

Next, in lines 40 to 55, you define the friendly names of the debug zones you want. These names will show up when you use the Debug Zones dialog or the "zo" command from Platform Builder. The predefined ones are always useful:

• Init

Use this zone to display debug messages during the initialization phase of your driver. I use this zone in the Init function of drivers.

• Function

This zone is used to display function entry and exit. Used by the FUNC_ENTRY and FUNC_EXIT macros (I'll discuss those later)

• Memory

This zone is used to display memory allocation and de-allocation. Having a separate zone for memory really helps in identifying memory leaks or memory related problems in your driver or application (besides CeDebugX)

• Info

This zone is used to display general information. I use this zone a lot through-out my code and enabling this zone usually means I get heaps of debug messages, but also heaps of information about the flow of my code

• Warning

Use this zone for non-fatal errors (also known as warnings ;o)

• Error

Use this zone for fatal errors; situations where you had to abort a certain operation

Another zone I use often is "IOCTL". If my driver handles custom IOCTLs I use that zone to display information when those IOCTLs are handled. If you want to add the IOCTL zone you'd change line 43 to:

Lines 58 to 73 define the actual zone IDs. You use these defines as the first parameter of LOG_MSG (that I'll discuss later) to indicate the zone this message belongs to. After you added the IOCTL zone to the friendly names list, you'd change line 61 to:

Lines 76 to 91 define the zone masks. You use these defines to indicate which zones should be enabled by default. After you added the IOCTL zone to the zone ID list, you'd change line 79 to:

Line 93 and 94 define the default zones to use in a release build and a debug build. I enable zones INIT, WARNING and ERROR in a release build and add FUNCTION, MEMORY and INFO to debug builds. Note that in a "ship" build (on Windows CE, WINCESHIP=1) debug/retail messages are defined as "nothing" (so all the logging code is effectively removed from the final binary).

If you define FULL_CONTEXT (line 98) the LOGMSG macro will output the full path to the source code filename in front of the message, instead of just the module name. We don't enable this by default because it makes the debug output cluttered and less readable (but it can be very handy in some cases).

This concludes the part of DebugZones.h that you should change. The remainder of the code mostly deals with the differences between Desktop Windows and Windows CE:

The interesting part is from line 190 to 199 where we define a couple of macros that allow you to log messages in a good and consistent format:

• FUNC_ENTRY

Usage:

FUNC_ENTRY(format_string [, arg1, arg2, ...]);

Examples:

FUNC_ENTRY(_T("void"));
FUNC_ENTRY(_T("lpParameter = 0x%08X"), lpParameter);

Output:
(Note the '+' characters that indicate function entry)

ModuleName: +FunctionName(void)+
ModuleName: +FunctionName(lpParameter = 0xA5A5A5A5)+
• FUNC_EXIT

Usage:

FUNC_EXIT(format_string [, arg1, arg2, ...]);

Examples:

FUNC_EXIT(_T(""));
FUNC_EXIT(_T("return %s"), bRet ? _T("true") : _T("false"));

Output:
(Note the '-' characters that indicate function exit)

ModuleName: -FunctionName()-
ModuleName: -FunctionName(return false)-
• LOGMSG

Usage:

LOGMSG(ZONE_ID, format_string [, arg1, arg2, ...]);

Examples:

LOGMSG(ZONE_INIT, _T("Started successfully!\r\n"));
LOGMSG(ZONE_INFO, _T("dwID = %d\r\n"), dwID);

Output:

ModuleName:  FunctionName> Started successfully!
ModuleName:  FunctionName> dwID = 1234
• ERRMSG

Examples:

ERRMSG(_T("Invalid parameter (dwParam = %d)\r\n"), dwParam);

Output:

ModuleName:  FunctionName> ERROR: Invalid parameter (dwParam = 1234)
• WRNMSG

Examples:

WRNMSG(_T("Could not reach IP %s\r\n"), to_T(inet_ntoa(IPAddress)));

Output:

ModuleName:  FunctionName> WARNING: Could not reach IP 10.0.0.1

To use the Debug Zones template in your projects you simply add DebugZones.cpp and DebugZones.h to your solution and call RETAILREGISTERZONES(hMod) from your entry point function:

or in case of an application:

Note that the parameter to RETAIL/DEBUGREGISTERZONES MUST be NULL if you want to register debug zones from an application!

If you are using precompiled headers you have to set DebugZones.cpp to "Not Using Precompiled Headers" (in VS2008 right click DebugZones.cpp in your solution, click "Properties", then select "Precompiled Headers" under "Configuration Properties -> C/C++" and change the "Create/Use Precompiled Header" value). Now include "DebugZones.h" in any file you want to use debug zone logging.

The attached ZIP file contains the complete template.

I hope this template will prove as useful to you as it is to us!