Chris Cant - Writing Windows WDM Device Drivers

When a USB client driver handles a PnP Start Device message, it first waits for the IRP to be processed by lower level drivers. It then typically issues one or more URBs to its device before completing its IRP.

For Stop Device messages, a USB client driver might well want to issue one or more URBs to its device before the IRP is sent down the stack.

The Wdm2Test Win32 console application in the Wdm2\exe subdirectory of the book software tests the Wdm2 driver. Wdm1Test is the same as Wdm1Test with only one change, apart from referencing the Wdm2 driver. Wdm2Test halts halfway through, waiting for the user to press a key. While it is waiting, it has a handle to the first Wdm2 device still open.

First, install a Wdm2 device using one of the installation INF files in the book software Wdm2\sys directory. It does not matter whether you use the free or checked build, although the checked build produces DebugPrint trace output.

Wdm2Test tests to see if a Query Remove request is rejected while there are any open handles to a Wdm2 device. Run Wdm2Test but do not press a key when it stops halfway through. Now try to remove the Wdm2 device or reinstall its driver. The request should be rejected. Windows will state that the system must be restarted for the operation to complete.

Check that the Wdm2 driver can be removed or reinstalled when Wdm2Test has completed.

It is very difficult to test the other new aspects of Plug and Play support in the Wdm2 driver. First, Stop Device and Surprise Removal requests should never be issued for virtual devices that have no resources. Second, it is not possible to suddenly remove a Wdm2 device in such a way that the Wdm2 driver has to wait for pending I/O to complete. Do appropriate tests for drivers that have resources and can be suddenly removed.

If the test for open handles is not made, then W2000 in fact will still not allow the device to be removed, as it must contain its own internal reference count for the device. However, W98 would let the device be removed. Any I/O requests on open handles would then simply fail.

The DebugPrint output from Wdm2 shows exactly which Plug and Plug messages are sent by Windows during add device and remove device operations.

Adding a Device

The following PnP calls are made when a Wdm2 device is successfully added, or when the driver for a device is reinstalled. Two of the messages are issued only by Windows 2000.

AddDevice

(W2000) IRP_MN_QUERY_LEGACY_BUS_INFORMATION

IRP_MN_FILTER_RESOURCE_REQUIREMENTS

IRP_MN_START_DEVICE

IRP_MN_QUERY_CAPABILITIES

IRP_MN_QUERY_PNP_DEVICE_STATE

IRP_MN_QUERY_DEVICE_RELATIONS BusRelations

IRP_MN_QUERY_DEVICE_RELATIONS BusRelations (W2000)

Removing a Device

The following PnP messages are sent when a Wdm2 device is successfully removed, or when the driver for a device is reinstalled.

IRP_MN_QUERY_DEVICE_RELATIONS RemoveRelations

IRP_MN_QUERY_REMOVE_DEVICE

IRP_MN_REMOVE_DEVICE

Unknown Status Returns

It is interesting to note the IRP status values are returned by the lower Unknown driver when Wdm2 sends IRPs down the stack. Windows is supposed to set the IRP status return value to STATUS_NOT_SUPPORTED before it is issued to the top of the device stack. If Wdm2 sees this value on return from its PnpDefaultHandler routine, it means that the lower drivers have not processed the IRP or have deliberately not returned STATUS_NOT_SUPPORTED.

For Wdm2, W98 succeeds all the PnP IRPs that it receives.

For Wdm2, W2000 does not process IRP_MN_FILTER_RESOURCE_REQUIREMENTS, IRP_MN_QUERY_PNP_DEVICE_STATE, IRP_MN_QUERY_BUS_INFORMATION, and IRP_MN_QUERY_DEVICE_RELATIONS IRPs.

This section briefly describes the Plug and Plug minor function code IRPs that have not been described in full before. These IRPs are handled by PnP bus drivers. The notes for each function code indicate if it is possible for a function driver to intercept the IRP.

Most function drivers ignore all these PnP IRPs. However, a function driver that performs Power Management may well want to handle IRP_MN_QUERY_CAPABILITIES. The following chapter describes how this is done.

This message tells a driver if its device is in the path of a paging, hibernation, or crash dump file. Do not allow a device to be removed until you are notified that no critical file is on its path.

The Windows 2000 PnP Manager sends this IRP to a device stack so filter and function drivers can adjust the resources required by the device, if appropriate. Function, filter, and bus drivers can handle this request.

The PnP Manager uses this IRP to request the type and instance number of a device's parent bus.

Bus drivers should handle this request for their child devices (PDOs). Function and filter drivers do not handle this IRP.

The PnP Manager sends this IRP to get the capabilities of a device, such as whether the device can be locked or ejected, and various Power Management features. Function and filter drivers can handle this request if they alter the capabilities supported by the bus driver. Bus drivers must handle this request for their child devices.

This IRP is sent twice, both before and after function drivers are loaded and started.

A driver can send one of these IRPs down the stack to see what the bus driver capabilities are.

This IRP asks how this device relates to other devices and comes in five different forms. All forms return an array of pointers to the relevant PDOs.

A BusRelations query asks for the PDOs of all the devices physically present on the bus. EjectionRelations asks which devices are also ejected if this device is ejected. PowerRelations asks which devices are also powered down when this device is powered down. RemovalRelations asks which devices must be removed when this device is removed. TargetDeviceRelation calls ObReferenceObject for the device PDO and returns the PDO.

The PnP Manager uses this IRP to get a device's description or location information. Bus drivers must handle this request for their child devices if the bus supports this information. Function and filter drivers do not handle this IRP.

Parameters.QueryDeviceText.DeviceTextType is either DeviceTextDescription or DeviceTextLocationInformation.Parameters.QueryDeviceText.LocaleId is an LCID specifying the locale for the requested text.

This IRP gets device, hardware, compatible, or instance IDs for a device, depending on whether Parameters.QueryId.IdType is BusQueryDeviceID, BusQueryHardwareIDs, BusQueryCompatibleIDs, or BusQueryInstanceID.

The IRP_MN_QUERY_INTERFACE request enables a driver to export a direct-call interface to other drivers.

The query asks the drivers in the device stack to set any of the state bits shown in Table 9.3. Be careful not to overwrite any bits that are set by other drivers.