Microsoft® Windows® 2000 Driver Development Kit

Author Microsoft Corporation Pages 3616 Disk N/A Level Int/Adv Published 04/12/2000 ISBN 9780735609297 ISBN-10 0-7356-0929-2 Price(USD) $169.99 To see this book's discounted price, select a reseller below.	More Information About the Book Table of Contents Sample Chapter Index Related Series Related Books About the Author Support: Book & CD Rate this book

Chapter 1: Driver Development Environment

• 1.1 Free Build and Checked Build
• 1.2 Debugging Environment

Chapter 1 Driver Development Environment

If the driver depends on underlying devices that include high-end workstations and servers, the driver should also be debugged and tested on a multiprocessor machine.

This chapter covers the following topics:

• 1.1 Free Build and Checked Build
• 1.2 Debugging Environment

1.1 Free Build and Checked Build

• The free build (or retail build) is the end-user version of the operating system. The system and drivers are built with full optimization, debugging asserts are disabled, and debugging information is stripped from the binaries. A free system and driver is smaller and faster, and it uses less memory.
• The checked build serves as a testing and debugging aid in the developing of the operating system and of kernel-mode drivers. The checked build contains extra error checking, argument verification, and debugging information that is not available in the free build. A checked system or driver can help isolate and track down driver problems that can cause unpredictable behavior, result in memory leaks, or result in improper device configuration.

Although the checked build provides extra protection, it consumes more memory and disk space than the free build. System and driver performance is slower for the following reasons:

• The executables contain symbolic debugging information.
• Additional code paths are executed due to parameter checking and debug output (diagnostic messages).

New driver development usually involves the following steps

1. Writing the driver code, which should include debugging checks that are flagged for conditional compilation
2. Testing and debugging a checked version of the driver on a checked build of the operating system
3. Testing and debugging the free version of the driver on a free build
4. Performance tuning of the driver on the free build
5. Additional testing and debugging using both checked and free builds of the driver and the operating system
6. Final testing and verification using the free build

In the early stages of driver development it is necessary to use the checked build of Windows 2000 to debug the driver. The additional debugging code in the checked build has protections against many errors that drivers can make (such as recursive spin locks).

Performance tuning, final testing, and verification of the driver should be done on the free build. The faster speed of the free build makes it possible to detect race conditions and other synchronization problems.

Final testing and verification should also be done on the free build since the free build is the same as the retail version of Windows 2000.

The driver code generally contains preprocessor symbols which allow it to be compiled into both free and checked versions.

The DBG flag is a reserved symbol that can be used during compilation to determine what build of Windows 2000 is running. If the Windows 2000 checked build is running, DBG is set to 1. If the free build is running, DBG is undefined (or it is set to zero if either the wdm.h or ntddk.h header files are included).

Drivers also should be tested and debugged on at least one multiprocessor platform and on at least one uniprocessor platform; both platforms should be running the current version of Windows 2000.

1.2 Debugging Environment

Figure 1.1 shows the typical Microsoft^® Windows^® 2000 setup used to debug drivers.

Figure 1.1 Typical Windows 2000 debugging setup

Kernel debugging does not require specific combinations of the free or checked builds. It is possible to debug a free system from a free or checked system or to debug a checked system from a free or checked system. However, there is generally no reason for the host machine to run the slower checked build.

See Debugging Drivers in the online DDK and the Using Microsoft Debuggers documentation for more details.