VIRTUAL_HW_FIND_ADAPTER Rückruffunktion (storport.h)

2025-02-07

Der virtuelle Storport-Miniport verwendet Konfigurationsinformationen, die der VIRTUAL_HW_FIND_ADAPTER Routine bereitgestellt werden, um sich weiter zu initialisieren.

Syntax

VIRTUAL_HW_FIND_ADAPTER VirtualHwFindAdapter;

ULONG VirtualHwFindAdapter(
  PVOID DeviceExtension,
  PVOID HwContext,
  PVOID BusInformation,
  PVOID LowerDevice,
  PCHAR ArgumentString,
  PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  PBOOLEAN Again
)
{...}

Parameter

DeviceExtension

Ein Zeiger auf den Nicht-Seitenspeicherbereich des Miniporttreibers pro Adapter. Der betriebssystemspezifische Porttreiber weist Speicher für diese Erweiterung mit Nullen zu und initialisiert diese Erweiterung, bevor sie die VIRTUAL_HW_FIND_ADAPTER Routine des Miniports aufruft.

HwContext

Ein Zeiger auf die PDO im Gerätestapel. Die HBA selbst ist die FDO. Der PDO gehört möglicherweise zum Pci.sys Treiber, wenn der Miniporttreiber physische Hardware steuert. Im Falle eines virtuellen Miniporttreibers gehört der PnP-Manager jedoch zum PnP-Manager.

BusInformation

Ein Zeiger auf das funktionale Geräteobjekt (FDO) des Miniports.

LowerDevice

Ein Zeiger auf das Geräteobjekt, das vom FDO des Miniports gesteuert wird.

ArgumentString

Ein Zeiger auf eine MIT NULL beendete ASCII-Zeichenfolge. Diese Zeichenfolge enthält, falls angegeben, Geräteinformationen aus der Registrierung, z. B. einen Basisparameter.

ConfigInfo

Ein Zeiger auf eine PORT_CONFIGURATION_INFORMATION Struktur. Der Porttreiber initialisiert diese Struktur mit allen bekannten Konfigurationsinformationen, z. B. Werten, die der Miniporttreiber DriverEntry im VIRTUAL_HW_INITIALIZATION_DATAfestgelegt. VIRTUAL_HW_FIND_ADAPTER müssen alle bereitgestellten Informationen verwenden, um festzustellen, ob der virtuelle HBA, den er beschreibt, einer ist, den der Miniporttreiber unterstützt. In diesem Fall initialisiert und konfiguriert VIRTUAL_HW_FIND_ADAPTER die HBA und füllt fehlende Konfigurationsinformationen aus. Wenn möglich, sollte ein Miniporttreiber Standardwerte für jeden unterstützten HBA-Typ aufweisen, falls der vom Betriebssystem abhängige Porttreiber keine zusätzlichen Konfigurationsinformationen bereitstellen kann, die nicht von der DriverEntry Routine des Miniporttreibers bereitgestellt wurden.

Again

Wird nicht verwendet.

Rückgabewert

VIRTUAL_HW_FIND_ADAPTER müssen einen der folgenden Statuswerte zurückgeben:

Rückgabecode	Beschreibung
SP_RETURN_FOUND	Es wurde eine unterstützte HBA gefunden und die HBA-relevanten Konfigurationsinformationen wurden erfolgreich ermittelt und in der PORT_CONFIGURATION_INFORMATION-Struktur festgelegt.
SP_RETURN_ERROR	Ein HBA wurde gefunden, aber beim Abrufen der Konfigurationsinformationen ist ein Fehler aufgetreten. Wenn möglich, sollte ein solcher Fehler mit ScsiPortLogError-protokolliert werden.
SP_RETURN_BAD_CONFIG	Die bereitgestellten Konfigurationsinformationen waren für den Adapter ungültig.
SP_RETURN_NOT_FOUND	Für die bereitgestellten Konfigurationsinformationen wurde keine unterstützte HBA gefunden.

Bemerkungen

Das feld VirtualDevice in der Konfigurationsinformationsstruktur muss auf TRUE-festgelegt werden. Andere Felder können nach Bedarf festgelegt werden.

Der Porttreiber ruft die VIRTUAL_HW_FIND_ADAPTER von Storport bei PASSIVE_LEVEL auf.

Der Name VirtualHwStorFindAdapter ist Platzhaltertext für den tatsächlichen Routinenamen. Der eigentliche Prototyp dieser Routine wird in Srb.h wie folgt definiert:

typedef
ULONG
VIRTUAL_HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_ PVOID  LowerDevice,
  _In_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _Out_ PBOOLEAN Again
  );

Beispiele

Um eine VIRTUAL_HW_FIND_ADAPTER 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 VIRTUAL_HW_FIND_ADAPTER Rückrufroutine zu definieren, die MyVirtualHwFindAdapterheißt, verwenden Sie den VIRTUAL_HW_FIND_ADAPTER Typ, wie in diesem Codebeispiel gezeigt:

VIRTUAL_HW_FIND_ADAPTER MyVirtualHwFindAdapter;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
ULONG
MyVirtualHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_ PVOID  LowerDevice,
  _In_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _Out_ PBOOLEAN Again
  );
  {
      ...
  }

Der VIRTUAL_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 VIRTUAL_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.