HwScsiFindAdapter routine

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.

Note  The SCSI port driver and SCSI miniport driver models may be altered or unavailable in the future. Instead, we recommend using the Storport driver and Storport miniport driver models.

Syntax

PHW_FIND_ADAPTER HwScsiFindAdapter;

ULONG HwScsiFindAdapter(
  _In_    PVOID                           DeviceExtension,
  _In_    PVOID                           HwContext,
  _In_    PVOID                           BusInformation,
  _In_    PCHAR                           ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  _Out_   PBOOLEAN                        Again
)
{ ... }

Parameters

• DeviceExtension [in]
  Points to the miniport driver's per-HBA storage area. The operating system-specific port driver allocates memory for and initializes this extension with zeros before it calls the miniport driver's HwScsiFindAdapter routine.

• HwContext [in]
  Points to a context value.

  Legacy (non-PnP) miniport drivers 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.

  Miniport drivers that use configuration information provided by the port driver, rather than by scanning the I/O bus, must not use this pointer. Even if the miniport driver does scan the I/O bus for other configuration information, if HwScsiFindAdapter receives nonzero access range values from the port driver it must not use the HwContext pointer.

• BusInformation [in]
  Points to bus-type-specific information that the operating system-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. This parameter is meaningful only for legacy (non-PnP) miniport drivers.

• ArgumentString [in]
  Points to a null-terminated ASCII string. This string originates from the user and, if supplied, contains device information such as a base parameter or an interrupt level from the registry.

• ConfigInfo [in, out]
  Points to the PORT_CONFIGURATION_INFORMATION structure. The operating system-specific port driver initializes this structure with any known configuration information, such as values the miniport driver 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 operating system-dependent port driver cannot supply additional configuration information to that provided by the miniport driver's DriverEntry routine.

• Again [out]
  Points to a BOOLEAN variable to be set by HwScsiFindAdapter before it returns control. TRUE indicates that the miniport driver wants the operating system-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. This parameter is meaningful only for legacy (non-PnP) miniport drivers.

Return value

HwScsiFindAdapter must return one of the following status values:

Remarks

For a legacy miniport driver, ScsiPortInitialize calls the HwScsiFindAdapter routine after allocating storage according to the DeviceExtensionSize that the miniport driver specified in the HW_INITIALIZATION_DATA structure. For a Plug and Play miniport driver, the port driver calls HwScsiFindAdapter when the Plug and Play manager has detected an adapter for that miniport driver.

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 driver would need to find and configure its HBA(s).

Next, every HwScsiFindAdapter routine should check the AccessRanges in the PORT_CONFIGURATION_INFORMATION to determine whether the operating system-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 driver-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 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 driver 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 driver 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 operating system-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 driver 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 driver 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 driver should set the interrupt configuration value to zero if it controls its HBA in a polled mode.

A miniport driver's HwScsiFindAdapter routine should return with the Again parameter set to TRUE so the operating system-specific SCSI port driver will search for additional HBAs on the I/O bus. Although Again is irrelevant when a miniport driver is loaded as a Plug and Play driver, Again must be set appropriately so the system can run a Plug and Play miniport driver as a legacy driver if necessary.

The name HwScsiFindAdapter is just a placeholder. The actual prototype of this routine is defined in srb.h as follows:

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

For more information about the HwScsiFindAdapter routine, see SCSI Miniport Driver's HwScsiFindAdapter Routine.

Requirements

See also

ACCESS_RANGE

DriverEntry

HW_INITIALIZATION_DATA

PORT_CONFIGURATION_INFORMATION

ScsiPortGetBusData

ScsiPortGetDeviceBase

ScsiPortInitialize

ScsiPortLogError

ScsiPortValidateRange

Send comments about this topic to Microsoft