storport.h) (回呼函式HW_ADAPTER_CONTROL

發行項
02/26/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值：

傳回碼	Description
ScsiAdapterControlSuccess	迷你埠驅動程式已成功完成要求的作業。目前，HwStorAdapterControl 必須針對所有控件類型傳回此值。
ScsiAdapterControlUnsuccessful	配接器控制作業未成功。

備註

HwStorAdapterControl 是必要函式。

Storport 會在 HBA 初始化但第一個 I/O 之前，使用 ScsiQuerySupportedControlTypes 控制件類型呼叫迷你埠的 HwStorAdapterControl。迷你埠驅動程式會在參數中填入其支援的作業SCSI_SUPPORTED_CONTROL_TYPE_LIST結構。 在 HwStorAdapterControl 從此呼叫傳回之後，Storport 驅動程式只會針對迷你埠支援的作業呼叫 miniport 驅動程式的 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的詳細資訊，請參閱標註函式行為。