Chris Cant - Writing Windows WDM Device Drivers

Double-clicking most other WinObj entries yields no useful information.

ObjDir is a command line version of WinObj.

Drivers is a command line utility that lists all drivers and their memory usage.

DebugPrint

The DebugPrint software is used by test drivers to produce formatted print statements. The trace messages are viewed in the DebugPrint Monitor Win32 application. This tool is explained in full in Chapter 6, because the book software makes extensive use of this debugging technique. Chapter 14 describes the source for the DebugPrint driver.

Wdm2Power

The Wdm2Power tool firstly lets you inspect the AC and battery status of your system. It also displays any system power events. Finally, it lets you suspend or hibernate your computer.

MakeDrvr

This batch file is used from Visual Studio to initiate each build, as described in the following text.

Servicer

The Servicer utility lets you inspect the status of any running Windows 2000 service, including drivers. You can see if a driver is running or not, and attempt to start or stop it.

Drivers can be built in free or checked versions, and in NT and Windows 2000 for different processors.

The free target is the final release retail version, optimized as necessary with all debug symbols removed.

The checked target is an unoptimised debug version that includes symbols to make debugging easier.

NT and Windows 2000 come in free and checked versions. If you use the Microsoft WinDbg debugger then you need two computers running NT or W2000. The development PC should be the faster computer running the free version of Windows. The driver should be running under test on the other target PC that is running the checked build. The fact that there are fewer resources available on the target system is good as it makes it easier to check that your driver will work in stressful situations.

Windows 2000 also runs on the Dec Alpha platform, so you can also build for the Alpha platform free and checked targets. This book only discusses the x86 platform.

In this book, the emphasis is on writing drivers that work in both Windows 98 and Windows 2000. However, a few features are present in only one operating system. The following preprocessor directives can be used to determine whether you are using the W2000 DDK or the W98 DDK. If you have separate versions of your driver, the installation files will have to be slightly different. As Chapter 11 shows, a single installation INF file can include separate instructions for W2000 and W98.

#if _WIN32_WINNT>=0x0500

// W2000+ code

#else

// W98 code

#endif

A driver is a Dynamic Link Library (DLL) with the file extension .sys. It is usually written in C or C++ and can include resources, such as a version block, event messages, and Windows Management Instrumentation (WMI) class definitions. In Windows 98, a driver executable must have an 8.3 filename.

Although drivers were traditionally written just in C, it is quite straightforward to use C++. The main requirement is to use the extern "C" directive in a couple of important places. However, do not use the new keyword in C++. The new keyword may be implemented using malloc, which is not available to kernel mode drivers.

In fact, most standard libraries and classes are not available to driver writers in either language, because they make inappropriate use of memory. If you are using one of the proprietary driver development kits, these provide various useful classes, including safe memory allocators.

Instead, you can use any of the routines provided by the operating system to kernel mode devices, as described in Chapter 3. While these are useful, it takes a while to get used to the different set of routines that are available.

Assembly code can be used if absolutely necessary. Obviously, this makes for more work if you port the driver to the Windows 2000 Alpha platform.

A resource .rc file should include a standard version block. Increment the version numbers as new builds are released. Make sure that you keep a full source backup of each version you release. Many version control packages can help you manage this task.

If you generate NT or Windows 2000 events, you should write these in an .mc file that is compiled using the mc utility and included in a driver's resource file. More details of this process are in Chapter 13.

Similarly, if you generate custom WMI classes, you need to write a .mof file that is compiled using the mofcomp tool and included in the driver's resource file. See Chapter 12 for more information.

A sophisticated driver might need to download microcode to its device and so would include the microcode as a binary resource in its executable.

A driver is an integral part of the operating system, so it can easily crash Windows if it goes wrong. You do not have the protection of a Win32 address space to stop you from overwriting memory that does not belong to you.

Please be especially careful when you write your driver. Keep it as simple as possible and document it well.

Treat all compiler warnings as errors that need to be fixed. For example, whether an integer is signed or not can make all the difference.

Make sure that you check the return values of all kernel functions that you call, and act on them accordingly. For example, if you get an error after you create a device, make sure that the clean-up code deletes the device.

Make sure that you use the kernel resources carefully, particularly memory. Some resources are scarce and overuse may degrade system functioning.

The DDK build command line utility is the primary tool for building drivers. It invokes the nmake make utility to build your driver using the correct compiler and linker settings. If necessary, build can be used to build standard user mode Win32 executables, etc.

The next section describes how to invoke build from within Visual Studio. However, you must still set up build so that it can be run at the command line. As well as your source code, you must specify a SOURCES file, a standard makefile , the directory structure, and optionally a makefile.inc file and a dirs file. All these steps are described in the following text.

build displays progress details and error results to its standard output. In addition, it lists the errors in a file called build.err , the warnings in build.wrn , and a log in build.log . In W2000 there are free and checked build versions of each of these files, i.e., buildfre.log, buildchk.log , etc.

Younger readers may not have come across makefiles. In the days before Integrated Development Environments (IDEs) such as Visual Studio, you had to use makefiles to determine which files in a project needed recompiling. If you changed only one module in a project consisting of eight modules, you want to recompile only that one module and then link the whole lot together.