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, such as IoDeleteDevice or ObQueryNameString.
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 check the Irp->PendingReturned flag. If this flag is set, the completion routine must call IoMarkIrpPending to mark the IRP as pending.
If a completion routine signals an event, it should not call IoMarkIrpPending.
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 should 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 calling IoAllocateIrp or IoBuildAsynchronousFsdRequest. Because the driver did not receive this IRP from a higher-level driver, it can safely free the IRP in the completion routine. After calling IoFreeIrp, 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 call IoMarkIrpPending before posting each IRP to the worker queue. Otherwise, the IRP could be dequeued, completed by another driver routine, and freed by the system before the call to IoMarkIrpPendingoccurs, thereby causing a crash.