A.2.3  SCSI Filter Driver’s DriverEntry Routine

Like any other kernel-mode driver, the DriverEntry routine of an SFD must define its Dispatch (and Unload, if any) entry points in the input driver object. Then, the SFD must create one or more device objects with IoCreateDevice, layer itself over the appropriate SCSI class driver with IoAttachDevice, and set up one or more requests to find its device(s), if any, on a SCSI bus in the machine.

SFDs for certain kinds of devices might call IoGetConfigurationInformation to determine how many devices of their respective types are already represented by named device objects. The count of named device objects in the I/O Manager’s CONFIGURATION_INFORMATION-type structure places an upper bound on the number of device objects such an SFD might need to create.

If this system-defined structure does not have a count for the driver’s type of device, an SFD can examine the registry for devices of its type. For more information about using the I/O Manager’s global configuration information structure and/or the registry, see Chapter 16.

Note that a configuration information count or the registry keys for a given type of device also could include device objects for nonSCSI devices and/or other hardware vendors’ SCSI devices of the filter driver’s type.

An SFD’s DriverEntry routine must determine whether any particular device object(s) created by another driver actually represent a SCSI device that the driver supports.

After the SFD has layered itself over the SCSI class driver (or over another driver for its type of device), the DriverEntry routine must allocate a buffer and set up a request for SCSI-II inquiry data about the underlying device(s). On a successful return from this request, the SFD must inspect the buffered inquiry data for the vendor name and, possibly, model designation to determine whether the device is one the driver supports. If so, the SFD should set up the device extension in its device object. For more information about GetInquiryData routines, see Section A.1.3.1.

Note that every driver must call IoAttachDevice with a driver-created device object. Therefore, an SFD must create a device object before it can determine whether the underlying device is one that it supports. Its DriverEntry routine must call IoDetachDevice and, then, IoDeleteDevice to release any device objects it creates for unsupported devices. The DriverEntry routine also must free the memory it allocated for SCSI-II inquiry data before it returns control.

Assuming it finds a device it supports, the SFD must save the pointer, returned from IoAttachDevice, to the SCSI class driver’s device object in its own device extension so the SFD can send IRPs on to the class driver. If the SFD sends device-specific requests through the class driver, it might need to set up SCSI-specific data in the device extension of its device object(s). In other words, such an SFD’s device extension should include any SCSI-specific data necessary to manage its device-specific requests.

For more information about setting up a higher-level driver’s device extension with SCSI-specific data, see Section A.1.3.4. For more information about the general requirements for DriverEntry routines, see Chapter 5.