StorPortBuildScatterGatherList-Funktion (storport.h)

Artikel
02/07/2025

Die StorPortBuildScatterGatherList Routine erstellt eine Punkt/Gather-Liste für den angegebenen Datenpuffer.

Syntax

ULONG StorPortBuildScatterGatherList(
  [in]      PVOID                        HwDeviceExtension,
  [in]      PVOID                        Mdl,
  [in]      PVOID                        CurrentVa,
  [in]      ULONG                        Length,
  [in]      PPOST_SCATTER_GATHER_EXECUTE ExecutionRoutine,
  [in]      PVOID                        Context,
  [in]      BOOLEAN                      WriteToDevice,
  [in, out] PVOID                        ScatterGatherBuffer,
  [in]      ULONG                        ScatterGatherBufferLength
);

Parameter

[in] HwDeviceExtension

Ein Zeiger auf die Hardwaregeräteerweiterung für den Hostbusadapter (HBA).

[in] Mdl

Ein Zeiger auf eine Speicherdeskriptorliste (MDL), die die dem Datenpuffer zugeordneten Speicherseiten beschreibt.

[in] CurrentVa

Die virtuelle Adresse des Datenpuffers.

[in] Length

Die Länge des Datenpuffers in Bytes.

[in] ExecutionRoutine

Ein Zeiger auf einen vom Miniporttreiber bereitgestellten ExecutionRoutine-. Der Storport-Treiber ruft diese Routine nach dem Erstellen der Punkt/Gather-Liste auf. Der Miniporttreiber sollte alle Vorgänge ausführen, die die Punkt/Gather-Liste innerhalb der Ausführungsroutine verwenden, nicht im Code, der dem Aufruf der StorPortBuildScatterGatherList Routine folgt.

Eine ExecutionRoutine- wird wie folgt deklariert:

VOID
ExecutionRoutine (
    IN PVOID  *DeviceObject,
    IN PVOID  *Irp,
    IN PSTOR_SCATTER_GATHER_LIST  ScatterGather,
    IN PVOID  Context
    );

DeviceObject

Miniport-Treiber sollten diesen Parameter ignorieren.

Irp

Miniport-Treiber sollten diesen Parameter ignorieren.

ScatterGather

Ein Zeiger auf eine STOR_SCATTER_GATHER_LIST Struktur, die die Punkt-/Gather-Liste für den angegebenen Datenpuffer enthält.

Zusammenhang

Der im StorPortBuildScatterGatherListContext Parameter der Funktion angegebene Kontextwert.

Der Storport-Treiber ruft die ExecutionRoutine eines Miniporttreibers bei IRQL = DISPATCH_LEVEL auf.

[in] Context

Ein Kontextwert, den der Porttreiber an die im ExecutionRoutine Parameter angegebene Ausführungsroutine übergibt. Die Ausführungsroutine verwendet diesen Wert, um die Anforderung eindeutig zu identifizieren.

[in] WriteToDevice

Ein Wert, der die Richtung der DMA-Übertragung angibt. Ein Wert von TRUE gibt eine Übertragung vom Datenpuffer an das Gerät an, und ein Wert von FALSE gibt eine Übertragung an, die vom Gerät zum Datenpuffer stammt.

[in, out] ScatterGatherBuffer

Ein Zeiger auf einen vom Miniport bereitgestellten Puffer, der die Punkt/Gather-Liste empfängt. Ein Miniporttreiber kann Speicher für diesen Puffer zuordnen, indem er die StorPortAllocatePool Routine aufruft.

[in] ScatterGatherBufferLength

Die Größe des Puffers in Bytes, auf den der ScatterGatherBuffer-Parameter verweist.

Rückgabewert

StorPortBuildScatterGatherList gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STOR_STATUS_NOT_IMPLEMENTED	Diese Funktion ist nicht auf dem aktiven Betriebssystem implementiert.
STOR_STATUS_SUCCESS	Gibt an, dass die Routine die Punkt/Gather-Liste erfolgreich erstellt hat. Wichtige siehe "Hinweise".
STOR_STATUS_INVALID_PARAMETER	Die übergebene HwDeviceExtension wurde NULL-.
STOR_STATUS_INVALID_IRQL	Der Aufruf wurde an einem ungültigen IRQL ausgeführt.
STOR_STATUS_INSUFFICIENT_RESOURCES	Das System verfügt über unzureichende Kartenregister für die Übertragung.
STOR_STATUS_BUFFER_TOO_SMALL	Der Parameter Length ist zu groß, um in den Puffer zu passen.

Bemerkungen

Der Miniport-Treiber ruft StorPortPutScatterGatherList- auf, um die Ressourcen freizugeben, die StorPortBuildScatterGatherList zugeordnet, während die Punkt-/Gather-Liste erstellt wird.

Der Miniporttreiber muss StorPortPutScatterGatherList- aufrufen, bevor er den für die Punkt/Gather-Liste zugewiesenen Speicher freigibt oder wiederverwendet.

Hinweis Wenn StorPortBuildScatterGatherList STOR_STATUS_SUCCESS zurückgibt, wurde der Rückruf in ExecutionRoutine erfolgreich in die Warteschlange gestellt, nachdem die Punkt-/Gather-Liste erstellt wurde. Der Miniport darf nicht davon ausgehen, dass ExecutionRoutine- aufgerufen wurde oder dass die Punkt-/Gather-Liste bereit ist, wenn StorPortBuildScatterGatherList- zurückgegeben wird. Bei Bedarf kann der Miniport die Ausführung von Code nach StorPortBuildScatterGatherList- mit dem Rückruf in ExecutionRoutine- synchronisieren, um sicherzustellen, dass die Punkt-/Gather-Liste verfügbar ist.

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Header-	storport.h (include Storport.h)
IRQL-	DISPATCH_LEVEL

Siehe auch

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList

Freigeben über