Module 4: Overview of the Windows CE .NET Debugging Process 1 Contents Overview 4 Overview of the Debug Process 5 Release Builds and Debug Builds 6 Introduction to the Kernel Debugger 11 Kernel Debugger Windows 14 Demonstration: Kernel Debugger Windows 21 Understanding Windows CE Remote Tools 22 Other Debugging Techniques 30 Other Debugging Techniques (continued) 32 Review 34 Module 4: Overview of the Windows CE .NET Debugging Process 2 Module 4: Overview of the Windows CE .NET Debugging Process Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, places or events is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.  2001 Microsoft Corporation. All rights reserved. Microsoft, MS-DOS, Windows, Windows NT, Visual Studio are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries. The names of actual companies and products mentioned herein may be the trademarks of their respective owners. Module 4: Overview of the Windows CE .NET Debugging Process 3 Overview  Overview of the Debug Process  Introduction to the Kernel Debugger  Kernel Debugger Windows  Understanding Windows CE Remote Tools  Other Debugging Techniques The process of locating and fixing errors in your application is known as debugging. There are no magic tricks to debugging, and there is no fixed sequence of steps that works every time. Basically, debugging helps you understand what is happening when your application runs. Every development environment is supported by special debugging tools. Debugging tools give you a snapshot of the current state of your application. In this module, you learn about the Windows CE .NET debugging process. You also learn about the different tools and techniques offered by Windows CE .NET to make debugging simple and easy. After completing this module, you will be able to:  Describe the Windows CE .NET debug process.  Describe the use of kernel debugger.  Identify the various kernel debugger window.  Identify the use of the remote tools supported by Platform Manager.  Recognize alternative debugging techniques. 4 Module 4: Overview of the Windows CE .NET Debugging Process    Overview of the Debug Process  Release Builds and Debug Builds  Building a Kernel Debug Image  Building a Driver Debug Image  Setting Debug Transport In this section, you will learn to differentiate between release and retail builds, and kernel debug image and driver debug image. You will learn how to build debug images and driver debug images. Then, you will also learn how to set debug transport. Module 4: Overview of the Windows CE .NET Debugging Process 5 Release Builds and Debug Builds  Release Build (Retail Image) z Built for deployment in the end product  Debug Build z Creates an operating system image capable of attaching to the debug tools of the Platform Builder  Two Techniques for Building Debug Images z Kernel Debug Image z Driver Debug Image Debug Drivers are DLLS built in debug mode containg debug messages Before you debug a platform, you must build an operating system image that can be debugged after it is downloaded to a target. When you create a project, the IDE automatically creates both a debug configuration and a release configuration, with default options set for each. Depending on which configuration you choose, you can build either a debug operating system image or a release operating system image. In addition, you can build a debugger operating system image that uses the kernel debugger. Release Build / Retail Image A Release build, also known as a Retail image, is the one which is built for deployment in the end product. It does not contain the kernel stub which is used to attach to the kernel debugger. It therefore boots without the connection to the IDE debugger necessary for a debug image. It does not build the object files used by the debugger to watch variables in any given dll. It also does not contain the debug driver builds which are compiled with debug zones and debug messages. The release build:  Uses .lib files from the directory %_WINCEROOT%\Public\Common\Oak\Lib\<microprocessor>\Retail  Places object files in a Release directory  Provides no symbolic debugging information  Is optimized for maximum speed  Has a smaller image size than either a debug or a debugger image Debug Build In order to use the debug tools provided in the Platform Builder IDE, you must first build a Debug image that is capable of attaching to them. A Debug build:  Uses .lib files from the directory %_WINCEROOT%\Public\Common\Oak\Lib\<microprocessor>\Debug 6 Module 4: Overview of the Windows CE .NET Debugging Process  Places object files in a Debug directory  Provides full symbolic debugging information, in Microsoft format  Provides Ethernet debug functions  Provides ability to turn debug zones on and off  No optimization. Optimization generally makes debugging more difficult. The Debug image contains two independently controllable debugging techniques:  Kernel Debug Image  Driver Debug Image You can build an image capable of attaching to the kernel debugger which does not contain debug drivers and vice versa. Kernel Debug Image The Kernel Debug Image contains a debug version of the kernel that includes KdStub. This build is required for using the kernel debugger. Driver Debug Image A Driver Debug Image is built with debug drivers. These are DLLs which have been built in debug mode so they contain debug messages. They are also concurrently built with their object files. Object files are used by the kernel debugger for watching variables within the driver. There are three ways to build debug images: 1. Full Kernel Debug image including debug drivers (this is the default debug build and the most common technique). 2. Kernel Debug image without debug drivers (Debug configuration with Build Type set to Retail.). 3. Driver Debug image without KdStub (Retail configuration with Build Type set to Debug). Module 4: Overview of the Windows CE .NET Debugging Process 7 Building a Kernel Debug Image  Two ways to build a Kernel Debug Image: z Set the Active Configuration by using the drop-down menu z Access the Platform Settings property sheet and independentl y control how your image is built There are two ways to set Microsoft Windows CE Platform Builder to build a Kernel Debug image:  From the Platform Builder toolbar, you can set the Active Configuration by using the dropdown menu. A Debug image setup in this way will have both the kdstub for kernel debugging and also the debug drivers.  Alternatively, you can access the Platform Settings property sheet and independently control whether your image is built with kernel integrated debugging functionality or debug drivers. 8 Module 4: Overview of the Windows CE .NET Debugging Process Building a Driver Debug Image  If you change the Active Configuration for the Platform from retail to debug, the default behavior changes both kernel debugging and driver debugging  By setting the Build Type to Debug, you are setting up the build to create debug drivers If you change the Active Configuration for the Platform from Retail to Debug, the default behavior changes both kernel debugging and driver debugging. By setting the Build Type to Debug, you are setting up the build to create debug drivers. Module 4: Overview of the Windows CE .NET Debugging Process 9 Setting Debug Transport  Select a transport: z Ethernet or Serial  The Kernel Independent Transport Layer (KITL) transport is used for communication between the host computer and the target device  Platform Manager uses the KITL transport to download and boot the operating system on a target device  KITL allows to transfer an operating system image to the target device and perform various forms of debugging To enable the debugging connection, you must select a transport.  The transport can be either Ethernet or serial. You can use the Services property sheet of the Configure Remote Connection dialog box. To access the Configure Remote Connection dialog box, from the Target menu, click Configure Remote Connection.  The Kernel Independent Transport Layer (KITL) transport is used for communication between the host computer and the target device over any hardware for which the manufacturer supplies an appropriate transport.  The KITL transport will download and boot the operating system on a target device. KITL allows remote tools to connect to the target device over the same channel used by the kernel debugger. KITL allows you to transfer an operating system image to the target device and perform various forms of debugging. In previous versions of the Windows CE operating system, only a small number of hard-wired transports were capable of working with communications hardware. KITL is an abstraction layer that makes the physical transport transparent to the tools. This removes the need for development boards and legacy connections to debug the kernel.  By using KITL, you can define your own services to communicate between applications running on the development workstation and applications running the target device.  To connect to a target device with KITL, you must first configure the connection to the target device using Windows CE Platform Manager. 10 Module 4: Overview of the Windows CE .NET Debugging Process    Introduction to the Kernel Debugger  About the Kernel Debugger  Starting the Kernel Debugger In this section, you will learn about the differences between the kernel debugger and the application debugger. You will also learn how to start the debugger. [...]... 4: Overview of the Windows CE NET Debugging Process Kernel Debugger Windows Source Code and Disassembly Windows Watch Window Variables Window Call Stack and Registers Windows Advanced Memory Dialog Box In this section, you will learn about the different windows present in kernel debugger that help you in the process of debugging 13 14 Module 4: Overview of the Windows CE NET Debugging Process Source... releasing the memory that it allocates Remote Heap Walker provides a process list window, a heap list window, and a heap dump window Process List Window The process list window is the default window for Remote Heap Walker The process list window shows the name of the flag associated with the default heap 26 Module 4: Overview of the Windows CE NET Debugging Process for each process From the process list... for several types of data and then list the memory location that matches the search You can also move and fill memory 20 Module 4: Overview of the Windows CE NET Debugging Process Demonstration: Kernel Debugger Windows In this demonstration, you will identify the different kernel debugger windows Module 4: Overview of the Windows CE NET Debugging Process 21 Understanding Windows CE Remote Tools Remote... to trace issues such as timing related problems or DMA transfers with your device driver Module 4: Overview of the Windows CE NET Debugging Process 31 Other Debugging Techniques (continued) Extended Debugging Interface (eXDI) Controls the execution of a target device Examines and modifies the state of the device IDE Debug Commands Extracted from a legacy command line tool called CESH or the CE Shell... interrupts Module 4: Overview of the Windows CE NET Debugging Process Remote Performance Monitor Measures the performance of remote Windows CE based platforms Helps you view the behavior of performance objects, such as processors, memory, threads, and processes Provides charting, alerting, and reporting capabilities that reflect both current activity and ongoing logging Windows CE Remote Performance Monitor... downcasting and the display format specifier To access the Variables windows, from the View menu, point to Debug Windows and then, click Variables 17 18 Module 4: Overview of the Windows CE NET Debugging Process Call Stack and Registers Windows Call Stack window displays the stack of function calls that are currently active The Registers window displays all the CPU registers of the target platform There are... by Execute-in-Place (XIP) applications 12 Module 4: Overview of the Windows CE NET Debugging Process Starting the Kernel Debugger Create a Debug Image of the operating system Download the Debug Image to the device Start the debugger Check the debugger status in the Status Bar To make the best use of the kernel debugger, you will most likely want to build a complete debug version of the operating system... many remote tools can display multiple windows The toolbar buttons and some of the menu items in the window for the remote tool become active after you connect to a target device 22 Module 4: Overview of the Windows CE NET Debugging Process Remote Kernel Tracker Provides a visual representation of the execution of the Windows CE operating system on a target device Enables you to view thread interactions,... fatal to a routine Module 4: Overview of the Windows CE NET Debugging Process Review Overview of the Debug Process Introduction to the Kernel Debugger Kernel Debugger Windows Understanding Windows CE Remote Tools Other Debugging Techniques 1 Which two debugging mechanisms are included in a full debug image? 2 Does the kernel debugger work in XIP regions? 3 Why should you avoid leaving the call stack window... the target platform To access the Registers window, from the View menu, point to Debug Windows, and then click Registers Module 4: Overview of the Windows CE NET Debugging Process 19 Advanced Memory Dialog Box Allows the search for data inside the system memory Lists the memory location that matches the search The Advanced Memory dialog box allows you to search for data inside the system memory It can . Other Debugging Techniques (continued) 32 Review 34 Module 4: Overview of the Windows CE .NET Debugging Process 2 Module 4: Overview of the Windows CE. Module 4: Overview of the Windows CE .NET Debugging Process 1 Contents Overview 4 Overview of the Debug Process 5 Release Builds