PGET_SCATTER_GATHER_LIST Rückruffunktion (wdm.h)

Artikel
08/08/2023

Die GetScatterGatherList-Routine bereitet das System für einen DMA-Scatter/Gather-Vorgang im Auftrag des Zielgeräteobjekts vor, entweder über den System-DMA-Controller oder einen Bus-master-Adapter.

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 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 bei MdlAddress im aktuellen IRP beschreibt.

[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 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 System-DMA-Controller oder der Bus-master-Adapter verfügbar ist.

[in] Context

Zeiger auf den vom Treiber bestimmten Kontext, der an die AdapterListControl-Routine des Treibers ü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 .

Rückgabewert

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

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

Hinweise

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

GetScatterGatherList 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.

Sobald der entsprechende DMA-Kanal und alle erforderlichen Kartenregister verfügbar sind, erstellt GetScatterGatherList eine Scatter/Gather-Liste , initialisiert die Kartenregister und ruft dann die vom Treiber bereitgestellte AdapterListControl-Routine auf, um den E/A-Vorgang auszuführen.

GetScatterGatherList kombiniert die Aktionen der Routinen AllocateAdapterChannel und MapTransfer für Treiber, die scatter/gather 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 Scatter/Gather-Liste aus. Anschließend wird die angegebene AdapterListControl-Routine aufgerufen und ein Zeiger auf die Scatter/Gather-Liste in ScatterGather übergeben. Der Treiber sollte diesen Zeiger zur Verwendung beim Aufrufen von PutScatterGatherList beibehalten. Beachten Sie, dass GetScatterGatherList nicht über die Warteschlangeneinschränkungen verfügt, die für AllocateAdapterChannel gelten.

In seiner AdapterListControl-Routine sollte der Treiber die E/A ausführen. Bei der Rückkehr von der vom Treiber bereitgestellten Routine behält GetScatterGatherList die Kartenregister bei, gibt aber die DMA-Adapterstruktur frei. Der Treiber muss PutScatterGatherList aufrufen (wodurch die Puffer geleert 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
Unterstützte Mindestversion (Client)	Verfügbar in Windows 2000 und höheren Versionen von Windows. Wird in Windows 98 oder Windows Me nicht unterstützt.
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL
DDI-Complianceregeln	IrqlDispatch(storport), IrqlDispatch(storport), IrqlDispatch(wdm)