HwStorAdapterControl routine

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 HBA for power management.

Syntax


HW_ADAPTER_CONTROL HwStorAdapterControl;

SCSI_ADAPTER_CONTROL_STATUS HwStorAdapterControl(
  _In_  PVOID DeviceExtension,
  _In_  SCSI_ADAPTER_CONTROL_TYPE ControlType,
  _In_  PVOID Parameters
)
{ ... }

Parameters

DeviceExtension [in]

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

ControlType [in]

Specifies an adapter-control operation. Each control type initiates an action by the miniport driver. The following are the control types and their meanings. Also listed, are the current IRQL and the spinlock acquired when the control type issued.

Control TypeMeaningIRQLSpinlock

ScsiQuerySupportedControlTypes

Reports the adapter-control operations implemented by the miniport driver. The Storport driver calls HwStorAdapterControl with this 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 it supports. After HwStorAdapterControl returns from this call, the Storport driver calls the miniport driver's HwStorAdapterControl only for supported operations.

PASSIVE_LEVEL

None

ScsiStopAdapter

Shuts down the HBA. The Storport driver calls HwStorAdapterControl with this control type when the HBA has been removed from the system, stopped for resource reconfiguration, shut down for power management, or otherwise reconfigured or disabled. The Storport driver ensures that there are no uncompleted requests and issues an SRB_FUNCTION_FLUSH request to the miniport driver before calling this routine.

The miniport driver disables interrupts on its HBA, halts all processing, (including background processing not subject to interrupts or processing of which the Storport driver is unaware, such as reconstructing fault-tolerant volumes), flushes any remaining cached data to persistent storage, and puts the HBA into a state from which it can be reinitialized or restarted.

The miniport driver should not free its resources when stopping its HBA. If the HBA was removed or stopped for PnP resource reconfiguration, the Storport driver releases resources on behalf of the miniport driver. If the HBA is shut down for power management, the miniport driver's resources are preserved so the HBA can be restarted.

After HwStorAdapterControl returns from stopping the HBA, any data structures allocated on behalf of the miniport driver for the HBA should be considered invalid until the miniport driver is asked to restart.

Note that the Storport driver might call HwStorAdapterControl to stop the adapter after the HBA has already been physically removed from the system, so the miniport driver's HwStorAdapterControl routine must not perform any operations that require the HBA to be physically present while it is stopping the HBA.

The miniport driver is not called again for the HBA until either the PnP manager requests that the HBA be started, in which case the Storport driver (re)initializes by calling its HwStorAdapterControl and HwStorInitialize routines, or an HBA that was stopped for power management is powered up, in which case the Storport driver calls the miniport driver's HwStorAdapterControl routine with ScsiRestartAdapter or, if the miniport driver does not implement that control type, repeats the initialization sequence for the HBA.

DIRQL

InterruptLock

ScsiRestartAdapter

Reinitializes an HBA. The Storport driver calls HwStorAdapterControl with this control type to power up an HBA that was shut down for power management. All resources previously assigned to the miniport driver are still available, and its device extension and logical unit extensions, if any, are intact.

The miniport driver performs the same operations as in its HwStorInitialize routine, such as setting up the HBA's registers and its initial state, if any.

The miniport driver must not call routines that can only be called from HwStorFindAdapter or from HwStorAdapterControl when the control type is ScsiSetRunningConfig, such as StorPortGetBusData and StorPortSetBusDataByOffset. If the miniport driver must call such routines to restart its HBA, it must also implement ScsiSetRunningConfig.

If the miniport driver does not implement ScsiRestartAdapter, the Storport driver calls the miniport driver's HwStorFindAdapter and HwStorInitialize routines. However, because such routines might do detection work unnecessary for restarting the HBA, such a miniport driver will not power up its HBA as quickly as a miniport driver that implements ScsiRestartAdapter.

DIRQL

InterruptLock

ScsiSetBootConfig

Restores any settings on an HBA that the BIOS might need to reboot. The Storport driver calls HwStorAdapterControl with this control type after calling this routine with ScsiStopAdapter.

A miniport driver must implement ScsiSetBootConfig if it must call StorPortGetBusData or StorPortSetBusDataByOffset before the system will be able to reboot.

PASSIVE_LEVEL

None

ScsiSetRunningConfig

Restores any settings on an HBA that the miniport driver might need to control the HBA while the system is running. The Storport driver calls HwStorAdapterControl with ScsiSetRunningConfig before calling this routine with ScsiRestartAdapter if the miniport driver implements that control type.

The HBA's interrupt is not yet connected when the Storport driver makes this call, so the miniport driver must take care not to generate an interrupt.

A miniport driver must implement ScsiSetRunningConfig if it must call StorPortGetBusData and StorPortSetBusDataByOffset to restore the appropriate running configuration to the HBA before it can be restarted.

PASSIVE_LEVEL

None

ScsiPowerSettingNotification

Notification for a registered power setting change. The Storport driver calls HwStorAdapterControl with this control type if a power setting change occurs. Miniports register for power setting notifications by calling StorPortSetPowerSettingNotificationGuids with a list of GUIDs representing the power change events of interest. This control type is valid in Windows 8 and later.

PASSIVE_LEVEL

None

ScsiAdapterPower

Reports the adapter power on or power off states. If the miniport supports this control type, it will not receive a storage request block with SRB_FUNCTION_POWER and HwStorAdapterControl is not called with the ScsiStopAdapter control type. This control type is valid in Windows 8 and later.

<= DISPATCH_LEVEL

None

ScsiAdapterPoFxPowerRequired

Notifies the miniport whether power is required or not for the adapter component. This control type is valid in Windows 8 and later.

<= DISPATCH_LEVEL

None

ScsiAdapterPoFxPowerActive

Notifies the miniport whether the adapter component is active or idle. This control type is valid in Windows 8 and later.

<= DISPATCH_LEVEL

None

ScsiAdapterPoFxPowerSetFState

Notifies the miniport to set the adapter component to the given F-state. This control type is valid in Windows 8 and later.

<= DISPATCH_LEVEL

None

ScsiAdapterPoFxPowerControl

Requests a power engine plug-in (PEP) initiated private power control operation for the miniport to execute for the adapter. This control type is valid in Windows 8 and later.

<= DISPATCH_LEVEL

None

ScsiAdapterPrepareForBusReScan

Notifies the miniport to prepare the adapter for bus enumeration. The miniport should power on the adapter and all connected devices to allow the bus enumeration operation to find the devices. This control type is valid in Windows 8 and later.

PASSIVE_LEVEL

None

ScsiAdapterSystemPowerHints

Notifies the miniport system power hints. This control type is valid in Windows 8 and later.

PASSIVE_LEVEL

None

 

Parameters [in]

Contains information related to the ControlType.

Control TypeParameters

ScsiQuerySupportedControlTypes

Caller-allocated SCSI_SUPPORTED_CONTROL_TYPE_LIST structure.


typedef struct _SCSI_SUPPORTED_CONTROL_TYPE_LIST { 
    IN ULONG MaxControlType;
    OUT BOOLEAN SupportedTypeList[0];
} SCSI_SUPPORTED_CONTROL_TYPE_LIST, *PSCSI_SUPPORTED_CONTROL_TYPE_LIST;

MaxControlType

Specifies the number of entries in the SupportedTypeList array.

SupportedTypeList

Points to a caller-allocated array of BOOLEAN values that indicate the control types implemented by the miniport driver. The port driver initializes each element to FALSE.

The miniport driver sets the corresponding array element to TRUE for each operation it supports:

SupportedTypeList[ScsiQuerySupportedControlTypes]
SupportedTypeList[ScsiStopAdapter]
SupportedTypeList[ScsiRestartAdapter]
SupportedTypeList[ScsiSetBootConfig]
SupportedTypeList[ScsiSetRunningConfig]
SupportedTypeList[ScsiPowerSettingNotification]
SupportedTypeList[ScsiAdapterPower]
SupportedTypeList[ScsiAdapterPoFxPowerRequired]
SupportedTypeList[ScsiAdapterPoFxPowerActive]
SupportedTypeList[ScsiAdapterPoFxPowerSetFState]
SupportedTypeList[ScsiAdapterPoFxPowerControl]
SupportedTypeList[ScsiAdapterPrepareForBusReScan]
SupportedTypeList[ScsiAdapterSystemPowerHints]

The miniport driver must not set any element beyond SupportedTypeList[MaxControlType - 1].

ScsiStopAdapter

NULL

ScsiRestartAdapter

NULL

ScsiSetBootConfig

NULL

ScsiSetRunningConfig

NULL

ScsiPowerSettingNotification

Caller-allocated STOR_POWER_SETTING_INFO structure.


typedef struct _STOR_POWER_SETTING_INFO {
    GUID  PowerSettingGuid;
    PVOID Value;
    ULONG ValueLength;
} STOR_POWER_SETTING_INFO, *PSTOR_POWER_SETTING_INFO;


PowerSettingGuid

The GUID of the power setting that changed.

Value

Data representing the new value for the power setting.

ValueLength

Length in bytes of the data pointed to by Value.

ScsiAdapterPower

Caller-allocated STOR_ADAPTER_CONTROL_POWER structure.


typedef struct _STOR_ADAPTER_CONTROL_POWER {
    STOR_POWER_CONTROL_HEADER   Header;
    STOR_POWER_ACTION           PowerAction;
    STOR_DEVICE_POWER_STATE     PowerState;
} STOR_ADAPTER_CONTROL_POWER, *PSTOR_ADAPTER_CONTROL_POWER;


Header

The power control header structure.

PowerAction

The power action indicator. For a runtime power transition, PowerAction set to StorPowerActionNone.

PowerState

The current adapter power state. This is either StorPowerDeviceD0 or StorPowerDeviceD3 for the power on or power of states respectively.

ScsiAdapterPoFxPowerRequired

A BOOLEAN which is TRUE if the adapter component requires power. Otherwise, FALSE.

ScsiAdapterPoFxPowerActive

Caller-allocated STOR_POFX_ACTIVE_CONTEXT structure.


typedef struct _STOR_POFX_ACTIVE_CONTEXT {
    STOR_POWER_CONTROL_HEADER   Header;
    ULONG                       ComponentIndex;
    BOOLEAN                     Active;
} STOR_POFX_ACTIVE_CONTEXT, *PSTOR_POFX_ACTIVE_CONTEXT;


Header

The power control header structure.

ComponentIndex

Index of the device component with the active status. The component index is always 0 for an adapter.

Active

The active status of the component. Active is always set to TRUE.

ScsiAdapterPoFxPowerSetFState

Caller-allocated STOR_POFX_FSTATE_CONTEXT structure.


typedef struct _STOR_POFX_FSTATE_CONTEXT {
    STOR_POWER_CONTROL_HEADER   Header;
    ULONG                       ComponentIndex;
    ULONG                       FState;
} STOR_POFX_FSTATE_CONTEXT, *PSTOR_POFX_FSTATE_CONTEXT;


Header

The power control header structure.

ComponentIndex

Index of the device component with the active status. The component index is always 0 for an adapter.

FState

The F-state to set for the adapter component. The F0 state is the only component power state set for an adapter.

ScsiAdapterPoFxPowerControl

Caller-allocated STOR_POFX_POWER_CONTROL structure.


typedef struct _STOR_POFX_POWER_CONTROL {
    STOR_POWER_CONTROL_HEADER   Header;
    LPCGUID                     PowerControlCode;
    SIZE_T                      InBufferSize;
    SIZE_T                      OutBufferSize;
    PVOID                       InBuffer;
    PVOID                       OutBuffer;
    PSIZE_T                     BytesReturned;
} STOR_POFX_POWER_CONTROL, *PSTOR_POFX_POWER_CONTROL;


Header

The power control header structure.

PowerControlCode

A power control code GUID identifying the private control private control operation to execute for the adapter.

InBufferSize

The size, in bytes, of the input buffer at InBuffer.

OutBufferSize

The size, in bytes, of the output buffer at OutBuffer.

InBuffer

The buffer containing input parameters and data for the private power control call.

OutBuffer

The buffer where the resulting output parameters and data are returned for the private power control call.

BytesReturned

The size, in bytes, of the data returned in OutBuffer.

ScsiAdapterPrepareForBusReScan

NULL

ScsiAdapterSystemPowerHints

Caller-allocated STOR_SYSTEM_POWER_HINTS structure.


typedef struct _STOR_SYSTEM_POWER_HINTS {
    ULONG Version;
    ULONG Size;
    RAID_SYSTEM_POWER SystemPower;
    ULONG ResumeLatencyMSec;
} STOR_SYSTEM_POWER_HINTS, *PSTOR_SYSTEM_POWER_HINTS;


TermDescription
VersionThe version of this structure. Currently set to STOR_SYSTEM_POWER_HINTS_V1.
SizeThe size of this structure. Set to sizeof(STOR_SYSTEM_POWER_HINTS).
SystemPowerA system power usage indicator. This is one of the following values.
RaidSystemPowerUnknown

Unknown power usage.

RaidSystemPowerLowest

Lowest power usage.

RaidSystemPowerLow

Low power usage.

RaidSystemPowerMedium

Medium power usage.

RaidSystemPowerHigh

High power usage.

ResumeLatencyMSecThe resume latency, in milliseconds, of the device.

 

 

Return value

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

Return codeDescription
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

Because miniport drivers that work with the Storport driver must support Plug and Play (PnP), this function is required. The control types, ScsiStopAdapter and ScsiRestartAdapter, must be supported.

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

Header

Storport.h (include Storport.h)

See also

HwStorFindAdapter
HwStorInitialize
StorPortGetBusData
StorPortSetBusDataByOffset
StorPortSetPowerSettingNotificationGuids

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft