Please give me any comments or corrections on the feedback page.

For both these methods, the driver sees the input buffer in buffered memory at Irp->AssociatedIrp.SystemBuffer with the input buffer length at the IRP stack Parameters.DeviceIoControl.InputBufferLength. These fields are NULL and 0 respectively if you pass no input buffer.

METHOD_IN_DIRECT is used if you are reading lots of data, or want to use an MDL in your driver. The Win32 program passes the read data buffer in the DeviceIoControl output buffer parameter. The read data buffer is passed to the driver as an MDL in Irp->MdlAddress. The size of the read data buffer is passed in Parameters.DeviceIoControl.OutputBufferLength. If no buffer is specified then these fields are NULL and 0 respectively.

METHOD_OUT_DIRECT is used if you are writing lots of data, or want to use an MDL in your driver. The Win32 program passes the write data buffer in the DeviceIoControl output buffer parameter. The write data buffer is passed to the driver as an MDL in Irp->MdlAddress. The size of the write data buffer is passed in Parameters.DeviceIoControl.OutputBufferLength. If no buffer is specified then these fields are NULL and 0 respectively.

There are two points to note about using these techniques:

• If METHOD_OUT_DIRECT is used, then the Win32 program is providing two sets of data into the driver. The 'input' buffer is in Irp->AssociatedIrp.SystemBuffer and the 'output' buffer is in Irp->MdlAddress.
• It seems as though it does not matter whether you use METHOD_IN_DIRECT or METHOD_OUT_DIRECT. In both cases it seems as though you can use MDL for either input or output.

		if( Irp->PendingReturned)
			IoMarkIrpPending();

Most completion routines need to use the above code in their completion routines to remember if any lower driver has pended an IRP. If any driver in a stack marks an IRP as pending then the I/O Manager has to take special steps to ensure that the IRP results are returned to user space in the correct thread context.

Calling IoMarkIrpPending sets an internal pending flag in the current IRP stack location (the SL_PENDING_RETURNED bit in the Control field). When a lower driver completes an IRP, IoCompleteRequest sets the Irp->PendingReturned flag equal to the IRP stack internal flag. To remember that the IRP was pended, a completion routine must therefore call IoMarkIrpPending if Irp->PendingReturned is set.

In two cases, the above code is not strictly necessary (though including the code will cause no bugs).

• If the completion routine sets an event which the main code waits for, then the IRP processing is back in the context of calling thread, and so the Pending flags do not need to be set.
• If the IRP is allocated by a driver, then there is no user space thread context completion work required. So you do not need to check the Pending flag in the completion routine of an IRP which you allocated.

Thanks to Jamie Hanrahan and others on the NTDEV mailing list for answering my questions on this.

The book software Servicer program should also be altered minorly to cope with this change of functionality.

Search for "PNPISA" in the MSDN library for some more details.

[ WmiMethodId(1),
  Implemented,
  Description("Power down the device")
]
void PowerDown();

In addition the ExecuteWmiMethod method in Wmi.cpp needs updating. The old code incorrectly checked that the MethodId parameter was 0. Instead, the first method, PowerDown, has MethodId 1 and so one line in ExecuteWmiMethod should be:

if( GuidIndex==WDM3_WMI_GUID_INDEX && MethodId==1) // 1.0.1

The PowerDown method now appears in the WMI Object Browser and can be executed successfully to power down individual Wdm3 devices.

Note 1: I have also added the WMIREG_FLAG_EVENT_ONLY_GUID flag to the Wdm3Event WMIGUIDREGINFO declaration. However I have still not found how to enable these events and view them. Any suggestions?

Note 2: the mofcomp tool can now generate a VBScript script to test a WMI implementation.

Listing 13.4 on page 284 should now be as follows:

[Wdm3.Install.NTx86.Services]
AddService = Wdm3, %SPSVCINST_ASSOCSERVICE%, Wdm3.Service, Wdm3.Service.EventLog

...

[Wdm3.Service.EventLog]
AddReg = Wdm3.Service.EventLog.AddReg

[Wdm3.Service.EventLog.AddReg]
HKR,,EventMessageFile,%FLG_ADDREG_TYPE_EXPAND_SZ%,"%%SystemRoot%%\System32\IoLogMsg.dll;%%SystemRoot%%\System32\drivers\Wdm3.sys"
HKR,,TypesSupported,%FLG_ADDREG_TYPE_DWORD%,7


Bob Fruth also pointed out that the latest W2000 DDK has a useful tool, ChkINF in the DDK Tools directory, for checking INF files. ChkINF is a perl script so I have not managed to check it out yet.
In addition a new tool for generating INF files is also available in the DDK Tools directory; it is called the INF wizard geninf.

File handles are a type of Object handle. All Object handles process dependent, ie they are only usable by threads running in the same process.

Thanks to Jamey Kirby of StorageCraft for this information. James also adds:

"If you use kernel worker threads (work queue items), you can assume that your file handle is valid no matter what worker thread happens to be processing the request (because they are all in the system process).

"It is also possible to create system threads in a process context other than the system process. This is useful if you have a driver that needs to access network resources (i.e. a file). My creating the system thread in the context of a process that has the appropriate access rights, the thread will be able to access the resources."

IoCancelIrp returns TRUE if an IRP's cancel routine was called, and FALSE if not, ie if there was no cancel routine (eg if the cancel routine was removed at the beginning of the StartIo handler).

The DDK documentation for IoCancelIrp might give the impression that if IoCancelIrp returns TRUE then the IRP has been completed. This is not the case for the technique I used earlier; the IRP's cancel routine has been called but the IRP has not been completed.

A quick look at all the W2000 DDK source code examples seems to indicate that none of these examples assume that an IRP has been completed, even if IoCancelIrp returns TRUE. If the IRP has a completion routine, wait for it to run. Only when the IRP has really completed can you free its memory.

I do not know what technique the I/O Manager uses if a user mode program cancels an IRP using CancelIo.

There is a chance that the CurrentIrp will have become NULL in my Timeout1s routine, and also a chance that a device interrupt will occur after the Cancel flag has been found true but before the DPC is called.

My revised code does its timeout and Cancel checks in the Critical Section routine, Timeout1sSynch.

The revised Timeout1sSynch routine now has to be changed because Timeout1s does not call the DPC routine directly. Instead, Timeout1sSynch asks that my DPC routine be called later in the normal way using IoRequestDpc.
Note that Timeout1sSynch returns TRUE if the DPC was scheduled. However this information is only used to do a debug printout.

VOID Timeout1s( IN PDEVICE_OBJECT fdo, IN PWDMIO_DEVICE_EXTENSION dx)
{
	if( dx->Timeout==-1) return;

	DebugPrint("Timeout1s: Timeout is %d",dx->Timeout);

	// Check for timeout in synch with interrupt
	if( KeSynchronizeExecution( dx->InterruptObject, (PKSYNCHRONIZE_ROUTINE)Timeout1sSynch, dx))
	{
		DebugPrint("Timeout1s: Timeout1sSynch cancelled in-progress IRP %x %I",Irp,Irp);
	}
}

static BOOLEAN Timeout1sSynch( IN PWDMIO_DEVICE_EXTENSION dx)
{
	if( dx->Timeout==-1) return FALSE;

	PDEVICE_OBJECT fdo = dx->fdo;
	PIRP Irp = fdo->CurrentIrp;
	if( Irp==NULL) return FALSE;

	// Only complete IRP if it is cancelled or if it has timed out
	if( !Irp->Cancel && --dx->Timeout>0)
		return FALSE;

	// Get DPC to complete the IRP
	dx->Timeout = -1;
	dx->TxStatus = STATUS_NO_MEDIA_IN_DEVICE;	// Win32: ERROR_NOT_READY
	IoRequestDpc( fdo, Irp, dx);
	return TRUE;
}

The problem is that the USBDI GET_DESCRIPTOR call must be directed to the interface, not the device. My UsbGetSpecifiedDescriptor routine uses the UsbBuildGetDescriptorRequest helper function that always uses the URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE function code.

As the desired HID Descriptor is an Interface descriptor, the URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE function code should be used instead. As a temporary hack the following code can be inserted after UsbBuildGetDescriptorRequest has been called.

urb->UrbHeader.Function = URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE;

A full fix for this problem would be add an extra parameter to UsbGetSpecifiedDescriptor to indicate whether a device, interface or endpoint descriptor is required. The IOCTL_USBKBD_GET_SPECIFIED_DESCRIPTOR handler and the corresponding UsbKbdTest code would also need to be amended. I shall leave this an exercise for the reader.

It seems as though some devices respond with the desired information even if the request is directed as the device.

Thanks to Bruce Ramsland for pointing out this problem.

The HidKbd CallHidIoctl routine calls IoBuildDeviceIoControlRequest to build a HID request. The supplied code builds an IRP_MJ_INTERNAL_DEVICE_CONTROL IRP. Change parameter 7 of IoBuildDeviceIoControlRequest to FALSE to make it build an IRP_MJ_DEVICE_CONTROL IRP instead.

Thanks to Will Dean for this information.

Listing 23.10 page 489.

Thanks to Russell Hocken for spotting this.

        dx->HidIrp=NULL;
        return;            // Add this return here
    }
    MmBuildMdlForNonPagedPool(dx->HidReportMdl); // new command
}

"Without this the report wouldn't get put in the right place. It now seems to work correctly."

Listing 23.12 page 493/494.