HW_FIND_ADAPTER Rückruffunktion (storport.h)

Artikel
02/07/2025

Die HwStorFindAdapter Routine verwendet die bereitgestellte Konfiguration, um zu bestimmen, ob eine bestimmte HBA unterstützt wird und ggf. Konfigurationsinformationen zu diesem Adapter zurückgegeben werden sollen.

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

Liefert einen Speicherbereich pro Adapter.

[in] HwContext

Auf NULL festgelegt.

[in] BusInformation

Auf NULL festgelegt.

[in] ArgumentString

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

[in/out] ConfigInfo

Stellt eine initialisierte PORT_CONFIGURATION_INFORMATION Struktur zum Einsatz, die der Miniporttreiber während der Initialisierung verwendet.

[in] Reserved3

Reserviert für die Systemverwendung.

Rückgabewert

HwStorFindAdapter- muss einen der folgenden Statuswerte zurückgeben:

Rückgabecode	Beschreibung
SP_RETURN_FOUND	Gibt an, dass eine unterstützte 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 StorPortLogErrorprotokolliert werden.
SP_RETURN_BAD_CONFIG	Gibt an, dass die bereitgestellten Konfigurationsinformationen für den Adapter ungültig waren.
SP_RETURN_NOT_FOUND	Gibt an, dass für die bereitgestellten Konfigurationsinformationen keine unterstützte HBA gefunden wurde.

Bemerkungen

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

HwStorFindAdapter- müssen die felder MaximumTransferLength und NumberOfPhysicalBreaks felder in der ConfigInfo- Struktur festlegen. Abgesehen von diesen Feldern gibt die PORT_CONFIGURATION_INFORMATION-Struktur immer alle Adapterressourcen an, die zum Starten des Adapters erforderlich sind.

Der Name HwStorFindAdapter ist nur ein Platzhalter. Der eigentliche Prototyp dieser Routine wird 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 auf == PASSIVE_LEVEL ohne Drehsperren zu erwerben. Der Ausnahmefall ist, wenn der Miniport das Aufrufen HwStorAdaptorControl- mit dem ScsiRestartAdapter Steuerelementtyp nicht unterstützt. In diesem Fall wird StorPort den Adapter stattdessen erneut initialisieren, indem sowohl HwStorFindAdapter als auch HwStorInitializeaufgerufen wird. Wenn dies der Fall ist, wird HwStorFindAdapter bei IRQL aufgerufen == DISPATCH_LEVEL. Im Speicherabbildmodus wird HwStorFindAdapter auch bei IRQL aufgerufen . HIGH_LEVEL.

Beispiele

Um eine HwStorFindAdapter- 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 HwStorFindAdapter Rückrufroutine zu definieren, die MyHwFindAdapterheißt, verwenden Sie den HW_FIND_ADAPTER Typ 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 wird in der Headerdatei Storport.h 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 Funktionstyp HW_FIND_ADAPTER 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.