PORT_CONFIGURATION_INFORMATION - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
// srb.h
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 BusInterruptVector2;
KINTERRUPT_MODE InterruptMode2;
ULONG DmaChannel2;
ULONG DmaPort2;
DMA_WIDTH DmaWidth2;
DMA_SPEED DmaSpeed2;
ULONG DeviceExtensionSize;
ULONG SpecificLuExtensionSize;
ULONG SrbExtensionSize;
UCHAR Dma64BitAddresses;
BOOLEAN ResetTargetSupported;
UCHAR MaximumNumberOfLogicalUnits;
BOOLEAN WmiDataProvider;
} PORT_CONFIGURATION_INFORMATION, *PPORT_CONFIGURATION_INFORMATION;
View the official Windows Driver Kit DDI reference// storport.h
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 MiniportDumpData;
PVOID Reserved;
UCHAR NumberOfBuses;
CCHAR InitiatorBusId[8];
BOOLEAN ScatterGather;
BOOLEAN Master;
BOOLEAN CachesData;
BOOLEAN AdapterScansDown;
BOOLEAN AtdiskPrimaryClaimed;
BOOLEAN AtdiskSecondaryClaimed;
BOOLEAN Dma32BitAddresses;
BOOLEAN DemandMode;
UCHAR MapBuffers;
BOOLEAN NeedPhysicalAddresses;
BOOLEAN TaggedQueuing;
BOOLEAN AutoRequestSense;
BOOLEAN MultipleRequestPerLu;
BOOLEAN ReceiveEvent;
BOOLEAN RealModeInitialized;
BOOLEAN BufferAccessScsiPortControlled;
UCHAR MaximumNumberOfTargets;
UCHAR SrbType;
UCHAR AddressType;
UCHAR ReservedUchars[2];
ULONG SlotNumber;
ULONG BusInterruptLevel2;
ULONG BusInterruptVector2;
KINTERRUPT_MODE InterruptMode2;
ULONG DmaChannel2;
ULONG DmaPort2;
DMA_WIDTH DmaWidth2;
DMA_SPEED DmaSpeed2;
ULONG DeviceExtensionSize;
ULONG SpecificLuExtensionSize;
ULONG SrbExtensionSize;
UCHAR Dma64BitAddresses;
BOOLEAN ResetTargetSupported;
UCHAR MaximumNumberOfLogicalUnits;
BOOLEAN WmiDataProvider;
STOR_SYNCHRONIZATION_MODEL SynchronizationModel;
PHW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE HwMSInterruptRoutine;
INTERRUPT_SYNCHRONIZATION_MODE InterruptSynchronizationMode;
MEMORY_REGION DumpRegion;
ULONG RequestedDumpBufferSize;
BOOLEAN VirtualDevice;
UCHAR DumpMode;
UCHAR DmaAddressWidth;
ULONG ExtendedFlags1;
ULONG MaxNumberOfIO;
ULONG MaxIOsPerLun;
ULONG InitialLunQueueDepth;
ULONG BusResetHoldTime;
ULONG FeatureSupport;
} PORT_CONFIGURATION_INFORMATION, *PPORT_CONFIGURATION_INFORMATION;
View the official Windows Driver Kit DDI reference// strmini.h
typedef struct _PORT_CONFIGURATION_INFORMATION {
ULONG SizeOfThisPacket;
PVOID HwDeviceExtension;
PDEVICE_OBJECT ClassDeviceObject;
PDEVICE_OBJECT PhysicalDeviceObject;
ULONG SystemIoBusNumber;
INTERFACE_TYPE AdapterInterfaceType;
ULONG BusInterruptLevel;
ULONG BusInterruptVector;
KINTERRUPT_MODE InterruptMode;
ULONG DmaChannel;
ULONG NumberOfAccessRanges;
PACCESS_RANGE AccessRanges;
ULONG StreamDescriptorSize;
PIRP Irp;
PKINTERRUPT InterruptObject;
PADAPTER_OBJECT DmaAdapterObject;
PDEVICE_OBJECT RealPhysicalDeviceObject;
ULONG Reserved[1];
} PORT_CONFIGURATION_INFORMATION, *PPORT_CONFIGURATION_INFORMATION;
View the official Windows Driver Kit DDI referenceNo description available.
PORT_CONFIGURATION_INFORMATION (SCSI) 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 driver's HW_INITIALIZATION_DATA structure. The miniport driver'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.
[!NOTE] The SCSI port driver and SCSI miniport driver models may be altered or unavailable in the future. Use the Storport driver and Storport miniport driver models instead.
LengthSpecifies the size of this structure in bytes. 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.
SystemIoBusNumberSpecifies 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.
AdapterInterfaceTypeIdentifies 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 (SCSI) structure.
BusInterruptLevelSpecifies 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.
BusInterruptVectorSpecifies 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.
InterruptModeSpecifies whether the HBA uses LevelSensitive or Latched (sometimes called "edge-triggered") interrupts. The OS-specific port driver initializes this member to an appropriate value for the bus and the device--for example, LevelSensitive for PCIBus. 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.
MaximumTransferLengthSpecifies 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 driver'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 driver's ISR does not cause the mouse to "jump" or serial/parallel throughput to drop to a user-noticeable level.
NumberOfPhysicalBreaksSpecifies 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 discontinuities. 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.
DmaChannelSpecifies the DMA channel used by a subordinate 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.
DmaPortSpecifies the DMA port used by a subordinate 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 set this member.
DmaWidthSpecifies 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 driver must reset this member to one of the following: Width8Bits, Width16Bits, or Width32Bits.
DmaSpeedSpecifies 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.
AlignmentMaskContains a mask indicating the alignment restrictions for buffers required by the HBA for transfer operations. Valid mask values are also restricted by characteristics of the memory managers on different versions of Windows. The mask values that are permitted under Windows 95 or Windows 98 are 0 (byte aligned), 1 (word aligned) or 3 (DWORD aligned). Under Windows NT and Windows 2000 the valid mask values are 0 (byte aligned), 1 (word aligned), 3 (DWORD aligned) and 7 (double DWORD aligned). The miniport driver should set this mask if the HBA supports scatter/gather.
NumberOfAccessRangesSpecifies 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.
AccessRangesReservedReserved for system use and not available for use by miniport drivers.
NumberOfBusesSpecifies the number of SCSI buses controlled by the HBA. By default, the value of this member is zero.
InitiatorBusId[8]Indicates the initiator bus ID. If the input InitiatorBusId[0] has the value zero, the miniport driver 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 driver should use any nonzero value assigned by the port driver if possible. Every miniport driver 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.
ScatterGatherIndicates when TRUE that the HBA supports scatter/gather. When FALSE the HBA does not support scatter/gather. By default, the value of this member is FALSE.
MasterIndicates when TRUE that the HBA is a bus master. When FALSE, the HBA is not a bus master. By default, the value of this member is FALSE.
CachesDataIndicates when TRUE that the HBA caches data or maintains cached state on the peripherals. When FALSE the HBA does not cache data or maintain 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.
AdapterScansDownIndicates when TRUE that the BIOS for the HBA scans for SCSI bus targets from seven to zero. When FALSE, the BIOS for the HBA looks for SCSI bus targets, starting with an ID zero and scanning upwards to (but not including) MaximumTargetIds. By default, the value of AdapterScansDown is FALSE.
AtdiskPrimaryClaimedIndicates when TRUE 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.
AtdiskSecondaryClaimedIndicates when TRUE that the secondary AT disk address range, 0x170 to 0x17F has been claimed in the registry by another driver for its device. When FALSE the secondary AT disk address range has not been claimed in the registry by another driver. The OS-specific port driver always initializes this member. Miniport drivers should treat this member as for AtdiskPrimaryClaimed.
Dma32BitAddressesIndicates when TRUE that the HBA has 32 address lines and can access memory with physical addresses greater than 0x00FFFFFF. When FALSE the HBA has either a number of DMA address lines other than 32. By default, the value of this member is FALSE. If the miniport driver sets Dma64BitAddresses, this member must be FALSE.
DemandModeIndicates when TRUE that the system DMA controller should be programmed for demand-mode rather than single-cycle operations. If the HBA is not a subordinate device, this member should be FALSE.
MapBuffersIndicates when TRUE that data buffers must be mapped to system virtual address ranges. When FALSE the data buffers do not have to be mapped to system virtual addresses. The OS-specific port driver always sets this member to the value passed in the HW_INITIALIZATION_DATA (SCSI) structure when the miniport driver called ScsiPortInitialize. A miniport driver can reset this value for any particular HBA it controls. If FALSE, the miniport driver must not access Srb.DataBuffer directly.
NeedPhysicalAddressesIndicates when TRUE that the miniport driver must translate virtual addresses to physical addresses, as required by the HBA. When FALSE, the miniport driver does not have to translate virtual addresses to physical addresses. The OS-specific port driver always sets this member to the value passed in the HW_INITIALIZATION_DATA (SCSI) structure when the miniport driver called ScsiPortInitialize. A miniport driver can reset this value for any particular HBA it controls.
TaggedQueuingIndicates when TRUE that the HBA supports queuing of multiple requests with SCSI tags. When FALSE, the HBA does not support SCSI-tagged queuing. The OS-specific port driver always sets this member to the value passed in the HW_INITIALIZATION_DATA (SCSI) structure when the miniport driver called ScsiPortInitialize. A miniport driver can reset this value for any particular HBA it controls.
AutoRequestSenseIndicates when TRUE that the HBA supports auto request sense. When FALSE the HBA does not support auto request sense. The OS-specific port driver always sets this member to the value passed in the HW_INITIALIZATION_DATA (SCSI) 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 bus-master HBA calls ScsiPortGetUncachedExtension.
MultipleRequestPerLuIndicates when TRUE that the HBA supports multiple requests per logical unit. When FALSE the HBA does not support 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 (SCSI) structure when the miniport driver called ScsiPortInitialize. A miniport driver can reset this value for any particular HBA it controls.
ReceiveEventIndicates when TRUE that the HBA supports SCSI receive-event operations. When FALSE the HBA does not support SCSI receive-event operations. The OS-specific port driver always sets this member to the value passed in the HW_INITIALIZATION_DATA (SCSI) structure when the miniport driver called ScsiPortInitialize. A miniport driver can reset this value for any particular HBA it controls.
RealModeInitializedIndicates when TRUE that an (x86-only) real-mode driver has already initialized the HBA. When FALSE the HBA has not been previously initialized by a real-mode driver. 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 driver that always initializes its HBA while running in protected mode on x86-based platforms and to all miniport drivers for which it is immaterial whether they are running on a CISC- or RISC-based platform.
BufferAccessScsiPortControlledIndicates when TRUE that the miniport driver 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. When FALSE the miniport driver does not have to call ScsiPortXxx routines to access data buffers or request-sense information. 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.
MaximumNumberOfTargetsSpecifies the number of target peripherals the HBA can control. By default, the value of this member is SCSI_MAXIMUM_TARGETS, according to the SCSI standard. A miniport driver 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 or Fibre Channel capabilities. This value is limited to SCSI_MAXIMUM_TARGETS_PER_BUS.
ReservedUchars[2]Reserved for system use and not available for use by miniport drivers.
SlotNumberSpecifies the slot number of an HBA with matching values to the VendorId and DeviceId that were specified in the HW_INITIALIZATION_DATA (SCSI) structure when the miniport driver called ScsiPortInitialize.
BusInterruptLevel2Reserved for system use and not available for use by miniport drivers.
BusInterruptVector2Reserved for system use and not available for use by miniport drivers.
InterruptMode2Reserved for system use and not available for use by miniport drivers.
DmaChannel2Reserved for system use and not available for use by miniport drivers.
DmaPort2Reserved for system use and not available for use by miniport drivers.
DmaWidth2Reserved for system use and not available for use by miniport drivers.
DmaSpeed2Reserved for system use and not available for use by miniport drivers.
DeviceExtensionSizeSpecifies the size in bytes required by a miniport driver for its per-HBA device extension to handle data transfers larger than 64K, which might require larger scatter/gather lists than the size defined in the registry for this driver.
SpecificLuExtensionSizeSpecifies the size in bytes required by the miniport driver for its per-logical-unit-storage, if any, to handle data transfers larger than 64K. Leave this member set to zero if the miniport driver does not maintain per-LU information for which it requires storage. This value is based on the assumption that the HBA is able to receive 32-bit addresses, regardless of what the controller can actually support. If additional space is needed in the LUN or SRB extensions to handle 64-bit addresses, then appropriate adjustments must be made to this value before using it with routines such as ScsiPortGetUncachedExtension.
SrbExtensionSizeSpecifies the size in bytes required by the miniport driver for its per-request storage, if any, to handle data transfers larger than 64K. Set this member before calling ScsiPortGetUncachedExtension to change the size of per-request storage based on NumberOfPhysicalBreaks. Leave this member set to zero if the miniport driver does not maintain per-SRB information for which it requires storage. This value is based on the assumption that the HBA is able to receive 32-bit addresses, regardless of what the controller can actually support. If additional space is needed in the LUN or SRB extensions to handle 64-bit addresses, then appropriate adjustments must be made to this value before using it with routines such as ScsiPortGetUncachedExtension.
Dma64BitAddressesIndicates that the HBA is able to access addresses greater than 4 GB, or 0x0FFFFFFFF if Dma64BitAddresses contains a value of SCSI_DMA64_MINIPORT_SUPPORTED. Prior to Windows 2000 the ScsiPort set this value based on the contents of HW_INITIALIZATION_DATA (SCSI). This is no longer the case. In Windows 2000 the value of Dma64BitAddresses is determined by the miniport driver callback HwScsiFindAdapter alone. If the operating system supports a 64-bit address space, the port driver passes a value of SCSI_DMA64_SYSTEM_SUPPORTED to the miniport driver in this member. If the HBA described by PORT_CONFIGURATION_INFORMATION also supports address spaces greater than 32-bits then the port/miniport driver is required to support full 64-bit addressing, and the miniport driver's callback HwScsiFindAdapter indicates this by assigning a value of SCSI_DMA64_MINIPORT_SUPPORTED to Dma64BitAddresses, writing over any previous value assigned by the port driver. The correct value must be assigned to the Dma64BitAddresses member before the miniport driver calls ScsiPortGetUncachedExtension.
ResetTargetSupportedObsolete. ScsiPort driver no longer sends SRB_FUNCTION_RESET_DEVICE requests to its miniport drivers. Do not use this member.
MaximumNumberOfLogicalUnitsSpecifies the maximum number of logical units per target the HBA can control. By default, the value of this member is SCSI_MAXIMUM_LOGICAL_UNITS. A miniport driver 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 SCSI-3 capabilities.
WmiDataProviderIndicates when TRUE that the miniport driver responds to Windows Management Instrumentation (WMI) requests. When FALSE the miniport driver does not respond to Windows Management Instrumentation (WMI) requests. By default, the value of this member is FALSE.
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 driver'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 storage class drivers, which load later than miniport drivers, depend on the information supplied by each miniport driver'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.
The Dma64BitAddresses member of PORT_CONFIGURATION_INFORMATION should no longer be thought of as a BOOLEAN value. A value of SCSI_DMA64_SYSTEM_SUPPORTED indicates that the port/miniport driver is required to support 64-bit addressing, but the ScsiPortGetUncachedExtension routine still interprets any nonzero value of Dma64BitAddresses as indicating that 64-bit support is required. This means that ScsiPortGetUncachedExtension still functions properly when called by a legacy driver that assigns BOOLEAN values to Dma64BitAddresses.
In addition to Dma64BitAddresses, both PORT_CONFIGURATION_INFORMATION and HW_INITIALIZATION_DATA have a pair of members called SpecificLuExtensionSize and SrbExtensionSize whose values must now be handled differently. The miniport driver must calculate the initial values of SpecificLuExtensionSize and SrbExtensionSize in HW_INITIALIZATION_DATA based on the assumption that the HBA is capable of receiving 32-bit addresses, regardless of what the controller can actually support. The default values for SpecificLuExtensionSize and SrbExtensionSize in PORT_CONFIGURATION_INFORMATION will also be based on an assumption of 32-bit addressing, since the values in PORT_CONFIGURATION_INFORMATION are derived from the values in HW_INITIALIZATION_DATA.
This means that if the miniport driver needs additional space in either the LUN extension or the SRB extension in order to handle 64 bit physical addresses, it must modify the values for SpecificLuExtensionSize and SrbExtensionSize in PORT_CONFIGURATION_INFORMATION to account for this before passing PORT_CONFIGURATION_INFORMATION to ScsiPortGetUncachedExtension.
PORT_CONFIGURATION_INFORMATION contains configuration information for a host bus adapter (HBA).
LengthSize, in bytes, of the PORT_CONFIGURATION_INFORMATION structure. Initialized by the Storport driver, this member also serves as the structure version.
SystemIoBusNumberSystem-assigned number of the I/O bus to which the HBA is connected. Miniport drivers must not modify this member. Its value is system-assigned because the platform might have several I/O buses of the specified AdapterInterfaceType.
AdapterInterfaceTypeThe I/O bus interface. Storport initializes this member to the value specified by the miniport driver in the HW_INITIALIZATION_DATA structure. Miniport drivers must not modify this member.
BusInterruptLevelThe bus-relative interrupt request level. Storport makes no assumptions about the HBA's interrupt usage, so the default value is zero. Storport initializes this member and miniport drivers must not modify it.
BusInterruptVectorThe bus-relative vector returned by the HBA. Storport 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. Storport initializes this member and miniport drivers must not modify it.
InterruptModeSpecifies whether the HBA uses LevelSensitive or Latched (sometimes called "edge-triggered") interrupts. Storport initializes this member to an appropriate value for the bus and the device--for example, LevelSensitive for PCIBus. Storport initializes this member and miniport drivers must not modify it.
MaximumTransferLengthMaximum 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 driver's HwStorInterrupt routine cannot disable interrupts on the HBA, this member can be adjusted during driver development to ensure that time spent in that miniport driver's ISR does not degrade overall system performance.
NumberOfPhysicalBreaksMaximum number of physical pages the storage adapter can manage in a single transfer (in other words, the extent of its scatter/gather support). By default, the value of this member is 0x11. The miniport driver must reset this member according to the storage adapter's capability.
DmaChannelThe DMA channel used by a subordinate HBA. By default, the value of this member is SP_UNINITIALIZED_VALUE. Storport initializes this member and miniport drivers must not modify it.
DmaPortThe DMA port used by a subordinate HBA. By default, the value of this member is SP_UNINITIALIZED_VALUE. Storport initializes this member and miniport drivers must not modify it.
DmaWidthWidth of DMA transfers if the HBA uses DMA. By default, the value of this member is zero. Storport initializes this member and miniport drivers must not modify it.
DmaSpeedThe DMA data-transfer speed for Eisa HBAs. Storport initializes this member and miniport drivers must not modify it.
AlignmentMaskMask indicating the alignment restrictions for buffers required by the HBA for transfer operations. Some example valid mask values are 0 (byte aligned), 1 (word aligned), 3 (DWORD aligned) and 7 (double DWORD aligned). The miniport driver should set this mask if the HBA supports scatter/gather. The following allowed alignment mask values are defined in wdm.h:
| Value | Meaning |
|---|---|
| FILE_BYTE_ALIGNMENT (0x00000000) | Data is byte aligned (no alignment requirements for the device) |
| FILE_WORD_ALIGNMENT (0x00000001) | Data must be aligned on a 2-byte boundary. |
| FILE_LONG_ALIGNMENT (0x00000003) | Data must be aligned on a 4-byte boundary. |
| FILE_QUAD_ALIGNMENT (0x00000007) | Data must be aligned on an 8-byte boundary. |
| FILE_OCTA_ALIGNMENT (0x0000000f) | Data must be aligned on a 16-byte boundary. |
| FILE_32_BYTE_ALIGNMENT (0x0000001f) | Data must be aligned on a 32-byte boundary. |
| FILE_64_BYTE_ALIGNMENT (0x0000003f) | Data must be aligned on a 64-byte boundary. |
| FILE_128_BYTE_ALIGNMENT (0x0000007f) | Data must be aligned on a 128-byte boundary. |
| FILE_256_BYTE_ALIGNMENT (0x000000ff) | Data must be aligned on a 256-byte boundary. |
| FILE_512_BYTE_ALIGNMENT (0x000001ff) | Data must be aligned on a 512-byte boundary. |
NumberOfAccessRangesSpecifies the number of AccessRanges elements in the array.
AccessRangesPointer to an array of ACCESS_RANGE-type elements. Storport allocates memory for the access ranges and initializes this member. Miniport drivers must not modify this member.
MiniportDumpDataPointer to a dump context used during a crashdump or a hibernation.
ReservedReserved for system use (pre-Windows 8).
NumberOfBusesNumber of buses controlled by the adapter. By default, the value of this member is zero. This member has a maximum value of SCSI_MAXIMUM_BUSES_PER_ADAPTER. This member is available starting in Windows 8.
InitiatorBusIdThe initiator bus ID. If the input InitiatorBusId[0] has the value SP_UNINITIALIZED_VALUE, the miniport driver 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 driver should use any nonzero value assigned by the port driver if possible. Typically, this value is bounded by the value set for MaximumNumberOfTargets.
ScatterGatherWhen TRUE, the HBA supports scatter/gather. Storport initializes this member to TRUE because its miniport drivers must support scatter/gather. Miniport drivers that work with Storport must not modify this value. (NOTE: in Windows versions prior to Windows Server 2008 R2 and Windows 7, this member is set to FALSE. In this case, miniport drivers must set this member to TRUE. Not setting this member to TRUE will cause the HBA device to fail to start.)
MasterWhen TRUE, the HBA is a master bus. Storport initializes this member to TRUE because its miniport drivers must support bus-mastering DMA. Miniport drivers that work with Storport must not modify this value. (NOTE: in Windows versions prior to Windows Server 2008 R2 and Windows 7, this member is set to FALSE. In this case, miniport drivers must set this member to TRUE. Not setting this member to TRUE will cause the HBA device to fail to start.)
CachesDataWhen TRUE, the HBA caches data or maintains cached state on the peripherals. When FALSE, the HBA does not cache data or maintain cached state on the peripherals. By default, the value of this member is FALSE. If this is reset to TRUE, Storport notifies the miniport driver when certain system events occur, such as file system cache flushes.
AdapterScansDownStorport ignores this member.
AtdiskPrimaryClaimedStorport does not use this member, and its miniport drivers must not set it.
AtdiskSecondaryClaimedStorport does not use this member, and its miniport drivers must not set it.
Dma32BitAddressesWhen TRUE, the HBA has 32 address lines and can access memory with physical addresses greater than 0x00FFFFFF. Storport initializes this member to TRUE, because its miniport drivers must support bus-width DMA. Miniport drivers must not modify this value since this is the default DMA addressing if a value for Dma64BitAddresses is not set. NOTE: If only 32-bit addresses are supported by the device hardware, then Dma64BitAddresses must be set to 0.
DemandModeIndicates whether the system DMA controller should be programmed for demand-mode rather than single-cycle operations. Storport initializes this member to FALSE, because it does not support subordinate-mode DMA. Miniport drivers must not modify this value.
MapBuffersIndicates whether Storport maps SRB data buffer addresses to system virtual addresses. The miniport driver sets this member to one of the following values to control mapping for SRB data buffer addresses.
| Value | Meaning |
|---|---|
| STOR_MAP_NO_BUFFERS | Maps the buffer only for SRB_FUNCTION_IO_CONTROL and SRB_FUNCTION_WMI. |
| STOR_MAP_ALL_BUFFERS | Obsolete. This value has the same effect as STOR_MAP_NON_READ_WRITE_BUFFERS. |
| STOR_MAP_NON_READ_WRITE_BUFFERS | Maps the buffer for all IO except for read and write requests. |
| STOR_MAP_ALL_BUFFERS_INCLUDING_READ_WRITE | Maps the buffer for all IO including read and write requests. Miniports supporting boot must handle a read or write request of PAGE_SIZE in length. These read or write requests must always complete successfully. Storport may fail to map the buffer under low system memory conditions. In this case, the DataBuffer member in the SRB will be NULL. |
NeedPhysicalAddressesWhen TRUE, the miniport driver must translate virtual addresses to physical addresses, as required by the HBA. Storport initializes this member to TRUE, because its miniport drivers must support scatter/gather lists. Miniport must not modify this value.
TaggedQueuingWhen TRUE, the HBA supports queuing of multiple requests with SCSI tags. Storport initializes this member to TRUE because its miniport drivers must support tagged-queuing. Miniport drivers must not modify this value.
AutoRequestSenseWhen TRUE, the HBA supports auto request sense. Storport initializes this member to TRUE because its miniport drivers must support auto-request sense. Miniport drivers must not modify this value.
MultipleRequestPerLuWhen TRUE, the HBA supports multiple requests per logical unit. Storport initializes this member to TRUE because its miniport drivers must support multiple requests issued to a logical unit at time. Miniport drivers must not modify this value.
ReceiveEventStorport does not use this member, and its miniport drivers must not set it.
RealModeInitializedStorport does not use this member, and its miniport drivers must not set it.
BufferAccessScsiPortControlledStorport does not use this member, and its miniport drivers must not set it.
MaximumNumberOfTargetsNumber of target peripherals the adapter can control. By default, the value of this member is SCSI_MAXIMUM_TARGETS_PER_BUS. A miniport driver 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 extended bus capabilities. The maximum value for this member is 255.
SrbTypeType of SRBs to be sent to the miniport driver. Available starting in Windows 8. This is set to one of the following values:
| Value | Meaning |
|---|---|
| SRB_TYPE_SCSI_REQUEST_BLOCK | The miniport driver receives standard SRBs. |
| SRB_TYPE_STORAGE_REQUEST_BLOCK | The miniport driver receives extended SRBs. |
AddressTypeAddress type used between Storport and the miniport driver. Available starting in Windows 8. This can be set to the following value:
| Value | Meaning |
|---|---|
| STORAGE_ADDRESS_TYPE_BTL8 | Bus, Target, and LUN (BTL) 8-bit addressing. |
ReservedUcharsReserved for system use (pre-Windows 8).
SlotNumberReserved for use by Storport. Miniport drivers must not modify this member.
BusInterruptLevel2Reserved for use by Storport. Miniport drivers must not modify this member.
BusInterruptVector2Reserved for use by Storport. Miniport drivers must not modify this member.
InterruptMode2Reserved for use by Storport. Miniport drivers must not modify this member.
DmaChannel2Reserved for use by Storport. Miniport drivers must not modify this member.
DmaPort2Reserved for use by Storport. Miniport drivers must not modify this member.
DmaWidth2Reserved for use by Storport. Miniport drivers must not modify this member.
DmaSpeed2Reserved for use by Storport. Miniport drivers must not modify this member.
DeviceExtensionSizeSize, in bytes, required by the miniport driver for its per-adapter device extension. A miniport driver uses its device extension as storage for driver-determined HBA information. The operating system-specific port driver initializes each device extension one time, when it first allocates the extension, and fills it with zeros. It passes a pointer to the HBA-specific device extension in every call to a miniport driver. The given size does not include any miniport driver-requested per-logical-unit storage. The size of per-logical-unit storage is specified via the SpecificLuExtensionSize field, described later in this topic.
Storport does not follow SCSIPort's model (which re-initializes the device extension whenever the adapter is stopped and thus subsequent calls to HwScsiFindAdapter receive a zeroed-out device extension). Rather, Storport resets the device extension to zero only when it is first allocated, so only the first call to HwStorFindAdapter for a given adapter receives a zeroed-out device extension. Subsequent calls to HwStorFindAdapter and other miniport functions receive the device extension as last modified by the miniport driver. This allows the miniport driver to maintain knowledge about the state of the adapter between Plug and Play (PnP) stops and restarts, possibly enabling the miniport driver to optimize its initialization procedure.
SpecificLuExtensionSizeSize in bytes required by the miniport driver for its per-logical-unit-storage, if any, to handle data transfers larger than 64K. Storport initializes this member to the value in the same member of the HW_INITIALIZATION_DATA structure sent in the StorPortInitialize routine.
Set this member to zero if the miniport driver does not maintain per-LU information for which it requires storage. This value is based on the assumption that the HBA is able to receive 32-bit addresses, regardless of what the controller can actually support. If additional space is needed in the LUN or SRB extensions to handle 64-bit addresses, then appropriate adjustments must be made to this value before using it with routines such as StorPortGetUncachedExtension.
SrbExtensionSizeSize in bytes required by the miniport driver for its per-request storage, if any, to handle data transfers larger than 64K. Storport initializes this member to the value in the same member of the HW_INITIALIZATION_DATA structure sent in the StorPortInitialize routine.
Set this member before calling StorPortGetUncachedExtension to change the size of per-request storage based on NumberOfPhysicalBreaks. Set this member to zero if the miniport driver does not maintain per-SRB information for which it requires storage. This value is based on the assumption that the HBA is able to receive 32-bit addresses, regardless of what the controller can actually support. If additional space is needed in the LUN or SRB extensions to handle 64-bit addresses, then appropriate adjustments must be made to this value before using it with routines such as ScsiPortGetUncachedExtension.
Dma64BitAddressesIf the device hardware supports only 32 bit addresses, then Dma64BitAddresses must be set to 0. If the device supports 64 bit addresses, this field indicates whether the HBA is able to access addresses greater than 4 GB.
Storport adapters are required to support bus-width DMA. Therefore, on a 64-bit or PAE machine, Storport initializes Dma64BitAddresses to SCSI_DMA64_SYSTEM_SUPPORTED indicating that the adapter can access the full range of addresses. When miniport drivers detect this value, they must return one of the values in the following table in the same member to indicate to the port driver that the miniport driver supports 64-bit DMA. If the miniport fails to do this, it might severely degrade the performance of the adapter.
| Value | Meaning |
|---|---|
| SCSI_DMA64_MINIPORT_SUPPORTED | The miniport driver supports 64-bit physical addresses for I/O transfers. |
| SCSI_DMA64_MINIPORT_FULL64BIT_SUPPORTED | The miniport driver supports full 64-bit addressing. This indicates that I/O requests may have physical addresses > 4GB. The uncached extension, SenseInfo, and Srb Extension may exist above 4GB. Allocations are restricted to 4GB boundary alignment in order to prevent them from crossing a 4GB boundary. |
| SCSI_DMA64_MINIPORT_FULL64BIT_NO_BOUNDARY_REQ_SUPPORTED | The miniport driver supports full 64-bit addressing. This indicates that I/O requests may have physical addresses > 4GB. The uncached extension, SenseInfo, and Srb Extension may exist above 4GB. Allocations have no boundary alignment requirement. |
| SCSI_DMA64_MINIPORT_64BIT_ONE_4GB_SUPPORTED | The miniport driver support 64-bit addressing in a single 4GB region. This indicates that I/O requests, uncached extension, SenseInfo, and Srb Extension may have physical addresses > 4GB in a single 4GB region. |
ResetTargetSupportedObsolete. Do not use this member.
MaximumNumberOfLogicalUnitsMaximum number of logical units per target that the HBA can control. By default, the value of this member is SCSI_MAXIMUM_LOGICAL_UNITS. A miniport driver 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 extended capabilities. The maximum value for this member is SCSI_MAXIMUM_LUNS_PER_TARGET.
WmiDataProviderWhen TRUE, the miniport driver responds to Windows Management Instrumentation (WMI) requests. Storport initializes this member to TRUE because its miniport drivers must support WMI. Additionally, miniport drivers for fibre channel adapters are expected to support the SAN Management HBA API through WMI, and miniport drivers for host-based RAID adapters are required to support the RAID Management Interface.
Miniport drivers must not modify this value.
SynchronizationModelThe I/O synchronization model that the miniport driver supports. Possible values are as follows:
| Value | Meaning |
|---|---|
| StorSynchronizeFullDuplex | The miniport supports full-duplex mode. |
| StorSynchronizeHalfDuplex | The miniport supports half-duplex mode. |
HwMSInterruptRoutinePointer to the miniport driver's HwMSInterruptRoutine routine, which is required for any miniport driver of an HBA that generates message signaled interrupts (MSIs). A miniport driver sets this member to NULL if the HBA does not generate MSIs.
InterruptSynchronizationModeAn INTERRUPT_SYNCHRONIZATION_MODE value that specifies the interrupt synchronization mode. The interrupt synchronization mode determines how the port driver synchronizes message signaled interrupts.
DumpRegionA MEMORY_REGION structure that describes a region of physically contiguous memory that miniport drivers can use during a crash dump or hibernation.
RequestedDumpBufferSizeSize in bytes of the uncached extension to be allocated for use during dump/hibernation.
VirtualDeviceWhen TRUE, there is no real hardware behind this device (for example, no DMA object, interrupt, I/O ports). Storport behaves differently in some circumstances when it supports a "virtual" miniport instead of a miniport that is controlling real hardware.
DumpModeIndicates the use of the miniport during dump mode. It can have one of the following values.
| Value | Meaning |
|---|---|
| DUMP_MODE_CRASH | The miniport in dump mode is used for a crashdump. |
| DUMP_MODE_HIBER | The miniport in dump mode is used for a hibernation. |
| DUMP_MODE_MARK_MEMORY | The miniport in dump mode is used for marking required memory. |
| DUMP_MODE_RESUME | The miniport in dump mode is used for a resume from hibernation. |
DmaAddressWidthThe width of an adapter's DMA address. Miniports must specify STOR_ADAPTER_DMA_ADDRESS_WIDTH_SPECIFIED in FeatureSupport when providing this value. The specified value must be (0 < DmaAddressWidth <= 64). This field can be used starting in Windows 10, version 2004.
ExtendedFlags1Reserved for system use.
MaxNumberOfIOMaximum number of outstanding I/O operations supported by the HBA. The default is set to 1000 by Storport. If the HBA does not support 1000 outstanding I/O operations, the miniport should adjust this to an appropriate smaller value.
If the HBA can support more than 1000 outstanding I/O operations, the miniport can increase this member to any value supported by the adapter hardware. To allow more than 1000 outstanding I/O operations, the HBA must support one of the following 64-bit DMA addressing methods, set in the Dma64BitAddresses field:
MaxIOsPerLunMaximum number of I/O requests supported on a LUN. Storport will set this to a default value of 255. If a LUN does not support 255 outstanding I/O requests, the miniport should adjust this member to an appropriate smaller value. This member must be <= MaxNumberOfIO. To support MaxIOsPerLun > 255, the SrbType field must be set to SRB_TYPE_STORAGE_REQUEST_BLOCK. Available starting in Windows 8.
InitialLunQueueDepthThe initial LUN I/O queue depth. Storport set this to a default value of 20 for physical miniports and to 250 for virtual miniports. This member adjusts the initial queue depth for all LUNs on the adapter. The queue depth for an individual LUN is set by calling StorPortSetDeviceQueueDepth. This member is typically set to the same value as MaxIOsPerLun. Available starting in Windows 8.
BusResetHoldTimeThe amount of time, in microseconds, to pause the adapter after a reset is detected. Set this value to 0 if no wait time is needed after a bus reset. Available starting in Windows 8.
FeatureSupportStorport features requested for the adapter. Available starting in Windows 8. A miniport driver can set this member to be a bitwise mask of any of the following values:
| Value | Meaning |
|---|---|
| STOR_ADAPTER_FEATURE_DEVICE_TELEMETRY 0x00000001 | The miniport driver supports storage device telemetry. |
| STOR_ADAPTER_FEATURE_STOP_UNIT_DURING_POWER_DOWN 0x00000002 | The miniport requests to receive the STOP_UNIT command during system shutdown. |
| STOR_ADAPTER_UNCACHED_EXTENSION_NUMA_NODE_PREFERRED 0x00000004 | The miniport driver wants UncachedExtension to be allocated from adapter NUMA node. |
| STOR_ADAPTER_DMA_V3_PREFERRED 0x00000008 | The miniport driver prefers to use DMA V3 kernel API for the adapter. |
| STOR_ADAPTER_FEATURE_ABORT_COMMAND 0x00000010 | The miniport driver supports the ability to abort an outstanding command via SRB_FUNCTION_ABORT_COMMAND. |
| STOR_ADAPTER_FEATURE_RICH_TEMPERATURE_THRESHOLD 0x00000020 | The adapter supports richer temperature threshold information than defined in SCSI SPC4 spec. |
| STOR_ADAPTER_DMA_ADDRESS_WIDTH_SPECIFIED 0x00000040 | The miniport driver specified the DMA address width in DmaAddressWidth for the adapter. This value was added in Windows 10, version 2004. |
| STOR_ADAPTER_FEATURE_UNIQUE_QUEUEING_TAG 0x00000080 | The miniport driver supports unique queueing tags for I/O operations. This value was added in Windows 11, version 24H2. |
The Storport driver allocates and initializes this structure, supplies as much HBA-specific configuration information as possible, and passes the structure to the miniport driver's HwStorFindAdapter routine. Storport does not support non-PnP devices, so HwStorFindAdapter does not search for the adapter. Its principal function is to initialize PORT_CONFIGURATION_INFORMATION.
INTERRUPT_SYNCHRONIZATION_MODE
PORT_CONFIGURATION_INFORMATION describes the hardware settings of a streaming minidriver's device. The class driver fills in most members with information provided by the operating system.
SizeOfThisPacketThe size of this structure, in bytes. The class driver fills in this member.
HwDeviceExtensionPointer to the minidriver's device extension. The minidriver may use this buffer to record private information global to the minidriver. The minidriver sets the size of this buffer in the HW_INITIALIZATION_DATA structure it passes when it registers itself via StreamClassRegisterMinidriver. The class driver also passes pointers to this buffer in the HwDeviceExtension member of the HW_STREAM_OBJECT, HW_STREAM_REQUEST_BLOCK, and HW_TIME_CONTEXT structures it passes to the minidriver.
ClassDeviceObjectPoints to the class-driver-provided functional device object (FDO) for the driver's device.
PhysicalDeviceObjectPoints to the device object for the driver at the top of the driver stack when the class driver attaches to the driver stack. Drivers use this member when calling IoCallDriver to communicate with the driver stack. The RealPhysicalDeviceObject member points to the actual PDO for the driver's device.
SystemIoBusNumberThe class driver fills in this member with the system bus ID number of the device. Bus 0 is the primary system bus.
AdapterInterfaceTypeSpecifies the type of system bus the device is connected to. Possible values include Isa, Eisa, MicroChannel, PCIBus, and PCMCIABus.
BusInterruptLevelThe class driver fills in this member with the IRQL for interrupts on this bus.
BusInterruptVectorThe class driver fills in this member with the interrupt vector used by the device.
InterruptModeThe class driver fills in this member with the interrupt mode, either Latched or LevelSensitive.
DmaChannelIf the device connects to the ISA bus, the class driver fills in this member with the DMA channel of the device.
NumberOfAccessRangesThe number of entries in the AccessRanges array.
AccessRangesThe number of entries in the AccessRanges array.
StreamDescriptorSizeThe minidriver fills in this member with the size of its HW_STREAM_DESCRIPTOR structure.
IrpPointer to the PnP device start IRP that triggered this SRB_INITIALIZE_DEVICE request.
InterruptObjectIf the device uses interrupts, the class driver fills in this member with a pointer to the associated Interrupt object.
DmaAdapterObjectIf the device uses DMA, the class driver fills in this member with a pointer to the associated DmaAdapter object.
RealPhysicalDeviceObjectPointer to the PDO for the driver's device.
ReservedReserved for system use. Do not use.
Most of the members of PORT_CONFIGURATION_INFORMATION provide information to the minidriver about its use of hardware resources, such as its interrupt vector and the IRQL for its interrupts.