StorPortBuildScatterGatherList-Funktion (storport.h)

Artikel
02/26/2024

Die StorPortBuildScatterGatherList-Routine erstellt eine Scatter/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 Host Bus Adapter (HBA).

[in] Mdl

Ein Zeiger auf eine Speicherdeskriptorliste (Memory Descriptor List, 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 eine vom Miniporttreiber bereitgestellte ExecutionRoutine. Der Storport-Treiber ruft diese Routine auf, nachdem die Scatter/Gather-Liste erstellt wurde. Der Miniporttreiber sollte alle Vorgänge ausführen, die die Scatter/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

Miniporttreiber sollten diesen Parameter ignorieren.

Irp

Miniporttreiber sollten diesen Parameter ignorieren.

ScatterGather

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

Kontext

Der im Context-Parameter der StorPortBuildScatterGatherList-Funktion angegebene Kontextwert.

Der Storport-Treiber ruft die ExecutionRoutine eines Miniporttreibers unter 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 der Wert FALSE gibt eine Übertragung vom Gerät an den Datenpuffer an.

[in, out] ScatterGatherBuffer

Ein Zeiger auf einen vom Miniport bereitgestellten Puffer, der die Punkt-/Sammlungsliste empfängt. Ein Miniporttreiber kann Arbeitsspeicher für diesen Puffer zuweisen, 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 auf dem aktiven Betriebssystem nicht implementiert.
STOR_STATUS_SUCCESS	Gibt an, dass die Routine die Scatter/Gather-Liste erfolgreich erstellt hat. Wichtig Weitere Informationen finden Sie unter "Hinweise".
STOR_STATUS_INVALID_PARAMETER	Die übergebene HwDeviceExtension war 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 Length-Parameter ist zu groß, um in den Puffer zu passen.

Hinweise

Der Miniporttreiber ruft StorPortPutScatterGatherList auf, um die Ressourcen freizugeben, die StorPortBuildScatterGatherList beim Erstellen der Scatter/Gather-Liste zugewiesen hat.

Der Miniporttreiber muss StorPortPutScatterGatherList aufrufen, bevor der Speicher freigegeben oder wiederverwendet wird, den er für die Scatter/Gather-Liste zugewiesen hat.

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

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	storport.h (einschließlich Storport.h)
IRQL	DISPATCH_LEVEL

Weitere Informationen

STOR_SCATTER_GATHER_LIST

StorPortAllocatePool

StorPortPutScatterGatherList

Freigeben über