PGET_SCATTER_GATHER_LIST_EX Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die GetScatterGatherListEx Routine weist die Ressourcen zu, die für eine DMA-Übertragung erforderlich sind, erstellt eine Punkt-/Gather-Liste und ruft die vom Treiber bereitgestellte AdapterListControl Routine auf, um die DMA-Übertragung zu initiieren.

Vorsicht

Rufen Sie diese Routine nicht für ein System-DMA-Gerät auf.

Syntax

PGET_SCATTER_GATHER_LIST_EX PgetScatterGatherListEx;

NTSTATUS PgetScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PSCATTER_GATHER_LIST *ScatterGatherList
)
{...}

Parameter

[in] DmaAdapter

Ein Zeiger auf eine DMA_ADAPTER Struktur. Diese Struktur ist das Adapterobjekt, das das Busmaster-DMA-Gerät des Treibers darstellt. Der Aufrufer hat diesen Zeiger aus einem vorherigen Aufruf an die IoGetDmaAdapter Routine abgerufen.

[in] DeviceObject

Ein Zeiger auf eine DEVICE_OBJECT Struktur. Diese Struktur ist das physische Geräteobjekt (PDO), das das Zielgerät für den angeforderten DMA-Vorgang darstellt.

[in] DmaTransferContext

Ein Zeiger auf einen initialisierten DMA-Übertragungskontext. Dieser Kontext wurde durch einen vorherigen Aufruf der InitializeDmaTransferContext Routine initialisiert. Dieser Kontext muss für alle Adapterzuweisungsanforderungen eindeutig sein. Um eine ausstehende Zuordnungsanforderung abzubrechen, muss der Aufrufer den DMA-Übertragungskontext für die Anforderung an die CancelAdapterChannel Routine bereitstellen.

[in] Mdl

Ein Zeiger auf eine MDL-Kette, die das physische Seitenlayout für eine Sammlung gesperrter Puffer im virtuellen Speicher beschreibt. Die Punkt/Gather-Liste für die DMA-Übertragung verwendet den Bereich dieses Speichers, der durch die parameter Offset und Length angegeben wird. Weitere Informationen zu MDL-Ketten finden Sie unter Verwenden von MDLs.

[in] Offset

Der Startoffset für die XY/Gather-DMA-Übertragung. Dieser Parameter ist ein Byte-Offset vom Anfang des Puffers in der ersten MDL in der MDL-Kette. Wenn die MDLs in der MDL-Kette eine Gesamtmenge von N Bytes Pufferspeicher angeben, befinden sich gültige Werte von Offset- im Bereich 0 bis N-1.

[in] Length

Die Länge der DMA-Übertragung in Bytes. Wenn die MDL-Kette insgesamt N Bytes Pufferraum angibt, befinden sich gültige Werte Length im Bereich 1 bis N –Offset.

[in] Flags

Die Zuordnungskennzeichnungen des Adapterkanals. Das folgende Flag wird unterstützt:

Flagge	Bedeutung
DMA_SYNCHRONOUS_CALLBACK	Die GetScatterGatherListEx Routine wird synchron aufgerufen. Wenn dieses Flag festgelegt ist und die erforderlichen DMA-Ressourcen nicht sofort verfügbar sind, schlägt der Aufruf fehl und gibt STATUS_INSUFFICIENT_RESOURCES zurück.

Wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist, ist die ExecutionRoutine Parameter optional und kann NULL sein. Wenn dieses Flag nicht festgelegt ist, muss ExecutionRoutine- ein gültiger, nichtNULL- Zeiger sein. Weitere Informationen zu dieser Kennzeichnung finden Sie im Abschnitt "Hinweise".

[in, optional] ExecutionRoutine

Ein Zeiger auf die vom Treiber bereitgestellte AdapterListControl Routine, die die DMA-Übertragung für den Treiber initiiert. Der E/A-Manager ruft die AdapterListControl Routine auf, nachdem die erforderlichen Ressourcen für das Adapterobjekt zugeordnet wurden. Nachdem die AdapterListControl Routine zurückgegeben wurde, gibt der E/A-Manager automatisch das Adapterobjekt und die Ressourcen frei, die für dieses Objekt zugeordnet wurden.

Wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist, ist die ExecutionRoutine Parameter optional und kann NULL sein. Wenn dieser Parameter NULL ist, kann der Aufrufer die von GetScatterGatherListEx zugeordneten Ressourcen verwenden, um die DMA-Übertragung auszuführen, nachdem GetScatterGatherListEx zurückgegeben wird. Weitere Informationen finden Sie im Abschnitt "Hinweise".

[in, optional] Context

Der vom Treiber bestimmte Kontext des Adaptersteuerelements. Dieser Kontext wird als Context Parameter an die AdapterListControl Routine übergeben.

[in] WriteToDevice

Die Richtung der DMA-Übertragung. Legen Sie diesen Parameter auf TRUE für einen Schreibvorgang fest, der Daten vom Speicher an das Gerät überträgt. Legen Sie diesen Parameter auf FALSE für einen Lesevorgang fest, der Daten vom Gerät in den Arbeitsspeicher überträgt.

[in, optional] DmaCompletionRoutine

Wird nicht verwendet. Wird auf NULL-festgelegt.

[in, optional] CompletionContext

Wird nicht verwendet. Wird auf NULL-festgelegt.

[out, optional] ScatterGatherList

Ein Zeiger auf eine Variable, in die die Routine einen Zeiger in die zugeordnete Punkt/Gather-Liste schreibt. Dieser Parameter verweist auf eine SCATTER_GATHER_LIST Struktur. Die Routine weist diese Struktur und das SCATTER_GATHER_ELEMENT Array zu, auf das sie verweist.

Der ScatterGatherList Parameter ist optional und kann NULL sein, wenn der ExecutionRoutine Parameter ungleich NULL ist.

Wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist und der ExecutionRoutine Parameter NULList, muss ScatterGatherList- ein gültiger, nichtNULL- Zeiger sein. Wenn ExecutionRoutine nichtNULL-ist, ist ScatterGatherList- optional und kann NULL- werden, wenn der aufrufende Treiber die Punkt/Gather-Liste nicht erfordert. Der GetScatterGatherListEx- Aufruf schlägt fehl, wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist und ScatterGatherList- und ExecutionRoutine- beide NULL-sind, oder wenn das DMA_SYNCHRONOUS_CALLBACK Flag nicht festgelegt ist und ExecutionRoutine-NULL-ist.

Rückgabewert

GetScatterGatherListEx gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrücklaufwerte sind die folgenden Statuscodes:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETERS	Fehler der Routine aufgrund ungültiger Parameterwerte, die vom Aufrufer übergeben werden.
STATUS_INSUFFICIENT_RESOURCES	Die Routine konnte ressourcen, die für die DMA-Übertragung erforderlich sind, nicht zuordnen.

Bemerkungen

GetScatterGatherListEx ist keine Systemroutine, die direkt anhand des Namens 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 IoGetDmaAdapter- mit dem Version Mitglied des DeviceDescription- Parameters auf DEVICE_DESCRIPTION_VERSION3 festgelegt wird. Wenn IoGetDmaAdapterNULL-zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

Verwenden Sie GetScatterGatherListEx- nur für Busmasteradapter. Verwenden Sie diese Routine nicht für einen System-DMA-Adapter.

Der Treiber eines Busmastergeräts kann GetScatterGatherListEx- verwenden, um die vom AllocateAdapterChannelEx ausgeführten Vorgänge und MapTransferEx-Routinen in einem einzigen Aufruf zu kombinieren. GetScatterGatherListEx führt die folgenden Vorgänge aus:

Ordnet die Ressourcen zu, die für die DMA-Übertragung erforderlich sind.
Erstellt eine Punkt/Gather-Liste basierend auf den Werten der Mdl, Offsetund Length Parametern.
Ruft die vom Treiber bereitgestellte AdapterListControl- Routine auf und stellt die Punkt-/Gather-Liste dieser Routine als Parameter bereit.

Die zugeordneten Ressourcen werden automatisch freigegeben, nachdem die AdapterListControl Routine zurückgegeben wurde. Wenn GetScatterGatherListEx synchron aufgerufen wird (d. h. wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist), kann die AdapterListControl- Routine weggelassen werden. In diesem Fall verwendet der Aufrufer die zugeordneten Ressourcen, um die DMA-Übertragung zu initiieren, nachdem GetScatterGatherListEx zurückgegeben wird. Der Aufrufer muss diese Ressourcen explizit freigeben.

Standardmäßig wird GetScatterGatherListEx asynchron zurückgegeben, ohne auf den Abschluss der angeforderten Ressourcenzuordnung zu warten. Nach dieser Rückgabe kann der Aufrufer ggf. die ausstehende Zuordnungsanforderung abbrechen, indem die CancelAdapterChannel Routine aufgerufen wird.

Wenn der aufrufende Treiber das DMA_SYNCHRONOUS_CALLBACK Flag festlegt, verhält sich die GetScatterGatherListEx- Routine wie folgt:

Wenn die angeforderten Ressourcen nicht sofort verfügbar sind, wartet GetScatterGatherListEx- nicht auf Ressourcen, erstellt keine Punkt-/Gather-Liste und ruft nicht die AdapterListControl Routine auf. Stattdessen schlägt GetScatterGatherListEx- fehl und gibt STATUS_INSUFFICIENT_RESOURCES zurück.
Der Treiber ist nicht erforderlich, um eine AdapterListControl- Routine zu liefern, wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist.
Wenn der Treiber eine AdapterListControl Routine bereitstellt, gibt das DMA_SYNCHRONOUS_CALLBACK Flag an, dass diese Routine im Kontext des aufrufenden Threads aufgerufen werden soll, bevor GetScatterGatherListEx zurückgibt.
Wenn der Treiber keine AdapterListControl- Routine liefert, kann der Treiber die zugeordneten Ressourcen und Punkt/Sammellisten verwenden, nachdem GetScatterGatherListEx zurückgegeben wird. In diesem Fall muss der Treiber einen gültigen, nicht NULL-ScatterGatherList- Zeiger angeben. Darüber hinaus muss der Treiber, nachdem der Treiber die DMA-Übertragung initiiert hat, die FreeAdapterObject Routine aufrufen, um die Ressourcen freizugeben, die GetScatterGatherListEx- für das Adapterobjekt zugeordnet wurden.

GetScatterGatherListEx ist eine erweiterte Version der GetScatterGatherList Routine. Die folgenden Features sind nur in der erweiterten Version verfügbar:

GetScatterGatherListEx- ähnelt der BuildScatterGatherListEx Routine, mit der Ausnahme, dass GetScatterGatherListEx automatisch den Puffer für die Punkt/Gather-Liste zuweist.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Verfügbar ab Windows 8.
Zielplattform-	Desktop
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL-	<= DISPATCH_LEVEL