Processing IO Operations

1. Processing IO Operations © 2004 Microsoft Corporation. All rights reserved.

2. In the IRP world… • In your dispatch (pre-operation) routine you can: • Pass through the operation with no completion • Do not care about this operation • Do not need to see the final status of this operation • Pend an operation • Will call IoCallDriver()/IoCompleteRequest() from a worker thread sometime later • Pass through the operation, setting a completion • Need to see the final status of the operation • Synchronize the operation • Allows post-operation processing to be done in the context of the same thread that the dispatch routine was called – safe IRQL, maintain your local variable state • Complete the operation © 2004 Microsoft Corporation. All rights reserved.

3. In the IRP world… • In your completion (post-operation) routine you can: • Do completion work directly in completion routine • All the post-operation work can be done at DPC-level • Do completion work at safe IRQL • Queue to a worker thread to allow processing at safe IRQL, call IoCompleteRequest() to continue completion processing • Synchronize back to dispatch by signaling event • Dispatch routine is waiting and will pick up doing the post-operation work in the context of the dispatch routine thread, call IoCompleteRequest() when done • Cancel a successful CREATE operation © 2004 Microsoft Corporation. All rights reserved.

4. In the Filter Manager world… • Still have same flexibility but is mainly controlled by the value returned in preOperation completion • No longer need code that does IRP maintenance • Copying parameters to next stack location • Propagating pending flag © 2004 Microsoft Corporation. All rights reserved.

5. PreOperation Callback Return Values • FLT_PREOP_SUCCESS_NO_CALLBACK • PostOperation callback will not be called for this operation • FLT_PREOP_SUCCESS_WITH_CALLBACK • PostOperation callback will be called for this operation • Not valid to return if no postOperation callback was registered for this operation • FLT_PREOP_PENDING • Operation will be pended • Filter must complete or continue processing this IO sometime in the future © 2004 Microsoft Corporation. All rights reserved.

6. PreOperation Callback Return Values (cont) • FLT_PREOP_SYNCHRONIZE • PostOperation callback will be called in the context of the current thread at safe IRQL • IRP_MJ_CREATE operations are always synchronized • Do not synchronize asynchronous read/write operations • Will destroy the performance of the system • FLT_PREOP_COMPLETE • Filter completed this operation • FLT_CALLBACK_DATA.IoStatus will be returned as the final status for operation • FLT_PREOP_DISALLOW_FASTIO • FAST_IO will be failed – IO Manager may reissue request via IRP path • Can only be returned for operations that map to FAST_IO calls (FLTFL_CALLBACK_DATA_FAST_IO_OPERATION will be set in FLT_CALLBACK_DATA.Flags) © 2004 Microsoft Corporation. All rights reserved.

7. Retrieving operation status • For some operations it is important to retrieve the operation status returned by IoCallDriver() • Needed to know if an oplock was granted or not • FltRequestOperationStatusCallback() • Specifies a callback routine to be called when the operation status is returned (return value of IoCallDriver()) • Properly synchronized with unload • Handles operation being completed by a lower minifilter/legacy filter • As in the legacy model, may be called after the operation has completed © 2004 Microsoft Corporation. All rights reserved.

8. PostOperation Callback Return Values • FLT_POSTOP_FINISHED_PROCESSING • Finished with post-operation processing • Can continue with higher filter/IO Manager post-operation processing • FLT_POSTOP_MORE_PROCESSING_REQUIRED • Have queued completion work to a worker thread • Filter must continue completion processing on this IO at a later time • Note: PostOperation callbacks may be called at DPC level like completion routines • To cancel a CREATE operation: • Call FltCancelFileOpen() • IoCancelFileOpen() bug has been fixed • Return failure status through callback data © 2004 Microsoft Corporation. All rights reserved.

9. Pending IO in PreOperation Callback • FltCompletePendedPreOperation() • Must call this to restart processing of IO pended in the preOperation callback • Filter may: • Complete operation • Request postOperation callback through the FLT_PREOP_CALLBACK_STATUS parameter • Typically called from a worker thread © 2004 Microsoft Corporation. All rights reserved.

10. Pending IO in PreOperation Callback (cont) • FltQueueDeferredIoWorkItem() • Queue operation to worker thread for continued processing • Can fail if this operation is not safe to post – i.e., this is paging IO or top-level IRP is already set on this thread • Can fail if this Instance is in the process of being torndown © 2004 Microsoft Corporation. All rights reserved.

11. Pending IO in PostOperation Callback • FltDoCompletionProcessingWhenSafe() • Can fail if it is not safe to post • Not safe to post Paging IO’s • Synchronize operation if you cannot handle this failure • Tells filter the appropriate postOperation callback status to return • Will only post operation if currently at DPC IRQL • Will continue completion processing when WorkerRoutine has completed © 2004 Microsoft Corporation. All rights reserved.

12. Pending IO in PostOperation Callback (cont) • FltQueueDeferredIoWorkItem() • Works just like in preOperation • Will always queue work to worker thread if it is safe to do so • If successfully queues work, return FLT_POSTOP_MORE_PROCESSING_REQUIRED • FltCompletePendedPostOperation() • Must call this to restart processing of IO pended in the postOperation callback © 2004 Microsoft Corporation. All rights reserved.

13. Queuing Mechanisms • Generic queuing support • Deferred IO queuing support • Cancel safe queuing support © 2004 Microsoft Corporation. All rights reserved.

14. Generic Queuing Support • FltAllocateGenericWorkItem() • Allocates a generic work item • FltQueueGenericWorkItem() • Queues a generic work item • Associated with an Instance or Filter object • FltFreeGenericWorkItem() • Frees a generic work item © 2004 Microsoft Corporation. All rights reserved.

15. Generic Queuing Support (cont) • Work just like ExXxxWorkItem() routines • Can reuse work items • Filter is responsible for allocation and freeing • The Instance/Filter will not finish unloading while outstanding work items are still being processed © 2004 Microsoft Corporation. All rights reserved.

16. Deferred IO Queue Support • FltAllocateDeferredIoWorkItem() • Allocates deferred IO work item • FltQueueDeferredIoWorkItem() • Queues deferred IO work item • This can fail if operation cannot be pended • FltFreeDeferredIoWorkItem() • Frees deferred IO work item © 2004 Microsoft Corporation. All rights reserved.

17. Deferred IO Queue Support (cont) • Filter is responsible for allocation and freeing of deferred IO work item • Deferred IO work item can be reused • Instance cannot go away while there are outstanding deferred IO work items being processed © 2004 Microsoft Corporation. All rights reserved.

18. Cancel Safe Queuing Support • FltCbdqInitialize() • Initializes the cancel safe queue • FltCbdqInsertIo() • Inserts a FLT_CALLBACK_DATA into the queue • FltCbdqRemoveIo() • Removes a given FLT_CALLBACK_DATA from the queue • FltCbdqRemoveNextIo() • Removes the next FLT_CALLBACK_DATA that meets the peek criteria from the queue • FltCbdqDisable() • Disables insertion of new IOs to the queue • Used to allow the queue to be drained when an Instance is being torn down © 2004 Microsoft Corporation. All rights reserved.

19. Cancel Safe Queuing Support • FltCbdqEnable() • Enables new IOs to be added to the queue • Once the queue is initialized, it is enabled by default • Used only when pending preOperation callbacks • Provides cancel logic for filters that need to maintain a queue of outstanding IOs to service • Equivalent functionality to IoCsqXxx() provided for IRPs • Filter is responsible for disabling and draining queue on InstanceTeardownStart() © 2004 Microsoft Corporation. All rights reserved.

20. Cancel Support • FltSetCancelCompletion() • Allows setting of cancel routine for a given FLT_CALLBACK_DATA • FltClearCancelCompletion() • Allows clearing of the cancel routine for a given FLT_CALLBACK_DATA • FltIsIoCanceled() • Returns TRUE if the current operation has been canceled © 2004 Microsoft Corporation. All rights reserved.

21. Cancel Support (cont) • Equivalent to IoSetCancelRoutine() for IRPs (read documentation) • Filter is responsible for locking to make sure set/clear/cancel is properly synchronized • Can be used to implement your own cancellation logic • It is recommended that you use cancel safe queues © 2004 Microsoft Corporation. All rights reserved.

22. Oplock Support • FltInitializeOplock() • FltUninitializeOplock() • FltOplockFsctrl() • FltCheckOplock() • FltOplockIsFastIoPossible() • FltCurrentBatchOplock() • Internally extracts IRP from Callback Data and calls equivalent FSRTL routines © 2004 Microsoft Corporation. All rights reserved.

23. Byte Range Lock Support • FltInitializeFileLock() • FltUninitializeFileLock() • FltAllocateFileLock() • FltFreeFileLock() • FltProcessFileLock() • FltCheckLockForReadAccess() • FltCheckLockForWriteAccess() • Use in conjunction with existing FsRtl routines • Internally extracts IRP from Callback Data and calls equivalent FSRTL routines © 2004 Microsoft Corporation. All rights reserved.