Writing Windows WDM Device Drivers

Chapter 15 WdmIo and PHDIo Drivers

Let's finally talk to some real hardware. The next chapters discuss the WdmIo and PHDIo drivers. These general-purpose drivers give Win32 programmers access to simple hardware devices. You can do basic reads and writes of hardware ports. The drivers also let you perform interrupt driven I/O. There is just enough functionality to let a user mode application send output to a standard LPT printer port. Although this is not the recommended way to talk to a printer port[34], it does show that these drivers can be used in a real application.

The generic nature of the WdmIo and PHDIo drivers does make them slightly more complicated to understand. However, a complete and genuinely useful driver is worth having. Using a generic driver as an example also shows all the steps that a you need to use it as the basis of a more advanced driver.

To make these drivers easier to understand, this chapter looks at the interface they make available to Win32 programmers. I will use the test programs WdmIoTest and PHDIoTest, which send a test message out a parallel port to a printer, as an example. This chapter also looks at the installation and resource allocation issues for these drivers.

The following chapters explain how the WdmIo and PHDIo drivers work. They explain the following topics in detail.

• Queuing IRPs for serial hardware I/O

• StartIo routines

• Cancel routines for queued IRPs

• Handling the Cleanup IRP

• Interrupt driven I/O

• Deferred Procedure Calls

• Timers for time-outs

• Custom timers

• NT hardware detection and allocation

Win32 Interface

The WdmIo driver is a Plug and Play driver for Windows 98 and Windows 2000. It is based on most of the previous drivers. However, it does not support Power Management, WMI, or NT events. Its installation INF file specifies the resources that are available to a WdmIo device. A WdmIo device must have one (and only one) I/O port address range. It usually has one interrupt line resource as well. This is needed if interrupt-driven reads or writes are to be used. More than one WdmIo device can be installed, provided that separate INF files with different resources are used.

The PHDIo driver is an NT style driver, primarily for NT 3.51, NT 4, and Windows 2000. However, it works perfectly well in Windows 98. When the driver is loaded, it creates one device called \.PHDIo. The I/O port and interrupt resources are specified as a part of the filename used to open a handle to this device. Again, one I/O port must be given, and one interrupt can be specified, if need be.

Win32 programs must open a handle to a WdmIo or PHDIo device. WdmIo devices are accessed using the device interface identified by WDMIO_GUID. The one PHDIo device has a symbolic link name of \.PHDIo. However, the filename passed to CreateFile must include a definition of the resources required.

Having opened a handle to a WdmIo or PHDIo device, the Win32 program can use several IOCTLs as well as issuing read and write requests. Finally, it must close the device handle.

IOCTLs

Table 15.1 lists the supported IOCTLs, including whether they need input or output parameters.

Most of the IOCTLs pass an input buffer that contains one or more PHDIO commands and their parameters.

IOCTL_PHDIO_RUN_CMDS is used to run a set of commands straightaway. The three following IOCTLs store the commands that are used later in the processing of read and write requests. Finally, IOCTL_PHDIO_GET_RW_RESULTS retrieves the command results and output from the last read or write.

Table 15.1 WdmIo and PHDIo IOCTL codes

IOCTL	Input	Output	Description
IOCTL_PHDIO_RUN_CMDS	Yes	Optional	Run the passed commands
IOCTL_PHDIO_CMDS_FOR_READ	Yes	No	Store the commands to read a byteand store in the read buffer
IOCTL_PHDIO_CMDS_FOR_READ_START	Yes	No	Store the commands that start theread process
IOCTL_PHDIO_CMDS_FOR_WRITE	Yes	No	Store the commands to output a byte from the write buffer
IOCTL_PHDIO_GET_RW_RESULTS	No	Yes	Get the command results of the last read or write operation

Commands

A Win32 program passes a block of commands in an IOCTL input buffer. These commands are either run straightaway or are run one or more times during the processing of read or write requests.

A command is a single byte, followed by one or more parameter bytes. Table 15.2 lists all the commands, their parameters, and their output. The Ioctl.h header in the WdmIoSys directory contains the command definitions. Note that all operations are currently byte-sized. However, the two top bits of the command byte are reserved to indicate 16-bit word transfers and 32-bit long word transfers. If either of these bits is currently set, the command is not run and command processing is aborted. All command parameters are BYTEs. A BYTE is an unsigned 8-bit value, so you cannot use negative values.

Most of the commands are fairly self-explanatory. They are best explained using examples in the context of a sample application, WdmIoTest, that outputs data to the LPT printer parallel port.

Table 15.2 WdmIo and PhdIo commands

Command	Input parameters	Output