Writing Windows WDM Device Drivers

This chapter has shown how to handle the various aspects of WDM Power Management. The Wdm2 driver provides a practical illustration of these techniques. The Wdm2Power user mode application can be used to suspend or hibernate a computer.

The next chapter shows how INF files are used to install WDM device drivers.

Chapter 11 Installation

This chapter looks at how to install WDM drivers using installation INF files and describes the process of finding INF files using Hardware and Compatible IDs. The chapter then looks at how to install NT style (non-WDM) drivers. Example Win32 installation code is listed.

WDM Driver Installation Process

A WDM driver is installed if a new device is detected by a bus driver, or if you install a device using the Add New Hardware wizard in the Control Panel. A later section describes how the right driver is found. In both cases, the Plug and Play (PnP) Manager adds entries for the device and its driver to its configuration tables in the registry.

A driver is installed by following the instructions in an INF file. The driver executable is copied to the right location, usually the Windows System32Drivers directory. Then various registry entries have to be made.

Some devices may now need to have some system resources assigned to them, such as I/O Port addresses and interrupt numbers. The PnP Manager may need to juggle the resources that have been assigned to existing devices to make the desired resources available to the new device. If necessary, existing devices are stopped (if they agree) and their resources reassigned.

If the driver is not already present, it is loaded and its DriverEntry routine is called. The driver AddDevice routine is called for the new device. Various Plug and Play IRPs are then sent to the device as detailed in Chapter 9. This process culminates when the Start Device PnP IRP is sent to tell a driver which resources it has been assigned. The driver uses these resource assignments to start its device. Normal I/O requests can then proceed.

The INF file that was used is copied to the Windows INF subdirectory. In Windows 98, they are put in the INFOTHER subdirectory, with the INF filename changed to include the Manufacturer name. In Windows 2000, the INF file is copied to the next available OEM*.INF filename in the INF directory (e.g., OEM4.INF). If you reinstall a driver with the Have Disk option, the new INF file is copied to a new OEM*. INF file. It is probably best if you delete any out-of-date OEM*.INF files.

Please note three important points about installation.

• The driver executable must have an 8.3 filename in Windows 98.

• Windows will not use the INF file if it contains invalid section details.

• Section names must be 28 characters or less to work in W98.

If you want to install a driver that is required in the text-mode setup phase of W2000 installation, you must provide a txtsetup.oem file on a floppy disk. See the DDK for details.

INF Files

An INF file contains all the necessary information to install a WDM device driver, including a list of the files to copy, the registry entries to make, etc.

Windows provides a standard installer for most classes of device and a default installer. The default class installer processes INF files in the manner described in the rest of this chapter. Installers for other classes of device may perform some additional installation steps.

An INF file is a text file that looks like an old INI file. It is made up of sections, each starting with a line with the section name in square brackets (e.g., [Version]). The section contents follow. Each line either has a simple entry (e.g., entry) or sets a value (e.g., entry=value). Sections can be in any order. The order of lines in a section is sometimes important. Comments can be added after a semicolon character. Section and entry names are not case sensitive. A backslash at the end of a line in a section indicates that the line continues onto the next. Double-quotes are used to ensure the correct interpretation of characters (e.g., a backslash in a filename or leading or trailing spaces in strings). INF files can be in Unicode or plain ANSI characters. In some sections, you can opt to include other INF files needed for the installation.

If you need to customize the installation process, consider writing a class installer or — for Windows 2000 — a class coinstaller or a device coinstaller. A class installer takes over the installation of a whole class of devices; it can choose which installation jobs it handles and which it leaves to the default class installer. A coinstaller helps an existing class installer to do its job. A class coinstaller helps install all new devices of a particular class, while a device coinstaller helps just the installation of the device currently being installed. Coinstallers should not interact with the user. Please see the W2000 DDK for details of how to write these DLLs.

Standard Sections

Table 11.1 shows the typical sections of an INF file. Sections that you must name are given in italics. The DDK has full details of these sections and the other ones that you can include. Most section names may also exist in a decorated form, as described in the following text. For example, Strings.LangIdSubLangId indicates a locale and SectionName.NT indicates a platform.

The Version section is usually placed at the start of the INF file. Any of the given values for Signature work for both Windows 98 and Windows 2000. See later for details of how to write cross- platform INF files for both Windows 98 and Windows 2000.

Once your driver has passed the Microsoft Hardware Compatibility Tests, you should include a reference to your digital signature file in the CatalogFile entry.

Table 11.1 Typical sections for an INF file

Section	Entry	Value description
Version	Signature	$Windows NT$, $Windows 95$ or $Chicago$
	Provider	INF file creator
	Class	One of the system-defined classnames (listed in the DDK) or your new class name.
	ClassGuid	The matching class GUID.
	DriverVer	mm/dd/yyyy [,a.b.c.d].
	CatalogFile[.NTetc]	Digitally-signed catalog file.
Strings	%string%='value'	Specifies a string.