HW_BUILDIO Rückruffunktion (storport.h)

Artikel
05/23/2024

Die HwStorBuildIo-Routine verarbeitet den SRB mit nicht synchronisiertem Zugriff auf freigegebene Systemdatenstrukturen, bevor sie an HwStorStartIo übergeben wird.

Syntax

HW_BUILDIO HwBuildio;

BOOLEAN HwBuildio(
  PVOID DeviceExtension,
  PSCSI_REQUEST_BLOCK Srb
)
{...}

Parameter

DeviceExtension

Ein Zeiger auf den Miniporttreiber pro HBA-Speicherbereich.

Srb

Ein Zeiger auf den zu verarbeitenden SCSI-Anforderungsblock (SRB).

Rückgabewert

HwStorBuildIo gibt TRUE zurück, um den Aufrufer darüber zu informieren, dass StorPort die HwStorStartIo-Routine aufrufen soll, wenn StorPort die LUN für den E/A-Empfang bereit hält. HwStorBuildIo gibt FALSE zurück, um den Aufrufer darüber zu informieren, dass der SRB nicht an HwStorStartIo übergeben werden soll. In solchen Fällen muss der Miniporttreiber den SRB durch Aufrufen von StorPortNotification mit dem Benachrichtigungstyp RequestComplete abschließen. Dies kann in HwStorBuildIo oder an einer anderen Stelle im Miniporttreiber erfolgen, solange der SRB vor dem Timeout abgeschlossen ist, das im Feld TimeOutValue der SRB-Struktur angegeben ist.

Hinweise

Der Name HwStorBuildIo ist nur ein Platzhalter für die Miniportfunktion, auf die das HwBuildIo-Element in der HW_INITIALIZATION_DATA-Struktur verweist. Der eigentliche Prototyp dieser Routine ist in Storport.h wie folgt definiert:

typedef
BOOLEAN
HW_BUILDIO (
  _In_ PVOID DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

Der Porttreiber ruft die HwStorBuildIo-Routine bei DISPATCH IRQL auf, ohne Spinsperren zu halten. Daher sind die Speicherbelegung mit StorPortAllocatePool und der gegenseitige Ausschluss über StorPortAcquireSpinLock in HwStorBuildIo zulässig. In einer Multiprozessorumgebung können mehrere HwStorBuildIo gleichzeitig aktiv sein, sodass der Miniporttreiber erforderlich ist, um den Zugriff auf Systemressourcen zu synchronisieren. Dies kann in Konflikt stehen, wenn zu einem bestimmten Zeitpunkt mehrere instance von HwStorBuildIo aktiv sind.

Durch abgeschlossene zeitaufwändige E/A-Setupaktivitäten in HwStorBuildIo statt in HwStorStartIo ermöglicht der Miniporttreiber eine höhere E/A-Parallelität und verbessert somit den E/A-Durchsatz. Für höchste Leistung wird von Miniporttreibern erwartet, dass sie in HwStorBuildIo so viele Vorverarbeitungen wie möglich ausführen, damit sie Anforderungen über HwStorStartIo in möglichst kurzer Zeit an den HBA senden können. Vorverarbeitete Daten und der Zustand können entweder in den Strukturen DeviceExtension oder SrbExtension gespeichert werden. Nur Änderungen an eindeutigen Teilen der DeviceExtension dürfen vorgenommen werden, da keine Sperren gehalten werden. HwStorBuildIo und HwStorStartIo erhalten die folgenden Srb-Funktionstypen:

SRB_FUNCTION_EXECUTE_SCSI: Sendet ein CDB an den angegebenen Bus/Ziel/Lun.
- Srb-DataTransferLength> ist für alle Cdbs gültig.
- Srb-DataBuffer> ist null für Lese- und Schreibanforderungen. Um auf die zugeordneten Daten zuzugreifen, verwenden Sie entweder StorPortGetScatterGatherList (für Dma-Übertragungen) oder StorPortGetSystemAddress (für programmgesteuerte E/A), um die Scatter Gather-Liste oder die virtuelle Adresse des Puffers abzurufen. Bei anderen Anforderungen verweist Srb-Databuffer> auf die Daten, die dem Srb zugeordnet sind.
- Srb-PathId> ist gültig und stellt die Pathid dar, die Storport in StorPortNotification (BusChange) zugewiesen wurde. Autoren von Miniporttreibern müssen pathid als Index in einer Tabelle mit Bussen innerhalb des Miniports verwenden.
- Srb-TargetId> und Srb-Lun> sind gültig.
SRB_FUNCTION_IO_CONTROL: Miniport definiert.
- Srb-DataTransferLength> und Srb-DataBuffer> sind gültig, wenn sie vom Anforderer festgelegt werden.
- Srb-PathId>, Srb-TargetId> und Srb-Lun> sind alle gültig.
SRB_FUNCTION_RESET_LOGICAL_UNIT: Setzen Sie die angegebene logische Einheit zurück (wenn das Gerät in der Lage ist).
- Srb-DataTransferLength> und Srb-DataBuffer> sind ungültig.
- Srb-PathId>, Srb-TargetId> und Srb-Lun> sind alle gültig.
SRB_FUNCTION_RESET_DEVICE: Setzen Sie das angegebene Scsi-Ziel zurück.
- Srb-DataTransferLength> und Srb-DataBuffer>, Srb-Lun> sind ungültig.
- Srb-PathId> und Srb-TargetId> sind gültig.
SRB_FUNCTION_RESET_BUS: Setzen Sie alle Ziele auf dem angegebenen SCSI-Bus zurück.
- Nur Srb-PathId> ist gültig.
SRB_FUNCTION_FLUSH: Weist den Miniporttreiber an, alle zwischengespeicherten Daten zu leeren.
- Wird nur vom Miniporttreiber ausgeführt, wenn cachesData == TRUE in der PORT_CONFIGURATION_INFORMATION-Struktur festgelegt wird.
- Srb-PathId>, Srb-TargetId> und Srb-Lun> sind alle gültig.
SRB_FUNCTION_SHUTDOWN: Weist den Miniporttreiber an, alle zwischengespeicherten Daten zu leeren, die das Herunterfahren vorbereiten.
- Wird nur vom Miniporttreiber ausgeführt, wenn cachesData == TRUE in der PORT_CONFIGURATION_INFORMATION-Struktur festgelegt wird.
- Srb-PathId>, Srb-TargetId> und Srb-Lun> sind alle gültig.
SRB_FUNCTION_DUMP_POINTERS: Stellt Informationen bereit, die für den Miniporttreiber erforderlich sind, um Absturzabbild und Ruhezustand zu unterstützen.
- Diese Anforderung wird an einen virtuellen Storport-Miniporttreiber gesendet, der zum Steuern des Datenträgers verwendet wird, der die Absturzabbilddaten enthält. Ab Windows 8 können nicht virtuelle Miniporttreiber diese Anforderung optional empfangen.
- Srb-PathId>, Srb-TargetId> und Srb-Lun> sind alle gültig.
SRB_FUNCTION_FREE_DUMP_POINTERS: Ab Windows 8 wird diese Anforderung an den Miniport gesendet, um ressourcen freizugeben, die während der SRB_FUNCTION_DUMP_POINTERS-Anforderung zugewiesen wurden.
- Srb-PathId>, Srb-TargetId> und Srb-Lun> sind alle gültig.

Ab Windows 8 kann der Srb-Parameter auf SCSI_REQUEST_BLOCK oder STORAGE_REQUEST_BLOCK verweisen. Wenn der Funktionsbezeichner im Feld Funktion von SrbSRB_FUNCTION_STORAGE_REQUEST_BLOCK ist, ist der SRB eine STORAGE_REQUEST_BLOCK Anforderungsstruktur.

Weitere Informationen dazu, was Sie in dieser Miniporttreiberroutine sicher tun können und was nicht, finden Sie unter Nicht synchronisierte HwStorBuildIo-Routine.

Beispiele

Um eine HwStorBuildIo-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 HwStorBuildIo-Rückrufroutine namens MyHwBuildIo zu definieren, verwenden Sie den typ HW_BUILDIO , wie in diesem Codebeispiel gezeigt:

HW_BUILDIO MyHwBuildIo;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
BOOLEAN
MyHwBuildIo (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );
  {
      ...
  }

Der HW_BUILDIO 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_BUILDIO 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.