© 2004 Microsoft Corporation. All rights reserved. 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!