Rules for Filters (both Legacy and Mini)

1. Rules for Filters (both Legacy and Mini) © 2004 Microsoft Corporation. All rights reserved.

2. Rules for Filters:Synchronization • Don’t issue file system calls while holding a lock (FastMutex, EResource, PushLock) • May cause the system to deadlock • Especially with other filters present © 2004 Microsoft Corporation. All rights reserved.

3. Rules for Filters:Synchronization • Minimize the synchronization your filter uses • Leading cause of performance degradation • When possible used shared/exclusive semantics • PushLocks are efficient, very hard to debug a deadlock © 2004 Microsoft Corporation. All rights reserved.

4. Rules for Filters:TopLevelIrp • Don’t issue file system calls if IoGetTopLevelIrp() returns a non-NULL value • May cause the system to deadlock • The failure status returned from a file system operation while processing a recursive IO operation (TopLevelIrp returns non-NULL value) will be propagated back to the TopLevel operation • FltGetVolumeInformation() example © 2004 Microsoft Corporation. All rights reserved.

5. Rules for Filters:Accessing User Buffers • If a MDL is defined always use it to get a system address for the buffer • MmGetSystemAddressForMdlSafe() • If the operation is not buffered, always wrap accesses with try/except • FLTFL_CALLBACK_DATA_SYSTEM_BUFFER • All FastIO operations must be treated as if method neither buffering was used © 2004 Microsoft Corporation. All rights reserved.

6. Rules for Filters:PostOperation Callbacks • PostOperation callback routines may be called at DPC IRQL • Code postOperation routine as if they are always called at DPC level • Don’t issue File IO operations • Can’t do anything that would cause the system to context switch • Can only use interlocked operations or SpinLocks • FLtDoCompletionProcessingWhenSafe() © 2004 Microsoft Corporation. All rights reserved.

7. Rules for Filters:PostOperation Callbacks • Can not call FltGetXxxContext() from a postOperation callback • Will work if you move to a safe IRQL or synchronize • FltDoCompletionProcessingWhenSafe() • Can call FltReleaseContext()at DPC level © 2004 Microsoft Corporation. All rights reserved.

8. Rules for Filters:PostOperation Callbacks • Calling FltGetFileNameInformation() from a postOperation callback: • Will work if operation is synchronized • Create operations are always synchronized • FLT_FILE_NAME_INFORMATION structures are allocated from PagedPool. • Can not be accessed at DPC level • Therefore FltReleaseFileNameInformation() can not be called at DPC level • May not work even if you use FltDoCompletionProcessingWhenSafe() • TopLevelIrp may still be set by file system © 2004 Microsoft Corporation. All rights reserved.

9. Rules for Filters:Paging IO • All code paths executed while processing a Paging IO operation (IRP_PAGING_IO flag set) must not page fault • You can take page faults accessing data while processing a Paging IO operation • You can not take any page faults while processing paging IO to the Paging File • FsRtlIsPagingFile() • Contexts are not supported on Paging Files © 2004 Microsoft Corporation. All rights reserved.

10. Rules for Filters:NonCached IO • While processing a preRead or a preWrite operation, the length of non-cached IO operations are normally rounded to a sector boundary • MM violates this rules • Operations at the end of the file may not be properly rounded • If swapping buffers, your filter must round the size of nonCached IO operations up to a sector boundary before allocating the new buffer • See the SwapBuffers sample © 2004 Microsoft Corporation. All rights reserved.

11. Rules for Filters:Volume Locks • If your filter maintains open files, it must be closed when the volume is locked • Monitor: • FSCTL_LOCK_VOLUME • Close File during preOperation callback • May reopen file in postOperation if operation fails • Remember the file object which requested lock (instance context) • FSCTL_UNLOCK_VOLUME • May reopen file in postOperation • IRP_MJ_CLEANUP • If cleanup occurs before unlock, volume implicitly unlocked • If you don’t do this you break app compatibility • Especially backup applications • See MedataManager minifilter sample © 2004 Microsoft Corporation. All rights reserved.

12. Rules for Filters:Volume Dismount • FSCTL_DISMOUNT_VOLUME • Close open files in preOperation callback • IRP_MJ_PNP - IRP_MN_QUERY_REMOVE_DEVICE • Close open files in preOperation callback • Some file systems dismount while processing this operation. • IRP_MJ_PNP - IRP_MN_CANCEL_REMOVE_DEVICE • System decided to not dismount device • May reopen file during preOperation callback • IRP_MJ_PNP - IRP_MN_SURPRISE_REMOVAL • Close open files in preOperation callback • When received volume is already gone • IRP_MJ_SHUTDOWN • Close open files in preOperation callback • A dismount request may be sent for the same operation © 2004 Microsoft Corporation. All rights reserved.

13. Rules for Filters:FILE_OBJECT • FileName and RelatedFileObject fields are only valid while processing IRP_MJ_CREATE • Fields are not valid during any other operation! • RelatedFileObject may have been freed • Name may be wrong © 2004 Microsoft Corporation. All rights reserved.

14. Rules for Filters:IRP_MJ_CREATE • If an IRP_MJ_CREATE operation fails, the contents of the FileName buffer may have changed • If you need to reissue the create • Save the name in your preCreate routine • Restore the original name • Be sure to free the original file name buffer © 2004 Microsoft Corporation. All rights reserved.

15. Rules for Filters:Rename • ParentOfTarget parameter for the SetFileInformation operation (used for rename and hardLinks) • May be NULL • Or contains the file object for the parent directory of the target • It is not the file being renamed • That is in the FltObjects parameter © 2004 Microsoft Corporation. All rights reserved.

16. Rules for Filters:Structured Exception Handling • Do not abuse structured exception handling • Only use when: • Accessing user buffers • Calling APIs which raise • Using it inappropriately: • Masks bugs in other drivers • Makes it look like your driver caused the problem • We recommend that you do not use it internally for returning status like FAT does • Makes the code harder to maintain © 2004 Microsoft Corporation. All rights reserved.

17. Rules for Filters:Linking • Filters should only be linked with the following libraries: • ntoskrnl.lib • hal.lib • fltmgr.lib (for minifilters) • Do not link with DDK APIs defined in other libraries! © 2004 Microsoft Corporation. All rights reserved.