This topic has not yet been rated - Rate this topic

HwStorStartIo routine

The Storport driver calls the HwStorStartIo routine one time for each incoming I/O request.

Syntax


HW_STARTIO HwStorStartIo;

BOOLEAN HwStorStartIo(
  IN PVOID DeviceExtension,
  IN PSCSI_REQUEST_BLOCK Srb
)
{ ... }

Parameters

DeviceExtension: A pointer to the miniport driver's per HBA storage area.
Srb: A pointer to the SCSI request block to be started.

Return value

HwStorStartIo returns TRUE if the request was successfully initiated. Otherwise, it returns FALSE.

Remarks

HwStorStartIo initiates an I/O operation. StorPort is designed to use miniport private data that is prepared in HwStorBuildIo and stored in either the DeviceExtension or Srb->SrbExtension. Because HwStorBuildIo is called without spin locks, the best driver performance is achieved by preparing as much data as possible in HwStorBuildIo.

Storport calls HwStorStartIo in the following ways:

For storage non-virtual miniport drivers, depending on the value of SynchronizationModel set in PORT_CONFIGURATION_INFORMATION, Storport always calls HwStorStartIo the same IRQL and uses an internal spin lock to ensure that I/O requests are initiated sequentially. The IRQL is either DISPATCH_LEVEL (full-duplex mode) or DIRQL (half-duplex mode).

When handling I/O in half-duplex mode, the HwStorStartIo routine does not have to acquire its own spin lock. Also, memory allocation using StorPortAllocatePool and mutual exclusion via StorPortAcquireSpinLock are not allowed in the HwStorStartIo routine. In full-duplex mode, StorPortAllocatePool and StorPortAcquireSpinLock may be used in the HwStorStartIo routine.

If a non-virtual miniport supports the concurrent channels optimization (STOR_PERF_CONCURRENT_CHANNELS set by StorPortInitializePerfOpts), multiple calls to HwStorStartIo concurrently are possible. In this case, the miniport will need to ensure that any shared resources are protected by a lock. With this performance optimization, Storport will not acquire the StartIo lock prior to calling HwStorStartIo and the miniport must provide its own lock if required.
For storage virtual miniport drivers, Storport calls HwStorStartIo at any IRQL <= DISPATCH_LEVEL and does not use an internal spin lock. The HwStorStartIo routine may acquire its own spin lock by calling StorPortAcquireSpinLock. Also, calls to StorPortAllocatePool are allowed in the HwStorStartIo routine of a storage virtual miniport driver.

SRBs that are created by HwStorStartIo are expected to complete within the timeout value that is specified in the SRB TimeoutValue field. If a request is not completed in the specified time, it will be completed by Storport and the logical unit, target, and bus will be reset by using new SRBs.

The SRB is expected to be completed when SCSI status is received. When the Storport driver completes the SRB by calling StorPortNotification with a NotificationType of RequestComplete, an SRB is expected to return one of the following values in the SrbStatus field of the Srb:

Status	Indicates	StorPort Action	Miniport action
SRB_STATUS_SUCCESS	The Srb was sent and SCSI status (possibly with data) was returned.	Returns the data and status to the caller.	None, except to complete the request by using StorPortNotification for RequestComplete, probably from the HwStorDpcRoutine.
SRB_STATUS_PENDING	The Srb has been sent, but status has not been received.	Re-queues the same Srb and recalls HwStorStartIo.	Check progress when HwStorStartIo is called and return either SRB_STATUS_PENDING or SRB_STATUS_SUCCESS.
SRB_STATUS_BUSY	There is a temporary problem with sending the Srb (for example, adapter registers or buffers are busy).	Discards the original Srb and issues a new Srb, including calls to HwStorBuildIo and HwStorStartIo. All data in the SrbExtension will be lost.	Because a new SRB is issued, the miniport must make sure that it never issues SRB_STATUS_BUSY in the middle of a SCSI transaction. After the transaction is started, it must be completed or canceled. Hardware busy states during the transaction must be handled by the miniport driver.

The name HwStorStartIo is a placeholder to describe the miniport routine set in the HwStartIo member of HW_INITIALIZATION_DATA structure. This structure is passed in the HwInitializationData parameter of StorPortInitialize. The actual prototype of this routine is defined in Storport.h as follows:


typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

Starting in Windows 8, the Srb parameter may point to either SCSI_REQUEST_BLOCK or STORAGE_REQUEST_BLOCK. If the function identifier in the Function field of Srb is SRB_FUNCTION_STORAGE_REQUEST_BLOCK, the SRB is a STORAGE_REQUEST_BLOCK request structure.

Examples

To define a HwStorStartIo callback routine, you must first provide a function declaration that Static Driver Verifier (SDV) and other verification tools require, as shown in the following code example:


HW_STARTIO MyHwStartIo;

Then, implement your callback routine as follows:


BOOLEAN
MyHwStartIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

The HW_STARTIO function type is defined in the Storport.h header file. For more information about SDV requirements for function declarations, see Declaring Functions Using Function Role Types for Storport Drivers.

Requirements

Header	Storport.h (include Storport.h)
IRQL	DISPATCH_LEVEL (See Remarks section.)