HW_ADAPTER_CONTROL callback function (storport.h)
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. |