HwFindAdapter Routines

The port driver fills in as much PORT_CONFIGURATION_INFORMATION as it can from the miniport's returned HW_INITIALIZATION_DATA and from the registry before calling a HwFindAdapter routine with a pointer to the configuration information buffer. In particular, the port driver always sets the following:

• Length to sizeof(PORT_CONFIGURATION_INFORMATION)
• AdapterInterfaceType to the miniport's HW_INITIALIZATION_DATA specification
• InterruptMode to LevelSensitive if the AdapterInterfaceType is set to MicroChannel; otherwise, set to Latched

If the miniport has no HwInterrupt routine and, therefore, set this entry point to NULL in the HW_INITIALIZATION_DATA, this field 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

The port driver also attempts to fill in the following fields with values from the registry:

• SystemIoBusNumber set to zero if there is only one bus of a particular type in the machine

  Otherwise, the miniport's HwFindAdapter routine can be called for each bus of the given AdapterInterfaceType with an updated value for SystemIoBusNumber, or this value can be set to a value from the registry if the system detects an HBA on a particular bus.

• AccessRanges elements, set with the RangeStart and RangeLength of each element, as well as whether each element is a RangeInMemory

  RangeInMemory set to FALSE indicates a range of ports in I/O space, rather than a memory-mapped range.

• BusInterruptLevel or BusInterruptVector

This field is irrelevant if the miniport has no HwInterrupt routine.

• DmaChannel or DmaPort if the HBA uses system DMA

  If the HBA is a busmaster or uses PIO, these fields in the PORT_CONFIGURATION_INFORMATION are irrelevant.

• InitiatorBusId

A HwFindAdapter routine calls ScsiGetBusData and examines the returned bus-type-specific configuration information, such as POS data or EISA configuration data, for a supported HBA. If the input PORT_CONFIGURATION_INFORMATION AccessRanges elements have been filled in from the registry, the HwFindAdapter routine should use these addresses and should not scan for adapters at other locations.

If HwFindAdapter cannot find an HBA it supports, it should set Again to FALSE and return SP_RETURN_NOT_FOUND. If the HwFindAdapter routine finds a supported HBA but the input PORT_CONFIGURATION_INFORMATION has invalid data (such as an invalid DmaChannel or BusInterruptLevel on an EISA bus), it should set Again to FALSE and return SP_RETURN_BAD_CONFIG.

Note that setting Again to FALSE and returning control with SP_RETURN_NOT_FOUND or SP_RETURN_BAD_CONFIG indicates that a given I/O bus, identified by the SystemIoBusNumber in the input PORT_CONFIGURATION_INFORMATION buffer, has no HBAs connected that the miniport driver can support. It does not prevent the port driver from calling HwFindAdapter again with updated PORT_CONFIGURATION_INFORMATION to scan another I/O bus for HBA(s) if the machine has additional buses of the same AdapterInterfaceType.

When the HwFindAdapter routine finds an HBA it can support, this routine must fill in pertinent fields, as appropriate for its HBA and the given AdapterInterfaceType, in the input PORT_CONFIGURATION_INFORMATION buffer. Every miniport driver must fill in the AccessRanges information, converting each AccessRanges element's RangeStart value with ScsiPortConvertUlongToPhysicalAddress.

For an "AT-compatible" HBA, the HwFindAdapter routine should check the input Atdisk..Claimed fields and attempt to claim an "AT" range by resetting the value to TRUE.

The HwFindAdapter routine can set Again to TRUE to indicate it should be called again with exactly the same configuration information if another of its HBAs might be connected on the same I/O bus. For a supported HBA, the HwFindAdapter routine returns SP_RETURN_FOUND.

If the PORT_CONFIGURATION_INFORMATION buffer input to the HwFindAdapter routine has no configuration information from the registry, HwFindAdapter can set driver-defined default values for AccessRanges elements, InterruptLevel or BusInterruptVector, DmaChannel or DmaPort if the HBA uses system DMA, and InitiatorBusId, and, then, call ScsiPortGetBusData and examine the returned configuration information for a supported HBA on the I/O bus.

Certain ScsiPortXxx routines can be called only from the miniport driver's HwFindAdapter routine(s), in particular, the following:

• ScsiPortGetBusData to get BUS_DATA_TYPE-specific configuration information
• ScsiPortGetDeviceBase to map the (bus-relative) base physical address range for an HBA to a system address range that the driver can use to communicate with the HBA by calling the ScsiPortReadXxx and ScsiPortWriteXxx routines
• ScsiPortFreeDeviceBase to release such a mapped range if HwFindAdapter 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

For more information about the PORT_CONFIGURATION_INFORMATION structure and these ScsiPortXxx routines, see the Introduction to SCSI Port Driver Services Reference.

When a miniport driver's HwFindAdapter routine returns control, ScsiPortInitialize returns to the DriverEntry routine if the call(s) to HwFindAdapter indicated that the miniport driver could not support an HBA. Otherwise, ScsiPortInitialize claims resources in the registry, sets up necessary system objects (such as interrupt and adapter objects) on behalf of the miniport driver, and calls the miniport's HwInitialize routine, described in HwInitialize Routine.

In addition to the values it sets in the PORT_CONFIGURATION_INFORMATION buffer, ScsiPortInitialize also checks the registry for user-set values that disable any or all of the following:

• Synchronous transfers on the HBA

The port driver ORs the default SrbFlags that it maintains for the HBA with SRB_FLAGS_DISABLE_SYNCH_TRANSFER.

• Bus-disconnect operations on the HBA

The port driver ORs the default SrbFlags with SRB_FLAGS_DISABLE_DISCONNECT.

• Tagged queueing

The port driver sets the TaggedQueuing Boolean that it maintains for the HBA to FALSE.

• Internal queueing of requests on the HBA

The port driver sets the MultipleRequestPerLu Boolean that it maintains about the HBA to FALSE.

If any of the immediately preceding "disable" values are in the registry, it overrides whatever the HwFindAdapter routine sets in the PORT_CONFIGURATION_INFORMATION buffer. Note that temporarily disabling synchronous transfers, bus-disconnect operations, tagged queueing, and HBA internal request queueing can simplify using a debugger to trace request handling in a miniport driver that is under development.

Note also that the port driver uses the PORT_CONFIGURATION_INFORMATION values provided by a miniport's HwFindAdapter routine and/or in the registry to fill in the IO_SCSI_CAPABILITIES data for use by SCSI class drivers.