ScsiPortGetDeviceBase

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

ScsiPortGetDeviceBase returns a mapped, logical base address that can be used to communicate with an HBA. Every miniport driver must pass mapped, logical access range addresses to the ScsiPort..PortXxx and ScsiPort..RegisterXxx routines to communicate with its HBA(s).

Parameters

HwDeviceExtension: Points to the miniport driver’s per-HBA storage area. Miniports usually store their mapped access ranges addresses for the HBA in this extension.
BusType: Specifies the interface type of the I/O bus on which the HBA is connected. The miniport’s HwScsiFindAdapter routine obtains the value for this parameter from the AdapterInterfaceType member of the input PORT_CONFIGURATION_INFORMATION.
SystemIoBusNumber: Specifies the system-assigned number of the I/O bus on which the HBA is connected. The HwScsiFindAdapter routine obtains the value for this parameter from the SystemIoBusNumber member of the input PORT_CONFIGURATION_INFORMATION.
IoAddress: Specifies the bus-relative base address of a range used by the HBA. The HwScsiFindAdapter routine obtains the value for this parameter from one of the AccessRanges elements in the PORT_CONFIGURATION_INFORMATION if the port driver supplies range-configuration information. Otherwise, this address can be a value returned by ScsiPortGetBusData or a miniport-supplied default value. Avoid using a base address of zero because its successful return status can conflict with the error status (NULL).
NumberOfBytes: Specifies the size in bytes of the range that the mapping should cover. The HwScsiFindAdapter routine obtains the value of this parameter from the same AccessRanges element as IoAddress if the port driver supplies range configuration information. Otherwise, this value can be returned by ScsiPortGetBusData or a miniport-supplied default. In any case, the driver must not access the hardware outside of the returned, mapped range.
InIoSpace: TRUE indicates the range to be mapped is in I/O space, and the miniport will pass mapped addresses in this range to the ScsiPort...PortXxx to communicate with the HBA. The HwScsiFindAdapter routine obtains the value of this parameter from the same AccessRanges element as IoAddress. Note that a miniport driver must invert the value of the InMemorySpace member in an ACCESS_RANGE-type element before it is passed to ScsiPortGetDeviceBase as the InIoSpace argument.

Return Value

ScsiPortGetDeviceBase returns a mapped logical base address for the given IoAddress if it successfully mapped the given range from IoAddress to NumberOfBytes. If a given range cannot be mapped, ScsiPortGetDeviceBase returns NULL.

Comments

Windows NT platforms can have several types of I/O buses and several I/O buses of the same type. Moreover, the HAL can map I/O space to memory in some platforms.

Consequently, a miniport driver cannot use bus-relative access range addresses to communicate with its HBA. To maintain miniport driver portability across CISC- and RISC-based machines, the addresses they use to access HBAs must be translated with ScsiPortGetDeviceBase.

Every miniport driver must use system-space logical range addresses, mapped by ScsiPortGetDeviceBase, to communicate with its HBA(s). Calls to the ScsiPort...Port/RegisterXxx routines require these mapped, logical addresses.

ScsiPortGetDeviceBase can be called several times, depending on how many HBAs the miniport driver supports and how many access ranges each HBA requires. Each mapped range corresponds to a range of bus-relative device addresses specified in an ACCESS_RANGE-type element of the AccessRanges array.

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

Follow these guidelines for calling ScsiPortGetDeviceBase:

If HwScsiFindAdapter is using a miniport-supplied set of default bus-relative access ranges or values returned by ScsiPortGetBusData, it should call ScsiPortValidateRange before attempting to call ScsiPortGetDeviceBase.
If HwScsiFindAdapter determines that a particular HBA is not one that the miniport supports, it must call ScsiPortFreeDeviceBase to release the mapping(s) it set up to communicate with that HBA.

The logical address returned by ScsiPortGetDeviceBase should be used for all subsequent references made to the hardware but should not be added to any AccessRanges specification in the PORT_CONFIGURATION_INFORMATION. Miniport driver writers should make no assumptions about how many bits are used in the logical base address returned by ScsiPortGetDeviceBase.