HW_INITIALIZATION_DATA structure (storport.h)

Artikel
12/07/2021

The HW_INITIALIZATION_DATA (Storport) structure contains information particular to each miniport driver and the hardware that the miniport driver manages.

Syntax

typedef struct _HW_INITIALIZATION_DATA {
  ULONG                       HwInitializationDataSize;
  INTERFACE_TYPE              AdapterInterfaceType;
  PHW_INITIALIZE              HwInitialize;
  PHW_STARTIO                 HwStartIo;
  PHW_INTERRUPT               HwInterrupt;
  PVOID                       HwFindAdapter;
  PHW_RESET_BUS               HwResetBus;
  PHW_DMA_STARTED             HwDmaStarted;
  PHW_ADAPTER_STATE           HwAdapterState;
  ULONG                       DeviceExtensionSize;
  ULONG                       SpecificLuExtensionSize;
  ULONG                       SrbExtensionSize;
  ULONG                       NumberOfAccessRanges;
  PVOID                       Reserved;
  UCHAR                       MapBuffers;
  BOOLEAN                     NeedPhysicalAddresses;
  BOOLEAN                     TaggedQueuing;
  BOOLEAN                     AutoRequestSense;
  BOOLEAN                     MultipleRequestPerLu;
  BOOLEAN                     ReceiveEvent;
  USHORT                      VendorIdLength;
  PVOID                       VendorId;
  union {
    USHORT ReservedUshort;
    USHORT PortVersionFlags;
  };
  USHORT                      DeviceIdLength;
  PVOID                       DeviceId;
  PHW_ADAPTER_CONTROL         HwAdapterControl;
  PHW_BUILDIO                 HwBuildIo;
  PHW_FREE_ADAPTER_RESOURCES  HwFreeAdapterResources;
  PHW_PROCESS_SERVICE_REQUEST HwProcessServiceRequest;
  PHW_COMPLETE_SERVICE_IRP    HwCompleteServiceIrp;
  PHW_INITIALIZE_TRACING      HwInitializeTracing;
  PHW_CLEANUP_TRACING         HwCleanupTracing;
  PHW_TRACING_ENABLED         HwTracingEnabled;
  ULONG                       FeatureSupport;
  ULONG                       SrbTypeFlags;
  ULONG                       AddressTypeFlags;
  ULONG                       Reserved1;
  PHW_UNIT_CONTROL            HwUnitControl;
} HW_INITIALIZATION_DATA, *PHW_INITIALIZATION_DATA;

Members

HwInitializationDataSize

Specifies the size of this structure in bytes, as returned by sizeof(HW_INITIALIZATION_DATA). In effect, this member indicates the version of this structure being used by the miniport driver. A miniport driver's DriverEntry routine should set this member's value for the port driver.

AdapterInterfaceType

The Storport driver does not support legacy buses. Therefore, most of the adapter interface types used with the SCSI Port driver are invalid for Storport. In particular, Isa, Eisa, MicroChannel, and TurboChannel are not supported. Furthermore, unlike the SCSI Port case, a miniport driver that works with the Storport driver is not required to supply values for the VendorIdLength, VendorId, DeviceIdLength, and DeviceId members.

HwInitialize

Pointer to the miniport driver's HwStorInitialize routine, which is a required entry point for all miniport drivers.

HwStartIo

Pointer to the miniport driver's HwStorStartIo routine, which is a required entry point for all miniport drivers.

HwInterrupt

Pointer to the miniport driver's HwStorInterrupt routine, which is a required entry point for all miniport drivers.

HwFindAdapter

Pointer to the miniport driver's HwStorFindAdapter routine, which is a required entry point for all miniport drivers.

HwResetBus

Pointer to the miniport driver's HwStorResetBus routine, which is a required entry point for all miniport drivers.

HwDmaStarted

The Storport driver does not support subordinate-mode DMA. Therefore, this member must be NULL.

HwAdapterState

The Storport driver does not support legacy drivers. Therefore, this member must be NULL.

DeviceExtensionSize

Specifies the size, 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 host bus adapter (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.

Although SCSIPort re-initializes the device extension whenever the adapter is stopped and thus subsequent calls to HwScsiFindAdapter receive a zeroed-out device extension, Storport does not follow that model. 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. 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.

SpecificLuExtensionSize

Specifies the size in bytes required by the miniport driver for its per-logical-unit storage, if any. A miniport driver can use its LU extensions as storage for driver-determined logical-unit information about peripherals on the bus. The Storport driver initializes each LU extension it allocates with zeros. 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 StorPortGetUncachedExtension.

SrbExtensionSize

Specifies the size, in bytes, required by the miniport driver for its per-request storage, if any. A miniport driver can use SRB extensions as storage for driver-determined, request-specific information, such as data necessary to process a particular request. The Storport driver does not initialize SRB extensions, but sets a pointer to this storage in each SRB it sends to the miniport driver. An SRB extension can be safely accessed by the HBA hardware. Because miniport drivers that work with the Storport driver must support scatter/gather lists, and the per-SRB scatter/gather lists are usually allocated in the SRB extension, this member is rarely zero. 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 StorPortGetUncachedExtension.

NumberOfAccessRanges

Specifies how many access ranges the adapter uses. Each is a range either of memory addresses or I/O port addresses.

Reserved

Reserved for system use and not available for use by miniport drivers.

MapBuffers

Indicates whether the Storport driver maps SRB data buffer addresses to system virtual addresses. The MapBuffers member can have one of the following values.

Value	Meaning
STOR_MAP_NO_BUFFERS	Do not map for any SRB except 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	Map the buffer for all I/O except for read or write requests.
STOR_MAP_ALL_BUFFERS_INCLUDING_READ_WRITE	Map the buffer for all I/O including read and write requests. This value is valid starting with Windows 8.

NeedPhysicalAddresses

Must be set to TRUE. A value of TRUE indicates that the miniport driver must translate certain types of addresses to physical addresses. Miniport drivers that work with the Storport driver must support bus-master DMA, so they will always be required to do address translation.

TaggedQueuing

Must be set to TRUE. A value of TRUE indicates that the miniport driver supports SCSI tagged queuing. All miniport drivers that work with the Storport driver must support tagged queuing.

AutoRequestSense

Must be TRUE. A value of TRUE indicates that the HBA can perform a request-sense operation without requiring an explicit request to do so. All miniport drivers that work with the Storport driver must support SCSI Auto-Request Sense.

MultipleRequestPerLu

Must be set to TRUE. A value of TRUE indicates that the miniport driver can queue multiple requests per logical unit. Miniport drivers that work with the Storport driver must support multiple requests per logical unit.

ReceiveEvent

The Storport driver ignores this member.

VendorIdLength

The Storport driver ignores this member, because miniport drivers that work with the Storport driver must support PnP.

VendorId

The Storport driver ignores this member, because miniport drivers that work with the Storport driver must support PnP.

ReservedUshort

PortVersionFlags

Flags to indicate supported features.

DeviceIdLength

The Storport driver ignores this member, because miniport drivers that work with the Storport driver must support PnP.

DeviceId

The Storport driver ignores this member, because miniport drivers that work with the Storport driver must support PnP.

HwAdapterControl

Pointer to the miniport driver's HwStorAdapterControl routine. This is a required routine because miniport drivers that work with the Storport driver require PnP support.

HwBuildIo

Pointer to an optional HwStorBuildIo routine that the port driver calls to do unsynchronized processing prior to calling the miniport driver's HwStorStartIo routine. This callback is specific to physical miniports and should be set to NULL by virtual miniports.

HwFreeAdapterResources

A pointer to the virtual miniport driver's HwStorFreeAdapterResources routine, which is a required entry point for all virtual miniport drivers. This callback is specific to virtual miniports and is set to NULL for physical miniports.