HW_ADAPTER_CONTROL callback function (storport.h)

Article
10/21/2021

A miniport driver's HwStorAdapterControl routine is called to perform synchronous operations to control the state or behavior of an adapter, such as stopping or restarting the host bus adapter (HBA) for power management.

Syntax

HW_ADAPTER_CONTROL HwAdapterControl;

SCSI_ADAPTER_CONTROL_STATUS HwAdapterControl(
  [in] PVOID DeviceExtension,
  [in] SCSI_ADAPTER_CONTROL_TYPE ControlType,
  [in] PVOID Parameters
)
{...}

Parameters

[in] DeviceExtension

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

[in] ControlType

A SCSI_ADAPTER_CONTROL_TYPE value that specifies an adapter-control operation, where each control type initiates an action by the miniport driver. See SCSI_ADAPTER_CONTROL_TYPE for details.

[in] Parameters

Pointer to a structure or value that contains information related to the ControlType, or NULL if the control type doesn't use a structure. All structures are caller-allocated. See SCSI_ADAPTER_CONTROL_TYPE for details.

Return value

Depending on the control type, HwStorAdapterControl returns one of the following SCSI_ADAPTER_CONTROL_STATUS values:

Return code	Description
ScsiAdapterControlSuccess	The miniport driver completed the requested operation successfully. Currently, HwStorAdapterControl must return this value for all control types.
ScsiAdapterControlUnsuccessful	The adapter control operation was not successful.

Remarks

HwStorAdapterControl is a required function.

Storport calls a miniport's HwStorAdapterControl with a ScsiQuerySupportedControlTypes control type after the HBA has been initialized but before the first I/O. The miniport driver fills in the SCSI_SUPPORTED_CONTROL_TYPE_LIST structure at Parameters with the operations that it supports. After HwStorAdapterControl returns from this call, the Storport driver calls the miniport driver's HwStorAdapterControl callback only for operations supported by the miniport.

Because miniport drivers that work with the Storport driver must support Plug and Play (PnP), miniports must support the ScsiStopAdapter and ScsiRestartAdapter control types.

The following table lists the current IRQL and the spinlock acquired when the control type is issued.

Control Type	IRQL	Spin lock
ScsiQuerySupportedControlTypes	PASSIVE_LEVEL	None
ScsiStopAdapter	DIRQL	InterruptLock
ScsiRestartAdapter	DIRQL	InterruptLock
ScsiSetBootConfig	PASSIVE_LEVEL	None
ScsiSetRunningConfig	PASSIVE_LEVEL	None
ScsiPowerSettingNotification	PASSIVE_LEVEL	None
ScsiAdapterPower	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerRequired	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerActive	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerSetFState	<= DISPATCH_LEVEL	None
ScsiAdapterPoFxPowerControl	<= DISPATCH_LEVEL	None
ScsiAdapterPrepareForBusReScan	PASSIVE_LEVEL	None
ScsiAdapterSystemPowerHints	PASSIVE_LEVEL	None
ScsiAdapterFilterResourceRequirements	< DISPATCH_LEVEL	None
ScsiAdapterPoFxMaxOperationalPower	PASSIVE_LEVEL	None
ScsiAdapterPoFxSetPerfState	<= DISPATCH_LEVEL	None
ScsiAdapterSurpriseRemoval	< DISPATCH_LEVEL	None
ScsiAdapterSerialNumber	< DISPATCH_LEVEL	None
ScsiAdapterCryptoOperation	PASSIVE_LEVEL	None
ScsiAdapterQueryFruId	PASSIVE_LEVEL	None
ScsiAdapterSetEventLogging	PASSIVE_LEVEL	None

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

typedef
SCSI_ADAPTER_CONTROL_STATUS
HW_ADAPTER_CONTROL (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );

Examples

To define an HwStorAdapterControl 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 HwStorAdapterControl callback routine that is named MyHwAdapterControl, use the HW_ADAPTER_CONTROL type as shown in this code example:

HW_ADAPTER_CONTROL MyHwAdapterControl;

Then, implement your callback routine as follows:

_Use_decl_annotations_
SCSI_ADAPTER_CONTROL_STATUS
MyHwAdapterControl (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );
  {
      ...
  }

The HW_ADAPTER_CONTROL 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_ADAPTER_CONTROL 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
Minimum supported client	Windows 8
Target Platform	Universal
Header	storport.h (include Storport.h)
IRQL	See Remarks.