Debug Zones: Eliminating Excess Chatter

Posted by Riki June

Last December Travis wrote an entry on Debug Zones, I’d like to follow this up with some practical examples. If you haven’t read his article, then I’d recommend you start there:

https://blogs.msdn.com/ce_base/archive/2006/12/18/debug-messages-and-debug-zones-in-windows-ce.aspx

To highlight his points, this document takes you though turning off as much debug chatter during boot as reasonable, but without modifying source code. Because, repeat after me: modifying the $(WINCEROOT)/private/ source code is a Bad Thing.

Step 1: Insert DLL Names in Pegasus

The easiest step is to add any module names into [HKEY_CURRENT_USER\Pegasus\Zones] on your development PC. This often works; as well behaved modules will have the same Debug Zone name as their filename. The .zip file in the link below contains a the DebugZone.reg file for your Desktop PC, which contains some module names I use in my development image:

<Link to DebugZone.zip>

Step 2: Insert Debug Names into Pegasus

Strictly speaking these Debug Zone names have to match the name the module registered, and (unfortunately) some modules register a different name to their filename. To find the right Debug Zone name, do a search in ‘sources’ files for the dll name, then search within that directory for ‘dpCurSettings’. For MDD/PDD devices Windows Desktop Search can be a blessing.

I would like to draw your attention to some instances from the above .reg file, whose Debug Zone do not match the module name:

The Early boot process:

Nk.exe and kernel.dll can be overridden at ‘make image’ time in your config.bib in CE6, like so:

To override the Debug Zone in a module as it loads, however, requires the registry APIs to be available which in turn requires the file system (filesys.dll) be loaded. Any file loaded before this cannot be overridden as it is loaded.

To override Debug Zones using the Development PC, the Release File System (relfsd.dll) must also be available.

In theory any modules loaded after FileSys can have their Debug Zone overridden at load time. Unfortunately modules loaded in Stage One boot, before the HIVE Registry goes read-write, ignore the Debug Zone that is set. So the net result is all files loaded in Stage One boot must have their debug zone overridden after they have loaded…

Step 3: Calling SetDbgZone()

To do this, I have written a little application you can add to your project. The application is launched as early as possible and iterates though the loaded modules calling SetDbgZone() on modules you specify. This application can be added to your project.reg with ‘#ifdef DEBUG’ style guards.

<Link to DebugZone.zip>

The list of modules I call SetDbgZone on:

What is Left?

Using the above application and .reg keys, you can go further and turn off all zones, and, in theory, there should be no messages. But sadly this is not the case. Some modules use DEBUGMSG(1 to output messages, which means you cannot turn them off. This is a bad practice to have in your drivers, and is something we are working towards removing in the Windows CE code.

A special case is the module loading code which outputs the message you will be familiar with:

Best Practices

This leads to best practices for Debug Zone use:

• Do NOT use DEBUGMSG(1
• Try to avoid RETAILMSG(1, although with some MDD/PDD drivers this cannot be avoided
• If you wish to have RETAILMSGs: place your declaration of dpCurSettings and ZONE_* inside ‘#ifndef SHIP_BUILD’ guards, rather than ‘#ifdef DEBUG’ and use RETAILREGISTERZONES() to replace DEBUGREGISTER().
• Where possible, set your drivers Debug Zone Name to the file name.
• Set the default zones for your drivers to ZONE_ERROR and ZONE_WARNING
• When bringing up a new platform, also turn on ZONE_INIT
• ZONE_ERROR should only be used when you driver is disabling significant functionality due to incorrect configuration, otherwise use ZONE_WARNING to indicate an issue which the driver is able to recover from.
• Your driver should be able to load without any ZONE_ERROR or ZONE_WARNING messages, if configuration correctly. In an ideal world, these two zones would be synonymous with your compliers error and warning messages.

Summary

These techniques can be employed to help reduce the boot chatter for developers. We still recommend you spend some time looking though these messages before you ship your device to ensure they don’t highlight something more sinister.

Have I missed some standard modules you use? Please post them in the comments so others can use them!

DebugZone.zip