Chris Cant - Writing Windows WDM Device Drivers

Listing 9.3 Wdm2 Wdm2Pnp

NTSTATUS Wdm2Pnp(IN PDEVICE_OBJECT fdo, IN PIRP Irp) {

PWDM2_DEVICE_EXTENSION dx=(PWDM2_DEVICE_EXTENSION)fdo->DeviceExtension;

DebugPrint("PnP %I",Irp);

if (!LockDevice(dx)) return CompleteIrp(Irp, STATUS_DELETE_PENDING, 0);

// Remember minor function

PIO_STACK_LOCATION TrpStack = IoGetCurrentIrpStackLocation(Irp);

ULONG MinorFunction = IrpStack->MinorFunction;

NTSTATUS status = STATUS_SUCCESS;

switch (MinorFunction) {

case IRP_MN_START_DEVICE:

status = PnpStartDeviceHandler(fdo,Irp);

break;

case IRP_MN_QUERY_REMOVE_DEVICE:

status = PnpQueryRemoveDeviceHandler(fdo,Irp);

break;

case IRP_MN_SURPRISE_REMOVAL:

status = PnpSurpriseRemovalHandler(fdo, Irp);

break;

case IRP_MN_REMOVE_DEVICE:

status = PnpRemoveDeviceHandler(fdo,Irp);

return status;

case IRP_MN_QUERY_STOP_DEVICE:

dx->Paused = true;

dx->IODisabled = true;

status = PnpDefaultHandler(fdo,Irp);

break;

case IRP_MN_STOP_DEVICE:

status = PnpStopDeviceHandler(fdo,Irp);

break;

case IRP_MN_QUERY_CAPABILITIES:

status = PnpQueryCapabilitiesHandler(fdo.Irp);

break;

case IRP_MN_CANCEL_REMOVE_DEVICE: // fall thru case IRP_MN_CANCEL_STOP_DEVICE:

dx->Paused = false;

dx-> IODisabled = false;

status = PnpDefaultHandler(fdo,Irp);

break;

default:

status = PnpDefaultHandler(fdo,Irp);

}

UnlockDevice(dx);

#if DBG

if (status!=STATUS_SUCCESS) DebugPrint("PnP completed %x",status);

#endif

return status;

}

PnpDefaultHandler (Listing 9.4) passes the PnP IRP down the device stack for processing by all the lower device drivers. Call IoCallDriver whenever you want a driver to process an IRP. If you have created an IRP from scratch, you must set up all the IRP and IRP stack fields correctly. The different ways of allocating and sending your own IRPs are discussed in Chapter 21.

For PnpDefaultHandler , all the IRP structure fields are already set up correctly in the existing PnP IRP that is to be passed onto the next driver. What about the IRP stack?

One IRP stack location is reserved for each possible device in a device stack. When an IRP is passed to the next driver, the next stack location must be set up for it. However, in this case, the Wdm2 driver is never going to need to look at the IRP or its stack location again. IoSkipCurrentIrpStackLocation does not copy the current stack location to the next one. In fact, it simply sets up the IRP internally so that the next driver's call to IoGetCurrentlrpStackLocation returns the same stack location as Wdm2 saw.

You need to set up the next IRP stack location properly if you are going to inspect the IRP processing results or even simply wait for the IRP to complete. Use the routine IoCopyCurrentIrpStackLocationToNext if you simply want to copy the current stack location without changing any of the information. An example of this function is given in Listing 9.4 when Wdm2 waits for an IRP to be processed by all the lower drivers.

IoCallDriver, IoSkipCurrentlrpStackLocation, IoCopyCurrentlrpStackLocationToNext , and the other relevant function IoSetCompletionRoutine must be called at DISPATCH_LEVEL IRQL or lower.

PnpDefaultHandler therefore simply sets up the stack location and passes the IRP to the next lower driver in the device stack. It does not wait for the IRP to complete. It returns the status code that IoCallDriver returns.

Listing 9.4 Wdm2 PnpDefaultHandler

NTSTATUS PnpDefaultHandler(IN PDEVICE_OBJECT fdo, IN PIRP Irp) {

DebugPrintMsg("PnpDefaultHandler");

PWDM2_DEVICE_EXTENSI0N dx=(PWDM2_DEVICE_EXTENSION)fdo->DeviceExtension;

IoSkipCurrentIrpStackLocation(Irp);

return IoCallDriver(dx->NextStackDevice, Irp);

}

Before continuing with the rest of the PnP implementation, it is worth looking again at the Plug and Play message and state diagram that was shown in the last chapter.

Figure 9.1 shows the main theoretical device states that a device can be in and the messages that are sent to change between these states. As mentioned before, a message such as START_DEVICE in this diagram corresponds to a PnP IRP with a minor code of IRP_MN_START_ DEVICE.

Note that I said "theoretical" device states. There are no visible flags in the kernel device structure that say which state a device is in. Wdm2 has to maintain its own state variables.

Another important point to note is that your code should be prepared to accept more-or-less any message from any state. The DDK documentation says in at least two places that an unexpected message may occasionally be sent when in one particular state.

Figure 9.1 Plug and Play device states and messages

The device extension for Wdm2 device objects is shown in Listing 9.5. Four state flags are used to ensure that I/O requests are only begun when the device is in the Started state.

The GotResources flag is set when the device has retrieved and allocated any hardware resources that it needs. In Figure 9.1, the GotResources flag is set when the device is in the Started, Stop pending, and Remove Pending states.

The Paused flag is set when the device is in the Stop Pending or Remove Pending States.

The IODisabled flag is set when GotResources is false or Paused is true (i.e., in the Stoppending, Remove Pending, Stopped, and Surprise removed states).

The Stopping flag is used during the processing of Remove Device and Stop Device messages, as described in the following text.

In the Device not present state, a device object and its flags simply do not exist.

Some devices may want to have an InterruptsEnabled flag, as well, to indicate when device interrupts are enabled.

Listing 9.5 Wdm2 device extension

typedef struct _WDM2_DEVICE_EXTENSION {

PDEVICE_OBJECT fdo;

PDEVICE_OBJECT NextStackDevice;

UNICODE_STRING ifSymLinkName;

bool GotResources; // Not stopped

bool Paused; // Stop or remove pending

bool IODisabled; // Paused or stopped

LONG OpenHandleCount; // Count of open handles

LONG UsageCount; // Pending I/O Count

bool Stopping; // In process of stopping