HW_ADAPTER_CONTROL回调函数 (storport.h)

项目
02/29/2024

调用微型端口驱动程序的 HwStorAdapterControl 例程以执行同步操作来控制适配器的状态或行为，例如停止或重启主机总线适配器 (用于电源管理的 HBA) 。

语法

HW_ADAPTER_CONTROL HwAdapterControl;

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

参数

[in] DeviceExtension

指向微型端口驱动程序的每个 HBA 存储区域的指针。

[in] ControlType

一个SCSI_ADAPTER_CONTROL_TYPE值，该值指定适配器控制操作，其中每个控件类型由微型端口驱动程序启动一个操作。有关详细信息 ，请参阅SCSI_ADAPTER_CONTROL_TYPE 。

[in] Parameters

指向包含与 ControlType 相关的信息的结构的指针;如果控件类型不使用结构，则为 NULL。所有结构都由调用方分配。有关详细信息 ，请参阅SCSI_ADAPTER_CONTROL_TYPE 。

返回值

根据控件类型， HwStorAdapterControl 返回以下SCSI_ADAPTER_CONTROL_STATUS值之一：

返回代码	说明
ScsiAdapterControlSuccess	微型端口驱动程序成功完成了请求的操作。目前， HwStorAdapterControl 必须为所有控件类型返回此值。
ScsiAdapterControlUnsuccessful	适配器控制操作未成功。

注解

HwStorAdapterControl 是必需函数。

Storport 在初始化 HBA 之后，但在第一个 I/O 之前，使用 ScsiQuerySupportedControlTypes 控件类型调用微型端口的 HwStorAdapterControl。微型端口驱动程序使用它支持的操作填充参数中的SCSI_SUPPORTED_CONTROL_TYPE_LIST结构。 HwStorAdapterControl 从此调用返回后，Storport 驱动程序仅为微型端口支持的操作调用微型端口驱动程序的 HwStorAdapterControl 回调。

由于使用 Storport 驱动程序的微型端口驱动程序必须支持即插即用 (PnP) ，因此微型端口必须支持 ScsiStopAdapter 和 ScsiRestartAdapter 控件类型。

下表列出了发出控件类型时获取的当前 IRQL 和旋转锁。

控件类型	IRQL	旋转锁
ScsiQuerySupportedControlTypes	PASSIVE_LEVEL	无
ScsiStopAdapter	DIRQL	InterruptLock
ScsiRestartAdapter	DIRQL	InterruptLock
ScsiSetBootConfig	PASSIVE_LEVEL	无
ScsiSetRunningConfig	PASSIVE_LEVEL	无
ScsiPowerSettingNotification	PASSIVE_LEVEL	无
ScsiAdapterPower	<= DISPATCH_LEVEL	无
ScsiAdapterPoFxPowerRequired	<= DISPATCH_LEVEL	无
ScsiAdapterPoFxPowerActive	<= DISPATCH_LEVEL	无
ScsiAdapterPoFxPowerSetFState	<= DISPATCH_LEVEL	无
ScsiAdapterPoFxPowerControl	<= DISPATCH_LEVEL	无
ScsiAdapterPrepareForBusReScan	PASSIVE_LEVEL	无
ScsiAdapterSystemPowerHints	PASSIVE_LEVEL	无
ScsiAdapterFilterResourceRequirements	< DISPATCH_LEVEL	无
ScsiAdapterPoFxMaxOperationalPower	PASSIVE_LEVEL	无
ScsiAdapterPoFxSetPerfState	<= DISPATCH_LEVEL	无
ScsiAdapterSurpriseRemoval	< DISPATCH_LEVEL	无
ScsiAdapterSerialNumber	< DISPATCH_LEVEL	无
ScsiAdapterCryptoOperation	PASSIVE_LEVEL	无
ScsiAdapterQueryFruId	PASSIVE_LEVEL	无
ScsiAdapterSetEventLogging	PASSIVE_LEVEL	无

名称 HwStorAdapterControl 只是占位符。此例程的实际原型在 storport.h 中定义，如下所示：

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

示例

若要定义 HwStorAdapterControl 回调函数，必须首先提供一个函数声明，用于标识要定义的回调函数的类型。 Windows 为驱动程序提供一组回调函数类型。使用回调函数类型声明函数有助于驱动程序代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，并且这是编写适用于 Windows 操作系统的驱动程序的要求。

例如，若要定义名为 MyHwAdapterControl 的 HwStorAdapterControl 回调例程，请使用 HW_ADAPTER_CONTROL 类型，如以下代码示例所示：

HW_ADAPTER_CONTROL MyHwAdapterControl;

然后，按如下所示实现回调例程：

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

HW_ADAPTER_CONTROL函数类型在 Storport.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 Use_decl_annotations 注释添加到函数定义。 Use_decl_annotations批注可确保使用应用于头文件中HW_ADAPTER_CONTROL函数类型的注释。有关函数声明要求的详细信息，请参阅使用 Storport 驱动程序的函数角色类型声明函数。有关 Use_decl_annotations的信息，请参阅批注函数行为。