HW_STARTIO Rückruffunktion (storport.h)

Artikel
08/07/2023

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.

Hinweise

HwStorStartIo initiiert einen E/A-Vorgang. StorPort ist für die Verwendung der privaten Daten eines Miniports konzipiert, die in HwStorBuildIo vorbereitet und entweder in DeviceExtension oder Srb-SrbExtension> gespeichert werden. Da HwStorBuildIo ohne Drehsperren aufgerufen wird, wird die beste Treiberleistung erreicht, indem so viele Daten wie möglich in HwStorBuildIo vorbereitet werden.

Storport ruft HwStorStartIo auf folgende Weise auf:

Für nicht virtuelle Speicher-Miniporttreiber ruft Storport je nach Wert von SynchronizationModel , der in PORT_CONFIGURATION_INFORMATION festgelegt ist, immer HwStorStartIo mit demselben IRQL auf und verwendet eine interne Spinsperre, um sicherzustellen, dass E/A-Anforderungen sequenziell initiiert werden. Der IRQL ist entweder DISPATCH_LEVEL (Vollduplexmodus) oder DIRQL (Halbduplexmodus).

Beim Verarbeiten von E/A im Halbduplexmodus muss die HwStorStartIo-Routine keine eigene Drehsperre erhalten. Außerdem sind die Speicherzuordnung mithilfe von StorPortAllocatePool und der gegenseitige 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 gleichzeitiger Kanäle unterstützt (STOR_PERF_CONCURRENT_CHANNELS durch StorPortInitializePerfOpts festgelegt), sind mehrere Aufrufe von HwStorStartIo gleichzeitig möglich. In diesem Fall muss der Miniport sicherstellen, dass alle freigegebenen Ressourcen durch eine Sperre geschützt sind. Bei dieser Leistungsoptimierung ruft Storport die StartIo-Sperre nicht ab, bevor HwStorStartIo aufgerufen wird, und der Miniport muss bei Bedarf eine eigene Sperre bereitstellen.
Bei virtuellen Speicher-Miniporttreibern ruft Storport HwStorStartIo bei jedem IRQL <= DISPATCH_LEVEL auf und verwendet keine interne Spinsperre. Die HwStorStartIo-Routine kann eine eigene Spinsperre abrufen, indem Sie StorPortAcquireSpinLock aufrufen. Außerdem sind Aufrufe von StorPortAllocatePool in der HwStorStartIo-Routine eines virtuellen Speicher-Miniporttreibers zulässig.

Es wird erwartet, dass der SRB abgeschlossen ist, wenn SCSI-status empfangen wird. Wenn der Storport-Treiber den SRB durch Aufrufen von StorPortNotification mit einem NotificationType von RequestComplete abschließt, wird erwartet, dass ein SRB einen der folgenden Werte im Feld SrbStatus des Srb zurückgibt:

SRB_STATUS_SUCCESS
- Gibt an, dass der Srb gesendet und SCSI-status (möglicherweise mit Daten) zurückgegeben wurde.
- Storport gibt die Daten zurück und status an den Aufrufer.
- Die Miniportaktion ist keine, außer zum Abschließen der Anforderung mithilfe von StorPortNotification für RequestComplete, wahrscheinlich aus der HwStorDpcRoutine.
SRB_STATUS_BUSY
- Gibt an, dass beim Senden des Srb ein temporäres Problem vorliegt (z. B. sind Adapterregister oder Puffer ausgelastet).
- Storport verwirft die ursprüngliche Srb-Erweiterung, auf die Srb-SrbExtension> verweist, und gibt eine neue aus. Storport sendet den ursprünglichen Srb mit der neu ausgestellten Srb-Erweiterung in nachfolgenden Aufrufen von 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. Hardware-Auslastungszustände während der Transaktion müssen vom Miniporttreiber verarbeitet werden.

Der Name HwStorStartIo ist ein Platzhalter, um die Miniportroutine im HwStartIo-MemberHW_INITIALIZATION_DATA Struktur zu beschreiben. 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 Srb-Parameter entweder 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.

Beispiele

Um eine HwStorStartIo-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die für die Statische Treiberüberprüfung (Static Driver Verifier , SDV) und andere Überprüfungstools erforderlich ist, wie im folgenden Codebeispiel gezeigt:

Um eine HwStorStartIo-Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückruffunktion identifiziert. 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 HwStorStartIo-Rückrufroutine namens MyHwStartIo zu definieren, 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 Headerdatei Storport.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die _Use_decl_annotations_ annotation hinzu. Stellt _Use_decl_annotations_ annotation sicher, dass die Anmerkungen verwendet werden, die auf den HW_STARTIO 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 Annotating Function Behavior.