Module 4: Overview of the Windows CE .NET Debugging Process

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.
Module 4: Overview of the Windows CE .NET Debugging Process 11


About the Kernel Debugger

Requires a special operating system version

Remains active after the DLL being debugged stops

DLL remains active after stopping the debugger

Can debug modules loaded by Execute-in-Place (XIP)
applications

Platform Builder provides a kernel debugger that allows you to trace virtually
any code, ranging from device drivers to high-level applications. This is
different from the application debuggers provided in the Visual Studio.
The kernel debugger behaves differently than an application debugger. The
major differences are:

The kernel debugger requires a special Debug Build of the operating system
while an application debugger does not. In order to attach an image to the
kernel debugger, you must build an image with the debug kernel. This
kernel has a special stub (KdStub) added to the image during the build.

When an application being debugged stops, the kernel debugger remains
active. An application debugger stops as soon as the debugged application
ends.

When you stop debugging in the kernel debugger, the system continues to
run. With an application debugger, the application is terminated as soon as
the debugger is stopped.

The kernel debugger can debug modules loaded 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. You should build debug
drivers which incorporate all the symbols, and disables optimizations. It is
possible to kernel debug a driver retail build of the operating system, but you
lose the information on symbols that helps you to know where you are in the
operating system.
Create a Debug Image of the Operating System
From the Build menu, select a target type that has the word Debug in it, such as
Win32 (WCE PPC821) Debug. All other build actions are the same as for a
non-debug build.
Download the Debug Image to the Device
Download the image as normal.
Start the Debugger
If you built and download a debug image, the kernel debugger starts
automatically on system startup. Open the individual windows of the kernel
debugger by using the View menu, under Debug Windows.
Check the Debugger Status
Check the status of the debugger using the status monitor by clicking on it in
the Status Bar.
Module 4: Overview of the Windows CE .NET Debugging Process 13





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.