Chris Cant - Writing Windows WDM Device Drivers

Windows provides a well-defined hierarchy and structure for drivers. Go with the grain and learn how to fit in nicely with the rest of the operating system. Do not forget to cope with multiprocessor machines.

Windows provides a generic model of different processors that may be running. Drivers have routines that run at PASSIVE_LEVEL, DISPATCH_LEVEL, and DIRQL interrupt levels. Use system memory carefully and access user memory using the relevant kernel routines.

The kernel calls a driver in many ways. Most driver processing is in response to I/O Request Packets (IRPs). Conversely, a driver can make use of a whole host of kernel routines. Many system drivers have specific interfaces defined to handle particular I/O control codes. Drivers should use these interfaces wherever possible.

Enough prevarication, let's start on the first real device driver. The following chapters describe the Wdm1 virtual device driver in detail, how it is implemented and used, and how to test and debug drivers.

This chapter writes a simple WDM device driver, called Wdm1. It shows how Wdm1 is built and installed in Windows 98 and Windows 2000. The basics of the driver are explained, but a full explanation of the guts has to wait until the following chapters.

The Wdm1 driver is for a virtual WDM device that does not correspond to any real hardware. For now, the Plug and Play and Power Management support is minimal. The Wdm1 driver implements a shared memory buffer for all Wdm1 devices.

First, I describe how to set up your computer for WDM driver development by installing the various development kits and by setting up Visual Studio. I describe the other useful tools that you will need.

The book software provides a Visual Studio workspace called WDM Book that you can use to compile the drivers and any associated user mode Win32 applications. Be careful if editing within this workspace as the different projects in this workspace often have files of the same name.

The section details what you will have to do to set up your development computer or computers for WDM driver development. This task is laborious, especially as you have to do it at least twice, once for Windows 2000 and once for Windows 98.

You will have to be an Administrative user to install the W2000 Driver Development Kit (DDK) and drivers in Windows 2000.

These instructions assume that you are using Visual C++ for development. While other compilers can almost certainly do the job, most Windows driver writers will be firmly in the Visual Studio camp. Visual C++ also has various useful tools that you will need such as rebase and guidgen. I used VC++ version 5.

You will need a Microsoft Developer Network (MSDN) Professional (or Universal) subscription to get the necessary development kits. While some of these kits are available free online, it is best to get an MSDN subscription to ensure that you receive the most recent releases and beta versions. The Installable File System (IFS) DDK costs extra and is only available currently in the USA and Canada.

Install the W98 DDK in Windows 98. Install the W2000 DDK in Windows 2000. Install the Platform Software Development Kit (SDK) and MSDN Library in both versions of Windows. The Platform SDK is not vital, but it has quite a few useful tools.

The DDK tools and documentation are listed in the Start+Programs+Development kits menu. The Platform SDK tools are listed in the Start+Programs+Platform SDK menu.

The SETENV.BAT file in the DDK bin directory is used to set the environment variables for the build process [8] You will probably need to ensure that the Windows 98 environment space size is at least 2048 for device driver development. . Shortcuts to this batch file are set up in the Start menu. It calls other batch files in the bin directory. The current batch files install DosKey; I decided to comment these lines out as I already have a similar command processor installed.

The Platform SDK may have more up to date tools than are supplied with VC++ (e.g., the rebase utility). Put the MSSDK bin directory before the Visual Studio directories on your path.

You may need to add the DDK bin directory to the directories list in VC++.

Currently, the documentation is released in HTML Help format. Each help file is viewed in its own incarnation of the HTML Help viewer, and is not merged into the Visual Studio 97 documentation. The help files are probably merged together in Visual Studio 6.

Each function found in the W2000 DDK states which header files you can use. If wdm.h is listed, the routine can be used in a WDM driver for Windows 98 or Windows 2000. There are some routines that compile correctly in Windows 98 but have no effect, such as the event log writing routines. If the W2000 DDK lists only ntddk.h for a routine, it can be used only in Windows 2000 drivers, not Windows 98. The W98 DDK lists only routines that run in Windows 98.

The W98 DDK and the W2000 DDK are largely the same for WDM drivers. At the time of writing, the W98 DDK does not include the Windows Management Instrumentation libraries. Some header files are also different (e.g., SETUPAPI.H). For some reason, the checked build produced by W2000 seems quite a bit smaller than that produced by the W98 DDK.

The source code for the Wdm1 driver is supplied on the book's accompanying disk. Copy the source code directory tree to a fresh directory on your hard disk. These instructions assume that you have installed the software to C:\WDMBook. However, you can change the directory if you wish. If you use a different drive, you will need to alter the settings of every VC++ project, so it will be much easier for you if you can install the software on drive C:.

The WDM Book Visual Studio workspace in the book software base directory contains projects for each of the drivers in the book.

Three steps are needed before the book software drivers can be compiled.

• Ensure that the DDKROOT environment variable is set to the W2000 DDK or W98 DDK base directory.

• Set up an environment variable called WDMBOOK to point to the book software base directory (e.g., C:\WDMBook). In Windows 98, set environment variables by adding them to AUTOEXEC.BAT. You will probably need to reboot for the new definitions to come into effect. In Windows 2000, set environment variables in the Control Panel System proper ties applet "Advanced tab" Environment variables editor. You will need to restart Visual Studio and any DOS boxes for these changes to take effect.

• Ensure that the MakeDrvr.bat batch file in the book software base directory is available to be run by Visual Studio, as it is used to invoke the build make process. Either add MakeDrvr.bat to a directory that is on your path, or add the book software base directory to the list of "Executable files" directories in the Visual Studio Tools+Options Directories tab.

You can check that you have installed the development kits and book software correctly by compiling the book software drivers [9] The PHDIo and Wdm3 drivers are not included in the compilation list as they do not compile in Windows 98. . From the Start+Programs+Dуvelopment Kits+Windows XX DDK menu, select either the free or checked build environment. Then move to the book software base directory and enter build –nmake /a. If you want to recompile the Win32 applications, you will have to do this in the Visual Studio workspace.

Check that the drivers are actually updated. In the worst case, it will appear as if the files have compiled but nothing will in fact have been done. If the example drivers do not compile, then there are two usual causes. The first possible problem is that the environment variables have not been set up correctly.