HwStorUnitControl routine

A miniport driver's HwStorUnitControl routine is called to perform synchronous operations to control the state of storage unit device. The miniport driver is notified to start a unit or handle a power state transition for a unit device.

Syntax


SCSI_UNIT_CONTROL_STATUS HwStorUnitControl(
  _In_  PVOID DeviceExtension,
  _In_  SCSI_ADAPTER_CONTROL_TYPE ControlType,
  _In_  PVOID Parameters
);

Parameters

DeviceExtension [in]

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

ControlType [in]

Specifies an unit control operation. Each control type initiates an action by the miniport driver. The following are the control types and their meanings.

Control TypeMeaningIRQLSpinlock

ScsiQuerySupportedUnitControlTypes

Reports the unit-control operations implemented by the miniport driver. The Storport driver calls HwStorUnitControl 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 HwStorUnitControl returns from this call, the Storport driver calls the miniport driver's HwStorUnitControl only for supported operations.

PASSIVE_LEVEL

None

ScsiUnitUsage

Notifies the miniport if the logical unit is used for any supported usage types. Storport driver will call HwStorUnitControl separately for each usage type supported.

PASSIVE_LEVEL

None

ScsiUnitStart

Notifies the miniport to start a unit device.

PASSIVE_LEVEL

None

ScsiUnitPower

Reports the unit 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.

DISPATCH_LEVEL

None

ScsiUnitPoFxPowerInfo

Notifies the miniport if idle power management is enabled or disabled on the unit component. The miniport should call StorPortInitializePoFxPower within this unit control if idle power management was enabled and it if supports runtime power management for the unit device.

PASSIVE_LEVEL

None

ScsiUnitPoFxPowerRequired

Notifies the miniport whether power is required or not for the unit component.

DISPATCH_LEVEL

None

ScsiUnitPoFxPowerActive

Notifies the miniport that the unit component is either active or idle.

DISPATCH_LEVEL

None

ScsiUnitPoFxPowerSetFState

Notifies the miniport to set the unit component to the given functional power state (F-state). The miniport must support this control type if is specifies more than one F-state in the call to StorPortInitializePoFxPower.

DISPATCH_LEVEL

None

ScsiUnitPoFxPowerControl

Requests a power engine plug-in (PEP) initiated private power control operation for the miniport to execute for the unit.

DISPATCH_LEVEL

None

 

Parameters [in]

Contains information related to the ControlType.

Control TypeParameters

ScsiQuerySupportedUnitControlTypes

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[ScsiUnitUsage]
SupportedTypeList[ScsiUnitStart]
SupportedTypeList[ScsiUnitPower]
SupportedTypeList[ScsiUnitPoFxPowerInfo]
SupportedTypeList[ScsiUnitPoFxPowerRequired]
SupportedTypeList[ScsiUintPoFxPowerActive]
SupportedTypeList[ScsiUnitPoFxPowerSetFState]
SupportedTypeList[ScsiUnitPoFxPowerControl]

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

ScsiUnitUsage

Caller-allocated STOR_UC_DEVICE_USAGE structure.


typedef struct _STOR_UC_DEVICE_USAGE {
    PSTOR_ADDRESS   Address;
    SCSI_UC_DEVICE_USAGE_TYPE   UsageType;
    BOOLEAN InUse;
} STOR_UC_DEVICE_USAGE, *PSTOR_UC_DEVICE_USAGE;


Address

The device address for the usage notification.

UsageType

The usage type from a PnP device usage notification.

InUse

TRUE if the unit is used for the type in UsageType. Otherwise, FALSE.

ScsiUnitStart

The STOR_ADDR_BTL8 address of the unit to start.

ScsiUnitPower

Caller-allocated STOR_UNIT_CONTROL_POWER structure.


typedef struct _STOR_UNIT_CONTROL_POWER {
    PSTOR_ADDRESS               Address;
    STOR_POWER_ACTION           PowerAction;
    STOR_DEVICE_POWER_STATE     PowerState;
} STOR_UNIT_CONTROL_POWER, *PSTOR_UNIT_CONTROL_POWER;


Address

The device address for the power notification.

PowerAction

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

PowerState

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

ScsiUnitPoFxPowerInfo

Caller-allocated STOR_POFX_UNIT_POWER_INFO structure.


typedef struct _STOR_POFX_UNIT_POWER_INFO {
    STOR_POWER_CONTROL_HEADER   Header;
    BOOLEAN                     IdlePowerEnabled;
} STOR_POFX_UNIT_POWER_INFO, *PSTOR_POFX_UNIT_POWER_INFO;


Header

The power control header structure.

IdlePowerEnabled

TRUE if idle power management is enabled for the unit. Otherwise, FALSE.

ScsiUnitPoFxPowerRequired

Caller-allocated STOR_POFX_POWER_REQUIRED_CONTEXT structure.


typedef struct _STOR_POFX_POWER_REQUIRED_CONTEXT {
    STOR_POWER_CONTROL_HEADER Header;
    BOOLEAN                   PowerRequired;
} STOR_POFX_POWER_REQUIRED_CONTEXT, *PSTOR_POFX_POWER_REQUIRED_CONTEXT;


Header

The power control header structure.

PowerRequired

TRUE if the unit component requires power. Otherwise, FALSE.

ScsiUintPoFxPowerActive

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 a unit device.

Active

The active status of the component. Active is set to TRUE if the unit is active. Otherwise, FALSE if idle.

ScsiUnitPoFxPowerSetFState

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 a unit device.

FState

The F-state to set for the unit component.

ScsiUnitPoFxPowerControl

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 unit.

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.

 

For the structures that contain the STOR_POWER_CONTROL_HEADER header, it has the following definition in storport.h.


typedef struct _STOR_POWER_CONTROL_HEADER {
    ULONG Version;
    ULONG Size;
    PSTOR_ADDRESS Address;
} STOR_POWER_CONTROL_HEADER, *PSTOR_POWER_CONTROL_HEADER;


Version

The version of the parent structure.

Size

The size, in bytes, of the parent structure.

Address

The address of the unit the control operation is specified for.

Return value

Depending on the control type, HwStorUnitControl returns one of the following SCSI_UNIT_CONTROL_STATUS values:

Return codeDescription
ScsiUnitControlSuccess

The miniport driver completed the requested operation successfully.

ScsiAdapterControlUnsuccessful

The unit control operation was not successful.

 

Remarks

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


typedef
SCSI_UNIT_CONTROL_STATUS
HW_UNIT_CONTROL (
  _In_ PVOID  DeviceExtension,
  _In_ SCSI_UNIT_CONTROL_TYPE  ControlType,
  _In_ PVOID  Parameters
  );

Requirements

Version

Available starting with Windows 8.

Header

Storport.h (include Storport.h)

Library

Storport.lib

See also

HwStorAdapterControl

 

 

Send comments about this topic to Microsoft

Anzeigen:
© 2014 Microsoft