Module 6: Debugging a Windows CE Image

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

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

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

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)

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

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

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

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; . . .

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

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

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); . . .

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

Platform Settings

Service Settings

Enable Kernel Debugging

Environment Variables

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

Target Menu

Target | Advanced Commands (CESH)…

Target | Run Program…

Target | Processes

Target | Threads

Target | Modules and Symbols

Target | Exceptions

Target | Debug Zones…

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

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

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

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

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.

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

Debugger Windows: Source Code and Disassembly

Debugger Windows: Watch

Debugger Windows: Variables

Debugger Windows: Call Stack and Registers

Debugger Windows: Advanced Memory

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

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

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.

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

Lab A: Debugging a Windows CE Image

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