Completing IO Requests

Completing I/O Requests

When a driver completes an I/O request, it supplies a completion status and the number of bytes of data transferred in the request. KMDF drivers can also specify a priority boost for the thread that issued the request.

Table 8-14 summarizes the I/O request completion methods that WDF drivers can call. All the UMDF methods belong to the IWDFIoRequest interface.

Table 8-14: I/O Request Completion Methods
Open table as spreadsheet

Action	UMDF method	KMDF method
Completes an I/O request with status and the default priority boost.	Complete	WdfRequestComplete
Completes an I/O request with status, the number of bytes transferred, and the default priority boost.	CompleteWithInformation	WdfRequestCompleteWithInformation
Completes an I/O request with status, number of bytes transferred, and priority boost.	None	WdfRequestCompleteWithPriorityBoost

To complete an I/O request, a driver calls one of the I/O request completion methods in Table 8-14. Create, cleanup, and close requests typically do not involve data transfer, so the driver can use the simple Complete method. Read requests, write requests, and most device I/O control requests, however, require the driver to transfer data. For any request to transfer data, the driver should use one of the other methods so that it can notify the application of the number of bytes of data that were actually transferred as a result of the request.

 KMDF   KMDF drivers can supply a priority boost by calling WdfRequestCompleteWithPriorityBoost to complete a request. The priority boost is a system-defined constant that increases the runtime priority of the thread that is waiting for the I/O request to complete or received the results of the completed request. The priority boost constants are defined in Wdm.h. If the driver does not specify a boost, the framework applies a default priority boost that is based on the type of device that the driver specified when it created the device object.

 Tip  See "Completing I/O Requests" in the WDK for a list of the defaults-online at http://go.microsoft.com/fwlink/?LinkId=80614.

 Chapter 5 describes object cleanup callbacks   In response to any of the completion methods, WDF completes the underlying IRP and then deletes the WDF request object and any child objects. If the driver implements a cleanup callback for the WDF request object, WDF invokes that callback before completing the IRP, so that the IRP itself is still valid when the callback runs. Because the IRP is still valid, the driver has access to the IRP's parameters and memory buffers.

After the I/O completion method returns, the I/O request object and its resources have been released. The driver must not attempt to access the object or any of its resources, such as parameters and memory buffers that were passed in the request.

If the request was dispatched from a sequential queue, the driver's call to complete the request might cause the framework to deliver the next request in the queue. If the queue is configured for parallel dispatching, the framework can deliver another request at any time. If the driver holds any locks while it calls the I/O completion method, it must ensure that its event callback methods for the queue do not use the same locks because a deadlock might occur. In practice, this is difficult to ensure, so the best practice is not to call any of the I/O completion methods while holding a lock.