HW_BUILDIO Rückruffunktion (storport.h)

Artikel
02/26/2024

Die HwStorBuildIo-Routine verarbeitet den SRB mit nicht synchronisiertem Zugriff auf freigegebene Systemdatenstrukturen, bevor er 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 Empfang von E/A 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 abschließen, indem StorPortNotification mit dem Benachrichtigungstyp RequestComplete aufgerufen wird. 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 wird 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 ohne Spinsperren auf. Aus diesem Fall sind die Speicherzuordnung mithilfe von StorPortAllocatePool und der gegenseitige Ausschluss über StorPortAcquireSpinLock in HwStorBuildIo zulässig. In einer Multiprozessorumgebung kann mehr als ein HwStorBuildIo gleichzeitig aktiv sein, sodass der Miniporttreiber erforderlich ist, um den Zugriff auf Systemressourcen zu synchronisieren. Dies kann zu Konflikten führen, wenn mehrere instance von HwStorBuildIo zu einem bestimmten Zeitpunkt aktiv ist.

Durch das Abschließen zeitaufwändiger E/A-Setupaktivitäten in HwStorBuildIo anstelle von in HwStorStartIo ermöglicht der Miniporttreiber eine höhere E/A-Parallelität und verbessert daher 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 so kurzer Zeit wie möglich an den HBA senden können. Vorverarbeitete Daten und der Zustand können entweder in den Strukturen DeviceExtension oder SrbExtension gespeichert werden. Es müssen nur Änderungen an eindeutigen Teilen der DeviceExtension vorgenommen werden, da keine Sperren gehalten werden. HwStorBuildIo und HwStorStartIo erhalten die folgenden Srb-Funktionstypen:

SRB_FUNCTION_EXECUTE_SCSI: Sendet einen CDB an den angegebenen bus/target/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 eine 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 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 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 gültig.
SRB_FUNCTION_SHUTDOWN: Weist den Miniporttreiber an, alle zwischengespeicherten Daten zu leeren, um das Herunterfahren zu 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 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 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 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 Unsynchronized HwStorBuildIo Routine.

Beispiele

Um eine HwStorBuildIo-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 HwStorBuildIo-Rückrufroutine mit dem Namen 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 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 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.