HW_STARTIO Rückruffunktion (storport.h)

Artikel
02/07/2025

Der Storport-Treiber ruft die HwStorStartIo Routine einmal für jede eingehende E/A-Anforderung auf.

Syntax

HW_STARTIO HwStartio;

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

Parameter

DeviceExtension

Ein Zeiger auf den Miniporttreiber pro HBA-Speicherbereich.

Srb

Ein Zeiger auf den zu startenden SCSI-Anforderungsblock.

Rückgabewert

HwStorStartIo gibt TRUE zurück, wenn die Anforderung erfolgreich initiiert wurde. Andernfalls wird FALSE-zurückgegeben.

Bemerkungen

HwStorStartIo initiiert einen E/A-Vorgang. StorPort wurde entwickelt, um die privaten Daten eines Miniports zu verwenden, die in HwStorBuildIo- vorbereitet und entweder in DeviceExtension oder Srb->SrbExtensiongespeichert sind. Da HwStorBuildIo ohne Drehsperren aufgerufen wird, wird die beste Treiberleistung erreicht, indem in HwStorBuildIoso viele Daten wie möglich vorbereitet werden.

Storport ruft HwStorStartIo auf folgende Weise auf:

Bei nicht-virtuellen Miniporttreibern, abhängig vom Wert SynchronizationModel in PORT_CONFIGURATION_INFORMATIONfestgelegt, ruft Storport immer HwStorStartIo- an derselben IRQL auf und verwendet eine interne Spin-Sperre, um sicherzustellen, dass I/O-Anforderungen sequenziell initiiert werden. IrQL ist entweder DISPATCH_LEVEL (Vollduplexmodus) oder DIRQL (Halbduplexmodus).

Bei der Behandlung von E/A im Halbduplexmodus muss die HwStorStartIo Routine keine eigene Drehsperre erwerben. Außerdem sind die Speicherzuweisungen mit StorPortAllocatePool- und gegenseitiger Ausschluss über StorPortAcquireSpinLock in der HwStorStartIo- Routine nicht zulässig. Im Vollduplexmodus können StorPortAllocatePool- und StorPortAcquireSpinLock- in der HwStorStartIo Routine verwendet werden.

Wenn ein nicht virtueller Miniport die Optimierung der gleichzeitigen Kanäle unterstützt (STOR_PERF_CONCURRENT_CHANNELS durch StorPortInitializePerfOptsfestgelegt), sind mehrere Aufrufe an HwStorStartIo gleichzeitig möglich. In diesem Fall muss der Miniport sicherstellen, dass alle freigegebenen Ressourcen durch eine Sperre geschützt sind. Mit dieser Leistungsoptimierung erwirbt Storport die StartIo-Sperre nicht, bevor HwStorStartIo- aufgerufen wird, und der Miniport muss bei Bedarf eine eigene Sperre bereitstellen.
Für virtuellen Miniporttreiberwird Storport HwStorStartIo- bei einem IRQL-<= DISPATCH_LEVEL aufgerufen und verwendet keine interne Drehsperre. Die HwStorStartIo Routine kann ihre eigene Drehsperre abrufen, indem StorPortAcquireSpinLockaufgerufen wird. Außerdem sind Aufrufe von StorPortAllocatePool- in der HwStorStartIo Routine eines virtuellen Speicher-Miniporttreibers zulässig.

Der SRB wird voraussichtlich abgeschlossen, wenn der SCSI-Status empfangen wird. Wenn der Storport-Treiber den SRB durch Aufrufen von StorPortNotification mit einem NotificationType- von RequestComplete-beendet, wird erwartet, dass ein SRB einen der folgenden Werte im SrbStatus- Feld des Srb zurückgibt:

SRB_STATUS_SUCCESS
- Gibt an, dass der Srb gesendet wurde und der SCSI-Status (möglicherweise mit Daten) zurückgegeben wurde.
- Storport gibt die Daten und den Status an den Aufrufer zurück.
- Die Miniport-Aktion ist keine, außer die Anforderung mit StorPortNotification für RequestComplete-auszuführen, wahrscheinlich aus der HwStorDpcRoutine.
SRB_STATUS_BUSY
- Gibt an, dass es ein temporäres Problem beim Senden des Srb gibt (z. B. Adapterregister oder Puffer sind ausgelastet).
- Storport verwirft die ursprüngliche Srb-Erweiterung, die Srb->SrbExtension verweist und ein neues ausgibt. Storport sendet den ursprünglichen Srb mit der neu ausgestellten Srb-Erweiterung in nachfolgenden Aufrufen an HwStorBuildIo und HwStorStartIo. Alle Daten in der ursprünglichen Srb-Erweiterung gehen verloren.
- Der Miniport sollte die DataTransferLength-des Srb nicht aktualisieren.
- Da eine neue Srb-Erweiterung ausgegeben wird, muss der Miniport sicherstellen, dass er nie SRB_STATUS_BUSY in der Mitte einer SCSI-Transaktion ausgibt. Nachdem die Transaktion gestartet wurde, muss sie abgeschlossen oder abgebrochen werden. Hardwarebelastungszustände während der Transaktion müssen vom Miniporttreiber verarbeitet werden.

Der Name HwStorStartIo ist ein Platzhalter zur Beschreibung der Miniportroutine, die im HwStartIo Element der HW_INITIALIZATION_DATA Struktur festgelegt ist. Diese Struktur wird im HwInitializationData Parameter von StorPortInitializeübergeben. Der eigentliche Prototyp dieser Routine wird in Storport.h wie folgt definiert:

typedef
BOOLEAN
(*PHW_STARTIO) (
  _In_ PVOID  DeviceExtension,
  _In_ PSCSI_REQUEST_BLOCK  Srb
  );

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.

Beispiele

Um eine HwStorStartIo Rückrufroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die statische Treiberüberprüfung (SDV) und andere Überprüfungstools erforderlich ist, wie im folgenden Codebeispiel gezeigt:

Um eine HwStorStartIo 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.

Wenn Sie beispielsweise eine HwStorStartIo- Rückrufroutine definieren möchten, die MyHwStartIoheißt, verwenden Sie den HW_STARTIO Typ, und implementieren Sie Ihre Rückrufroutine wie folgt:

HW_STARTIO MyHwStartIo

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

Der HW_STARTIO Funktionstyp ist in der Storport.h Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die _Use_decl_annotations_ annotation hinzufügen. Die _Use_decl_annotations_ annotation stellt sicher, dass die Anmerkungen, die auf den HW_STARTIO Funktionstyp 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_annotations_finden Sie unter Annotating Function Behavior.