HW_BUILDIO Rückruffunktion (storport.h)

Artikel
02/07/2025

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 Anrufer darüber zu informieren, dass StorPort die HwStorStartIo Routine aufrufen soll, wenn StorPort die LUN für den Empfang von E/A 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 einem Benachrichtigungstyp von RequestCompleteabschließen. Dies kann in HwStorBuildIo- oder an anderer Stelle im Miniporttreiber erfolgen, solange der SRB abgeschlossen ist, bevor das im TimeOutValue Feld der SRB-Struktur angegebene Timeoutout angegeben wird.

Bemerkungen

Der Name HwStorBuildIo ist nur ein Platzhalter für die Miniportfunktion, auf den 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 auf, ohne Drehsperren zu halten. Aus diesem Gründen sind speicherzuordnungen mit StorPortAllocatePool und gegenseitiger Ausschluss über StorPortAcquireSpinLock in HwStorBuildIozulässig. In einer Multiprozessorumgebung können mehrere HwStorBuildIo- gleichzeitig aktiv sein, sodass der Miniporttreiber zum Synchronisieren des Zugriffs auf Systemressourcen erforderlich ist, was sich möglicherweise in Einem Streit befinden kann, wenn mehrere Instanzen von HwStorBuildIo zu einem bestimmten Zeitpunkt aktiv sind.

Durch abgeschlossene zeitaufwändige E/A-Setupaktivitäten in HwStorBuildIo statt in HwStorStartIoermöglicht der Miniporttreiber eine höhere E/A-Parallelität und verbessert daher den E/A-Durchsatz. Für höchste Leistung werden Miniporttreiber in HwStorBuildIo- so viel Vorverarbeitung wie möglich ausführen, damit sie Anforderungen über HwStorStartIo- in so kurzer Zeit wie möglich an die HBA senden kann. Vorverarbeitete Daten und Der Zustand können entweder im DeviceExtension- oder in SrbExtension- Strukturen gespeichert werden. Es müssen nur Änderungen an eindeutigen Teilen der DeviceExtension- erfolgen, da keine Sperren gehalten werden. HwStorBuildIo und HwStorStartIo die folgenden Srb-Funktionstypen erhalten:

SRB_FUNCTION_EXECUTE_SCSI: Sendet eine 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) angegeben wird. 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 (sofern das Gerät fähig 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 in der PORT_CONFIGURATION_INFORMATION Struktur CachesData == TRUE 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 für das Herunterfahren vorbereiten.
- Wird nur vom Miniporttreiber ausgeführt, wenn in der PORT_CONFIGURATION_INFORMATION Struktur CachesData == TRUE 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 optional diese Anforderung 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 während der SRB_FUNCTION_DUMP_POINTERS Anforderung zugeordnete Ressourcen freizugeben.
- Srb->PathId, Srb->TargetId und Srb->Lun sind alle gültig.

Ab Windows 8 kann der parameter Srb entweder auf SCSI_REQUEST_BLOCK oder STORAGE_REQUEST_BLOCKverweisen. Wenn der Funktionsbezeichner im Feld Function von SrbSRB_FUNCTION_STORAGE_REQUEST_BLOCKist, ist der SRB eine STORAGE_REQUEST_BLOCK Anforderungsstruktur.

Weitere Informationen dazu, was Sie in dieser Miniporttreiberroutine tun können, finden Sie unter Unsynchronized HwStorBuildIo Routine.

Beispiele

Um eine HwStorBuildIo- 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 HwStorBuildIo Rückrufroutine zu definieren, die MyHwBuildIoheißt, verwenden Sie den HW_BUILDIO Typ 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 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_BUILDIO 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.