Книга: Writing Windows WDM Device Drivers

Kernel Mode HID Clients

Kernel Mode HID Clients

A device driver can talk to a HID device using the HID class driver. As mentioned previously, it is far easier to write a user mode application to control a HID device. However, you may find that it is necessary to write a HID client driver (e.g., if you need to implement an existing device API). A kernel client should be more efficient than a user mode client, though speed ought not to be a problem for most human input devices.

A kernel mode HID client can take one of two main forms, depending on how it relates to devices. An "AddDevice" HID client uses installation files (as usual) to layer itself above the HID class driver for each device. Alternatively, "Plug and Play Notification" HID client driver is not initially associated with any one device. Instead, it receives notifications when a HID device arrives or disappears. A PnP Notification HID client makes its own device objects if a HID device of interest arrives.

As I have not examined Plug and Play Notification before, this chapter's example driver, HidKbd, uses this technique.

"AddDevice" HID Clients

An "AddDevice" HID client will look like all the previous WDM device drivers. The driver is loaded using installation INF files in the normal way. The driver's AddDevice routine is called when a suitable device is loaded. The driver must handle Plug and Play IRPs in the same way as usual.

An "AddDevice" HID client makes calls to the HID class driver by calling the NextStackDevice as usual. The HID class driver responds to read and write requests as well as various IOCTL IRPs.

As is usual for WDM drivers, your driver's upper edge may be completely different. For example, the kbdhid.sys system keyboard driver has an upper edge that reports 8042 equivalent key presses. However, kbdhid.sys makes HID requests on its lower edge to find the HID keyboard data.

Things can now get complicated. Note that user mode clients will still be able to find the HID device. If they try to send HID requests to the HID device, these requests will be routed to your driver first. If your driver implements some other upper edge, it will not recognize these requests. Or, if you are being very clever, you could recognize when HID operations have been requested and route them straight through to the HID class driver. If you do this job, you are acting as a HID filter driver.

All in all, it is probably easier if you do not use the "AddDevice" device technique when writing a HID client driver. Therefore, I shall take a close look at how to write a Plug and Play Notification client. However, kernel mode PnP Notification does not seem to work in Windows 98, so you will have to write an "AddDevice" client.

"PnP Notification" HID Clients

A PnP Notification HID client is usually an NT style driver. Therefore, it is not loaded as a result of a device being plugged in. As an NT style driver, it is usually loaded when the system boots up. Installation INF files are not used. Instead, you must write a custom installation program, as described in Chapter 11.

The DriverEntry routine calls the IoRegisterPlugPlayNotification function to ask to receive any device interface change events for a particular device interface GUID. The driver AbcUnload routine calls IoUnregisterPlugPlayNotification to indicate that it no longer wants to receive such notifications.

In this case, the device interface change callback is informed whenever any HID device is plugged into the system. The HidKbd code then interrogates the device to see if it is a HID keyboard. If it is, it creates a HidKbd device.

Just to complicate matters, HidKbd now has two options. First, it can layer itself over the HID device so that is becomes part of the device stack for this device. However, this suffers from the same drawbacks as the "AddDevice" technique, that user mode requests to the HID device would be routed to HidKbd.

The HidKbd driver takes the second option. HidKbd stores a pointer to the HID device object, but does not layer itself above the HID device. Both HidKbd and a user mode application can therefore call the HID class driver safely.

Kernel mode drivers can register to receive three different types of notification events. As far as I can tell, none of these notifications work in Windows 98, as calling IoRegisterPlugPlayNotification seems to hang the system. Therefore, ail the subsequent discussion here applies to Windows 2000 only. The Beta 2 version of W2000 let the HidKbd driver access the HID keyboard. Later versions do not, so most of the code in HidKbd will now not run.

Table 23.2 shows how to call IoRegisterPlugPlayNotification. The EventCategory parameter specifies what type of event you want to receive. HidKbd only asks for device interface change events, EventCategoryDeviceInterfaceChange, and so passes the relevant GUID as the EventCategoryData parameter. It also specifies the PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES flag as the EventCategoryFlags parameter. This means that it receives notifications straightaway for any existing devices that support the given interface.

If you register to receive EventCategoryHardwareProfileChange events, you are supposed to receive hardware profile change events. The callback is told whether a Query Change, Change Complete, or Change Cancelled event occurred.

Registering for EventCategoryTargetDeviceChange events asks for notifications when a target device is removed. You must pass a PFILE_OBJECT as the EventCategoryFlags. The callback is told whether a Query Remove, Remove Complete, or Remove Cancelled event occurred. In my mind, there is a fundamental flaw to this notification. You must pass a file object to IoRegisterPlugPlayNotification. To have a file object pointer, you must have opened a file. If a file is open on a device, Windows 2000 automatically stops any PnP remove request for the device. When I tried it, my target device callback received a Query Remove event followed straightaway by a Remove Cancelled event. It seems as though registering for target device notifications automatically stops any remove requests from completing.

Table 23.2 IoRegisterPlugPlayNotification function

Device Interface Change Notifications

Anyway, device interface change notifications do seem to work, so let's look at the HidKbd device interface change callback, HidKbdDicCallback shown in Listing 23.7. Each callback receives the context pointer and a notification structure pointer. For device interface change events, this is a pointer to a DEVICE_INTERFACE_CHANGE_NOTIFICATION structure.

The notification structure Event GUID field says what type of event has occurred. The SymbolicLinkName UNICODE_STRING field can be used to open a handle to the device.

When a new device arrives, Event contains GUID_DEVICE_INTERFACE_ARRIVAL For DeviceRemoval events, Event is GUID_DEVICE_INTERFACE_REMOVAL. HidKbdDicCallback uses the IsEqualGUID macro to detect each of these events. For Device Arrival events, the CreateDevice routine is called, and for Device Removals, DeleteDevice is called.

Listing 23.7 PnP device interface change notification callback

NTSTATUS HidKbdDicCallback(IN PVOID NotificationStructure, IN PVOID Context) {
 PDEVICE_INTERFACE_CHANGE_NOTIFICATION dicn = (PDEVICE_INTERFACE_CHANGE_NOTIFICATION)NotificationStructure;
 PDRIVER_OBJECT DriverObject = (PDRIVER_OBJECT)Context;
 if (IsEqualGUID(dicn->Event, GUID_DEVICE_INTERFACE_ARRIVAL)) {
  DebugPrint("Device arrival: XT", dicn->SymbolicLinkName);
  CreateDevice(DriverObject, dicn->SymbolicLinkName);
 } else if(IsEqualGUID(dicn->Event, GUID_DEVICE_INTERFACE_REMOVAL)) {
  DebugPrint("Device removal: %T", dicn->SymbolicLinkName);
  DeleteDevice(dicn->SymbolicLinkName);
 } else DebugPrint("Some other device event: %T", dicn->SymbolicLinkName);
 return STATUS_SUCCESS;
}

Hold onto your hats, as the HidKbd device handling is a bit complicated.

Remember that the CreateDevice routine is called whenever a HID device is added to the system. HidKbd is just looking for a HID keyboard. However, it must cope if a HID device arrives that is not a keyboard, and if two HID keyboards arrive (it is possible).

HidKbd tries to make things simple by only coping with one keyboard. If a second HID keyboard arrives, it is ignored.

HidKbd creates its own device called .HidKbd for the first HID keyboard that arrives. A user mode program can open a handle to this device and issue read requests. HidKbd handles these by calling the HID device to get an input report. HidKbd does not do anything for Write or IOCTL requests.

Has a HID Keyboard Been Found?

The CreateDevice routine shown in Listing 23.8 starts by checking to see if it has already found a HID keyboard. The HidKbdDo global variable stores a pointer to the HidKbd device object; if this is non-NULL, a suitable keyboard has already been found.

The first job is to open a connection to the HID device and see if it is HID keyboard. While CreateDevice could use ZwCreateFile to open a handle to the HID device, the IoGetDeviceObjectPointer routine is what is really needed. IoGetDeviceObjectPointer is passed the symbolic link for a device. If the symbolic link is found, IoGetDeviceObjectPointer issues a Create IRP to the device, passing an empty string as the IRP filename parameter[59]. IoGetDeviceObjectPointer returns two pieces of information: the device object pointer and the PFILE_OBJECT pointer.

HidKbd is going to use the HID device object pointer a lot. In addition, it needs a file object pointer when it eventually reads reports from (or writes reports to) the HID class driver. However, in the mean time, CreateDevice closes the file object pointer by calling ObDereferenceObject. Why is this done? If a file is open on a device, Windows 2000 will not let a device be removed. The file must be closed to let device removals take place.

CreateDevice now inspects the HID device capabilities using the GetCapabilities routine, which I describe later. If GetCapabilities finds a HID keyboard, HidKbdUser, like its user mode equivalent, returns a pointer to the preparsed data and the maximum input and output report lengths.

Creating the HidKbd Device

If a HID keyboard is found, CreateDevice can go on to create its own device object. However, it first calls ObReferenceObjectByPointer to reference the HID class driver device object. This ensures that the device object will not disappear from under our feet. When the HidKbd device is deleted, ObDereferenceObject is called to dereference the object. Note that referencing this device object does not stop it from processing removal requests successfully.

The next job is to allocate some memory for a copy of the HID device symbolic link name. This name is stored in a UNICODE_STRING field called HidSymLinkHame in the new device extension. The HidKbd Device Removal event handler only deletes a device if the correct underlying HID device is being removed.

HidKbd now sets up the device name and symbolic link names for the new HidKbd device. These are DeviceHidKbd and DosDevicesHidKbd respectively, and so the device appears in Win32 as .HidKbd.

HidKbd is finally ready to call IoCreateDevice, with most of the parameters set up as usual. However this time it passes the device type FILE_DEVICE_KEYBOARD, as this seems most appropriate. If the device is created successfully, the global variable, HidKbdDo, stores the device object. Next, CreateDevice sets up the device extension. Finally, CreateDevice calls IoCreateSymbolicLink to create the symbolic link that makes the device visible to Win32 applications.

Note that HidKbd did not call IoAttachDeviceToDeviceStack. If it did make this call, the HidKbd device would be layered over the HID device. Any user mode calls direct to the HID device would arrive at the HidKbd device first, which is not what is wanted.

As a last touch, note that CreateDevice sets up the StackSize field of the HidKbdDo device object. If HidKbd had called IoAttachDeviceToDeviceStack, this routine would have set the IRP stack size to be one greater than the HID device stack size. As it did not call IoAttachDeviceToDeviceStack, HidKbd has to do this same job. Later, HidKbd passes IRPs to the HID class driver for processing. Setting the stack size in this way ensures that there will be enough IRP stack locations available.

Listing 23.8 HidKbd CreateDevice routine

void CreateDevice( IN PDRIVER_OBJECT DriverObject, IN PUNICODE_STRING HidSymLinkName) {
 if (HidKbdDo!=NULL) {
  DebugPrintMsg("Already got HidKbdDo");
  return;
 }
 PFILE_OBJECT HidFileObject = NULL;
 PDEVICE_OBJECT HidDevice;
 NTSTATUS status = IoGetDeviceObjectPointer(HidSymLinkName, FILE_ALL_ACCESS, &HidFileObject, &HidDevice);
 if (!NT_SUCCESS(status)) {
  DebugPrintMsg("IoGetDeviceObjectPointer failed");
  return;
 }
 // Close file object
 ObDereferenceObject(HidFileObject);
 // Inspect HID capabilities here
 PHIDP_PREPARSED_DATA HidPreparsedData = NULL;
 USHORT HidInputReportLen, HidOutputReportLen;
 if (!GetCapabilities(HidDevice, HidPreparsedData, HidInputReportLen, HidOutputReportLen)) {
  DebugPrintMsg("GetCapabilities failed");
  FreeIfAllocated(HidPreparsedData);
  return;
 }
 // Reference device object
 status = ObReferenceObjectByPointer(HidDevice, FILE_ALL_ACCESS, NULL, Kernel Mode);
 if (!NT_SUCCESS(status)) {
  DebugPrintMsg("ObReferenceObjectByPointer failed");
  FreeIfAllocated(HidPreparsedData);
  return;
 }
 // Allocate a buffer for the device ext HidSymLinkName
 PWSTR HidSymLinkNameBuffer = (PWSTR)ExAllocatePool(NonPagedPool, HidSymLinkName->MaximumLength);
 if (HidSymLinkNameBuffer==NULL) {
  FreelfAllocated(HidPreparsedData);
  ObDereferenceObject(HidDevice);
  return;
 }
#define NT_DEVICE_NAME L"DeviceHidKbd"
#define SYM_LINK_NAME L"DosDevicesHidKbd"
 // Initialise NT and Symbolic link names
 UNICODE_STRING deviceName, linkName;
 RtlInitUnicodeString(&deviceName, NT_DEVICE_NAME);
 RtlInitUnicodeString(&linkName, SYM_LINK_NAME);
 // Create our device object
 status = IoCreateDevice(DriverObject, sizeof(HIDKBD_DEVICE_EXTENSION), &deviceName, FILE_DEVICE_KEYBOARD, 0, FALSE, &HidKbdDo);
 if (!NT_SUCCESS(status)) {
  HidKbdDo = NULL;
  FreeIfAllocated(HidSymLinkNameBuffer);
  FreeIfAllocated(HidPreparsedData);
  ObDereferenceObject(HidDevice);
  return;
 }
 // Set up our device extension
 PHIDKBD_DEVICE_EXTENSION dx = (PHIDKBD_DEVICE_EXTENSION)HidKbdDo->DeviceExtension;
 dx->HidKbdDo = HidKbdDo;
 dx->HidDevice = HidDevice;
 dx->HidPreparsedData = HidPreparsedData;
 dx->HidSymLinkName.Length = 0;
 dx->HidSymLinkName.MaximumLength = HidSymLinkName->MaximumLength;
 dx->HidSymLinkName.Buffer = HidSymLinkNameBuffer;
 RtlCopyUnicodeString(&dx->HidSymLinkName, HidSymLinkName);
 // Create a symbolic link so our device is visible to Win32…
 DebugPrint("Creating symbolic link XT", &linkName);
 status = IoCreateSymbolicLink(&linkName, &deviceName);
 if (!NT_SUCCESS(status)) {
  DebugPrintMsg("Could not create symbolic link");
  FreeIfAllocated(dx->HidSymLinkName.Buffer);
  IoDeleteDevice(HidKbdDo);
  ObDereferenceObject(HidDevice);
  HidKbdDo = NULL;
  return;
 }
 HidKbdDo->Flags |= DO_BUFFERED_IO;
 HidKbdDo->Flags &= ~DO_DEVICE_INITIALIZING;
 HidKbdDo->StackSize = HidDevice->StackSize+1;
 DebugPrintMsg("Device created OK");
}

Deleting the HidKbd Device

The HidKbd device must be deleted in two circumstances. First, if HidKbd is notified that the HID device has been removed. Second, if the HidKbd driver is unloaded. The DeleteDevice routine shown in Listing 23.9 handles both these cases. When the driver is unloaded the HidSymLinkName parameter is NULL. However, if a HID device is being removed, HidSymLinkName contains the symbolic link name of the device.

DeleteDevice first checks that a HidKbd device has been created. If one has and a device is being removed, DeleteDevice calls RtlCompareUnicodeString to see if the device name matches the one to which HidKbd refers. If it is a different HID device, nothing more is done.

Before the device is deleted, DeleteDevice must free any memory that is associated with it (i.e., the preparsed data and the buffer for the copy of the symbolic link name). DeleteDevice now remakes the HidKbd symbolic link name. The symbolic link name is deleted using IoDeleteSymbolicLink. ObDereferenceObject is called to deference the HID device object. Finally, IoDeleteDevice deletes the HidKbd device.

Listing 23.9 HidKbd DeleteDevice routine

void DeleteDevice(IN PUNICODE_STRING HidSymLinkName) {
 if (HidKbdDo==NULL) return;
 PHIDKBD_DEVICE_EXTENSION dx = (PHIDKBD_DEVICE_EXTENSION)HidKbdDo->DeviceExtension;
 if (HidSymLinkName!=NULL && RtlCompareUnicodeString(HidSymLinkName, &dx->HidSymLinkName, FALSE)!=0) {
  DebugPrintMsg("DeleteDevice: symbolic link does not match our device");
  return;
 }
 DebugPrintMsg("Deleting our device");
 FreelfAllocated(dx->HidPreparsedData);
 FreeIfAllocated(dx->HidSymLinkName.Buffer);
 // Initialise Symbolic link names
 UNICODE_STRING linkName;
 RtlInitUnicodeString(&linkName, SYM_LINK_NAME);
 // Remove symbolic link
 DebugPrint("Deleting symbolic link XT", &linkName);
 IoDeleteSymbolicLink(&linkName);
 ObDereferenceObject(dx->HidDevice);
 IoDeleteDevice(HidKbdDo);
 HidKbdDo = NULL;
}

The HidKbd GetCapabilities routine is largely the same as its equivalent in HidKbdUser. It returns true if the HID device capabilities indicate that it is a HID keyboard.

However, GetCapabilities must obtain the device attributes and the preparsed data in a different way from HidKbdUser. The GetPreparsedData routine shown in Listing 23.10 does this job.

GetPreparsedData uses two IOCTLs to obtain the information needed from the HID class driver. IOCTL_HID_GET_COLLECTION_INFORMATION returns the attributes and the size of memory buffer required for the preparsed data. Next, IOCTL_HID_GET_COLLECTION_DESCRIPTOR is used to get the preparsed data itself. GetPreparsedData returns a pointer to the preparsed data memory. This memory must eventually be freed.

The CallHidIoctl routine is used to issue the two IOCTLs. This works in a very similar way to the CallUSBDI routine shown in Listing 21.2. It calls IoBuildDeviceIoControlRequest to build the IOCTL passing the IOCTL code, the output buffer details and a completion event. CallHidIoctl calls the HID class driver using IoCallDriver, waiting until it completes using the event, if necessary.

Listing 23.10 HidKbd GetPreparsedData routine

bool GetPreparsedData(IN PDEVICE_OBJECT HidDevice, OUT PHIDP_PREPARSED_DATA HidPreparsedData) {
 HID_COLLECTION_INFORMATION HidCi;
 NTSTATUS status = CallHidIoctl(HidDevice, IOCTL_HID_GET_COLLECTION_INFORMATION, &HidCi, sizeof(HidCi));
 if (!NT_SUCCESS(status)) {
  DebugPrint("IOCTL_HID_GET_COLLECTION_INFORMATION failed %x", status);
  return false;
 }
 DebugPrint("HID attributes: VendorID=%4x, ProductID=%4x, VersionNumber=%4x",
  HidCi.VendorID, HidCi.ProductIO, HidCi.VersionNumber);
 ULONG PreparsedDatalen = HidCi.DescriptorSize;
 DebugPrint("PreparsedDatalen %d", PreparsedDatalen);
 HidPreparsedData = (PHIDP_PREPARSED_DATA)ExAllocatePool(NonPagedPool, PreparsedDatalen);
 if (HidPreparsedData==NULL) {
  DebugPrintMsg("No memory");
  return false;
 }
 status = CallHidIoctl(HidDevice, IOCTL_HID_GET_COLLECTON_DESCRIPTOR, HidPreparsedData, PreparsedDatalen);
 if (!NT_SUCCESS(status)) {
  DebugPrint("IOCTL_HID_GET_COLLECTION_DESCRIPTOR failed %x", status);
  return false;
 }
 return true;
}

The DDK documentation for the HID class driver read and write handler says that the IRP file object pointer must be valid. HidKbd obtained a file object using IoGetDeviceObjectPointer when it first found a HID device. However, this file handle was closed because it stops the HID device from being removed.

When a user mode application opens a handle to a HidKbd device, the Create IRP handler receives another file object pointer. This same file object pointer is passed in subsequent Read, Write, and Close IRPs, etc.

The HidKbd Create IRP handler, HidKbdCreate, therefore, has to tell the HID class driver about this new file object pointer. It does this by passing the Create IRP to the HID class driver. This is actually very easy to do by putting this extra code in the HidKbdCreate routine.

As HidKbd does not need to process the IRP afterwards, there is no need to set a completion routine.

// Forward IRP to HID class driver device
IoSkipCurrentIrpStackLocation(Irp);
return IoCallDriver(dx->HidDevice, Irp);

The HidKbd Close IRP handler, HidKbdClose, has exactly the same lines in it. This tells the HID class driver that the file handle is being closed.

A side effect of making the HID class driver open a handle for the device is that Windows 2000 will not let the HID device be removed for the duration. This is a perfectly acceptable behavior.

Reading and Writing Data

Our HID kernel mode client is now finally ready to read and write data.

HidKbd currently only supports reading of input reports. The Read IRP expects the provided buffer to be big enough. For a keyboard-input report, the buffer must be at least nine bytes long. The first byte will be 0, with the eight bytes of the input report in the remaining bytes. HidKbd makes no attempt to analyze the data in the same way as HidKbdUser. Instead, it simply returns all the information to the user mode application.

The main Read IRP handler, HidKbdRead, eventually calls ReadHidKbdInputReport, shown in Listing 23.11. ReadHidKbdInputReport is passed the precious file object pointer and a pointer to the buffer. It returns a count of the number of bytes transferred.

ReadHidKbdInputReport looks similar to the CallUSBDI and CallHidIoctl routines described before. This time HidKbd must issue a read request to the HID class driver, so it uses IoBuildSynchronousFsdRequest kernel call to build a suitable Read IRP. An event can be used to wait synchronously for the IRP to be completed, so ReadHidKbdInputReport must be called at PASSIVE_LEVEL IRQL.

By default, IoBuildSynchronousFsdRequest does not insert a file object pointer into the IRP. Therefore, HidKbd must do this job by hand. It calls IoGetNextIrpStackLocation to get the stack location that will be seen by the next driver, the HID class driver. ReadHidKbdInputReport then simply stores the PFILE_OBJECT in the stack FileObject field.

Finally, HidKbd runs IoCallDriver to call the HID class driver. If the IRP is still pending when this call returns, ReadHidKbdInputReport waits for the event to become signalled when the IRP does complete.

I have left out one small part of the story. The DDK says that HID class drivers use Direct I/O for their input and output buffers, not Buffered I/O. Luckily, IoBuildSynchronousFsdRequest sorts this out for us. It checks if the called driver uses Direct I/O. If it does,it allocates the required MDL for the passed input or output buffer (and deallocates it on completion).

Listing 23.11 ReadHidKbdlnputReport routine

NTSTATUS ReadHidKbdInputReport(PFILE_OBJECT FileObject, PVOID Buffer, ULONG& BytesTxd) {
 PHIDKBD_DEVICE_EXTENSION dx = (PHIDKBD_DEVICE_EXTENSION)HidKbdDo->DeviceExtension;
 BytesTxd = 0;
 if (HidKbdDo==NULL) return STATUS_NO_MEDIA_IN_DEVICE;
 IO_STATUS_BLOCK IoStatus;
 IoStatus.Information = 0;
 KEVENT event;
 LARGE_INTEGER FilePointer;
 FilePointer.QuadPart = 0i64;
 // Initialise IRP completion event
 KeInitializeEvent(&event, NotificationEvent, FALSE);
 PIRP Irp = IoBuildSynchronousFsdRequest(IRP_MJ_READ, dx->HidDevice,
  Buffer, dx->HidInputReportLen, &FilePointer, &event, &IoStatus);
 if (Irp==NULL) return STATUS_INSUFFICIENT_RESOURCES;
 // Store file object pointer
 PIO_STACK_LOCATI0N IrpStack = IoGetNextIrpStackLocation(Irp);
 IrpStack->FileObject = FileObject;
 // Call the driver and wait for completion if necessary
 NTSTATUS status = IoCallDriver(dx->HidDevice, Irp);
 if (status == STATUS_PENDING) {
  KeWaitForSingleObject(&event, Suspended, KernelMode, FALSE, NULL);
  status = IoStatus.Status;
 }
 // return IRP completion status
 DebugPrint("ReadHidKbdInputReport: status %x", status);
 BytesTxd = IoStatus.Information;
 return status;
}

Permanently Allocated IRP

A kernel mode HID client is likely to be reading many input reports. Rather than building up a suitable IRP for each call, it is more efficient to have one at the ready all the time. However, this approach is a bit more complicated to set up. The HidKbd driver has this alternative code commented out.

When a HidKbd device is created, it must allocate the IRP that will be reused in all subsequent read and write requests. The SetupHidIrp routine, shown in Listing 23.12, calls IoAllocateIrp to obtain a suitable IRP pointer from the I/O Manager. As IRPs have a variable number of stack locations, SetupHidIrp must pass the desired stack size. The second parameter to IoAllocateIrp should be FALSE for intermediate drivers.

It also makes sense to preallocate a buffer for input and output reports. SetupHidIrp works out the size of buffer needed and allocates it from the nonpaged pool. The final preparatory step is to allocate an MDL for this buffer. Remember that the HID class driver uses Direct I/O and so needs an MDL passed in Read and Write IRPs. The call to IoAllocateMdl makes a suitable MDL out of the buffer pointer.

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] 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.

The CallUSBDI routine in the UsbKbd driver is a candidate for this technique, as it is more than likely that the USB class drivers will take some time to process a USBDI request. However, it is usually the case that the USBDI call results are needed. Processing the results in a completion routine is just about possible. However, this will probably lead to code that is very complicated. In the end, it is probably simplest to leave the UsbKbd code as it is.

The DDK header files define several other HID IOCTLs. However, some of these are used by the HID class driver when it talks to a minidriver. It is not clear if any of these are available to HID clients.

Оглавление книги