HW_FIND_ADAPTER Rückruffunktion (storport.h)

Artikel
08/07/2023

Die HwStorFindAdapter-Routine verwendet die angegebene Konfiguration, um zu bestimmen, ob ein bestimmter HBA unterstützt wird, und, wenn dies der Grund ist, um Konfigurationsinformationen zu diesem Adapter zurückzugeben.

Syntax

HW_FIND_ADAPTER HwFindAdapter;

ULONG HwFindAdapter(
           PVOID DeviceExtension,
  [in]     PVOID HwContext,
  [in]     PVOID BusInformation,
  [in]     PCHAR ArgumentString,
  [in/out] PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  [in]     PBOOLEAN Reserved3
)
{...}

Parameter

DeviceExtension

Stellt einen Speicherbereich pro Adapter bereit.

[in] HwContext

Auf NULL festgelegt.

[in] BusInformation

Auf NULL festgelegt.

[in] ArgumentString

Stellt eine NULL-beendete Zeichenfolge mit Kontextinformationen zum Treiber bereit.

[in/out] ConfigInfo

Stellt eine initialisierte PORT_CONFIGURATION_INFORMATION-Struktur bereit, die der Miniporttreiber während der Initialisierung verwendet.

[in] Reserved3

Ist für das System reserviert.

Rückgabewert

HwStorFindAdapter muss einen der folgenden status-Werte zurückgeben:

Rückgabecode	Beschreibung
SP_RETURN_FOUND	Gibt an, dass ein unterstützter HBA gefunden wurde und dass die HBA-relevanten Konfigurationsinformationen erfolgreich ermittelt und in der PORT_CONFIGURATION_INFORMATION-Struktur festgelegt wurden.
SP_RETURN_ERROR	Gibt an, dass ein HBA gefunden wurde, aber beim Abrufen der Konfigurationsinformationen ein Fehler aufgetreten ist. Wenn möglich, sollte ein solcher Fehler mit StorPortLogError protokolliert werden.
SP_RETURN_BAD_CONFIG	Gibt an, dass die angegebenen Konfigurationsinformationen für den Adapter ungültig waren.
SP_RETURN_NOT_FOUND	Gibt an, dass für die bereitgestellten Konfigurationsinformationen kein unterstützter HBA gefunden wurde.

Hinweise

Da der Storport-Treiber nur Plug & Play (PnP)-Geräte unterstützt, werden die Parameter HwContext und BusInformation für HwStorFindAdapter nicht für nicht virtuelle Miniporttreiber bereitgestellt.

HwStorFindAdapter muss die Felder MaximumTransferLength und NumberOfPhysicalBreaks in der ConfigInfo-Struktur festlegen. Außer diesen Feldern gibt die PORT_CONFIGURATION_INFORMATION-Struktur immer alle Adapterressourcen vollständig an, die zum Starten des Adapters erforderlich sind.

Der Name HwStorFindAdapter ist nur ein Platzhalter. Der eigentliche Prototyp dieser Routine ist in Storport.h wie folgt definiert:

typedef
ULONG
HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );

In den meisten Fällen ruft StorPort die HwStorFindAdapter-Routine bei IRQL == PASSIVE_LEVEL auf, ohne Drehsperren zu erhalten. Der Ausnahmefall ist, wenn der Miniport das Aufrufen von HwStorAdaptorControl mit dem ScsiRestartAdapter-Steuerelementtyp nicht unterstützt. In diesem Fall initialisiert StorPort stattdessen den Adapter erneut, indem sowohl HwStorFindAdapter als auch HwStorInitialize aufgerufen werden. In diesem Fall wird HwStorFindAdapter unter IRQL == DISPATCH_LEVEL aufgerufen. Außerdem wird HwStorFindAdapter im Speicherabbildmodus unter IRQL == HIGH_LEVEL aufgerufen.

Beispiele

Um eine HwStorFindAdapter-Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückruffunktion identifiziert, die Sie definieren. 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 HwStorFindAdapter-Rückrufroutine namens MyHwFindAdapter zu definieren, verwenden Sie den typ HW_FIND_ADAPTER , wie in diesem Codebeispiel gezeigt:

HW_FIND_ADAPTER MyHwFindAdapter;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
ULONG
MyHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );
  {
      ...
  }

Der HW_FIND_ADAPTER 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_FIND_ADAPTER 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.