Chris Cant - Writing Windows WDM Device Drivers

Listing 23.12 SetupHidIrp routine

void SetupHidIrp(IN PHIDKBD_DEVICE_EXTENSION dx, IN CCHAR StackSize) {

// Work out maximum size of input and output reports

dx->HidMaxReportLen = dx->HidInputReportLen;

if (dx->HidOutputReportLen > dx->HidMaxReportLen) dx->HidMaxReportLen = dx->HidOutputReportLen;

DebugPrint("Setting up HidIrp etc %d", dx->HidMaxReportLen);

if( dx->HidMaxReportLen==0) return;

dx->HidReport = ExAllocatePool(NonPagedPool, dx->HidMaxReportLen);

if (dx->HidReport==NULL) return;

dx->HidIrp = IoAlIocateIrp(StackSize, FALSE);

if (dx->HidIrp==NULL) return;

dx->HidReportMdl = IoAllocateMdl(dx->HidReport, dx->HidMaxReportLen, FALSE, FALSE, NULL);

if (dx->HidReportMdl==NULL) {

IoFreeIrp(dx->HidIrp);

dx->HidIrp = NULL;

}

}

When the HidKbd device is removed, the IRP, the buffer memory, and the MDL must be freed. Listing 23.13 shows how the RemoveHidIrp routine does this job using the IoFreeMdl, IoFreeIrp , and ExFreePool routines.

Listing 23.13 RemoveHidIrp routine

void RemoveHidIrp(IN PHIDKBD_DEVICE_EXTENSION dx) (

DebugPrintMsg("Removing HidIrp etc");

if (dx->HidReportMdl!=NULL) {

IoFreeMdl(dx->HidReportMdl);

dx->HidReportMdl = NULL;

}

if (dx->HidIrp!=NULL) {

IoFreeIrp(dx->HidIrp);

dx->HidIrp = NULL;

}

if (dx->HidReport!=NULL) {

ExFreePool(dx->HidReport);

dx->HidReport = NULL;

}

}

I can now discuss how to use this preallocated IRP. Listing 23.14 shows the replacement ReadHidKbdInputReport routine. This time, it cannot use IoBuildSynchronousFsdRequest , so the IRP and its stack must be built by hand.

The IoInitializeIrp call is used to initialize the IRP. IoInitializeIrp incorrectly clears the IRP AllocationFlags field, so this must be preserved. In W2000, IoReuseIrp correctly reinitialises the IRP. ReadHidKbdInputReport then stores the MDL for the buffer in the IRP MdlAddress field. As before, it calls IoGetNextIrpStackLocation to get the next stack location. ReadHidKbdInputReport must set up all the stack parameters carefully: the MajorFunction, the Parameters.Read fields, and the FileObject.

Finally, ReadHidKbdInputReport needs to set a completion routine so that it knows when the IRP has completed. It passes an event to the completion routine. The completion routine sets the event into the signalled state when it is run). ReadHidKbdInputReport waits until the event is set (i.e., when the IRP has been completed by the lower driver. Assuming that the HID driver has returned data, the final job is to copy the data into the user's buffer, using RtlCopyMemory .

The ReadComplete completion routine returns STATUS_MORE_PROCESSING_REQUIRED. This stops the I/O Manager from deleting the IRP. The IRP will be reused so it must not be deleted.

Listing 23.14 New ReadHidKbdInputReport routine

NTSTATUS ReadHidKbdInputReport(PHIDKBD_DEVICE_EXTENSION dx, PFILE_OBJECT FileObject, PVOID Buffer, ULONG& BytesTxd) {

BytesTxd = 0;

if (HidKbdDo==NULL || dx->HidIrp==NULL || dx->HidReport==NULL) {

DebugPrintMsg("No HidIrp");

return STATUS_INSUFFICIENT_RESOURCES;

}

RtlZeroMemory(dx->HidReport, dx->HidMaxReportLen);

// Initialise IRP completion event

KEVENT event;

KeInitializeEvent(&event, NotificationEvent, FALSE);

// Initialise IRP

UCHAR AllocationFlags = dx->HidIrp->AllocationFlags;

IoInitializeIrp(dx->HidIrp, IoSizeOfIrp(HidKbdDo->StackSize), HidKbdDo->StackSize);

dx->HidIrp->AllocationFlags = AllocationFlags;

dx->HidIrp->MdlAddress = dx->HidReportMdl;

PIO_STACK_LOCATION IrpStack = IoGetNextIrpStackLocation(dx->HidIrp);

IrpStack->MajorFunction = IRP_MJ_READ;

IrpStack->Parameters.Read.Key = 0;

IrpStack->Parameters.Read.Length = dx->HidInputReportLen;

IrpStack->Parameters.Read.ByteOffset.QuadPart = 0;

IrpStack->FileObject = FileObject;

IoSetCompletionRoutine(dx->HidIrp, (PIO_COMPLETION_ROUTINE)ReadComplete, &event, TRUE, TRUE, TRUE);

NTSTATUS status = IoCallDriver(dx->HidDevice, dx->HidIrp);

if (status == STATUS_PENDING) {

KeWaitForSingleObject(&event, Suspended, KernelMode, FALSE, NULL);

status = dx->HidIrp->IoStatus.Status;

}

// return IRP completion status

DebugPrint("ReadHidKbdInputReport: status %x", status);

BytesTxd = dx->HidIrp->IoStatus.Information;

if (BytesTxd>0) RtlCopyMemory(Buffer, dx->HidReport, BytesTxd);

return status;

}

NTSTATUS ReadComplete(IN PDEVICE_OBJECT fdo, IN PIRP Irp, IN PKEVENT Event) {

KeSetEvent(Event, 0, FALSE);

return STATUS_MORE_PROCESSING_REQUIRED;

}

Even Better …

Two problems exist with the permanently allocated IRP solution I have just presented. The first is that the driver will not cope with two "simultaneous" read requests as it uses the same buffer in each call. A quick fix to this problem would be to allow only one read request at a time. The next best solution is dropping the shared buffer; an MDL must then be allocated for the user buffer in each read request.

In fact, the best solution is not to use a permanently allocated IRP, but to reuse the Read IRP. If the HidKbd device uses Direct I/O, the operating system will even do the MDL allocation. In this version, the ReadHidKbdInputReport routine only needs to set up the next IRP stack location appropriately. In fact, calling IoCopyCurrentIrpStackLocationToNext will probably do this job just fine.

The second problem with both the earlier techniques of calling the HID class driver is that they can be inefficient. In both the earlier cases, the call to KeWaitForSingleObject forces the current thread to block waiting for the event to become signalled. As HidKbd may operate in the context of a user thread, this may stop any other overlapped operations from running. [60] So far, we have not considered how the kernel calls our driver. However, to be most efficient, we should not block while processing an IRP for very long. Blocking in a Power or PnP IRP handler or a system thread is fine. The solution to this problem is to modify the completion routine. If the completion routine completes the original Read IRP, there is no need for ReadHidKbdInputReport to wait for the IRP completion event.

This technique should be used wherever possible. The HidKbd Create and Close IRP use this technique as they pass their IRPs to the HID class driver, which completes them in due course. However, it is probably still worth using events in the CallHidIoctl routine for two reasons. The first is that HidKbd needs to know the IRP results. Secondly, my guess is that the HID class driver will be able to complete these IOCTLs straightaway, as it should already have the information at hand.