■ Use retail macros in release builds If you also want to use debug zones in release builds, include the global variable dpCurSettings and zone mask definitions in #ifndef SHIP_BUILD #endif guards and replace the call to DEBUGREGISTER with a call to RETAILREGISTERZONES.
■ Clearly identify the module name If possible, set the dpCurSettings.lpszName value to the module's file name.
■ Limit verbosity by default Set the default zones for your drivers to ZONE_ERROR and ZONE_WARNING only. When bringing up a new platform, enable ZONE_INIT.
■ Restrict the error debug zone to unrecoverable issues Use ZONE_ERROR only when your module or significant functionality fails due to incorrect configuration or other issues. Use ZONE_WARNING for recoverable issues.
■ Eliminate all errors and warnings if possible Your module should be able to load without any ZONE_ERROR or ZONE_WARNING messages.
Target Control Commands
The Target Control service provides access to a command shell for the debugger to transfer files to the target device and debug applications. This target control shell, displayed in Figure 4-3, is accessible from within Visual Studio with Platform Builder via the Target Control option on the Target menu. However, it is important to keep in mind that the target control shell is only available if the Platform Builder instance is attached to a device through KITL.
Figure 4-3 The target control shell
Among other things, the target control shell enables you to perform the following debugging actions:
■ Break into the Kernel Debugger (break command).
■ Send a memory dump to the debug output (dd command) or to a file (df command).
■ Analyze memory usage for the kernel (mi kernel command) or the entire system (mi full command).
■ List processes (gi proc command), threads (gi thrd command), and thread priorities (tp command), as well as the modules loaded on the system (gi mod command).
■ Launch processes (s command) and end processes (kp command).
■ Dump the processes heap (hp command).
■ Enable or disable the system profiler (prof command).
For a complete list of target control commands, see the section "Target Control Debugging Commands" in the Windows Embedded CE 6.0 Documentation, available on the Microsoft MSDN® Web site at http://msdn2.microsoft.com/en-us/library/aa936032.aspx.
Debugger Extension Commands (CEDebugX)
In addition to the regular debugger commands, the Target Control service provides the debugger with a debugger commands extension (CEDebugX) to increase the efficiency of kernel and application debugging. This extension provides additional features to detect memory leaks and deadlocks and diagnose the overall health of the system. The additional commands are accessible through the target control shell and start with an exclamation point (!).
To use CEDebugX, you need to break into the Kernel Debugger by using the break command in the target control shell or the Break All command on the Target menu in Visual Studio. Among other things, you can then enter a !diagnose all command to identify the potential reason for a failure, such as heap corruption, deadlocks, or memory starvation. On a healthy system, the CEDebugX should detect no any issues, as illustrated in Figure 4-4.
Figure 4-4 Diagnosing a run-time image with CEDebugX
The !diagnose all command runs the following diagnostics:
■ Heap Diagnoses all the heap objects of all processes on the system to identify potential content corruption.
■ Exception Diagnoses an exception that occurs on the system and is able to provide details on the exception, such as process and thread ID, and PC address at the exception time.
■ Memory Diagnoses the system memory to identify potential memory corruptions and low memory conditions.
■ Deadlock Diagnoses the thread states and system objects (see Chapter 3 for more details on thread synchronization). It can provide a list of system objects and thread IDs that generated the deadlock.
■ Starvation Diagnoses threads and system objects to identify potential thread starvation. Starvation occurs when a thread is never scheduled on the system by the scheduler because the scheduler is busy with higher-priority threads.
Advanced Debugger Tools
The target control shell and CEDebugX commands enable you to perform a thorough analysis of a running system or a CE dump file (if you select the CE Dump File Reader as the debugger to perform postmortem debugging), yet you are not restricted to the command-line interface. Platform Builder includes several graphical tools with a dedicated purpose to increase your debugging efficiency. You can access these advanced debugger tools in Visual Studio via the Debug menu when you open the Windows submenu.
The Platform Builder IDE includes the following advanced debugger tools:
■ Breakpoints Lists the breakpoints enabled on the system and provides access to the breakpoint properties.
■ Watch Provides read and write access to local and global variables.
■ Autos Provides access to variables similar to the Watch window, except that the debugger creates this list of variables dynamically, while the Watch window lists all manually added variables whether they are accessible or not. The Autos window is useful if you want to check the parameter values passed to a function.
■ Call Stack Accessible only when the system is in a break state (code execution has halted on a breakpoint). This window provides a list of all processes enabled on the system and a list of hosted threads.
■ Threads Provides a list of the threads running in the processes on the system. This information is dynamically retrieved and can be updated at any time.
■ Modules Lists the modules loaded and unloaded on the system and provides the memory address where those modules are loaded. This feature is useful for identifying whether a driver DLL is actually loaded or not.
■ Processes Similar to the Threads window, this window provides a list of the processes running on the system. Among other things, you can terminate processes if required.
■ Memory Provides direct access to device memory. You can use memory addresses or variable names to locate the desired memory content.
■ Disassembly Reveals the assembly code of the current code line executed on the system.
■ Registers Provides access to the CPU register values when running a specific line of code.
■ Advanced Memory Can be used to search the device memory, move portions of memory to different sections, and fill memory ranges by using content patterns.
■ List Nearest Symbols Determines a specific memory address for the nearest symbols available in the binaries. It also provides the complete path to the file containing the symbol. This tool is useful to locate the name of a function that generated an exception.