Debug Message Tips (Compact 2013)

3/26/2014

Debug messages can be a useful tool for developers when debugging code. As you write your code, consider adding meaningful debug messages that will help other developers who are unfamiliar with the details of your implementation.

The following list offers a few basic guidelines that can help make debug message output more useful:

• Indicate the source of the message.
• Write meaningful messages. Debug messages should be easily understood by someone such as a product support technician who is unfamiliar with the implementation of the component.
• Highlight significant types of messages with consistent symbols that help identify them, such as watched function calls or error messages.
• Use debug macros to print messages based on build type.
• Use debug zones to filter output.

Indicate the source of the message

All debug messages should clearly identify the source of the message. By identifying the source, you can save significant amounts of time for yourself and also prevent other developers from wasting time and resources by searching for the code that generated the message.

The following list provides some suggestions for providing clear identification:

• Component/module name. To make it possible for the user to easily map messages to modules controlled through the integrated development environment (IDE) or shell, include the module name in the debug message. For example, the following message shows that the problem arose in the NE2000 component and clearly states that the problem encountered involved handling interrupts:

  TID:6319237a NE2000:HandleInterrupt - Loop in ISR detected
  

• File/line number. Some developers find it easier to track down messages by file and line number. The __FILE__ and __LINE__ macros can be used to automatically include this information in your debug messages. For example, instead of identifying the NE2000 component, the message now indicates that it originated from a file named interrup.c at line 247:

  TID:6319237a interrup.c#247:HandleInterrupt - Loop in ISR detected
  

• Combination of component and file line number. To make messages as informative as possible, include identifying information about both component and file location, as shown in the following example message.

  TID:6319237a [NE2000, interrupt.c#247]:HandleInterrupt - Loop in ISR detected
  

Write meaningful messages

• **Be as specific as possible about what went wrong.**The following example shows an error message produced by the Romimage Tool (romimage.exe) that is included with Windows Embedded Compact:

  ERROR: The ROMImage tool encountered an error processing Module nk.exe.
  Instructions explaining how to correct the problem can be found in 
  section "Invalid Fix-ups in ROM Image" of the online documentation. 
  Use the following information to correct the problem:
  Relocation Offset = 0x778
  Relocation Page   = 0x33000
  Opcode            = 0x80a4718c
  Opcode Address    = 0x8c5b3778
  

Highlight significant types of messages with consistent symbols

Establish a convention for highlighting commonly occurring events, such as function entry and exit. In this way, the targeted events can be quickly spotted in the output.

For example, you can:

• Prepend a plus sign ("+") for function entry and a minus sign ("-") for function exit. For example:

  TID:83c22f66 CXPORT:+CTEAllocMem(64)
  

  Some developers prefer to place the plus sign or minus sign at the beginning of the message, such as this example:

  TID:83c22f66 +CXPORT:CTEAllocMem(64)
  

Use debug macros to print messages based on build type

You can use debug macros to print debug messages to the default output stream based on whether you want these messages to appear in Debug, Checked, Retail, and Ship builds. For more information about debug macros, see Add Debug Messages.

Note

Many components have no message output during normal operation. In general, this is a good goal.

The following suggestions show additional ways to limit debug output to only the messages that you decide are important.

• Avoid direct calls in your code into NKDbgPrintfW and OutputDebugString. These calls are not affected by debug zone filters.
• Restrict output from the RETAILMSG macro to critical messages that indicate that something is seriously wrong with the system. If you need more in-depth debugging about a retail image, consider using the debug version of your .dll or .exe file in an otherwise retail image.

Use debug zones to filter output

Always use debug zones to suppress messages that may not be of interest to other developers. For information about how to set up debug zones, see Use Debug Zones.

The debug zones in the following table are standard across many Windows Embedded Compact OS components. If you have similar zones in your component, it is a good idea to use the same zone numbers and naming convention.

Zone	Name	Description
0	Init	This zone includes messages printed out during initialization. Typically, disabled by default.
12	Alloc	This zone tracks memory allocations, free list sizes, and so on. Typically, disabled by default.
13	Function	This zone prints verbose messages about every function entry and exit. Typically, disabled by default.
14	Warning	This zone includes unusual conditions that can be normal but might indicate a problem. Can be enabled or disabled by default, depending on whether the messages meet the guidelines for the previous default messages listed in this table.
15	Error	Error and failure conditions. Typically, enabled by default.

See Also

Concepts

Add Debug Messages
Kernel Debugger
Debugging

Other Resources

Windows Embedded Compact 2013