HwScsiAdapterControl routine

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

Note  The SCSI port driver and SCSI miniport driver models may be altered or unavailable in the future. Instead, we recommend using the Storport driver and Storport miniport driver models.

Syntax

SCSI_ADAPTER_CONTROL_STATUS HwScsiAdapterControl(
  _In_ PVOID                     HwDeviceExtension,
  _In_ SCSI_ADAPTER_CONTROL_TYPE ControlType,
  _In_ PVOID                     Parameters
);

Parameters

HwDeviceExtension [in]

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

ControlType [in]

Specifies one of the following adapter-control operations.

• ScsiQuerySupportedControlTypes
  Reports the adapter-control operations implemented by the miniport driver. The port driver calls HwScsiAdapterControl 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 HwScsiAdapterControl returns from this call, the port driver calls the miniport driver's HwScsiAdapterControl only for supported operations.

• ScsiStopAdapter
  Shuts down the HBA. The port driver calls HwScsiAdapterControl 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 port 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 port 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 port 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 HwScsiAdapterControl 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 port driver might call HwScsiAdapterControl to stop the adapter after the HBA has already been physically removed from the system, so the miniport driver's HwScsiAdapterControl 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 port driver (re)initializes by calling its HwScsiAdapterControl and HwScsiInitialize routines, or an HBA that was stopped for power management is powered up, in which case the port driver calls the miniport driver's HwScsiAdapterControl routine with ScsiRestartAdapter or, if the miniport driver does not implement that control type, repeats the initialization sequence for the HBA.

• ScsiRestartAdapter
  Reinitializes an HBA. The port driver calls HwScsiAdapterControl 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 HwScsiInitialize 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 HwScsiFindAdapter or from HwScsiAdapterControl when the control type is ScsiSetRunningConfig, such as ScsiPortGetBusData and ScsiPortSetBusDataByOffset. 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 port driver calls the miniport driver's HwScsiFindAdapter and HwScsiInitialize 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.

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

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

• ScsiSetRunningConfig
  Restores any settings on an HBA that the miniport driver might need to control the HBA while the system is running. The port driver calls HwScsiAdapterControl 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 port driver makes this call, so the miniport driver must take care not to generate an interrupt.

  A miniport driver must implement ScsiSetRunningConfigif it must call ScsiPortGetBusData and ScsiPortSetBusDataByOffset to restore the appropriate running configuration to the HBA before it can be restarted.

Parameters [in]

If ControlType is ScsiStopAdapter, ScsiSetBootConfig, ScsiSetRunningConfig, or ScsiRestartAdapter, Parameters is NULL.

If ControlType is ScsiQuerySupportedControlTypes, Parameterspoints to a caller-allocated SCSI_SUPPORTED_CONTROL_TYPE_LIST structure, which is defined as follows:

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]

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

Return value

Depending on the control type, HwScsiAdapterControl might return one of the following SCSI_ADAPTER_CONTROL_STATUS values:

Remarks

A PnP miniport driver must implement HwScsiAdapterControl for PnP and power management operations. At a minimum, a miniport driver's HwScsiAdapterControl routine must support ScsiQuerySupportedControlTypes and ScsiStopAdapter.

A non-PnP miniport driver should set the HwScsiAdapterControl entry point to NULL in its HW_INITIALIZATION_DATA structure. PnP and power management are effectively disabled for an HBA controlled by a legacy miniport driver.

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

typedef
SCSI_ADAPTER_CONTROL_STATUS
(*PHW_ADAPTER_CONTROL) (
  IN PVOID  DeviceExtension,
  IN SCSI_ADAPTER_CONTROL_TYPE  ControlType,
  IN PVOID  Parameters
  );

For more information about the HwScsiFindAdapter routine, see SCSI Miniport Driver's HwScsiFindAdapter Routine.

Requirements

See also

HW_INITIALIZATION_DATA

HwScsiFindAdapter

HwScsiInitialize

ScsiPortGetBusData

ScsiPortSetBusDataByOffset

Send comments about this topic to Microsoft