Constraints on completion routines

Http://msdn.microsoft.com/en-us/library/windows/hardware/ff539307 (V = vs.85). aspx

 

 

The following guidelines briefly discuss how to avoid common programming errors in file system filter driver completion routines.

IRQL-related constraints

Because completion routines can be called at IRQL dispatch_level, they are subject to the following constraints:

• Completion routines cannot safely call kernel-mode routines that require a lower IRQL, suchIodeletedeviceOrObquerynamestring.

• Any data structures used in completion routines must be allocated from nonpaged pool.

• Completion routines cannot be made pageable.

• Completion routines cannot acquire resources, mutexes, or fast mutexes. However, they can acquire spin locks.

Checking the pendingreturned flag

• Unless the completion routine signals an event, it must checkIRP-> pendingreturnedFlag. If this flag is set, the completion routine must callIomarkirppendingTo mark the IRP as pending.

• If a completion routine signals an event, it shocould not callIomarkirppending.

Constraints on returning status

• A file system filter driver completion routine must return either STATUS_SUCCESS or status_more_processing_required. All other ntstatus values are reset to STATUS_SUCCESS by the I/O manager.

Constraints on returning status_more_processing_required

There are three cases when completion routines shoshould return status_more_processing_required:

• When the corresponding dispatch routine is waiting for an event to be signaled by the completion routine. in this case, it is important to return status_more_processing_required to prevent the I/O manager from completing the IRP prematurely after the completion routine returns.

• When the completion routine has posted the IRP to a worker queue and the corresponding dispatch routine has returned status_pending. in this case as well, it is important to return status_more_processing_required to prevent the I/O manager from completing the IRP prematurely after the completion routine returns.

• When the same driver created the IRP by callingIoallocateirpOrIobuildasynchronousfsdrequest. Because the driver did not receive this IRP from a higher-level driver, it can safely free the IRP in the completion routine. After callingIofreeirp, The completion routine must return status_more_processing_required to indicate that no further completion processing is needed.

A completion routine cannot return status_more_processing_required for an oplock operation. oplock operations cannot be pended (posted to a worker Queue), and dispatch routines cannot return status_pending for them.

Constraints on posting IRPs to a work queue

• If a completion routine posts IRPs to a work queue, it must callIomarkirppendingBefore posting Each IRP to the worker queue. Otherwise, the IRP cocould be dequeued, completed by another driver routine, and freed by the system before the callIomarkirppendingOccurs, thereby causing a crash.