HW_ADAPTER_CONTROL Rückruffunktion (storport.h)

2025-02-07

Die HwStorAdapterControl Routine eines Miniporttreibers wird aufgerufen, um synchrone Vorgänge auszuführen, um den Zustand oder das Verhalten eines Adapters zu steuern, z. B. das Anhalten oder Neustarten des Hostbusadapters (HBA) für die Energieverwaltung.

Syntax

HW_ADAPTER_CONTROL HwAdapterControl;

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

Parameter

[in] DeviceExtension

Ein Zeiger auf den Miniporttreiber pro HBA-Speicherbereich.

[in] ControlType

Ein SCSI_ADAPTER_CONTROL_TYPE Wert, der einen Adaptersteuerungsvorgang angibt, wobei jeder Steuerelementtyp eine Aktion vom Miniporttreiber initiiert. Weitere Informationen finden Sie unter SCSI_ADAPTER_CONTROL_TYPE.

[in] Parameters

Zeigen Sie auf eine Struktur oder einen Wert, die Informationen zum ControlType-oder NULL enthält, wenn der Steuerelementtyp keine Struktur verwendet. Alle Strukturen sind aufrufergeteilt. Weitere Informationen finden Sie unter SCSI_ADAPTER_CONTROL_TYPE.

Rückgabewert

Je nach Steuerelementtyp gibt HwStorAdapterControl einen der folgenden SCSI_ADAPTER_CONTROL_STATUS Werte zurück:

Rückgabecode	Beschreibung
ScsiAdapterControlSuccess	Der Miniporttreiber hat den angeforderten Vorgang erfolgreich abgeschlossen. Derzeit muss HwStorAdapterControl- diesen Wert für alle Steuerelementtypen zurückgeben.
ScsiAdapterControlUnsuccessful	Der Adaptersteuerungsvorgang war nicht erfolgreich.

Bemerkungen

HwStorAdapterControl ist eine erforderliche Funktion.

Storport ruft die HwStorAdapterControl- eines Miniports mit einem ScsiQuerySupportedControlTypes Steuerelementtyp auf, nachdem die HBA initialisiert wurde, aber vor dem ersten E/A. Der Miniporttreiber füllt die SCSI_SUPPORTED_CONTROL_TYPE_LIST Struktur bei Parameters mit den unterstützten Vorgängen aus. Nachdem HwStorAdapterControl- von diesem Aufruf zurückgegeben wurde, ruft der Storport-Treiber den HwStorAdapterControl Rückruf nur für Vorgänge auf, die vom Miniport unterstützt werden.

Da Miniporttreiber, die mit dem Storport-Treiber arbeiten, Plug and Play (PnP) unterstützen müssen, müssen Miniports die ScsiStopAdapter- und ScsiRestartAdapter Steuerelementtypen unterstützen.

In der folgenden Tabelle sind die aktuellen IRQL und das Spinlock aufgeführt, das beim Ausgestellt des Steuerelementtyps abgerufen wurde.

Steuerelementtyp	IRQL	Drehsperre
ScsiQuerySupportedControlTypes-	PASSIVE_LEVEL	Nichts
ScsiStopAdapter-	DIRQL	InterruptLock
ScsiRestartAdapter-	DIRQL	InterruptLock
ScsiSetBootConfig-	PASSIVE_LEVEL	Nichts
ScsiSetRunningConfig-	PASSIVE_LEVEL	Nichts
ScsiPowerSettingNotification-	PASSIVE_LEVEL	Nichts
ScsiAdapterPower-	<= DISPATCH_LEVEL	Nichts
ScsiAdapterPoFxPowerRequired	<= DISPATCH_LEVEL	Nichts
ScsiAdapterPoFxPowerActive-	<= DISPATCH_LEVEL	Nichts
ScsiAdapterPoFxPowerSetFState-	<= DISPATCH_LEVEL	Nichts
ScsiAdapterPoFxPowerControl-	<= DISPATCH_LEVEL	Nichts
ScsiAdapterPrepareForBusReScan-	PASSIVE_LEVEL	Nichts
ScsiAdapterSystemPowerHints	PASSIVE_LEVEL	Nichts
ScsiAdapterFilterResourceRequirequirements-	< DISPATCH_LEVEL	Nichts
ScsiAdapterPoFxMaxOperationalPower	PASSIVE_LEVEL	Nichts
ScsiAdapterPoFxSetPerfState-	<= DISPATCH_LEVEL	Nichts
ScsiAdapterSurpriseRemoval-	< DISPATCH_LEVEL	Nichts
ScsiAdapterSerialNumber	< DISPATCH_LEVEL	Nichts
ScsiAdapterCryptoOperation	PASSIVE_LEVEL	Nichts
ScsiAdapterQueryFruId-	PASSIVE_LEVEL	Nichts
ScsiAdapterSetEventLogging-	PASSIVE_LEVEL	Nichts

Der Name HwStorAdapterControl ist nur ein Platzhalter. Der eigentliche Prototyp dieser Routine wird in storport.h wie folgt definiert:

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

Beispiele

Um eine HwStorAdapterControl- Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der rückruffunktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine HwStorAdapterControl Rückrufroutine zu definieren, die MyHwAdapterControlheißt, verwenden Sie den HW_ADAPTER_CONTROL Typ wie in diesem Codebeispiel gezeigt:

HW_ADAPTER_CONTROL MyHwAdapterControl;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

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

Der HW_ADAPTER_CONTROL Funktionstyp wird in der Storport.h Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den HW_ADAPTER_CONTROL Funktionstyp in der Headerdatei angewendet werden, verwendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für Storport-Treiber. Informationen zu Use_decl_annotationsfinden Sie unter Annotating Function Behavior.