ScsiPortValidateRange

BOOLEAN
ScsiPortValidateRange(
IN PVOID HwDeviceExtension,
IN INTERFACE_TYPE BusType,
IN ULONG SystemIoBusNumber,
IN SCSI_PHYSICAL_ADDRESS IoAddress,
IN ULONG NumberOfBytes,
IN BOOLEAN InIoSpace
);

ScsiPortValidateRange indicates whether the specified access range values have already been claimed in the registry by another driver.

Parameters

HwDeviceExtension: Points to the per-HBA storage the OS-specific port driver allocated, initialized with zeros, and passed in to the miniport’s HwScsiFindAdapter routine.
BusType: Is the value of the AdapterInterfaceType member in the PORT_CONFIGURATION_INFORMATION structure when HwScsiFindAdapter is called.
SystemIoBusNumber: Is the value of the SystemIoBusNumber member in the configuration information when HwScsiFindAdapter is called.
IoAddress: Is a bus-relative base address for the range of ports or device memory to be validated before the miniport’s HwScsiFindAdapter routine attempts to map the access range for the adapter at that address.
NumberOfBytes: Specifies the size in bytes or number of elements in the range.
InIoSpace: TRUE indicates the range is in I/O space, rather than in memory.

Return Value

ScsiPortValidateRange returns TRUE if the HwScsiFindAdapter routine can safely map and use the mapped range to access the adapter. ScsiPortValidateRange returns FALSE if the specified access range values have already been claimed in the registry by another driver.

Comments

ScsiPortValidateRange can be called only from a miniport driver’s HwScsiFindAdapter routine. Calls from other miniport driver routines will result in system failure or incorrect operation for the caller.

If the OS-specific port driver initializes any AccessRanges element of the PORT_CONFIGURATION_INFORMATION structure before it calls the miniport’s HwScsiFindAdapter routine, the miniport must pass the supplied values to ScsiPortGetDeviceBase and use the mapped logical addresses for the range to determine whether an HBA is one that it supports.

The port driver either fills an ACCESS_RANGE-type element with a complete description of a bus-relative address range for an adapter, or the port driver zeros all members of the element.

For input AccessRanges elements set with default zeros, the HwScsiFindAdapter routine can attempt to locate an adapter it supports on the given I/O bus. In these circumstances, a miniport driver usually has a set of driver-determined default addresses for its type(s) of HBA. However, a previously loaded driver might already be using an initialized adapter at one of this miniport’s default address ranges, particularly in x86-only systems in which some devices are initialized in x86 real mode. To prevent such a device from being inadvertantly reprogrammed, each miniport driver’s HwScsiFindAdapter routine should call ScsiPortValidateRange before it maps any driver-supplied addresses with ScsiPortGetDeviceBase and then uses the mapped logical addresses to interrogate adapters on an I/O bus.

If ScsiPortValidateRange returns FALSE, HwScsiFindAdapter must not attempt to map the input range addresses because another driver has already claimed the range in the registry.

If ScsiPortValidateRange returns TRUE, HwScsiFindAdapter can safely do the following:

Map the bus-relative range addresses to system-space logical range addresses with ScsiPortGetDeviceBase.
Use the mapped logical addresses with the ScsiPortRead/WriteXxx to determine whether the adapter actually is an HBA that the driver supports.

If a miniport uses a range successfully passed to ScsiPortValidateRange for an HBA it supports, that driver must invert the InIoSpace value when it sets the RangeInMemory member of an AccessRanges element in the PORT_CONFIGURATION_INFORMATION.