HW_RESET_BUS callback function (storport.h)

Article
07/29/2021

The HwStorResetBus routine is called by the port driver to clear error conditions.

Syntax

HW_RESET_BUS HwResetBus;

BOOLEAN HwResetBus(
  PVOID DeviceExtension,
  ULONG PathId
)
{...}

Parameters

DeviceExtension

A pointer to the miniport driver's per HBA storage area.

PathId

Identifies the SCSI bus to be reset.

Return value

If the bus is successfully reset, HwStorResetBus returns TRUE.

Remarks

The name HwStorResetBus is just a placeholder. The actual prototype of this routine is defined in Storport.h as follows:

typedef
BOOLEAN
HW_RESET_BUS (
  _In_ PVOID  DeviceExtension,
  _In ULONG  PathId
  );

The port driver pauses all device IO queues for the adapter and then calls the HwStorResetBus routine at IRQL DISPATCH_LEVEL after acquiring the StartIo spin lock. A miniport driver is responsible for completing SRBs received by HwStorStartIo for PathId during this routine and setting their status to SRB_STATUS_BUS_RESET if necessary.

In addition to the StartIo spin lock being taken and subsequently released after HwStorResetBus returns, if the miniport has requested multiple channel support through PERF_CONFIGURATION_DATA, all channel tokens will be taken and, on return of the callback, released. This ensures that no IO’s are dispatched to HwStorStartIo during the reset bus phase.

Examples

To define an HwStorResetBus callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define a HwStorResetBus callback routine that is named MyHwResetBus, use the HW_RESET_BUS type as shown in this code example:

HW_RESET_BUS MyHwResetBus;

Then, implement your callback routine as follows:

_Use_decl_annotations_
BOOLEAN
MyHwResetBus (
  _In_ PVOID  DeviceExtension,
  _In_ ULONG  PahtId
  );
  {
      ...
  }

The HW_RESET_BUS function type is defined in the Storport.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the HW_RESET_BUS function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions Using Function Role Types for Storport Drivers. For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Target Platform	Universal
Header	storport.h (include Storport.h)
IRQL	DISPATCH_LEVEL (See Remarks section.)

Share via