1. Module 6: Debugging a Windows CE Image

2. Overview Debug Zones IDE Debug Setup IDE Debug Commands
Platform Builder Integrated Kernel Debugger
Other Debugging Techniques

3. Debug Zones What Are Debug Zones? Defining Debug Zones
Declaring Debug Zones
Registering Debug Zones
Using Debug Zones

4. What Are Debug Zones?
Provide debug information without halting the system
Allow you to control the output of debug messages
Debug zone = Name + Output status (On/Off)
16 debug zones per module
Must be registered with the debug subsystem to dynamically change the output status of debug zones.
Use macros to output debug messages

5. Defining Debug Zones // Define Ids for each zone (1->15)
#define ZONEID_INIT 0
#define ZONEID_SECOND 1
. . .
#define ZONEID_ERROR 15
// Define masks for each zone (16-bit mask)
#define ZONEMASK_INIT (1<<ZONEID_INIT)
#define ZONEMASK_SECOND (1<<ZONEID_SECOND)
#define ZONEMASK_ERROR (1<<ZONEID_ERROR)

6. Defining Debug Zones (continued)
#ifdef DEBUG
// These constants are used as the first arg to MACROS
#define ZONE_INIT DEBUGZONE(ZONEID_INIT)
#define ZONE_SECOND DEBUGZONE(ZONEID_SECOND)
. . .
#define ZONE_ERROR DEBUGZONE(ZONEID_ERROR)
#else
// Disable all output when compiled in release.
#define ZONE_INIT 0
#define ZONE_SECOND 0
#define ZONE_ERROR 0
#endif

7. Declaring Debug Zones Include DbgApi.h header file in your source code
Declare a DBGPARAM structure that contains:
Your module name
A name for each debug zone
An initial mask for the output status of all debug zones
DBGPARAM structure must be called dpCurSettings
dpCurSettings must be a global variable in your module

8. Declaring Debug Zones (continued)
#ifdef DEBUG
// Init DBGPARAM structure
DBGPARAM dpCurSettings = {
TEXT(”TestDebugZones"),
TEXT("Init"),
TEXT(”Second"),
. . .
TEXT("Error") },
// As a default, turn on init & error debug zones.
ZONEMASK_INIT | ZONEMASK_ERROR };
#endif

9. Registering Debug Zones
The DEBUGREGISTER(param) macro registers the dpCurSettings structure with the debug subsystem
Override zone mask with a REG_DWORD value in HKCU\Pegasus\zones\module_name
DllMain(...) {
switch(ulReason) {
case DLL_PROCESS_ATTACH:
DEBUGREGISTER(hMod);
break;
. . .

10. Using Debug Zones Send debug messages through macros
First parameter is a condition. The message is issued when condition is TRUE.
Usually condition is a zone (ZONE_zonename )
Can also be an expression
Second parameter is a Unicode string representing the message
Retail and Debug macros

11. Using Debug Zones (continued)
DEBUGMSG(cond,msg), RETAILMSG(cond,msg)
Conditionally output message
DEBUGLED(cond,word), RETAILLED(cond,word)
Conditionally output word to LEDs
ERRORMSG(cond,msg)
Conditionally output ERROR + file + line + msg
DEBUGCHK(expr)
Issue a DebugBreak if the expr evaluates to FALSE

12. Using Debug Zones (continued)
DEBUGMSG (ZONE_INIT, (TEXT (”TestDebugZones starting 1\n")));
RETAILMSG(1, (TEXT (” TestDebugZones starting 2\n")));
hThread = CreateThread (…PeriodicThread…)
if (NULL == hThread) {
ERRORMSG (1, (TEXT (”GetLastError: %u\n"), GetLastError() ));
return (1); }
DWORD PeriodicThread(LPVOID pUnused)
int i = 0;
while (1) {
DEBUGMSG(ZONE_SECOND,(TEXT(”Seconds: %d\n"), i));
Sleep(1000);
. . .

13. IDE Debug Setup Platform Settings Service Settings
Enabling Kernel Debugging
Environment Variables

14. Platform Settings

15. Service Settings

16. Enable Kernel Debugging

17. Environment Variables

18. IDE Debug Commands Target Menu Target | Advanced Commands (CESH)…
Running Commands : An Alternate Method
Processes
Threads
Modules and Symbols
Setting Exception Handling
Debug Zones

19. Target Menu

20. Target | Advanced Commands (CESH)…

21. Target | Run Program…

22. Target | Processes

23. Target | Threads

24. Target | Modules and Symbols

25. Target | Exceptions

26. Target | Debug Zones…

27. Platform Builder Integrated Kernel Debugger
About the Kernel Debugger
Starting the Debugger
Setting a Breakpoint
Handling Exceptions
Debugger Windows

28. About the Kernel Debugger
Requires a special OS version
Remains active after the application being debugged stops
Application remains active after stopping the debugger
Can debug modules loaded by XIP applications

29. Starting the Debugger Create a Debug Image of the Operating System
Download the debug image to the device
Start the Debugger
Target | Start | Debugger
Check the Debugger Status
Target | Status Monitor

30. Setting a Breakpoint Symbols must be loaded first
Breakpoints can be set before starting the OS image
Windows CE OS must be halted to set breakpoints after the OS has started
Debug| Break
DebugBreak Win32 API
Open the source file
Put breakpoints in the source code, assembly code, and call-stack window

31. Handling Exceptions When exception occurs, you can choose to:
Stop always
Stop if not handled
If the debugger is stopped in order to debug an exception, you can choose:
Go handled - the kernel again executes the instruction that caused the exception.
Go not handled - the kernel tries to find a handler of the exception. If one is not found, it then tries to handle the exception, and if unsuccessful, terminates the thread that caused the exception.

32. Debugger Windows Source Code and Disassembly windows Watch window
Variables window
Call Stack and Registers windows
Advanced Memory Dialog Box

33. Debugger Windows: Source Code and Disassembly

34. Debugger Windows: Watch

35. Debugger Windows: Variables

36. Debugger Windows: Call Stack and Registers

37. Debugger Windows: Advanced Memory

38. Other Debugging Techniques
Why Use Alternate Methods?
Logic Analyzer
Debug LEDs

39. Why Use Alternate Methods?
Some devices need quick response from the system and cannot allow even a slight delay during processing
Debug messages affect timing issues
The kernel debugger needs the system to be in break mode
There are less intrusive methods for solving timing issues when debugging
Logic analyzer
LEDs

40. Logic Analyzer Records probes’ activities simultaneously
Supports sophisticated reports and graphs
Useful for debugging bus/timing problems
Requires hardware attach points
LA Connector
Probe points
Specialized bus analyzer for ISA, PCI, etc.

41. Debug LEDs
You must code OEMWriteDebugLed function to enable Debug LEDs routines
LEDs activities can be monitored and decoded later
Less intrusive than debug messages
Use DEBUGLED and RETAILLED macros
Can be used for measuring ISR latency

42. Lab A: Debugging a Windows CE Image

43. Review Debug Zones IDE Debug Setup IDE Debug Commands
Platform Builder Integrated Kernel Debugger
Other Debugging Techniques