Chapter 1 Storage Drivers

Transcription

1 1.0 Storage Drivers Page 1 of 79 Chapter 1 Storage Drivers This chapter contains the following information: 1.1 Storage Driver Architecture 1.2 Storage Drivers and Device Objects 1.3 System Header Files for Storage Drivers 1.4 Restrictions on Storage Drivers in the Paging Path Subsequent chapters contain guidelines for designing the following kinds of Windows NT kernelmode storage drivers: An operating system-independent miniport driver for a vendor-specific SCSI HBA (see Chapter 2) A miniport driver for a non-scsi storage adapter (see Chapter 2) A class driver for a new type of peripheral device (see Chapter 3) An operating system-independent tape miniclass driver for a vendor-specific tape device (see Chapter 4) A changer miniclass driver for a vendor-specific medium changer device (see Chapter 5) A filter driver for a peripheral device of a type that already has a class driver (see Chapter 6) 1.1 Storage Driver Architecture Windows NT /Windows 2000 class and filter drivers for peripheral storage devices act as an interface between any intermediate or highest level drivers layered above the class or filter driver and a system-supplied port driver. I/O requests from a user application or kernel component reach storage class drivers through Windows NT/Windows 2000 I/O System Services and one or more intermediate or highest level drivers, such as a file system driver. Storage class drivers translate the standard IRPs they get into IRPs with system-defined SCSI request blocks (SRBs) containing SCSI-2 command descriptor blocks (CDBs) before sending each IRP on to the next lower driver. A storage port driver translates SRBs from class drivers into bus-specific commands which it sends to the storage HBA, through an I/O bus driver and possibly one or more filter drivers. Figure 1.1 shows the layered architecture of Windows NT/Windows 2000 storage drivers.

2 1.0 Storage Drivers Page 2 of 79 Figure 1.1 Windows NT/Windows 2000 Storage Driver Architecture Starting from the bottom of the figure, the following describes each type of storage driver: 1. A storage port driver defines an interface to all Windows NT storage class drivers, including the system-supplied disk, tape, CDROM, DVD, and changer class drivers. This port/class interface insulates class drivers from adapter-specific requirements of the host bus adapter to which their respective devices are connected. A storage port driver also synchronizes access to the bus for all drivers of devices on the corresponding HBA. The system supplies storage port drivers for SCSI, IDE, and IEEE 1394 adapters. A storage port driver receives SRBs from the next higher driver (a storage class driver or intervening filter driver) and processes them as follows: ϒ The storage port driver for a SCSI bus passes SRBs with CDBs on to an operating system-independent, HBA-specific SCSI miniport driver, which is dynamically linked to the SCSI port driver and provides hardware-specific support for a particular SCSI HBA. For information about implementing a SCSI miniport driver, see Chapter 2. ϒ The storage port driver for an IDE/ATAPI or IEEE 1394 bus translates the SRBs received from the storage class driver into the format required by the underlying adapter for example, repackaging CDBs according to a bus-specific transport protocol, or translating them into a different format, thereby insulating upper level drivers from peculiarities of the underlying bus. 2. An upper or lower storage filter driver supports device-specific functionality not provided by a system-supplied storage class driver. A lower filter storage driver monitors SRBs and/or IRPs issued by a storage class driver and modifies them as needed before passing them to the next lower driver (a storage port driver or another storage filter driver).

3 1.0 Storage Drivers Page 3 of 79 For information about implementing a storage filter driver, see Chapter A storage class driver uses the well-established SCSI port/class interface to control a device of its type on any bus for which the system provides a storage port driver. A class driver is specific to a particular class of device for example, one class driver can run all CD-ROM devices on any supported bus; another can control all disk devices. The storage class driver handles I/O requests from user applications or higher level drivers by building SRBs containing CDBs and issuing those SRBs to the next lower driver (a storage port driver or intervening filter driver), just as if the device were a SCSI device. The implementation of a storage class driver is transparent to upper level drivers. A class driver for a tape or medium changer device is implemented as a device-specific miniclass driver that links to a system-supplied class driver. System-supplied class drivers for other storage devices, such as disk and CD-ROM/DVD, are implemented as single monolithic drivers. For information about implementing a storage class driver, see Chapter 3. For information about implementing a tape or changer miniclass driver, see Chapter 4 and Chapter 5, respectively. 4. An upper filter storage driver intercepts IRPs from user applications and still higher level drivers and might modify them before passing them to the next lower driver (a storage class driver or another storage filter driver), or might monitor performance of the underlying device. The type of bus to which a device is attached and the implementation of its storage port driver are transparent to upper level drivers. A storage port driver might be implemented according to the port/miniport architecture, like the SCSI port driver; as a monolithic driver that controls a single, standard piece of hardware, such as the IDE/ATAPI port driver; or as a filter driver that translates SRBs into the format required by a different driver stack, such as the IEEE 1394 port driver. The system-supplied SCSI port driver can also act as an interface between a storage class driver and a SCSI miniport that controls a nonscsi storage device of the same type. For example, rather than writing a standard Windows NT driver for a new disk-array controller, a driver writer can save considerable design, development, and debugging effort by writing a pseudoscsi miniport driver that links to the system SCSI port driver and uses the interface it provides. Such a miniport is required to translate incoming SCSI commands into device-specific commands and support higher level Windows NT drivers as if it were a SCSI HBA miniport. On the other hand, the system-supplied port and class drivers handle much necessary work on such a pseudoscsi miniport's behalf, including registry accesses during initialization, all resource and object allocations, synchronization, presizing requested transfers to suit the capabilities of the miniport's device, and retrying requests. For more detailed information about SRBs, see the Kernel-Mode Driver Reference. For device-typespecific information about CDBs, consult the ANSI X X SCSI-2 standard. 1.2 Storage Drivers and Device Objects

4 1.0 Storage Drivers Page 4 of 79 The storage device stack consists of a tree of device objects created by the drivers that are involved in handling I/O to storage devices on the system. The root of this tree is a functional device object (FDO) for a storage adapter or for another driver stack integrated with the storage stack. The leaves of this tree are device objects for use by file systems and user-mode applications. Like any PnP driver, a storage class or storage filter driver adds itself to the tree in its AddDevice routine by creating a device object with IoCreateDevice and attaching it to the device stack with IoAttachDeviceToDeviceStack, using the pointer to the device object passed to the driver's AddDevice routine by the PnP Manager at initialization. IoAttachDeviceToDeviceStack attaches the new device object to the current top of the device stack. A tape miniclass, medium changer miniclass, or SCSI miniport driver is not required to create a device object and attach it to the device stack. Instead, the system-supplied tape class, changer class, or SCSI port driver handles these tasks on behalf of the miniclass/miniport, calling miniclass/miniport routines to gather the data needed to create the device object. For information about designing PnP drivers, see the Setup, Plug and Play, and Power Management Design Guide. For information about PnP-related IoXxx routines, see the Setup, Plug and Play, and Power Management Reference Device Object Example for a SCSI HBA Figure 1.2 shows the device objects that are created for system with a PCI IEEE 1394 controller and a PCI SCSI adapter with a CD-ROM and partitionable disk device attached. Objects for devices attached to the IEEE 1394 controller are shown and described in Section

5 1.0 Storage Drivers Page 5 of 79 Figure 1.2 Device Object Tree for CD-ROM and Disk Devices on a SCSI HBA Starting from the bottom of the figure, the following describes each device object and its associated driver: 1. The storage bus driver creates the FDO for the storage bus and attaches it to the storage bus PDO created by the PnP Manager (not shown in this figure). The structure of the device object tree below the storage bus FDO depends on the storage bus and how it is integrated into the system. Storage drivers above the port driver level do not interact with any of these lower objects. Figure 1.2 shows the storage bus FDO created by the PCI bus driver for a system with a PCI bus. 2. The PCI bus driver enumerates and creates a PDO for each storage adapter on its bus. The corresponding storage port driver creates an FDO and attaches it to the PDO for its adapter. Figure 1.2 shows two adapter PDOs: one for an IEEE 1394 controller (described in Section 1.2.2) and another for a SCSI HBA. The SCSI port driver and an associated miniport create an FDO and attach it to the SCSI adapter PDO. 3. The storage port driver virtualizes target devices by creating a PDO for each target device attached to its adapter. Figure 1.2 shows two such PDOs created by the SCSI port/miniport drivers: one for a hard drive and one for a CD-ROM. 4. One or more filter drivers can attach a filter device object (filter DO) to a target device PDO exported by a storage port driver. Such a filter driver can intercept and alter requests sent by the class driver to the target device, for example, to work around device-specific problems without requiring hardware-specific changes to the generic class or port drivers. Figure 1.2 shows a filter DO attached by a CD audio filter driver to the CD-ROM's PDO. 5. A storage class driver creates an FDO and attaches it to next lower device object, which is either a target device PDO exported by a storage port driver or a filter DO attached to the stack by an intervening filter driver. The class driver issues all subsequent requests to the storage

6 1.0 Storage Drivers Page 6 of 79 device through the lower driver's device object. Figure 1.2 shows two such FDOs: one that represents a CD-ROM device, and one that represents Partition 0 of a hard drive. Partition 0 represents the entire raw disk, and always exists whether the drive is partitioned or not. 6. A class driver can also act as a bus driver, returning a list of PDOs when the PnP Manager queries for its child devices (IRP_MN_QUERY_DEVICE_RELATIONS with BusRelations). For example, a driver of a partitioned media device such as a removable disk might return a list of PDOs representing its partitions. Higher level drivers attach FDOs to these PDOs. Figure 1.2 shows three such PDOs, each representing a disk partition that can be addressed as a target device. In the case of a fixed disk, the partition manager attaches to the FDO that represents Partition 0 and handles PnP operations on behalf of all partitions. The activities of the partition manager are transparent to the disk class driver and any upper level filter drivers. 7. One or more filter drivers can be attached above a class driver. Unlike a lower level filter driver, an upper level filter driver intercepts IRPs sent to the class driver, and can alter them before forwarding them to next lower device object. The filter driver can intercept any readwrite requests and transform the data as necessary, as well as define additional I/O control codes (IOCTLs), for example, to enable a user application to supply passwords or other related information. Figure 1.2 shows a filter DO created by a disk-encryption filter driver and attached to the disk PDO for partition Device Object Example for an IEEE 1394 Controller Figure 1.3 shows the device objects that are created for system with a PCI IEEE 1394 controller with an IEEE 1394 CD-ROM attached. Device objects for devices attached to the SCSI adapter are described in Section

7 1.0 Storage Drivers Page 7 of 79 Figure 1.3 Device Object Tree for a CD-ROM Device on an IEEE 1394 Controller Starting from the bottom of the figure, the following describes each device object and its corresponding driver: 1. For a description of the device tree from the storage bus FDO up to the adapter PDOs, see Section The highest driver in the IEEE 1394 driver stack creates an SBP2 disk device PDO. The IEEE 1394 driver stack ultimately issues SBP2 commands to the target CD-ROM device on the IEEE 1394 bus. 3. The system-supplied IEEE 1394 storage port driver is implemented as a filter driver that creates a filter DO and attaches it to the SBP2 disk device PDO. The IEEE 1394 storage port driver translates SRBs from the CD-ROM class driver into SBP2 commands which are issued to the underlying IEEE 1394 driver stack. The interface this driver presents to higher level storage drivers is identical to that presented by the SCSI port/miniport driver described in Section The CD-ROM class driver creates an FDO and attaches it to the next lower device object, which is either the SBP2 port filter DO or another filter DO attached to the stack by an intervening filter driver. The class driver issues all subsequent requests to the device through the lower driver's device object Device Object Example for a PCI IDE Controller Figure 1.4 shows the device objects that are created for a system using a PCI IDE controller that has two IDE disks attached to one channel and an IDE CD-ROM attached to the other.

8 1.0 Storage Drivers Page 8 of 79 Figure 1.4 Device Object Tree for CD-ROM and Disk Devices on an IDE controller Starting from the bottom of the figure, the following describes each device object and its associated driver: 1. The PCI bus driver creates an FDO for the PCI bus and attaches it to the PCI bus PDO created by the PnP Manager (not shown in this figure). 2. The PCI bus driver enumerates the adapters and controllers on its bus, including all the IDE controllers, and creates a PDO for each one. 3. The IDE controller driver, together with its IDE controller minidriver, create an FDO and attach it to the PDO for the controller. 4. The IDE controller driver "enumerates" the controller's channels. In effect, this means that it creates two PDOs, one for each of the controller's channels, and that it attaches both channel PDOs to the controller FDO. 5. The IDE channel driver creates an FDO and attaches it to the PDO for the channel. 6. The IDE channel driver enumerates the devices on its channel and creates a PDO for each device. Figure 1.3 shows three such PDOs that were created by the IDE channel driver: two hard drive PDOs that were created by the channel driver for the controller's first channel, and a CD-ROM PDO that was created by the channel driver for the controller's second channel. 7. The disk class driver creates an FDO and attaches it to the associated disk PDO, exactly as in the case of the SCSI, and the CD-ROM driver creates an FDO and attaches it to the associated

9 1.0 Storage Drivers Page 9 of 79 CD-ROM PDO. As in the case of the SCSI, a filter driver DO can be inserted between the device PDO and the device FDO. Figure 1.3 illustrates this using a CD Audio Filter DO that can be optionally placed just above the CD-ROM PDO. 1.3 System Header Files for Storage Drivers The system-supplied storage drivers include the header file scsi.h, which contains SCSI-2-compliant definitions for CDBs and other structures used by most SCSI-2-compliant drivers. This header file includes srb.h, which defines the interfaces provided by the system-supplied port drivers to higher level storage class and filter drivers. System-supplied class and filter drivers also can include the header file classpnp.h so they can call the ClassXxx routines provided by classpnp.c. The Windows 2000 DDK provides classpnp.h and classpnp.c as sample source code. However, classpnp.c should not be considered a system-supplied library for all future storage class drivers. Both classpnp.h and classpnp.c are subject to change without notice. operating system-independent SCSI miniport drivers, which can be designed to run both with all platforms of Microsoft Windows NT /Windows 2000 and with x86-only Microsoft Windows systems, include the system-supplied header files miniport.h and scsi.h, which includes srb.h. Tape miniclass drivers include minitape.h. Medium changer miniclass drivers include mcd.h. 1.4 Restrictions on Storage Drivers in Paging Path A driver is in the "paging path" if it participates in I/O operations on the paging file. To prevent deadlock, the I/O routines of such drivers (DispatchRead, DispatchWrite, and DeviceControl routines) must not contain pageable code, and they must never attempt to access pageable memory. In the case of storage drivers, I/O and DeviceControl routines must never contain pageable code, even if the storage driver is not in the paging path. This is because I/O and DeviceControl routines can be called at IRQL > PASSIVE_LEVEL, and the in-paging I/O that services a page fault takes place at IRQL = APC_LEVEL. By default, the code for kernel-mode drivers is not pageable, nor is the global memory used by

10 1.0 Storage Drivers Page 10 of 79 kernel-mode drivers pageable. If a driver routine does no I/O and runs at IRQL = PASSIVE_LEVEL, as is the case with routines such as DriverEntry, Reinitialize, and Unload, then its code can be made pageable by means of the #pragma_alloc_text() compiler directive. It can then be locked and unlocked dynamically at run-time by calling memory manager routines MmLockPagableCodeSection () and MmUnlockPagableImageSection() (See MmLockPagableCodeSection and MmUnlockPagableImageSection for a discussion of these routines and for a discussion of the #pragma_alloc_text() directive). Chapter 2 SCSI Miniport Drivers This chapter contains the following information: 2.1 Supporting Plug and Play in a SCSI Miniport Driver Registry Entries for Plug and Play SCSI Miniport Drivers SCSI Miniport Initialization Under Plug and Play Converting a Windows NT 4.0 SCSI Miniport for Plug and Play 2.2 Required and Optional SCSI Miniport Routines 2.3 SCSI Miniport Driver's DriverEntry Routine Calling ScsiPortInitialize Storage Driver's Return from DriverEntry 2.4 SCSI Miniport Driver's HwScsiFindAdapter Routine Calling ScsiPortXxx from HwScsiFindAdapter Port-Driver-Supplied ConfigInfo for HwScsiFindAdapter Setting up ConfigInfo in HwScsiFindAdapter Setting Again and Returning from HwScsiFindAdapter Returning Control from HwScsiFindAdapter 2.5 SCSI Miniport Driver's HwScsiInitialize Routine 2.6 SCSI Miniport Driver's HwScsiStartIo Routine

11 1.0 Storage Drivers Page 11 of Modifying SRBs Handling SRB_FUNCTION_EXECUTE_SCSI Handling SRB_FUNCTION_ABORT_COMMAND Handling SRB_FUNCTION_RESET_BUS Handling SRB_FUNCTION_RESET_DEVICE Handling SRB_FUNCTION_FLUSH and SRB_FUNCTION_SHUTDOWN Handling SRB_FUNCTION_IO_CONTROL Handling SRB_FUNCTION_WMI Handling Unsupported SRB_FUNCTION_XXX Return from HwScsiStartIo Other SRB_FUNCTION_XXX Requests 2.7 SCSI Miniport Driver's HwScsiDmaStarted Routine 2.8 SCSI Miniport Driver's HwScsiResetBus Routine 2.9 SCSI Miniport Driver's HwScsiInterrupt Routine Deferring Interrupt-Driven I/O from HwScsiInterrupt SCSI Miniport Driver's HwScsiEnableInterruptsCallback Routine SCSI Miniport Driver's HwScsiDisableInterruptsCallback Routine 2.10 SCSI Miniport Driver's HwScsiTimer Routine 2.11 SCSI Miniport Driver's HwScsiAdapterState Routine 2.12 SCSI Miniport Driver's HwScsiAdapterControl Routine 2.13 Error Handling in SCSI Miniport Drivers Windows NT /Windows 2000 SCSI miniport drivers are HBA-specific but operating systemindependent. That is, each miniport driver links itself with the system-supplied SCSI port driver, which is a dynamic-link library (DLL), and calls only the port driver's ScsiPortXxx routines to communicate with the system and its HBA. Such SCSI miniport drivers run on other Microsoft operating systems that support Win32 applications and also export the ScsiPortXxx routines.

12 1.0 Storage Drivers Page 12 of 79 Note that any SCSI miniport driver that calls routines other than the ScsiPortXxx cannot run in both Microsoft operating system environments. To remain portable across Microsoft Windows systems, including Windows NT/Windows 2000, SCSI miniport drivers must call only the system-supplied ScsiPortXxx. A SCSI miniport can be a Plug and Play driver, or it can run as a legacy driver that does not participate in Plug and Play operations such as resource redistribution or power management. The primary differences between a Plug and Play and a legacy miniport driver are the order in which initialization routines are called and enforcement of certain restrictions that were applied to miniports in Windows NT 4.0 but not enforced. 2.1 Supporting Plug and Play in a SCSI Miniport Driver Although Windows 2000 is a Plug and Play operating system, by default SCSI miniports are run as legacy drivers. The HBA for a legacy miniport driver cannot be removed from the system while it is running, nor are legacy miniports automatically detected when added to a running system. These limitations might be acceptable for certain HBAs, but SCSI miniports for PCMCIA/CardBus HBAs and HBAs in laptops should support Plug and Play. A Plug and Play miniport must implement an HwScsiAdapterControl routine to stop and manage power to the HBA. No additional routines are required of a Plug and Play miniport driver to accommodate changes in driver initialization. The SCSI port driver creates PDOs for target devices and the FDO for the miniport driver, and handles AddDevice, StartDevice, and UnloadDevice requests on a Plug and Play miniport driver's behalf. For general information about Plug and Play drivers, see the Setup, Plug and Play, and Power Management Design Guide Registry Entries for Plug and Play SCSI Miniport Drivers To support Plug and Play, a SCSI miniport driver must: Be installed as a service for the HBA. Have a PnPInterface entry in the registry that indicates the interfaces for which the miniport supports Plug and Play.

13 1.0 Storage Drivers Page 13 of 79 Installing a miniport driver as a service for a SCSI HBA is customarily done by providing an INF file that matches the Plug and Play hardware ID for a given HBA to the correct driver to control that device. For details about setting up an INF file, see the Setup, Plug and Play, and Power Management Design Guide. Unless a miniport driver is installed as a service for an HBA, the PnPInterface registry entry will prevent the miniport from initializing. The specified interfaces are initialized only when Plug and Play locates an appropriate HBA. If no service is properly assigned to the HBA, Plug and Play will never determine which driver to notify when it detects the device. This behavior is by design and a miniport should not attempt to circumvent it. The PnPInterface registry entry should be made under the Services key for the miniport. For example, the following registry entry enables Plug and Play for a fictitious miniport driver called Twiddle. HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services \Twiddle \Parameters \PnpInterface 5 : REG_DWORD : 1 1 : REG_DWORD : 1 2 : REG_DWORD : 1 8 : REG_DWORD : 1 The values preceding REG_DWORD correspond to the INTERFACE_TYPE enumerated type declared in miniport.h. The values in this example indicate that the Twiddle miniport supports Plug and Play for the following interfaces: PCIBus (5), Isa (1), Eisa (2) and PCMCIABus (8). The value following REG_DWORD is a flag that indicates Plug and Play support for the interface. (Currently, this flag can be any value but must be present. In the future, the flag may be optional.) After the PnPInterface values are set in the registry and the system is restarted, the miniport driver can be initialized as a Plug and Play driver. During initialization, the SCSI port driver checks the registry to determine whether the miniport should be run as a Plug and Play or legacy driver. The SCSI port driver checks the registry for each interface type that the miniport supports (PCI, ISA, etc.). This is intended primarily to simplify debugging for writers of multiple-interface miniport drivers. The miniport driver writer should make sure that a miniport driver is capable of being run as a Plug and Play driver for all interfaces that driver supports SCSI Miniport Initialization Under Plug and Play For Windows 2000, a legacy miniport is initialized in exactly the same way as for Windows NT 4.0. When a legacy miniport calls ScsiPortInitialize, the port driver calls the miniport to locate and initialize its HBA. This is done either once for each HBA it finds (if the HBA is on an enumerable bus) or repeatedly until the miniport reports that it cannot find any more devices. Control then returns to the miniport's DriverEntry routine, where the miniport can call ScsiPortInitialize again for a

14 1.0 Storage Drivers Page 14 of 79 different type of HBA (for example, a different interface or a different vendor and product ID). All of the initialization calls are made within the context of the miniport's DriverEntry routine and are made in the order that ScsiPortInitialize was called. Initialization of legacy drivers occurs at system startup and at no other time. Under Plug and Play, the order of initialization cannot be preserved. When a miniport driver that is enabled for Plug and Play calls ScsiPortInitialize, the port driver stores the initialization data for future reference, then returns STATUS_SUCCESS. This is done for each interface type that is listed in the miniport's PnPInterface registry key any interfaces not listed in that key are still initialized immediately. Later, when the Plug and Play Manager detects an HBA for the miniport, it notifies the port driver. The port driver allocates the necessary system resources (such as memory for the miniport's device extension) and calls the miniport to find the HBA and then to initialize it. This usually happens during system startup, but it might also happen when the system detects a docking operation or when an HBA such as a PCMCIA card is hot-plugged into the system. By the time the Plug and Play Manager reports a device, it has already allocated bus resources (such as I/O ports, memory addresses, and interrupts) for that device and that device alone. These resources are supplied to the miniport, which must either use these resources or report that no device was found. In particular, the miniport must not attempt to access ports or memory locations other than the ones specified to find a device. A miniport driver that has been started as a Plug and Play driver might be asked to detect devices that are on non-enumerable buses. This includes buses such as ISA, which require that the miniport issue commands on the bus to find its HBA. Devices located during such detection are recorded in the registry and initialized as Plug and Play devices the next time the system is started. For more information about Plug and Play, see the Setup, Plug and Play, and Power Management Design Guide Converting a Windows NT 4.0 SCSI Miniport for Plug and Play Even if a miniport driver has enabled Plug and Play in the registry, the driver will fault during initialization unless it honors certain restrictions in the use of the HwContext pointer and resources supplied by the port driver. A miniport might also fault during initialization if it depends on a predictable initialization order of drivers. In order to run successfully under Plug and Play, a Windows NT 4.0 miniport driver's source code might need to be modified as described in the following sections.

15 1.0 Storage Drivers Page 15 of Use the HwContext Pointer to HwScsiFindAdapter Correctly If a miniport's HwScsiFindAdapter receives nonzero access range values from the port driver, it must not use the HwContext pointer. Although this restriction also applied to version 4.0 miniports, nothing prevented such a miniport from using this pointer. If the miniport can be initialized as a Plug and Play driver in Windows 2000, it must not use the HwContext pointer because the SCSI port driver passes in a NULL pointer as the HwContext argument. How an existing miniport must be modified depends on how it currently uses HwContext. For example, if the miniport uses HwContext to maintain a count of HBAs (for example, to use in DebugPrint statements) an alternative might be to use the HwDeviceExtension pointer instead. HwDeviceExtension provides a unique number that is related to the particular HBA originating the DebugPrint message. (Using a global variable to store the HBA count is a bad practice, because miniport drivers should not use global variables to maintain state information.) As another example, if the 4.0 version of the miniport uses HwContext to communicate information about the type of device being initialized (such as information about the capabilities supported by a particular model of PCI HBA), the 5.0 version of the miniport might use ScsiPortGetBusData to get an identifier for the HBA, then use that identifier to search through a list of such parameter blocks to find the correct information. Another possible miniport modification might be to provide this information in a registry string passed in the ArgumentString parameter. The registry string could be set by the miniport's INF file during initialization to information that pertains to the model of card detected. This provides more flexibility than hardcoding the parameters in the miniport, because such a miniport could handle new models of cards using an updated INF file instead of requiring the miniport driver to be recompiled Do Not Depend on Order of SCSI Miniport Initialization Some miniport drivers support HBAs on several different system buses such as PCI, EISA, and ISA. Under Windows NT 4.0, such a miniport driver's HwScsiFindAdapter routine(s) were called in the order that the miniport called ScsiPortInitialize. In several cases, this was used to track the location of a card on one type of bus so the miniport could avoid detecting it on another. For example, assume the Twiddle PCI SCSI HBA is also accessible on the ISA bus. Under Windows NT 4.0, the Twiddle miniport would keep track of which PCI HBAs it was called to initialize and the ISA bus locations in which they appeared. The miniport could use this information while scanning the ISA bus to determine which I/O ranges to skip. Under Windows 2000, this technique is no longer dependable. Because Plug and Play makes

16 1.0 Storage Drivers Page 16 of 79 initialization order unpredictable, the Twiddle miniport could easily be called to scan for its ISA cards before initializing its PCI cards. The miniport would detect each PCI HBA twice, which could lead to a system crash. In this case, if the Twiddle HBA had a command that could be used to determine the real bus interface of the card, the ISA bus scan could query each card it found. If the card were a PCI card and not an ISA card, then the Twiddle miniport driver would leave it alone until Plug and Play issued requests to pick it up. If the order-dependent code of a miniport cannot be removed it must be run as a legacy driver on the Windows 2000 platform Use Only Supplied Resources in a Plug and Play SCSI Miniport One of the goals for a Plug and Play system is to reduce or eliminate the number of drivers that detect their devices by accessing known memory locations. This includes drivers that determine their resources by reading the configuration space for their HBA. Under Plug and Play, devices on enumerable buses are detected by the driver for the bus. This allows the bus driver to handle any resource conflicts, provide special-case fixes for broken bus and bridge parts, and so forth. Consequently, a SCSI miniport must use only the resources provided by the port driver (if any) in Windows 2000 systems. The miniport is allowed to scan the bus for an HBA only if the port driver passes in zero-value access ranges. If the miniport attempts to use resources that are not assigned to it, the ScsiPortGetDeviceBase call will fail. Calls to read and write device registers or ports that have not been properly mapped also might fail Verify Resource Ranges in HwScsiFindAdapter During Detection Although detection of devices by drivers is usually unnecessary under Plug and Play, the port driver might call a Plug and Play miniport's HwScsiFindAdapter routine to detect devices on a nonenumerable bus. Although this operation is similar to detection in Windows NT 4.0, the miniport must take care not to operate on ranges that might be in use by another device. The miniport should call ScsiPortValidateRange before calling ScsiPortGetDeviceBase to ensure that the miniport-supplied range is safe to use. The miniport must be prepared for ScsiPortGetDeviceBase to fail and return a NULL pointer. The miniport should also avoid mapping memory starting at address zero, which makes it impossible to detect the failure of ScsiPortGetDeviceBase on some systems.

17 1.0 Storage Drivers Page 17 of Required and Optional SCSI Miniport Routines Every SCSI miniport driver must have at least the following system-defined routines: DriverEntry to initialize the miniport driver HwScsiFindAdapter to determine how (or whether) driver-supported HBA(s) are configured in the machine HwScsiInitialize to initialize supported HBA(s) HwScsiStartIo to start operations on its HBA(s) for incoming requests HwScsiResetBus to handle bus-reset requests. Depending on each HBA and the driver designer, SCSI miniport drivers also have some or all of the following system-defined routines: HwScsiInterrupt to handle HBA-generated interrupts, which is optional if and only if the HBA does not generate interrupts so the miniport manages all I/O operations on its HBA by polling However, using polling exclusively has an adverse effect on a miniport's performance and on its HBA's I/O throughput. Such a miniport driver should also have a HwScsiTimer routine. HwScsiDisableInterruptsCallback and HwScsiEnableInterruptsCallback to handle deferred I/O processing if interrupt-driven I/O operations take a long time HwScsiTimer to time operations that require long delays on the HBA, or for any other purpose determined by the driver designer A miniport should have a HwScsiTimer routine if it has no HwScsiInterrupt routine so it can use the HwScsiTimer routine for efficient polling of its HBA. HwScsiDmaStarted, which is required if the HBA uses a system DMA controller, to set up an HBA transfer after the system DMA controller has been programmed by the port driver HwScsiAdapterState, which is optional if and only if the HBA has no BIOS or x86-real-mode driver and/or will never run in x86-only Microsoft Windows systems HwScsiAdapterControl, which is required if the miniport driver supports Plug and Play Each of the preceding miniport driver routines, except DriverEntry, has a name chosen to describe its functionality. Except for DriverEntry, which is a required name for every miniport's initial entry point, names for miniport driver routines can be anything the driver writer chooses. The following sections describe the requirements for and functionality of each of these miniport driver routines. See the Kernel-Mode Driver Reference for their formal definitions and descriptions of their parameters. Section 2.13 describes error-handling requirements for SCSI miniport drivers.

18 1.0 Storage Drivers Page 18 of SCSI Miniport Driver's DriverEntry Routine A DriverEntry routine is the initial entry point for most Windows NT kernel-mode drivers and for every SCSI miniport driver. A miniport's DriverEntry routine is called with two input arguments of type PVOID and must do the following: 1. Initialize a HW_INITIALIZATION_DATA structure on the stack with zeros. 2. Set the HwInitializationDataSize member to sizeof(hw_initialization_data). 3. Set driver-specific and HBA-specific values in the HW_INITIALIZATION_DATA members, including the miniport driver's entry points. The following entry points must be set: ϒ HwScsiFindAdapter ϒ HwScsiInitialize ϒ HwScsiStartIo ϒ HwScsiResetBus The following entry points can be set to a driver-supplied routine or must be set to NULL: ϒ HwScsiInterrupt (NULL if the miniport uses polling exclusively) ϒ HwScsiDmaStarted (NULL if the HBA uses PIO or is a busmaster) ϒ HwScsiAdapterState (NULL if the miniport runs only on Windows NT /Windows 2000 platforms or if it is designed to also run on x86-only Windows platforms but the HBA has neither a BIOS nor x86-real-mode driver) ϒ HwScsiAdapterControl (NULL if the miniport does not support Plug and Play) 4. In a legacy miniport driver, set up any driver-determined context data that the miniport's HwScsiFindAdapter routine will use. 5. Call ScsiPortInitialize with the pointers that were input to the DriverEntry routine, the address of the filled-in HW_INITIALIZATION_DATA, and the address of the context data, if any Calling ScsiPortInitialize If a miniport driver's HBA can be connected on more than one type of I/O bus, the miniport must call ScsiPortInitialize for each bus type and can have a different HwScsiFindAdapter routine for each bus type. After each call to ScsiPortInitialize, such a miniport driver must modify the AdapterInterfaceType member, modify the HwScsiFindAdapter member in the HW_INITIALIZATION_DATA if the miniport has a different HwScsiFindAdapter routine for that bus type, possibly modify the miniport-supplied context data for the new bus type, and call

19 1.0 Storage Drivers Page 19 of 79 ScsiPortInitialize for each type of bus on which a supported HBA might be connected. If the miniport is a legacy driver that does not support Plug and Play, ScsiPortInitialize calls the miniport's HwScsiFindAdapter routine one or more times before it returns control to the miniport's DriverEntry routine. All of the HwScsiFindAdapter calls are made in the context of the miniport's DriverEntry routine, in the order DriverEntry called ScsiPortInitialize. If the miniport supports Plug and Play, ScsiPortInitialize stores the initialization data for future use and returns STATUS_SUCCESS to the miniport's DriverEntry routine. The port driver does not call the miniport's HwScsiFindAdapter routine until the Plug and Play Manager detects an HBA for which the miniport is registered as a service. For both Plug and Play and legacy miniport drivers, the port driver does all of the following before it calls the miniport'shwscsifindadapter routine: Checks the validity of the HW_INITIALIZATION_DATA Collects and stores pertinent information in the device extension of a device object that it creates to represent the HBA Allocates memory for and initializes with zeros a device extension of the requested size in which the miniport driver can store driver-determined information about the HBA Allocates memory for a configuration information buffer that is sizeof (PORT_CONFIGURATION_INFORMATION) In the configuration information buffer, fills in a PORT_CONFIGURATION_INFORMATION structure with as much configuration information about an HBA on a particular I/O bus as possible, from the miniport-supplied HW_INITIALIZATION_DATA and from other sources, such as the registry for a legacy miniport or from the Plug and Play Manager for a Plug and Play miniport. For more information about the miniport driver's HwScsiFindAdapter routine, see Section 2.4. If the miniport's DriverEntry routine sets a particular AdapterInterfaceType value in the HW_INITIALIZATION_DATA but there is no bus of that type in the machine, the port driver returns an operating system-specific status value indicating that such an HBA does not exist in the current machine. It does not call the driver-supplied HwScsiFindAdapter routine for that bus type. A miniport driver does not remain loaded if the machine has no I/O buses of the type(s) specified by the miniport's DriverEntry routine. For a legacy miniport, note that ScsiPortInitialize also is responsible for the following before it returns control to the legacy miniport's DriverEntry routine: Setting up all necessary system objects Getting configuration information from and setting configuration information in the registry Allocating system resources on behalf of the miniport driver, including memory in the amounts indicated by the miniport-specified DeviceExtensionSize, SpecificLuExtensionSize, and/or SrbExtensionSize in which the miniport driver can maintain HBA-specific state, per-logicalunit state, and/or per-request state, respectively For a Plug and Play miniport, the port driver performs these operations after the miniport driver's

20 1.0 Storage Drivers Page 20 of 79 HwScsiFindAdapter routine returns and before the port driver calls the miniport's HwScsiInitialize routine. Each SCSI miniport driver defines the internal structure and contents of its device extension, logical unit extensions (if any), and SRB extensions (if any). A pointer to the HBA-specific device extension is an input argument to every system-defined miniport driver routine except DriverEntry. Many ScsiPortXxx routines require this pointer as an argument. ScsiPortInitialize can be called only from a miniport driver's DriverEntry routine. For more information about the HW_INITIALIZATION_DATA structure and ScsiPortInitialize, see the Kernel-Mode Driver Reference Storage Driver's Return from DriverEntry When ScsiPortInitialize returns control, the DriverEntry routine propagates the return value of ScsiPortInitialize when DriverEntry itself returns control. If a miniport driver calls ScsiPortInitialize more than once, its DriverEntry routine must propagate the lowest value returned by ScsiPortInitialize. A miniport driver writer cannot make any assumptions about the values returned by ScsiPortInitialize. 2.4 SCSI Miniport Driver's HwScsiFindAdapter Routine The operating system-specific port driver fills in as much of the PORT_CONFIGURATION_INFORMATION in the configuration information buffer as it can from the miniport's HW_INITIALIZATION_DATA specification and other sources in the system before calling the given HwScsiFindAdapter routine with a pointer to the configuration information buffer. In general, a HwScsiFindAdapter routine is responsible for using the supplied configuration information and/or for calling ScsiPortXxx to collect sufficient configuration information to determine whether it supports an HBA on the I/O bus identified by the SystemIoBusNumber in the PORT_CONFIGURATION_INFORMATION supplied by the port driver. If so, HwScsiFindAdapter is responsible for filling in any remaining configuration information for the supported HBA in the PORT_CONFIGURATION_INFORMATION, for setting up the miniport's device extension with driver-determined state about that HBA, and for setting the Again parameter to an appropriate value before it returns control.

21 1.0 Storage Drivers Page 21 of 79 For more information about the PORT_CONFIGURATION_INFORMATION structure and the HwScsiFindAdapter routine, see also the Kernel-Mode Driver Reference Calling ScsiPortXxx from HwScsiFindAdapter Certain ScsiPortXxx routines can be called only from the miniport driver's HwScsiFindAdapter routine(s), in particular, the following: ScsiPortValidateRange to verify that a miniport-supplied bus-relative access range has not already been claimed in the registry by another driver for its device ScsiPortGetDeviceBase to map the (bus-relative) "physical" address range for an HBA to a system-assigned logical address range that the driver can use to communicate with the HBA by calling the ScsiPortReadXxx and ScsiPortWriteXxx routines with the mapped logical range addresses ScsiPortFreeDeviceBase to release such a mapped range if HwScsiFindAdapter does not find an HBA it can support on a given I/O bus, as indicated by the PORT_CONFIGURATION_INFORMATION SystemIoBusNumber value ScsiPortGetUncachedExtension to allocate a DMA buffer shared between the system and a busmaster HBA In addition to these four routines, there is one routine which can only be called from the miniport driver's HwScsiFindAdapter routine or from HwScsiAdapterControl when the control type is ScsiSetRunningConfig: ScsiPortGetBusData to get BUS_DATA_TYPE-specific configuration information, such as bus-relative device memory (access) ranges, interrupt vector or IRQL, DMA channel or port, etc. For more information about these ScsiPortXxx routines, see also the Kernel-Mode Driver Reference Port-Driver-Supplied ConfigInfo for HwScsiFindAdapter The system port driver always sets up the following PORT_CONFIGURATION_INFORMATION before it calls a miniport's HwScsiFindAdapter routine with a pointer to the PORT_CONFIGURATION_INFORMATION (the ConfigInfo buffer): Length to sizeof(port_configuration_information) AdapterInterfaceType to the miniport's HW_INITIALIZATION_DATA specification

22 1.0 Storage Drivers Page 22 of 79 InterruptMode to LevelSensitive for a PCI bus or Latched for all other bus types If the miniport has no HwScsiInterrupt routine and, therefore, set the HwInterrupt entry point to NULL in the HW_INITIALIZATION_DATA, this member is irrelevant. AtdiskPrimaryClaimed to TRUE if a previously loaded driver is using the I/O port range 0x1F0 to 0x1FF AtdiskSecondaryClaimed to TRUE if a previously loaded driver is using the I/O port range 0x170 to 0x17F NumberOfAccessRanges to the miniport's HW_INITIALIZATION_DATA specification Dma64BitAddresses to the miniport's HW_INITIALIZATION_DATA specification if the system has memory with physical addresses above 4GB The port driver also attempts to fill in the following members with values from other sources in the system, such as the registry for a legacy minport or from the Plug and Play Manager for a Plug and Play miniport: SystemIoBusNumber set to the system-assigned value for the I/O bus The miniport's HwScsiFindAdapter routine can be called for each bus of the given AdapterInterfaceType with an updated value for SystemIoBusNumber, or this can be set to a system-determined value if the system detects an HBA on a particular bus of the given AdapterInterfaceType. AccessRanges elements of type ACCESS_RANGE, set with the bus-relative RangeStart address and RangeLength, as well as whether each range is a RangeInMemory RangeInMemory set to FALSE indicates a range of ports in I/O space, rather than a memoryspace range. The port driver either supplies all the information in an ACCESS_RANGE element or it sets all members of the element to (default) zero. Usually, the port driver supplies additional configuration information if it provides nonzero values for an access range. A miniport driver must map any bus-relative access range values supplied by the port driver with ScsiPortGetDeviceBase and use the mapped logical address values to determine whether the corresponding HBA is one that the driver supports. Never map and use a miniport-supplied range to access an HBA on the bus if the port driver supplies filled-in access range elements in the PORT_CONFIGURATION_INFORMATION it passes to the HwScsiFindAdapter routine. Using miniport-supplied addresses when the port driver has supplied range configuration information can reset an already configured HBA, making it dysfunctional, or even cause the system to fail the boot process. For more information about using mapped logical access ranges, see also Section BusInterruptLevel or BusInterruptVector This member is irrelevant if the miniport has no HwScsiInterrupt routine. DmaChannel or DmaPort if the HBA uses a system DMA controller If the HBA is a busmaster or uses PIO, these members are irrelevant. InitiatorBusId

23 1.0 Storage Drivers Page 23 of 79 If the input InitiatorBusId[0] has the value zero, the miniport can assign a default value if its HBA does not require the use of particular value(s) determined by querying the HBA. Otherwise, the miniport should use any nonzero value assigned by the port driver if possible. Every miniport must update InitiatorBusId specifications to match what its HBA uses, if necessary querying the HBA to determine the appropriate values(s). A miniport driver must set an entry for each SCSI bus supported by the HBA, as indicated by the value of NumberOfBuses Setting up ConfigInfo in HwScsiFindAdapter A HwScsiFindAdapter routine can call ScsiPortGetBusData and examine the returned bus-typespecific configuration information, such as POS data or EISA configuration data, for a supported HBA. If the AccessRanges elements in the input PORT_CONFIGURATION_INFORMATION (the ConfigInfo buffer) have been filled in by the port driver, the HwScsiFindAdapter routine should map the bus-relative access ranges with ScsiPortGetDeviceBase and use the returned logical access range addresses to communicate with the HBA. If access range addresses are supplied by the port driver, HwScsiFindAdapter must not scan for HBAs at other locations on that I/O bus. In addition, if the port driver supplies access range values, HwScsiFindAdapter must not use the HwContext parameter. Such access range values are usually accompanied by additional configuration information, which indicates a Plug and Play environment. In such an environment, HwScsiFindAdapter is being called after the miniport's DriverEntry routine has returned and thus the HwContext pointer is no longer valid. Only drivers that receive zero access range values from the port driver and that do their own scanning for supported HBAs can safely use the HwContext pointer. If the input PORT_CONFIGURATION_INFORMATION contains no configuration information other than that previously supplied by the miniport in the HW_INITIALIZATION_DATA, HwScsiFindAdapter can use values returned by ScsiPortGetBusData or, if necessary, set miniportdriver-defined default values for AccessRanges elements, BusInterruptLevel or BusInterruptVector, DmaChannel or DmaPort if the HBA uses system DMA, and InitiatorBusId. HwScsiFindAdapter must call ScsiPortValidateRange to check whether such miniport-driversupplied access ranges can be used safely before it accesses an HBA on the bus. If ScsiPortValidateRange returns TRUE, the miniport can call ScsiPortGetDeviceBase to map the range and use the returned logical addresses in calls to ScsiPortReadXxx and/or ScsiPortWriteXxx to determine whether it supports an HBA on the I/O bus. If ScsiPortValidateRange returns FALSE, the miniport driver must not attempt to map and use those bus-relative access range values. Similarly, if the port driver calls a Plug and Play miniport to detect devices on a nonenumerable bus,