handling IRPs 15: Building IRPs

Building IRPs

Drivers can create two types of IRPs:

·         Threaded IRPs, also called synchronous requests.

·         Nonthreaded IRPs, also called asynchronous requests.

Threaded IRPs

Threaded IRPs are bound to the current thread of execution when they are created. When the thread terminates, any threaded IRPs associated with it are automatically canceled.

Drivers create threaded IRPs by calling one of the following routines:

·         IoBuildSynchronousFsdRequest

·         IoBuildDeviceIoControlRequest

 

IoBuildSynchronousFsdRequest allocates and builds a threaded IRP for a read or write request.IoBuildDeviceIoControlRequest allocates and builds a threaded IRP to send an IOCTL.

When creating a threaded IRP, a driver specifies an event to signal when the IRP is complete and provides pointers to the buffers in which to return the requested data. When every sub-request in the IRP is complete (that is, when all the required drivers have completed the IRP), the entire request is complete. The I/O Manager then performs post-processing as follows:

·         Copies kernel-mode data to user-mode buffers to be returned to the caller. For example,ZwReadFile,IoBuildDeviceIoControlRequest, and similar system support routines pass user-mode buffers.

·         Signals the event, if the response is asynchronous. If the IoCallDriver routine returns STATUS_PENDING, the caller should wait on the event. 

·         Copies the value of the Irp->IoStatus.Status field to the Irp->UserIosb.Status field of the user I/O status block, if the response is asynchronous. IfIoCallDriver returns STATUS_PENDING, the caller can read this field after the event is signaled.

·         Copies the value of the Irp->IoStatus.Information field to the Irp‑>UserIosb.Information field of the user I/O status block, if the response is asynchronous and the I/O request succeeded. IfIoCallDriver returns STATUS_PENDING, the caller can read this field after the event is signaled. If the request returns an error status, the I/O Manager does not transfer any data to the user buffers, so the caller should treat the value atIrp‑>UserIosb.Information as zero; some driver writers might prefer to zero-initialize the field as an added precaution.  

·         Frees the IRP.

 

Nonthreaded IRPs

Nonthreaded IRPs are not associated with any thread. The driver that initiates a nonthreaded IRP must set a completion routine to “catch” the IRP when it is complete. The I/O Manager does not free nonthreaded IRPs; the driver that initiated the IRP must free it. Nonthreaded IRPs are intended for driver-to-driver communication.

Drivers create nonthreaded IRPs by calling one of the following routines:

·         IoBuildAsynchronousFsdRequest

·         IoAllocateIrp

 

IoBuildAsynchronousFsdRequest allocates and builds a nonthreaded IRP for a read or write request.IoAllocateIrp allocates an IRP for a driver to send to lower drivers in the same device stack or to another device stack.

IRP Cancellation

IRPs can be canceled (sometimes described as “recalled”). When an IRP is canceled, the driver that currently owns the IRP must complete it immediately.

A driver that requires special processing to cancel an IRP must either:

·         Supply an IoCancel routine to be notified when cancellation occurs and test theCancel flag in the IRP at various times during processing to determine whether the IRP has been canceled.

·         Use the new cancel-safe IRP queuing routines (IoCsqXxx).  

 

IRP cancellation can be difficult to code correctly because cancellation is inherently asynchronous and race conditions can occur at numerous points. The cancel-safe IRP queues greatly simplify cancellation logic and are strongly recommended for all new drivers. IRP cancellation is covered in the WDK and in the white paper titled “Cancel Logic in Windows Drivers.”