Chris Cant - Writing Windows WDM Device Drivers

for(;;) {

// Initiate overlapped read

DWORD TxdBytes;

ResetEvent(FileIOWaiter);

memset(Event,0,MAX_EVENT_LEN+1);

if (!ReadFile(ListenerInfo.DebugPrintDriver, Event, MAX_EVENT_LEN, &TxdBytes, &ol)) {

// Check for read errors

if (GetLastError() !=ERROR_IO_PENDING) {

CString Msg;

Msg.Format("Read didn't return pending %d", GetLastError());

DebugPrint_Event::SendEvent("Monitor", Msg);

goto Exit;

}

// Wait for read to complete (check for KeepGoing

// going false every 100ms)

while (WaitForSingleObject(FileIOWaiter, 100)== WAIT_TIMEOUT) {

if (!ListenerInfo.KeepGoing) {

// Cancel the pending read

CancelIo(ListenerInfo.DebugPrintDriver);

goto Exit;

}

}

// Get read result, ie bytes transferred

if (!GetOverlappedResult(ListenerInfo.DebugPrintDriver, &ol, &TxdBytes, FALSE)) {

DebugPrint_Event::SendEvent("Monitor", "GetOverlappedResult failed");

continue;

}

}

// Check there's something there

if (TxdBytes < sizeof(TIME_FIELDS)+2) {

DebugPrint_Event::SendEvent("Monitor", "Short read msg");

continue;

}

// Extract Timestamp, Driver and Msg, and post to View

Event[MAX_EVENT_LEN] = '\0';

PTIME_FIELDS pTF = (PTIME_FIELDS)Event;

CTime gmtEventTime(pTF->Year, pTF->Month, pTF->Day, pTF->Hour, pTF->Minute, pTF->Second);

CTime EventTime = GMTtoLocalTime(gmtEventTime);

char* DriverName = Event+sizeof(TIME_FIELDS);

CString CSDriverName = DriverName;

CString CSDriverMsg = Event+sizeof(TIME_FIELDS)+strlen(DriverName)+1;

DebugPrint_Event::SendEvent(CSDriverName, CSDriverMsg, EventTime);

}

Exit:

CloseHandle(FileIOWaiter);

Exit2:

CloseHandle(ListenerInfo.DebugPrintDriver);

ListenerInfo.DebugPrintDriver = NULL;

DebugPrint_Event::SendEvent("Monitor", "Stopped listening");

return 0;

}

This chapter has built a full working driver, which can be used to generate debug trace prints that can be seen in a user application. It has covered system threads, dispatcher objects, linked lists, file I/O, a simple IRP queue, and IRP cancel routines.

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] See Chapter 19 for the best way to talk to a parallel port in NT and W2000. , 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

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.

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

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 WdmIo\Sys 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.