PGET_SCATTER_GATHER_LIST Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die GetScatterGatherList Routine bereitet das System für einen DMA-Punkt/Gather-Vorgang im Auftrag des Zielgerätobjekts über den System-DMA-Controller oder einen Busmasteradapter vor.

Syntax

PGET_SCATTER_GATHER_LIST PgetScatterGatherList;

NTSTATUS PgetScatterGatherList(
  [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
)
{...}

Parameter

[in] DmaAdapter

Zeiger auf die DMA_ADAPTER Struktur, die von IoGetDmaAdapter zurückgegeben wird, die den Busmasteradapter oder DMA-Controller darstellt.

[in] DeviceObject

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

[in] Mdl

Zeigen Sie auf die MDL, die den Puffer bei MdlAddress- im aktuellen IRP beschreibt.

[in] CurrentVa

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

[in] Length

Gibt die Länge in Bytes an, die zugeordnet werden soll.

[in] ExecutionRoutine

Zeiger auf eine vom Treiber bereitgestellte AdapterListControl Routine, die bei DISPATCH_LEVEL aufgerufen wird, wenn der DMA-Controller oder der Busmasteradapter des Systems verfügbar ist.

[in] Context

Zeiger auf den vom Treiber bestimmten Kontext, der beim Aufruf an die AdapterListControl-Routine des Treibers übergeben wird.

[in] WriteToDevice

Gibt die Richtung der DMA-Übertragung an: TRUE für eine Übertragung vom Puffer auf das Gerät und ANDERENfalls FALSE.

Rückgabewert

Diese Routine kann einen der folgenden NTSTATUS-Werte zurückgeben.

Rückgabecode	Beschreibung
STATUS_SUCCESS	Der Vorgang war erfolgreich.
STATUS_INSUFFICIENT_RESOURCES	Die Routine konnte nicht genügend Arbeitsspeicher zuordnen, oder die Anzahl der für die Übertragung erforderlichen Kartenregister ist größer als der von IoGetDmaAdapterzurückgegebene Wert.
STATUS_BUFFER_TOO_SMALL	Der Puffer ist für die angeforderte Übertragung zu klein.

Bemerkungen

Die GetScatterGatherList Routine weist einen Puffer dynamisch zu, um die Punkt/Gather-Liste zu speichern. Mögliche NTSTATUS-Werte, wenn die Pufferzuordnung fehlschlägt, finden Sie im Rückgabewert.

GetScatterGatherList ist keine Systemroutine, die direkt nach Namen aufgerufen werden kann. Diese Routine kann nur durch Zeiger von der in einer DMA_OPERATIONS Struktur zurückgegebenen Adresse aufgerufen werden. Treiber rufen die Adresse dieser Routine ab, indem sie IoGetDmaAdapteraufruft.

Sobald der entsprechende DMA-Kanal und alle erforderlichen Kartenregister verfügbar sind, GetScatterGatherList erstellt eine Punkt-/Sammelliste, initialisiert die Kartenregister und ruft dann die vom Treiber bereitgestellte AdapterListControl Routine zum Ausführen des E/A-Vorgangs auf.

GetScatterGatherList kombiniert die Aktionen der AllocateAdapterChannel und MapTransfer Routinen für Treiber, die Punkt-/Sammel-DMA ausführen. GetScatterGatherList bestimmt, wie viele Kartenregister für die Übertragung erforderlich sind, weist die Kartenregister zu, ordnet die Puffer für DMA zu und füllt die Punkt-/Gather-Liste ein. Anschließend wird die bereitgestellte AdapterListControl Routine aufgerufen, wobei ein Zeiger auf die Punkt/Gather-Liste in ScatterGather-übergeben wird. Der Treiber sollte diesen Zeiger beibehalten, um ihn beim Aufrufen von PutScatterGatherListzu verwenden. Beachten Sie, dass GetScatterGatherList- nicht über die Warteschlangeneinschränkungen verfügt, die für AllocateAdapterChannelgelten.

In der AdapterListControl- Routine sollte der Treiber die E/A ausführen. Wenn Sie von der vom Treiber bereitgestellten Routine zurückkehren, behält GetScatterGatherList die Kartenregister, gibt aber die DMA-Adapterstruktur frei. Der Treiber muss PutScatterGatherList- aufrufen (wodurch die Puffer gelebt werden), bevor er auf die Daten im Puffer zugreifen kann.

Diese Routine kann verkettete MDLs verarbeiten, vorausgesetzt, die Gesamtanzahl der Kartenregister, die für alle verketteten MDLs erforderlich sind, überschreitet nicht die Anzahl der verfügbaren Kartenregister.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Verfügbar in Windows 2000 und höheren Versionen von Windows. In Windows 98 oder Windows Me nicht unterstützt.
Zielplattform-	Desktop
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL-	DISPATCH_LEVEL
DDI-Complianceregeln	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)