Potential issues involved in updating Windows NT IFS drivers to Windows 2000_potential implementations with weaker access privi-CSDN博客

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 they should consider. Some of the issues referred to in this checklist are undocumented at 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.

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 IoGetRelatedDeviceObject. Unfortunately, the change impacts a small number of drivers (primarily file system filter drivers) 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 IoGetRelatedDeviceObject on a file object that represents 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 that call IoGetDeviceObjectPointer. Such drivers should pass the appropriate access mask value in that routine's DesiredAccess parameter. 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.
KeStackAttachProcess	The KeAttachProcess kernel routine is exported 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 routine that can be used to notify registered applications of the following volume lock and mount events: FSRTL_VOLUME_DISMOUNT FSRTL_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 CANCEL_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_QUOTA IRP_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	There is a new rule for ObReferencing 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 as 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 behavior.
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 or on for a 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.
MdlReadCompleteCompressed MdlWriteCompleteCompressed	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. This 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 unless 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 are overridden, most of the EFS-related APIs should also be overridden. 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 normally done by calling IoMarkIrpPending from your driver's completion routine. Thus the following code has been added to SFilter's completion 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 point contains a 32-bit reparse tag that identifies the filter driver to be notified when the file is opened. Reparse 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 how to 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 driver makes arbitrary changes to these dates (for example, when scanning volumes), Remote Storage cannot 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 unchanged: 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 needs to be broken up. If the master IRP is queued internally and is cancelable, 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 internally.

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

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 that arbitrarily changing last-access dates on files (for example, when scanning volumes) interferes with the Remote Storage 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 exhaustive 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 Driver Verifier (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 follows: BOOL WINAPI SfcIsFileProtected( IN HANDLE RpcHandle, //must be NULL IN LPCWSTR ProtFileName ); 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.