HW_ADAPTER_CONTROL Rückruffunktion (storport.h)

Artikel
02/26/2024

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 Beenden oder Neustarten des Host bus Adapters (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 HBA-Speicherbereich des Miniporttreibers.

[in] ControlType

Ein SCSI_ADAPTER_CONTROL_TYPE Wert, der einen Adaptersteuerungsvorgang angibt, bei dem jeder Steuerelementtyp eine Aktion des Miniporttreibers initiiert. Weitere Informationen finden Sie unter SCSI_ADAPTER_CONTROL_TYPE .

[in] Parameters

Zeiger auf eine Struktur oder einen Wert, der Informationen im Zusammenhang mit controlType enthält, oder NULL, wenn der Steuerelementtyp keine Struktur verwendet. Alle Strukturen werden aufruferseitig zugeordnet. Weitere Informationen finden Sie unter SCSI_ADAPTER_CONTROL_TYPE .

Rückgabewert

Abhängig vom 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.

Hinweise

HwStorAdapterControl ist eine erforderliche Funktion.

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

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

In der folgenden Tabelle sind die aktuelle IRQL und der Spinlock aufgeführt, der beim Erteilen des Steuerelementtyps abgerufen wurde.

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

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 zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückruffunktion identifiziert. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine HwStorAdapterControl-Rückrufroutine namens MyHwAdapterControl zu definieren, verwenden Sie den typ HW_ADAPTER_CONTROL , 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 ist in der Storport.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den HW_ADAPTER_CONTROL Funktionstyp in der Headerdatei angewendet 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_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.