Handling IRPs 8: Propagating the Pending Bit

Propagating the Pending Bit

Any time a driver handling an I/O request returns the response of the next-lower driver, the value of the pending bit in its I/O stack location (SL_PENDING_RETURNED in the Control field of the IO_STACK_LOCATION structure) must be the same as that of the next-lower driver. If the driver does not set an IoCompletion routine, the I/O Manager automatically propagates the value of the bit, freeing the driver of this responsibility. However, if the driver sets an IoCompletion routine, and the next-lower driver returns STATUS_PENDING, the current driver must mark its own I/O stack location as pending. For example:

// Forward request to next driver

IoCopyCurrentIrpStackLocationToNext( Irp );

 

// Send the IRP down

status = IoCallDriver( nextDevice, Irp );

 

// Return the lower driver’s status

return status;

 

Because this example does not set an IoCompletion routine, the driver must not call the IoMarkIrpPending macro. The driver simply returns the same status as the next-lower driver and the I/O Manager copies the value of the pending bit.    

However, if the driver sets an IoCompletion routine, this code is insufficient for situations in which the lower driver returns STATUS_PENDING. In such situations, the driver must call the IoMarkIrpPending macro to set the SL_PENDING_RETURNED bit for its own I/O stack location. The driver must call IoMarkIrpPending from an IoCompletion routine; it must not make this call from its dispatch routine. Thus, the following code is incorrect:

// Forward request to next driver

IoCopyCurrentIrpStackLocationToNext( Irp );

 

// Send the IRP down

status = IoCallDriver( nextDevice, Irp );

 

// The following is an error because this driver

// no longer owns the IRP.

If (status == STATUS_PENDING) {

 

    IoMarkIrpPending( Irp );

}

 

// Return the lower driver’s status

return status;

 

This approach is incorrect because IoMarkIrpPending operates on the current I/O stack location. After IoCallDriver passes the IRP to the next lower driver, the current driver no longer owns the IRP. Thus, when the call to IoMarkIrpPending is executed, there is no current I/O stack location; in fact, if a lower driver completed the IRP, then the pointer is no longer valid. To avoid this problem, the driver must call IoMarkIrpPending from an IoCompletion routine. For example:

NTSTATUS

CompletionRoutine( ... )

{

   if (IrpàPendingReturned) {

 

      // Return the lower driver’s result. If the

      // lower driver marked its stack location pending,

      // so do we.

      IoMarkIrpPending( Irp );

   }

 

… //additional processing in IoCompletion routine

 

   return STATUS_CONTINUE_COMPLETION;

}

 

Drivers should use this code sequence only when returning the same status as the lower driver. If the driver does not set an IoCompletion routine, the I/O Manager automatically propagates the value of the SL_PENDING_RETURNED bit upwards to the next I/O stack location. A driver is not required to use an IoCompletion routine simply to call IoMarkIrpPending; but if a driver does have an IoCompletion routine, and a lower driver returns STATUS_PENDING, the IoCompletion routine must call IoMarkIrpPending.