VIRTUAL_HW_FIND_ADAPTER Rückruffunktion (storport.h)

Artikel
03/05/2024

Der virtuelle Storport-Miniport verwendet Konfigurationsinformationen, die für die VIRTUAL_HW_FIND_ADAPTER-Routine bereitgestellt werden, um sich selbst 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 ausgelagerten Speicherbereich des Miniporttreibers pro Adapter. Der betriebssystemspezifische Porttreiber weist Arbeitsspeicher zu und initialisiert diese Erweiterung mit Nullen, bevor er die VIRTUAL_HW_FIND_ADAPTER Routine des Miniports aufruft.

HwContext

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

BusInformation

Ein Zeiger auf das funktionale Geräteobjekt (Functional Device Object, 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, sofern 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 DriverEntry des Miniporttreibers im VIRTUAL_HW_INITIALIZATION_DATA festgelegt hat. VIRTUAL_HW_FIND_ADAPTER müssen alle angegebenen Informationen verwenden, um zu bestimmen, ob der vom Miniporttreiber unterstützte virtuelle HBA ist. Wenn dies der Fall ist, initialisiert und konfiguriert VIRTUAL_HW_FIND_ADAPTER diesen HBA und füllt alle fehlenden Konfigurationsinformationen aus. Wenn möglich, sollte ein Miniporttreiber Standardwerte für jeden unterstützten HBA-Typ aufweisen, falls der betriebssystemabhä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 muss einen der folgenden status Werte zurückgeben:

Rückgabecode	Beschreibung
SP_RETURN_FOUND	Es wurde ein unterstützter HBA gefunden, und die HBA-relevanten Konfigurationsinformationen wurden erfolgreich ermittelt und in der PORT_CONFIGURATION_INFORMATION-Struktur festgelegt.
SP_RETURN_ERROR	Es wurde ein HBA 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 angegebenen Konfigurationsinformationen waren für den Adapter ungültig.
SP_RETURN_NOT_FOUND	Für die bereitgestellten Konfigurationsinformationen wurde kein unterstützter HBA gefunden.

Hinweise

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

Der Porttreiber ruft den VIRTUAL_HW_FIND_ADAPTER des virtuellen Storport-Miniports unter 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 zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückruffunktion angibt. 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 Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine VIRTUAL_HW_FIND_ADAPTER Rückrufroutine namens MyVirtualHwFindAdapter zu definieren, verwenden Sie den typ VIRTUAL_HW_FIND_ADAPTER , 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 ist in der Headerdatei Storport.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzu. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den VIRTUAL_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.