Potential Issues Involved in Updating Windows NT IFS Drivers To Windows 2000
Updated: March 20, 2001
This document is a checklist intended for Independent Software Vendors (ISVs) who have sufficient knowledge of Microsoft® Windows NT® 4.0 File system drivers, and who are developing or porting file system drivers to run under Windows® 2000. The document does not attempt to Describe Each of these Issues Fully, but is intended to help Isvs Keep Track of the Various Issues That The Issues Referred To in This Time.
Note: This document is provided for informational purposes only and Microsoft makes no warranties, either express or implied, in this document Information in this document is subject to change without notice The entire risk of the use or the results of the use of this.. document remains with the user. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give You any license to these Patents, Trademarks, Copyrights, or Other Intellectual property.
On this Page
General IFS ISSUESFILTER-ONLY ISSUESMEDIA-BASED FILE SYSTEM ISSREDIRECTOR ISSUESGENERAL OS ENVIRONMENT CHANGES
General IFS Issues
Let us know the status of your Windows 2000 support. Microsoft is testing third-party file system drivers to ensure that they work properly on systems that are upgraded from Microsoft Windows NT 3.51 / 4.0 to Windows 2000. For this reason, we are building a comprehensive list of file system drivers and file system filter drivers. Even if you are unsure of your Windows 2000 compatibility, please tell us about your driver so that we can make sure it is covered in our research and testing. Windows 2000 Post-RC1 Behavior Change in IoGetRelatedDeviceObject A bug in IoGetRelatedDeviceObject was discovered in Windows 2000 RC1 and fixed in RC2. This bug caused IoGetRelatedDeviceObject to behave incorrectly in some cases where the file object represented the underlying storage device and was not known to the file system. Fixing the bug required A Minor Change In The Behavior of IoGetRelyDeviceObject. Unfortunately, The Change Impacts A Small Number of Drivers (Primarily File System Filter Driv) ers) that called IoGetRelatedDeviceObject directly or indirectly and relied on the incorrect behavior. When called on a file object that represents the underlying storage device, IoGetRelatedDeviceObject now always returns the highest-level device object in the storage device stack. To obtain the highest-level Device Object In The File System Driver Stack, Drivers Must Call IOGETREDDEVICEOBJECT ON A File Object That Rerests The File System '
s driver stack, and the file system must currently be mounted. (Otherwise, the storage device stack is traversed instead of the file system stack.) To ensure that the file system is mounted on the storage device, the driver must have specified an appropriate access mask, such as FILE_READ_DATA or FILE_WRITE_ATTRIBUTES, when opening the file. Specifying FILE_READ_ATTRIBUTES does not cause the file system to be mounted. This requirement also applies to drivers. Such drivers should pass the appropriate access mask value in that routine's DesiredAccess parameter that call IoGetDeviceObjectPointer . Drivers that call IoAttachDevice are also affected by this change. IoAttachDevice opens the file with FILE_READ_ATTRIBUTES and then calls IoGetRelatedDeviceObject. This does not cause a file system to be mounted. Thus a successful call to IoAttachDevice returns the device object of the storage driver, not That of the file system driver. KESTACKATTAPROCESS The KeattachProcess Kernel Routine IS E .. Xported to support existing binaries and is obsolete Use KeStackAttachProcess instead KeStackAttachProcess is declared in ntifs.h and is prototyped as follows: NTKERNELAPI VOID KeStackAttachProcess (IN PRKPROCESS
Process, OUT PRKAPC_STATE ApcState); The Process parameter is a pointer to the target process object The ApcState parameter is an opaque pointer to a KAPC_STATE structure for which the caller must allocate storage either from nonpaged pool or from the caller's own thread stack KeStackAttachProcess.. attaches the current thread to the address space of the process pointed to by the Process parameter. If the current thread was already attached to another process, the ApcState parameter receives the current APC state before KeStackAttachProcess attaches to the new process. FsRtlNotifyVolumeEvent FsRtlNotifyVolumeEvent is a new FSRTL ROTINE THATE CAN BE Used To Notify Registered Applications Of The Following Volume Lock and Mount Events: FSRTL_VOLUME_DISMOUNTFSRTL_VOLUME_DISMOUNT_FAILED
FSRTL_VOLUME_LOCK
FSRTL_VOLUME_LOCK_FAILED
FSRTL_VOLUME_MOUNT
FSRTL_VOLUME_UNLOCK Note: FsRtlNotifyVolumeEvent is not supported in Windows NT 4.0 Drivers that use FsRtlNotifyVolumeEvent will not load on Windows NT 4.0 with any current service pack IRP_MJ_PNP All device drivers must now support Plug and Play (PnP) devices This behavior is seen in the... updated CDFS and FAT samples in the Windows 2000 IFS Kit. to do this, your driver must process IRP_MJ_PNP requests appropriately. For example, a QUERY_REMOVE request (IRP_MN_QUERY_REMOVE_DEVICE) grabs a volume lock to assert that all handles are closed and the device is removable. This Lock is released on caledel_remove (IRP_MN_CANCEL_REMOVE_DEVICE). Similarly, There is a new "remove pending"
state to prevent devices from being mounted while they are being removed IRP_MJ_SET_QUOTAIRP_MJ_QUERY_QUOTA IRP_MJ_SET_QUOTA and IRP_MJ_QUERY_QUOTA existed in Windows NT 4.0 but were not used by file systems In Windows 2000, they are used for disk quota support in NTFS via the following undocumented API calls..: NtQueryQuotaInformationFile, NtSetQuotaInformationFile, NtSetVolumeInformationFile, and NtQueryVolumeInformationFile. Support for these IRPs by new file systems is optional, but filters should allow them to pass through to NTFS unless they wish to explicitly override quota behavior. IRP_MN_DPC IRP_MN_DPC has been obsolete since Windows NT 4.0. ObReferencing Thereference Your Target Device Object (for PNP). This Behavior Is Seen In The Updated CDFS AND FAT Samples in The Windows 2000 IFS Kit. The Rule IS Follows:
The I / O Manager ObReferences your target device during mount. If the mount fails, the I / O Manager will ObDereference the device object. If the mount succeeds, you are responsible for performing the final ObDereference at volume tear-down. Object IDs In Windows 2000, NTFS permits users to generate an object ID for a file. This object ID is unique within the volume where the file resides. The Windows 2000 Replicator service and the Distributed Link Tracking service manipulate file object IDs via FSCTLs such as FSCTL_CREATE_OR_GET_OBJECT_ID. ( These FSCTLs are documented in the Platform SDK.) NTFS allows files to be opened by object ID as well as by file reference number. File system filter drivers that use file object IDs should be tested for interoperability with DFS, the Replicator service, and the Distributed Link Tracking Service, All of Which Use and Manipulate File Object IDs. Sparse File Support in Windows 2000, NTFS Supports Sparse Files. See The Documentation for Fsctl_set_sparse , FSCTL_SET_ZERO_DATA, and FSCTL_QUERY_ALLOCATED_RANGES in the Platform SDK for details. Note that the Remote Storage service uses sparse files. Support for these FSCTLs by new file systems is optional, but filters should allow them to pass through to NTFS unless they wish to explicitly override sparse File_Attribute_offline When This New Attribute IS Set on A File, The Network Timeout on The File IS Extended from 45 Seconds To 1000 Seconds.
(This new default value can in turn be changed via the registry setting System / CurrentControlSet / Services / LanmanWorkStation / Parameters / OffLineFileTimeoutInterval.) This new attribute is supported in the Windows 2000 redirector (RDR). It may also be backported to a Windows NT 4.0 service pack at some point (it is not in SP4), and possibly a Windows 98 service pack. It is intended for use by devices with high latencies, such as tape or optical disk libraries. use and interpretation of FILE_ATTRIBUTE_OFFLINE is optional, except for filter drivers that perform volume scans. Such drivers should ignore offline files by default, although they may offer advanced users the option of including offline files in the scan Change Journal in Windows 2000, NTFS maintains a per-volume change journal, which records changes To Files On That Volume. This Journal Can Be Independently Turned Off Ors The Given Volume. The Change Journal Includes Features That Make File System Filter Drivers Unnecessary . For many applications Change journal FSCTLs are documented in the Platform SDK File system filters should allow these to pass through to NTFS MdlReadCompleteCompressedMdlWriteCompleteCompressed Two new entries have been added to the Fast I / O Dispatch table:... MdlReadCompleteCompressed and MdlWriteCompleteCompressed These routines are not called in Windows 2000, but they may be called in future releases. These entries may be called at DPC level, and thus must be non-paged and reference only non-paged memory. FsRtlInitializeFileLock There are new FsRtl functions for handling file locks. Use Of these New Functions is Optional, But Rather Useful.
FSCTL_DISMOUNT_VOLUME The device I / O control code FSCTL_DISMOUNT_VOLUME is now allowed to (and should) work on live volumes, performing forced or controlled shutdown / invalidation of the volume to be formatted or ejected. This functionality is particularly important in clustering environments. Support for this control code is mandatory for Windows 2000. (Note that FSCTL_DISMOUNT_VOLUME is also available in Windows NT 4.0 SP4.) FSCTL_DISMOUNT_VOLUME is passed to drivers via IRP_MJ_FILE_SYSTEM_CONTROL and IRP_MN_USER_FS_REQUEST. Reference information for FSCTL_DISMOUNT_VOLUME can be found in the Platform SDK. (See Base Services-> Hardware-> Device Input and Output-> Device Input and Output Reference-> Device Input and Output Control Codes-> FSCTL_DISMOUNT_VOLUME.) FSCTL_IS_VOLUME_DIRTY FSCTL_IS_VOLUME_DIRTY is new in Windows 2000 and should be considered mandatory, even by read-only file systems. FSCTL_SECURITY_ID_CHECK FSCTL_SECURITY_ID_CHECK IS A New Fsctl for Performing Bulk ACL CHECKS. THI s feature, which is used by the Microsoft Indexing Server, is supported only by NTFS. This FSCTL will be documented in the Platform SDK for the RTM release of Windows 2000. Support for FSCTL_SECURITY_ID_CHECK is optional, but filters should allow it to pass through to NTFS UnsS They wish to explicitly override it.top of page
FILTER-ONLY ISSUES
Built-in Filters Windows 2000 uses a number of file system filter drivers internally to support certain features. It is strongly recommended that ISV filters should filter above these in order to simplify testing scenarios. This may become a mandatory requirement at some future time. Encrypted File Support in Windows 2000, NTFS supports the Encrypted File System (EFS) through the EFS.SYS driver. Note that the EFS driver is not a filter (despite descriptions in some earlier documentation), but a driver that is tightly bound to NTFS. EFS support in NTFS uses the following FSCTLs:.. FSCTL_ENCRYPTION_FSCTL_IO, FSCTL_READ_RAW_ENCRYPTED, FSCTL_SET_ENCRYPTION and FSCTL_WRITE_RAW_ENCRYPTED New file systems are not required to support these FSCTLs However, file system filters should allow them to pass through to NTFS unless they wish to explicitly override support for EFS . IF fsctl_encryption_fsctl_io and fsctl_set_encryption is overridden, MOST OF THE EFS-Related Apis Should Also Be Overridde n. These APIs encrypt the FSCTL input parameters. The user context must be present in all Create IRPs, or else EFS will fail to open encrypted files. Thus your filter should not post a Create IRPs unless the IRP contains a valid Security_Context. Some current filter drivers incorrectly attempt to open an encrypted file in the local system context while blocking the normal open request from the application; this happens for every open request from the application This incorrect behavior can dramatically decrease system performance The correct behavior is for the driver.. To attempt to open the encrypted file only in the user's context. if the file cannot be opened in the user '
s context, that file should be skipped. All file system filter drivers should be tested with EFS files. Good filter behavior Your driver should not return STATUS_PENDING in response to IRP_MJ_CREATE. However, if a lower-level driver returns STATUS_PENDING, your driver should pass this status value up the driver chain. If your file system filter driver was based on sFilter, be sure to study the updated sFilter sample in the Win2000 IFS Kit. A number of fixes and other changes have recently been applied to that sample that you should also make to your own driver code Following are some of the more important ones Note:.. These changes were made to correct omissions in the original sFilter sample, and do not reflect changes in Windows 2000. • IRP STATUS_PENDING values must be faithfully passed up The Driver Chain, or else Irp Processing Will HANG. This is Normal Done by Calling Iomarkirppending from your Driver's Completion Routine. thus the follter's comp Leion Routine: IF (IRP-> PendingReturned)
{
Iomarkirppending (IRP);
}
• All entry points should check for and handle the driver's primary device object. A filter driver can receive IRPs for files on an underlying file system, but it can also receive IRPs that specify the device object that belongs to the filter driver. A device object handle can be obtained by opening up the driver itself in the name space. (Previous versions of sFilter did not handle this case, thus causing an access violation in utilities such as objDir.) • If a file system driver load fails, your filter driver should delete any resources or synchronization objects that it has acquired, including memory, spinlocks, and mutexes. (Previous versions of sFilter did not delete the FsLock resource, thus causing corruption of the system-wide resource list.) STATUS_REPARSE Windows 2000 introduces reparse points , Which Notify A File System Filter WHEN A File Is Opened. A File's Reparse Tag That Identifies The Filter Driver To Be Notified by File Is Opened. r eparse points can be created and used via the FSCTLs such as FSCTL_DELETE_REPARSE_POINT, FSCTL_GET_REPARSE_POINT, and FSCTL_SET_REPARSE_POINT. (These are documented in the Platform SDK.) A file can have at most one reparse point attached to it. If you choose to use reparse points, you will need to plan and test for interoperability with Remote Storage, SIS, volume mount points, and directory junctions, all of which use reparse points. you will also need to apply for a reparse tag value. (These are assigned by Microsoft. for Information on now Obtain One for your product, see http:
//www.microsoft.com/whdc/devtools/ifskit/reparse.mspx.) CNSS The Native Structured Storage (NSS) implementation within OLE Structured Storage has been removed from Windows 2000. For this reason, the CNSS.SYS filter has also been removed from the Windows 2000. It will not be a released feature of Windows 2000. Remote Storage Remote Storage is the hierarchical storage management (HSM) service for NTFS in Windows 2000. It migrates least-recently-used (LRU) files from local disk to near-line media. When files are migrated, Remote Storage makes them sparse, so their sizes are reported correctly, yet they consume no media space. When a file is needed by the user, it is restored to local disk, unless the file open mode is set to FILE_FLAG_OPEN_NO_RECALL, in which case it is accessed directly from near-line media. File system filter drivers should be layered above Remote Storage. Remote Storage uses last-access dates on files to determine which ones to migrate to near- Line Media. if Your Drive r makes arbitrary changes to these dates (for example, when scanning volumes), Remote Storage can not provide true LRU migration, because the last-access date will no longer reflect actual user file access. Thus, if your driver must touch files, it should PRESERVE LAST-Access Dates on Those Files if at all Possible. Remote Storage Uses The Following Fsctls, Which Your Driver Should Allow To Pass Through unciVhange
FSCTL_HSM_MSG and FSCTL_HSM_DATA (used for private communication) and FSCTL_RECALL_FILE (used to force a file to be recalled from the migrated store). Be sure to test your drivers for interoperability with Remote Storage. Single Instance Store (SIS) Single Instance Store (SIS) is a file system filter driver that conserves disk space by removing multiple copies of a file and replacing them with links to a single shared copy in a common folder. These links differ from hard links in that if one copy of the file is changed, it Then "splits off"
from the others and becomes a separate file. SIS, which is installed only as part of Windows 2000 Remote Installation Services (RIS), uses two FSCTLs for private communication (FSCTL_SIS_COPYFILE and FSCTL_SIS_LINK_FILES), which your filter driver should allow to pass through unchanged. You should layer your file system filter driver above SIS. Be sure to test your drivers for interoperability with SIS. use of Associated IRPs File system drivers that use associated IRPs should create them only for master IRPs that are not themselves associated IRPs. Before creating associated IRPs for an IRP that is received from an upper-level driver, the file system driver should first make sure that this IRP does not have the IRP_ASSOCIATED_IRP flag set. If this flag is set, the driver should either not use associated IRPs for this request , or create a new master Irp and use it to create the associated Irps if The request neseds to be brokeen up. If the master irst is queueued inNternal and is cancelabl e, it is the driver's responsibility to let its cancel routine cancel the associated IRPs if necessary. One way to ensure that the master IRP does not complete automatically when the associated IRPs complete is to increment the AssociatedIrp.IrpCount field. This technique might be useful When Queuing Cancelable Master IRPS INTERLY.TOP OF Page
Media-based file system issues
DO_LOW_PRIORITY_FILESYSTEM This flag was introduced to force the correct scan order between UDFS and CDFS. CDFS sets this flag in DeviceObject-> Flags to indicate that CDFS is a low-priority file system, so it will get to recognize media after UDFS (which does not SET this flag.
Top of page
Redirector Issues
FSCTLS The Microsoft Windows 2000 network redirector now permits most FSCTLs to pass through. However, LAN Manager servers permit FSCTL_DELETE_REPARSE_POINT, FSCTL_GET_REPARSE_POINT, and FSCTL_SET_REPARSE_POINT to pass through only for Admin users. INF File Format All redirectors need to use the new INF format for installation and Setup. for more information, See Part 1, Section 4.1, "Network INF Files" in The Windows 2000 DDK Network Drivers Design Guide.top of Page
General OS Environment Changes, INVIRONMENT CHANGES
Clustering See FSCTL_DISMOUNT_VOLUME above. Oplocks There is now limited documentation on opportunistic locks (also called oplocks) in the Platform SDK. (See Base Services-> Files and I / O-> File Systems-> Shared File System Features-> Opportunistic Locks. ) Take extra care to handle OpLocks correctly. Some new system components, including the Content Indexer, will hang otherwise. Entry Points for IOCTLs / FSCTLs In Windows NT 4.0, the following FSCTLs were delivered via IRP_MJ_FILE_SYSTEM_CONTROL, and all others delivered via IRP_MJ_DEVICE_CONTROL.FSCTL_LOCK_VOLUME
FSCTL_UNLOCK_VOLUME
FSCTL_DISMOUNT_VOLUME
FSCTL_MOUNT_DBLS_VOLUME
FSCTL_GET_COMPRESSION
FSCTL_SET_COMPRESSION
FSCTL_READ_COMPRESSION
FSCTL_WRITE_COMPRESSION
In Windows 2000, this explicit list has been replaced by a more generalized check to see ifdwIoControlCode >> 16 == FILE_DEVICE_FILE_SYSTEM. Implementations that send private IOCTLs from user mode to their file system drivers and expect to receive them in the IRP_MJ_DEVICE_CONTROL path will be affected by this change, because these IOCTLs will now be delivered via the IRP_MJ_FILE_SYSTEM_CONTROL path. A possible solution for drivers that need to run on both Windows NT 4.0 and Windows 2000 is to case on the IOCTL number in both paths and call a common routine. Stack sizes Windows 2000 kernel stack sizes are the same as for Windows NT 4.0. On x86, the kernel stack size is 12 KB. On Alpha, it is 16 KB. Content Indexing Service The Windows 2000 Content Indexing Service makes extensive use of NTFS features, Including Oplocks, Change Journals, And Sparse Streams. Be aware triams (for Example, When Scanning Volumes) Interferes with the Remote Stora ge service, and might also interfere with the Content Indexing Service. Be sure to test your drivers for interoperability with these services. Backup / Restore Like the Content Indexing Service, NTBackup makes extensive use of file system features. In addition, NTBackup can now back up to a file. Be sure to test your file system as both a source and a destination for backup and restore. Driver code is read only in Windows 2000, all kernel-mode drivers are executed in read-only memory. Attempting to write to A Read-Only Memory Segment Causes Bug Check 0xbe To Be Issued. for More Information, See "Read-Only Memory Protection" in The Windows 2000 DDK Driver Writer '
s Guide Physical Location of Logical Volumes Windows 2000 introduces two new disk IOCTLs:.. IOCTL_STORAGE_GET_DEVICE_NUMBER and IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS These IOCTLs are used as follows: To get information about the physical location of a disk partition or other logical volume, the driver should issue an IOCTL_STORAGE_GET_DEVICE_NUMBER request . If this request fails, the drivers should then issue an IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS request. These new IOCTLs are defined in the DDK header files ntddstor.h and ntddvol.h. For more information, see Part 3, Section 7.3, "Disk I / O Control Codes "in the Windows 2000 DDK Kernel-Mode Driver Reference Note:. These IOCTLs are not supported in Windows NT 4.0 Driver Verifier Windows 2000 (B3RC0 and later) introduces Driver Verifier, a tool that monitors one or more kernel-mode drivers to. Verify That They Do Not Issue Any Illegitimate Function Calls. This New Tool Uncovers Many Problems That Might Otherwise Remain Hidden Despite Exha ustive stress testing. Driver Verifier can be run as a Windows 2000 application (called the "Driver Verifier Manager"), as an MS-DOS command, or as a debugger option in WinDbg. For more information, see "Testing Drivers" in the Windows 2000 DDK Driver Writer's Guide. Testing with Driver Verifier is likely to become a Windows Logo requirement in the near future. Special Pool Special Pool is a new feature for quickly locating memory corruption bugs that was introduced in Windows NT 4.0 Service Pack 4 and Windows 2000 Beta 2. Special Pool Can Be Used Alone (See Knowledge Base Article Q192486) OR TOGETHER WITH DOCUMER (See The Driver Verifier Documentation In The Windows 2000 DDK Driver Writer)
s Guide). Testing with Special Pool is likely to become a Windows Logo requirement in the near future. Windows File Protection (WFP) In Windows 2000, a new feature called Windows File Protection (WFP) automatically restores monitored system files if they are overwritten by non-operating system installation programs or if their contents are modified by (for example) file system filters such as anti-virus utilities. This means that drivers are no longer permitted to modify files at will. Instead, they must first call SfcIsFileProtected to determine if a file is covered by WFP If it is, the file should not be modified.. (Note: SfcIsFileProtected is a user-mode function It has no kernel-mode equivalent..) SfcIsFileProtected is implemented in SFC.DLL and declared in Sfc.h. IT IS prototyped as flollows: boolwinapi
Sfcisfileprotacected
In Handle Rpchandle, // Must Be Null
In lpcwstr protefilename
);. SfcIsFileProtected returns TRUE if the file ProtFileName is protected by Windows File Protection The list of files protected by WFP is subject to change (for example, when a Service Pack or Hot-fix is installed) If this information is cached, make. sure that your driver updates the cached list after a Service Pack or Hot-fix is installed. For detailed information about Windows File Protection, see http://www.microsoft.com/whdc/winlogo/drvsign/wfp.mspx.
