Nicolas Besson - Microsoft Windows Embedded CE 6.0 Exam Preparation Kit

You can bypass debug zones in drivers and applications if you pass a Boolean variable to the DEBUGMSG and RETAILMSG macros that you can set to TRUE or FALSE when you rebuild the run-time image.

To use debug zones, you must define a global DBGPARAM variable with three fields that specify the module name, the names of the debug zones you want to register, and a field for the current zone mask, as summarized in Table 4-2.

Table 4-2 DBGPARAM elements

Windows Embedded CE supports a total of 16 named debug zones, yet not all have to be defined if the module doesn’t require them. Each module uses a separate set of zone names that should clearly reflect the purpose of each implemented zone.

The Dbgapi.h header file defines the DBGPARAM structure and debugging macros. Because these macros use a predefined DBGPARAM variable named dpCurSettings, it is important that you use the same name in your source code as well, as illustrated in the following code snippet.

#include

// A macro to increase the readability of zone mask definitions

#define DEBUGMASK(n) (0x00000001<

// Definition of zone masks supported in this module

#define MASK_INIT DEBUGMASK(0)

#define MASK_DEINIT DEBUGMASK(1)

#define MASK_ON DEBUGMASK(2)

#define MASK_FAILURE DEBUGMASK(13)

#define MASK_WARNING DEBUGMASK(14)

#define MASK_ERROR DEBUGMASK(15)

// Definition dpCurSettings variable with the initial debug zone state

// set to Failure, Warning, and Error.

DBGPARAM dpCurSettings = {

TEXT("ModuleName"), // Specify the actual module name for clarity!

{

TEXT("Init"), TEXT("Deinit"), TEXT("On"), TEXT("Undefined"),

TEXT("Undefined"), TEXT("Undefined"), TEXT("Undefined"),

TEXT("Undefined"), TEXT("Undefined"), TEXT("Undefined"),

TEXT("Undefined"), TEXT("Undefined"), TEXT("Undefined"),

TEXT("Failure"), TEXT("Warning"), TEXT("Error")

},

MASK_INIT | MASK_ON | MASK_ERROR

};

// Main entry point into DLL

BOOL APIENTRY DllMain( HANDLE hModule,

DWORD ul_reason_for_call, LPVOID lpReserved) {

if (ul_reason_for_call == DLL_PROCESS_ATTACH) {

// Register with the Debug Message service each time

// the DLL is loaded into the address space of a process.

DEBUGREGISTER((HMODULE)hModule);

}

return TRUE;

}

The sample code above registers six debug zones for the module that you can now use in conjunction with conditional statements in debugging macros. The following line of code shows one possible way to do this:

DEBUGMSG(dpCurSettings.ulZoneMask & (0x00000001<<(15)),

(TEXT("Error Information\r\n")));

If the debug zone is currently set to MASK_ERROR, the conditional expression evaluates to TRUE and DEBUGMSG sends the information to the debug output stream. However, to improve the readability of your code, you should use the DEBUGZONE macro defined in Dbgapi.h, as illustrated in the following code snippet, to define flags for your zones. Among other things, this approach simplifies the combination of debug zones through logical AND and OR operations.

#include

// Definition of zone flags: TRUE or FALSE according to selected debug zone.

#define ZONE_INIT DEBUGZONE(0)

#define ZONE_DEINIT DEBUGZONE(1)

#define ZONE_ON DEBUGZONE(2)

#define ZONE_FAILURE DEBUGZONE(13)

#define ZONE_WARNING DEBUGZONE(14)

#define ZONE_ERROR DEBUGZONE(15)

DEBUGMSG(ZONE_FAILURE, (TEXT("Failure debug zone enabled.\r\n")));

DEBUGMSG(ZONE_FAILURE && ZONE_ WARNING,

(TEXT("Failure and Warning debug zones enabled.\r\n")));

DEBUGMSG(ZONE_FAILURE || ZONE_ ERROR,

(TEXT("Failure or Error debug zone enabled.\r\n")));

The DBGPARAM field ulZoneMask is the key to setting the current debug zone for a module. You can accomplish this programmatically in the module by changing the ulZoneMask value of the global dpCurSettings variable directly. Another option is to change the ulZoneMask value in the debugger at a breakpoint within the Watch window. You can also control the debug zone through another application by calling the SetDbgZone function. Another option available at run time is to use the Debug Zones dialog box, illustrated in Figure 4-2, which you can display in Visual Studio with Platform Builder via the CE Debug Zones command on the Target menu.

Figure 4-2Setting debug zones in Platform Builder

The Name list shows the modules running on the target device that support debug zones. If the selected module is registered with the Debug Message service, you can find the list of 16 zones displayed under Debug Zones. The names correspond to the selected module's dpCurSettings definition. You can select or deselect zones to enable or disable them. By default, the zones defined in the dpCurSettings variable are enabled and checked in the Debug Zones list. For modules not registered with the Debug Message service, the Debug Zone list is deactivated and unavailable.

Windows Embedded CE enables the zones you specify in the dpCurSettings variable when you start the application or load the DLL into a process. At this point, it is not yet possible to change the debug zone unless you set a breakpoint and change the ulZoneMask value in the Watch window. However, CE supports a more convenient method through registry settings. To facilitate loading a module with different active debug zones, you can create a REG_DWORD value with a name that corresponds to the module name specified in the lpszName field of the dpCurSettings variable and set it to the combined values of the debug zones you want to activate. You can configure this value on the development workstation or the target device. It is generally preferable to configure this value on the development workstation because changing target device registry entries requires you to rebuild the run-time image, whereas a modification of the registry entries on the development workstation only requires you to restart the affected modules.