ScsiPortGetDeviceBase function (srb.h)
The ScsiPortGetDeviceBase routine 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).
Syntax
SCSIPORT_API PVOID ScsiPortGetDeviceBase(
[in] PVOID HwDeviceExtension,
[in] INTERFACE_TYPE BusType,
[in] ULONG SystemIoBusNumber,
[in] SCSI_PHYSICAL_ADDRESS IoAddress,
[in] ULONG NumberOfBytes,
[in] BOOLEAN InIoSpace
);
Parameters
[in] HwDeviceExtension
Pointer to the hardware device extension. This is a per-HBA storage area that the port driver allocates and initializes on behalf of the miniport driver. Miniport drivers usually store HBA-specific information in this extension, such as the state of the HBA and the HBA's mapped access ranges. This area is available to the miniport driver in the DeviceExtension->HwDeviceExtension member of the HBA's device object immediately after the miniport driver calls ScsiPortInitialize. The port driver frees this memory when it removes the device.
[in] BusType
Specifies the interface type of the I/O bus on which the HBA is connected. The miniport driver's HwScsiFindAdapter routine obtains the value for this parameter from the AdapterInterfaceType member of the input PORT_CONFIGURATION_INFORMATION.
[in] 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.
[in] 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 driver-supplied default value. Avoid using a base address of zero because its successful return status can conflict with the error status (NULL).
[in] 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 driver-supplied default. In any case, the driver must not access the hardware outside of the returned, mapped range.
[in] InIoSpace
TRUE indicates the range to be mapped is in I/O space, and the miniport driver 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. FALSE indicates that the range to be mapped is in memory space.
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.
Remarks
NT-based operating system 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 or from HwScsiAdapterControl when the control type is ScsiSetRunningConfig. Calls from other miniport driver 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 driver-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 driver supports, it must call ScsiPortFreeDeviceBase to release the mapping(s) it set up to communicate with that HBA.
ScsiPortGetDeviceBase uses SCSI_PHYSICAL_ADDRESS to represent bus-relative addresses.
typedef PHYSICAL_ADDRESS SCSI_PHYSICAL_ADDRESS, *PSCSI_PHYSICAL_ADDRESS;
The SCSI_PHYSICAL_ADDRESS type is an operating system-independent data type that SCSI miniport drivers use to represent either a physical addresses or a bus-relative address.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Desktop |
| Header | srb.h (include Miniport.h, Scsi.h) |
| Library | Scsiport.lib |