HwScsiFindAdapter

ULONG
HwScsiFindAdapter(
IN PVOID DeviceExtension,
IN PVOID HwContext,
IN PVOID BusInformation,
IN PCHAR ArgumentString,
IN OUT PPORT_CONFIGURATION_INFORMATION ConfigInfo,
OUT PBOOLEAN Again
);

HwScsiFindAdapter uses supplied configuration information to determine whether it supports a particular HBA and, if so, returns information about its HBA in the given ConfigInfo buffer.

Parameters

DeviceExtension

Points to the miniport driver’s per-HBA storage area. The OS-specific port driver allocates memory for and initializes this extension with zeros before it calls the miniport’s HwScsiFindAdapter routine.

HwContext

Points to a context value.

Miniports that scan for supported adapters can define the context in their DriverEntry routine and pass its address to ScsiPortInitialize. ScsiPortInitialize passes the context pointer to HwScsiFindAdapter. Such a miniport driver can use HwContext to store state between calls to HwScsiFindAdapter.

Miniports that use configuration information from the port driver rather than scanning the I/O bus should not use this pointer. If HwScsiFindAdapter receives nonzero access range values from the port driver it should not use the HwContext pointer.

BusInformation

Points to bus-type-specific information that the OS-specific port driver has gathered. The format of this information depends on the particular bus type, which the miniport driver determines by setting the AdapterInterfaceType value in the HW_INITIALIZATION_DATA structure.

ArgumentString

Points to a zero-terminated ASCII string. This string originates from the user and, if used, contains device information such as a base parameter or an interrupt level from the registry.

ConfigInfo

Points to the PORT_CONFIGURATION_INFORMATION structure. The OS-specific port driver initializes this structure with any known configuration information, such as values the miniport set in the HW_INITIALIZATION_DATA and the SystemIoBusNumber. HwScsiFindAdapter must use any supplied information to determine if the HBA it describes is one that the miniport driver supports, and, if so, to initialize and configure that HBA and to fill in any missing relevant configuration information for that HBA. If possible, each miniport driver should have a set of default configuration values for each type of HBA it supports, in case the OS-dependent port driver cannot supply additional configuration information to that provided by the miniport’s DriverEntry routine.

Again

Points to a BOOLEAN variable to be set by HwScsiFindAdapter before it returns control. TRUE indicates that the miniport driver wants the OS-specific port driver to call its HwScsiFindAdapter routine again with a new DeviceExtension and the same ConfigInfo. This member is set to TRUE by miniport drivers that can support more than one HBA on an I/O bus.

Return Value

HwScsiFindAdapter must return one of the following status values:

Value

Meaning

SP_RETURN_FOUND

Indicates a supported HBA was found and that the HBA-relevant configuration information was successfully determined and set in the PORT_CONFIGURATION_INFORMATION structure.

SP_RETURN_ERROR

Indicates an HBA was found but there was error obtaining the configuration information. If possible, such an error should be logged with ScsiPortLogError.

SP_RETURN_BAD_CONFIG

Indicates the supplied configuration information was invalid for the adapter.

SP_RETURN_NOT_FOUND

Indicates no supported HBA was found for the supplied configuration information.

Comments

ScsiPortInitialize calls the HwScsiFindAdapter routine after allocating storage according to the DeviceExtensionSize that the miniport specified in the HW_INITIALIZATION_DATA structure.

First, every HwScsiFindAdapter routine should check the value of Length in the input PORT_CONFIGURATION_INFORMATION to determine whether the port driver has allocated a structure with all the configuration information the miniport needs to find and configure its HBA(s).

Next, every HwScsiFindAdapter routine should check the AccessRanges in the PORT_CONFIGURATION_INFORMATION to determine whether the OS-specific port driver collected and set bus-relative range-configuration information for an HBA. If HwScsiFindAdapter finds nonzero access-range values, it must map the supplied values with ScsiPortGetDeviceBase and use the returned logical range addresses to access the HBA.

If the input PORT_CONFIGURATION_INFORMATION contains AccessRanges elements filled with default zeros, the HwScsiFindAdapter routine can use any appropriate search logic, such as calling ScsiPortGetBusData, or use a set of driver-supplied bus-relative default values, to fill in each such access range element and determine its validity.

HwScsiFindAdapter should call ScsiPortValidateRange before it maps any miniport-supplied access range values with ScsiPortGetDeviceBase and uses the mapped logical addresses to access an adapter. ScsiPortValidateRange verifies that the device range has not already been claimed in the registry by another driver. If ScsiPortValidateRange returns FALSE, HwScsiFindAdapter cannot map and use that range and must not attempt to do so.

HwScsiFindAdapter must check the value of NumberOfPhysicalBreaks in the input PORT_CONFIGURATION_INFORMATION. The port driver usually sets this member to a particular value. The miniport driver can set NumberOfPhysicalBreaks to a lower value if its HBA supports fewer breaks between scatter/gather lists, but the miniport must not set it to a higher value than that supplied by the port driver. If NumberOfPhysicalBreaks is set to SP_UNINITIALIZED_VALUE, the miniport must fill in the actual number of breaks between scatter/gather lists that its underlying adapter can support.

HwScsiFindAdapter should also check the input port configuration information for additional port-driver-supplied values, such as interrupt vector or level, and DMA channel or port. Usually, the OS-specific port driver supplies additional configuration information if it supplies nonzero, bus-relative values for AccessRanges elements.

A miniport driver must use any valid configuration information it finds in the input port configuration information to configure the HBA.

The port driver is responsible for doing bus-level configuration programming, particularly of dynamically configurable I/O buses with published standard interfaces, such as PCI and PCMCIA. For an HBA on such an I/O bus, the miniport driver can simply accept the interrupt configuration information provided as values reserved for system use. For an HBA on other types of I/O buses, a miniport should program its HBA to use any supplied interrupt value if its HBA supports programmable interrupt configuration. If no interrupt configuration is supplied, as indicated either by the value zero or the value SP_UNINITIALIZED_VALUE, the miniport should either query its HBA if the HBA supports interrupt selection using jumpers or should supply a nonzero default interrupt configuration unless the HBA does not use interrupts. The miniport should set the interrupt configuration value to zero if it controls its HBA in a polled mode.

A miniport’s HwScsiFindAdapter routine should return with the Again parameter set to TRUE so the OS-specific SCSI port driver will search for additional HBAs on the I/O bus.

Value	Meaning
SP_RETURN_FOUND	Indicates a supported HBA was found and that the HBA-relevant configuration information was successfully determined and set in the PORT_CONFIGURATION_INFORMATION structure.
SP_RETURN_ERROR	Indicates an HBA was found but there was error obtaining the configuration information. If possible, such an error should be logged with ScsiPortLogError.
SP_RETURN_BAD_CONFIG	Indicates the supplied configuration information was invalid for the adapter.
SP_RETURN_NOT_FOUND	Indicates no supported HBA was found for the supplied configuration information.