PBUILD_SCATTER_GATHER_LIST Rückruffunktion (wdm.h)

Artikel
02/29/2024

Die BuildScatterGatherList-Routine bereitet das System auf einen DMA-Vorgang vor, wobei ein vom Treiber bereitgestellter Puffer verwendet wird, um die Scatter/Gather-Liste zu erstellen.

Syntax

PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;

NTSTATUS PbuildScatterGatherList(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PMDL Mdl,
  [in] PVOID CurrentVa,
  [in] ULONG Length,
  [in] PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in] PVOID Context,
  [in] BOOLEAN WriteToDevice,
  [in] PVOID ScatterGatherBuffer,
  [in] ULONG ScatterGatherLength
)
{...}

Parameter

[in] DmaAdapter

Zeiger auf die DMA_ADAPTER Struktur, die von IoGetDmaAdapter zurückgegeben wird und den Bus-master-Adapter oder DMA-Controller darstellt.

[in] DeviceObject

Zeiger auf das Geräteobjekt, das das Zielgerät für den DMA-Vorgang darstellt.

[in] Mdl

Zeiger auf die MDL, die den Puffer beschreibt, der vom MdlAddress-Member des aktuellen IRP angegeben wird.

[in] CurrentVa

Zeiger auf die aktuelle virtuelle Adresse in der MDL für den Puffer, der für einen DMA-Übertragungsvorgang zugeordnet werden soll.

[in] Length

Gibt die Länge des zuzuordnenden Puffers in Bytes an.

[in] ExecutionRoutine

Zeiger auf eine vom Treiber bereitgestellte AdapterListControl-Routine, die unter IRQL = DISPATCH_LEVEL aufgerufen wird, wenn der System-DMA-Controller oder der Bus-master-Adapter verfügbar ist.

[in] Context

Zeiger auf den vom Treiber bestimmten Kontext, der an ExecutionRoutine übergeben wird, wenn er aufgerufen wird.

[in] WriteToDevice

Gibt die Richtung der DMA-Übertragung an: TRUE für eine Übertragung vom Puffer zum Gerät, andernfalls FALSE .

[in] ScatterGatherBuffer

Zeiger auf den vom Aufrufer bereitgestellten Puffer, den die Routine mit einer SCATTER_GATHER_LIST Struktur füllt.

[in] ScatterGatherLength

Gibt die Größe des Puffers in Bytes an, der im ScatterGatherBuffer-Parameter übergeben wird.

Rückgabewert

BuildScatterGatherList gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der Vorgang wurde erfolgreich abgeschlossen.
STATUS_INSUFFICIENT_RESOURCES	Das System verfügt über unzureichende Kartenregister für die Übertragung.
STATUS_BUFFER_TOO_SMALL	Die angegebene Länge ist zu groß, um in den Puffer zu passen.

Hinweise

BuildScatterGatherList ist keine Systemroutine, die direkt mit dem Namen aufgerufen werden kann. Diese Routine kann nur durch zeiger von der Adresse aufgerufen werden, die in einer DMA_OPERATIONS-Struktur zurückgegeben wird. Treiber erhalten die Adresse dieser Routine, indem Sie IoGetDmaAdapter aufrufen, wobei das Versionselement des DeviceDescription-Parameters auf DEVICE_DESCRIPTION_VERSION2 festgelegt ist. Wenn IoGetDmaAdapterNULL zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

BuildScatterGatherList führt den gleichen Vorgang wie GetScatterGatherList aus, mit dem Unterschied, dass es den Puffer verwendet, der im ScatterGatherBuffer-Parameter angegeben ist, um die von ihr erstellte Scatter/Gather-Liste aufzunehmen. Im Gegensatz dazu weist GetScatterGatherList dynamisch einen Puffer zu, der die Scatter/Gather-Liste enthält. Wenn nicht genügend Arbeitsspeicher zum Zuweisen des Puffers verfügbar ist, kann GetScatterGatherList mit einem STATUS_INSUFFICIENT_RESOURCES Fehler fehlschlagen. Treiber, die dieses Szenario vermeiden müssen, können einen Puffer vorab zuweisen, um die Scatter/Gather-Liste zu speichern, und stattdessen BuildScatterGatherList verwenden.

Ein Treiber kann die CalculateScatterGatherList-Routine verwenden, um die Größe des Puffers zu bestimmen, der zugeordnet werden soll, um die Scatter/Gather-Liste zu speichern.

Der Treiber sollte den Zeiger auf die Scatter/Gather-Liste in ScatterGatherBuffer beibehalten, damit der Treiber PutScatterGatherList aufruft. Der Treiber muss PutScatterGatherList aufrufen (wodurch die Liste geleert wird), bevor er auf die Daten in der Liste zugreifen kann.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows XP und höheren Versionen von Windows.
Zielplattform	Desktop
Kopfzeile	wdm.h (einschließen von Wdm.h)
IRQL	DISPATCH_LEVEL
DDI-Complianceregeln	IrqlDispatch(wdm)