PORT_CONFIGURATION_INFORMATION
typedef struct _PORT_CONFIGURATION_INFORMATION {
ULONG Length;
ULONG SystemIoBusNumber;
INTERFACE_TYPE AdapterInterfaceType;
ULONG BusInterruptLevel;
ULONG BusInterruptVector;
KINTERRUPT_MODE InterruptMode;
ULONG MaximumTransferLength;
ULONG NumberOfPhysicalBreaks;
ULONG DmaChannel;
ULONG DmaPort;
DMA_WIDTH DmaWidth;
DMA_SPEED DmaSpeed;
ULONG AlignmentMask;
ULONG NumberOfAccessRanges;
ACCESS_RANGE (*AccessRanges)[];
PVOID Reserved;
UCHAR NumberOfBuses;
UCHAR InitiatorBusId[8];
BOOLEAN ScatterGather;
BOOLEAN Master;
BOOLEAN CachesData;
BOOLEAN AdapterScansDown;
BOOLEAN AtdiskPrimaryClaimed;
BOOLEAN AtdiskSecondaryClaimed;
BOOLEAN Dma32BitAddresses;
BOOLEAN DemandMode;
BOOLEAN MapBuffers;
BOOLEAN NeedPhysicalAddresses;
BOOLEAN TaggedQueuing;
BOOLEAN AutoRequestSense;
BOOLEAN MultipleRequestPerLu;
BOOLEAN ReceiveEvent;
BOOLEAN RealModeInitialized;
BOOLEAN BufferAccessScsiPortControlled;
UCHAR MaximumNumberOfTargets;
UCHAR ReservedUchars[2];
ULONG SlotNumber;
ULONG BusInterruptLevel2;
ULONG BusInterrutVector2;
KINTERRUPT_MODE InterruptMode2;
ULONG DmaChannel2;
ULONG DmaPort2;
DMA_WIDTH DmaWidth2;
DMA_SPEED DmaSpeed2;
} PORT_CONFIGURATION_INFORMATION,
*PPORT_CONFIGURATION_INFORMATION;
PORT_CONFIGURATION_INFORMATION contains configuration information for an HBA.
The OS-specific port driver allocates and initializes this structure, supplies
as much HBA-specific configuration information as possible, and passes the
structure to the miniport driver’s HwScsiFindAdapter routine. The port driver
gets some of the information for this structure from the miniport’s
HARDWARE_INITIALIZATION_DATA structure. The miniport’s HwScsiFindAdapter
routine is responsible for determining whether the miniport driver can support
the HBA and, if so, for filling in the pertinent remaining information in the
PORT_CONFIGURATION_INFORMATION structure.
Members
-
Length
-
Specifies the size of this structure in bytes, as returned by sizeof().
In effect, this member, which is always initialized by the OS-specific port
driver, indicates the version of this structure used by the port driver.
-
SystemIoBusNumber
-
Specifies the system-assigned number of the I/O bus to which the HBA is
connected. The OS-specific port driver always initializes this member. Its
value is system-assigned because the platform might have several I/O buses of
the given AdapterInterfaceType.
-
AdapterInterfaceType
-
Identifies the I/O bus interface. The OS-specific port driver always sets this
member to the value specified by the miniport driver in the
HW_INITIALIZATION_DATA structure.
-
BusInterruptLevel
-
Specifies the bus-relative interrupt request level. The OS-specific port
driver makes no assumptions about the HBA’s interrupt usage, so the default
value is zero. Depending on the given AdapterInterfaceType and HBA, the
value set for this member can correspond to the IRQL for the bus, such as for Isa
and MicroChannel type buses. Drivers of Eisa HBAs must set this
value to the bus-relative IRQL for the HBA if the adapter is configured for
level-sensitive interrupts.
-
BusInterruptVector
-
Specifies the bus-relative vector returned by the HBA. The OS-specific port
driver makes no assumptions about the HBA’s interrupt usage, so the default
value is zero. This member is irrelevant to drivers that set up the BusInterruptLevel
member for their HBAs. It is pertinent for HBAs on types of I/O buses that use
interrupt vectors, such as PCIBus.
-
InterruptMode
-
Specifies whether the HBA uses LevelSensitive or Latched
interrupts. The OS-specific port driver always initializes this member to Latched
(sometimes called “edge-triggered”). Drivers of Eisa HBAs must
reset this value if the adapter is configured for level-sensitive interrupts,
as must drivers of HBAs on I/O buses that use level-sensitive interrupts, such
as MicroChannel type buses.
-
MaximumTransferLength
-
Specifies the maximum number of bytes the HBA can transfer in a single
transfer operation. By default, the value of this member is
SP_UNINITIALIZED_VALUE, which indicates an unlimited maximum transfer size. If
its HBA has more limited transfer support, a miniport driver must reset this
member according to the HBA’s transfer capacity. If a miniport’s
HwScsiInterrupt routine cannot disable interrupts on the HBA, this member can
be adjusted during driver development to ensure that time spent in that
miniport’s ISR does not cause the mouse to “jump” or serial/parallel
throughput to drop to a user-noticeable level.
-
NumberOfPhysicalBreaks
-
Specifies the maximum number of breaks between address ranges that a data
buffer can have if the HBA supports scatter/gather. In other words, the number
of scatter/gather lists minus one. By default, the value of this member is
SP_UNINITIALIZED_VALUE, which indicates the HBA can support an unlimited
number of physical discontiguities. If the port driver sets a value for this
member, the miniport driver can adjust the value lower but no higher. If this
member is SP_UNINITIALIZED_VALUE, the miniport driver must reset this member
according to the HBA’s scatter/gather capacity, with zero representing no
scatter/gather support.
-
DmaChannel
-
Specifies the DMA channel used by a slave HBA. By default, the value of this
member is SP_UNINITIALIZED_VALUE. If the HBA uses a system DMA controller and
the given AdapterInterfaceType is any value except MicroChannel,
the miniport driver must reset this member.
-
DmaPort
-
Specifies the DMA port used by a slave HBA. By default, the value of this
member is SP_UNINITIALIZED_VALUE. If the HBA uses a system DMA controller and
the given AdapterInterfaceType is MicroChannel, the miniport
driver must reset this member.
-
DmaWidth
-
Specifies the width of DMA transfers if the HBA uses DMA. By default, the
value of this member is zero. If its HBA does DMA, the miniport must reset
this member to one of the following: Width8Bits, Width16Bits, or
Width32Bits.
-
DmaSpeed
-
Specifies the DMA data-transfer speed for Eisa HBAs. By default, the
value of this member specifies compatibility timing. Acceptable values for
this member are any of the following: Compatible, TypeA, TypeB,
or TypeC.
-
AlignmentMask
-
Is a mask indicating the alignment boundary for buffers required by the HBA
for transfer operations. A miniport driver should set this mask to indicate
any alignment restrictions on scatter/gather buffer pointers if the HBA
supports scatter/gather. For example, the value 0x00000001 indicates
(two-byte) word alignment.
-
NumberOfAccessRanges
-
Specifies the number of AccessRanges elements in the array, described
next. The OS-specific port driver always sets this member to the value passed
in the HW_INITIALIZATION_DATA structure when the miniport driver called ScsiPortInitialize.
-
AccessRanges
-
Points to an array of ACCESS_RANGE-type elements. The given NumberOfAccessRanges
determines how many elements must be configured with bus-relative range
values. The AccessRanges pointer must be NULL if NumberOfAccessRanges
is zero. By default, all values within array elements are zero. If possible,
the OS-specific port driver initializes this member’s elements, possibly from
the registry or possibly by interrogating an I/O bus, for an HBA it found by
using the miniport’s specified HW_INITIALIZATION_DATA.
If any access range element is set to nondefault values on entry to the
miniport’s HwScsiFindAdapter routine, the miniport must map the
supplied addresses with ScsiPortGetDeviceBase and use the corresponding
logical addresses to verify whether that HBA is one it supports. If the input AccessRanges
have nondefault values supplied, a miniport should never attempt
to scan the I/O bus for HBAs it supports using a set of driver-devised
port/memory addresses that its HBA(s) might use.
-
Reserved
-
Reserved for system use and not available for use by miniport drivers.
-
NumberOfBuses
-
Specifies the number of SCSI buses controlled by the HBA. By default, the
value of this member is zero.
-
InitiatorBusId
-
If the input InitiatorBusId[0] has the value zero, the miniport can
assign a default value if its HBA does not require the use of particular
value(s) determined by querying the HBA. Otherwise, the miniport should use
any nonzero value assigned by the port driver if possible. Every miniport must
update InitiatorBusId specifications to match what its HBA uses, if
necessary querying the HBA to determine the appropriate values(s).
A miniport driver must set an entry for each SCSI bus supported by the HBA, as
indicated by the value of NumberOfBuses.
-
ScatterGather
-
TRUE indicates the HBA supports scatter/gather. By default, the value of this
member is FALSE.
-
Master
-
TRUE indicates the HBA is a busmaster. By default, the value of this member is
FALSE.
-
CachesData
-
TRUE indicates the HBA caches data or maintains cached state on the
peripherals. By default, the value of this member is FALSE. If this is reset
to TRUE, the OS-specific port driver notifies the miniport driver when certain
system events occur, such as file system cache flushes and system shutdown.
For example, if a controller on the bus mirrors two disks, the miniport driver
would normally set this member to TRUE.
-
AdapterScansDown
-
TRUE indicates the BIOS for the HBA scans for SCSI bus targets from seven to
zero. By default, the value of this member is FALSE.
-
AtdiskPrimaryClaimed
-
TRUE indicates that the primary “AT” (WD1003-compatible) disk address range,
0x1F0 to 0x1FF, has been claimed in the registry by another driver for its
device. The OS-specific port driver always initializes this member. If the
input value of this member is TRUE, a miniport driver should assume that an
already loaded driver has claimed the device range. If the input value is
FALSE, a miniport driver can claim the address range for an HBA that emulates
an “AT” disk controller and reset this member to TRUE, thereby preventing
access to this range by the “AT” disk driver or subsequently loaded miniport
drivers.
-
AtdiskSecondaryClaimed
-
TRUE indicates that the secondary AT disk address range, 0x170 to 0x17F has
been claimed in the registry by another driver for its device. The OS-specific
port driver always initializes this member. Miniport drivers should treat this
member as for AtdiskPrimaryClaimed.
-
Dma32BitAddresses
-
TRUE indicates that the HBA has 32 address lines and can access memory with
physical addresses greater than 0x00FFFFFF. By default, the value of this
member is FALSE.
-
DemandMode
-
TRUE indicates the system DMA controller should be programmed for demand-mode
rather than single-cycle operations. If the HBA is not a slave device, this
member should be FALSE.
-
MapBuffers
-
TRUE indicates data buffers must be mapped to system virtual address ranges.
The OS-specific port driver always sets this member to the value passed in the
HW_INITIALIZATION_DATA structure when the miniport driver called ScsiPortInitialize.
A miniport driver can reset this value for any particular HBA it controls. If
FALSE, the miniport must not access Srb.DataBuffer directly.
-
NeedPhysicalAddresses
-
TRUE indicates the miniport driver must translate virtual addresses to
physical addresses, as required by the HBA. The OS-specific port driver always
sets this member to the value passed in the HW_INITIALIZATION_DATA structure
when the miniport driver called ScsiPortInitialize. A miniport driver
can reset this value for any particular HBA it controls.
-
TaggedQueuing
-
TRUE indicates the HBA supports queuing of multiple requests with SCSI-II
tags. The OS-specific port driver always sets this member to the value passed
in the HW_INITIALIZATION_DATA structure when the miniport driver called ScsiPortInitialize.
A miniport driver can reset this value for any particular HBA it controls.
-
AutoRequestSense
-
TRUE indicates the HBA supports auto request sense. The OS-specific port
driver always sets this member to the value passed in the
HW_INITIALIZATION_DATA structure when the miniport driver called ScsiPortInitialize.
A miniport driver can reset this value for any particular HBA it controls.
This member must be set to TRUE before the driver of a busmaster HBA calls ScsiPortGetUncachedExtension.
-
MultipleRequestPerLu
-
TRUE indicates the HBA supports multiple requests per logical unit. The
mechanism by which the adapter caches the requests is adapter-defined. The
OS-specific port driver always sets this member to the value passed in the
HW_INITIALIZATION_DATA structure when the miniport driver called ScsiPortInitialize.
A miniport driver can reset this value for any particular HBA it controls.
-
ReceiveEvent
-
TRUE indicates the HBA supports SCSI receive-event operations. The OS-specific
port driver always sets this member to the value passed in the
HW_INITIALIZATION_DATA structure when the miniport driver called ScsiPortInitialize.
A miniport driver can reset this value for any particular HBA it controls.
-
RealModeInitialized
-
TRUE indicates an (x86-only) real-mode driver has already initialized the HBA.
The OS-dependent port driver always initializes this member. If this is set to
TRUE, the miniport driver must not initialize its HBA if the driver’s
initialization sequence is identical to real-mode HBA initialization; not
reinitializing the HBA in these circumstances makes the miniport driver load
much faster. The value of this member is irrelevant to any miniport that
always initializes its HBA while running in protected mode on x86-based
platforms and to all miniports for which it is immaterial whether they are
running on a CISC- or RISC-based platform.
-
BufferAccessScsiPortControlled
-
TRUE indicates that the miniport always calls ScsiPortXxx to
access data buffers and/or request-sense information in SRBs, thereby allowing
the OS-specific port driver to optimize I/O request processing. Setting this
member to FALSE can degrade the I/O performance of the HBA. Calling routines
other than the ScsiPortXxx makes a miniport driver nonportable
across Microsoft operating systems.
-
MaximumNumberOfTargets
-
Specifies the number of target peripherals the HBA can control. By default,
the value of this member is SCSI_MAXIMUM_TARGETS, according to the SCSI-II
standard. A miniport can reset this member to a lesser value if the HBA has
more limited capabilities or to a greater value, indicating that the HBA has
wide-SCSI capabilities.
-
ReservedUchars[2]
-
Reserved for system use and not available for use by miniport drivers.
-
SlotNumber
-
Specifies the slot number of an HBA with matching values to the VendorId
and DeviceId that were specified in the HW_INITIALIZATION_DATA
structure when the miniport driver called ScsiPortInitialize.
-
BusInterruptLevel2
-
Reserved for system use and not available for use by miniport drivers.
-
BusInterruptVector2
-
Reserved for system use and not available for use by miniport drivers.
-
InterruptMode2
-
Reserved for system use and not available for use by miniport drivers.
-
DmaChannel2
-
Reserved for system use and not available for use by miniport drivers.
-
DmaPort2
-
Reserved for system use and not available for use by miniport drivers.
-
DmaWidth2
-
Reserved for system use and not available for use by miniport drivers.
-
DmaSpeed2
-
Reserved for system use and not available for use by miniport drivers.
Comments
The specific members initialized depend on the HBA miniport driver and on the
configuration information available to the OS-specific port driver. The
OS-specific port driver sets default values in all members for which it cannot
supply configuration information to the miniport’s HwScsiFindAdapter routine.
All HBA miniport drivers should have at least one set of defaults to use for
relevant members if the OS-specific port driver does not pass in all
initialized values.
The HwScsiFindAdapter routine must update all members relevant to an HBA that
the driver supports.
Windows NT SCSI class drivers, which load later than miniport drivers, depend
on the information supplied by each miniport’s HwScsiFindAdapter routine to
set up their subsequent I/O requests. For example, the MaximumTransferLength
and NumberOfPhysicalBreaks values supplied by each miniport driver
control whether a class driver must split large transfer requests into a set
of partial transfers to suit the limits of the HBA.
See Also
ACCESS_RANGE, DriverEntry,
HwScsiFindAdapter, ScsiPortGetDeviceBase,
ScsiPortGetUncachedExtension,
ScsiPortInitialize, ScsiPortValidateRange