PGET_SCATTER_GATHER_LIST_EX Rückruffunktion (wdm.h)

Artikel
02/29/2024

Die GetScatterGatherListEx-Routine ordnet 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.

Achtung

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 Bus-master DMA-Gerät des Treibers darstellt. Der Aufrufer hat diesen Zeiger aus einem vorherigen Aufruf der 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 Adapterzuordnungsanforderungen eindeutig sein. Um eine ausstehende Zuordnungsanforderung abzubrechen, muss der Aufrufer den DMA-Übertragungskontext für die Anforderung an die CancelAdapterChannel-Routine angeben.

[in] Mdl

Ein Zeiger auf eine MDL-Kette, der das layout der physischen Seite für eine Sammlung gesperrter Puffer im virtuellen Speicher beschreibt. Die Punkt-/Erfassungsliste für die DMA-Übertragung verwendet den Bereich dieses Arbeitsspeichers, 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 Scatter/Gather-DMA-Übertragung. Dieser Parameter ist ein Byteoffset vom Anfang des Puffers in der ersten MDL in der MDL-Kette. Wenn die MDLs in der MDL-Kette insgesamt N Byte Pufferspeicherplatz angeben, liegen gültige Werte von Offset im Bereich von 0 bis N–1.

[in] Length

Die Länge der DMA-Übertragung in Bytes. Wenn die MDL-Kette insgesamt N Bytes Pufferraum angibt, liegen die gültigen Werte für Length im Bereich von 1 bis N–Offset.

[in] Flags

Die Adapterkanalzuordnungsflags. Das folgende Flag wird unterstützt:

Flag	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 flag DMA_SYNCHRONOUS_CALLBACK festgelegt ist, ist der ExecutionRoutine-Parameter optional und kann NULL sein. Wenn dieses Flag nicht festgelegt ist, muss ExecutionRoutine ein gültiger Zeiger sein, der nicht NULL ist. Weitere Informationen zu diesem Flag 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 diesem Objekt zugeordnet wurden.

Wenn das flag DMA_SYNCHRONOUS_CALLBACK festgelegt ist, ist der 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 nach der Rückgabe von GetScatterGatherListEx durchzuführen. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[in, optional] Context

Der vom Treiber bestimmte Adapter-Steuerelement-Kontext. Dieser Kontext wird als Context-Parameter an die AdapterListControl-Routine übergeben.

[in] WriteToDevice

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

[in, optional] DmaCompletionRoutine

Wird nicht verwendet. Auf NULL festgelegt.

[in, optional] CompletionContext

Wird nicht verwendet. Auf NULL festgelegt.

[out, optional] ScatterGatherList

Ein Zeiger auf eine Variable, in die die Routine einen Zeiger auf die zugeordnete Punkt-/Sammlungsliste schreibt. Dieser Parameter verweist auf eine SCATTER_GATHER_LIST-Struktur . Die Routine ordnet 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 flag DMA_SYNCHRONOUS_CALLBACK festgelegt ist und der ExecutionRoutine-ParameterNULL ist, muss ScatterGatherList ein gültiger Zeiger ohne NULL sein. Wenn ExecutionRoutine nicht NULL ist, ist ScatterGatherList optional und kann NULL sein, wenn der aufrufende Treiber die Scatter/Gather-Liste nicht erfordert. Der GetScatterGatherListEx-Aufruf schlägt fehl, wenn das flag DMA_SYNCHRONOUS_CALLBACK festgelegt ist und ScatterGatherList und ExecutionRoutinebeide NULL sind, oder wenn das flag DMA_SYNCHRONOUS_CALLBACK nicht festgelegt ist und ExecutionRoutineNULL ist.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETERS	Fehler bei der Routine aufgrund ungültiger Parameterwerte, die vom Aufrufer übergeben wurden.
STATUS_INSUFFICIENT_RESOURCES	Die Routine konnte die für die DMA-Übertragung erforderlichen Ressourcen nicht zuordnen.

Hinweise

GetScatterGatherListEx ist keine Systemroutine, die direkt nach Namen aufgerufen werden kann. Diese Routine kann nur durch den 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 der Version-Member des DeviceDescription-Parameters auf DEVICE_DESCRIPTION_VERSION3 festgelegt ist. Wenn IoGetDmaAdapterNULL zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

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

Der Treiber eines Bus-master-Geräts kann GetScatterGatherListEx verwenden, um die Vorgänge, die von den Routinen AllocateAdapterChannelEx und MapTransferEx ausgeführt werden, 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 Parameter Mdl, Offset und Length .
Ruft die vom Treiber bereitgestellte AdapterListControl-Routine auf und stellt die Scatter/Gather-Liste an diese 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 flag DMA_SYNCHRONOUS_CALLBACK festgelegt ist), kann die AdapterListControl-Routine weggelassen werden. In diesem Fall verwendet der Aufrufer die zugeordneten Ressourcen, um die DMA-Übertragung nach der Rückgabe von GetScatterGatherListEx zu initiieren. Der Aufrufer muss diese Ressourcen explizit freigeben.

Standardmäßig gibt GetScatterGatherListEx asynchron zurück, ohne auf den Abschluss der angeforderten Ressourcenzuordnung zu warten. Nach dieser Rückgabe kann der Aufrufer die ausstehende Zuordnungsanforderung bei Bedarf abbrechen, indem er die CancelAdapterChannel-Routine aufruft.

Wenn der aufrufende Treiber das flag DMA_SYNCHRONOUS_CALLBACK 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 Scatter-/Gather-Liste und ruft die AdapterListControl-Routine nicht auf. Stattdessen schlägt GetScatterGatherListEx fehl und gibt STATUS_INSUFFICIENT_RESOURCES zurück.
Der Treiber muss keine AdapterListControl-Routine bereitstellen, wenn das flag DMA_SYNCHRONOUS_CALLBACK 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ückgegeben wird.
Wenn der Treiber keine AdapterListControl-Routine angibt, kann der Treiber die zugeordneten Ressourcen und die Scatter/Gather-Liste verwenden, nachdem GetScatterGatherListEx zurückgegeben wurde. In diesem Fall muss der Treiber einen gültigen ScatterGatherList-Zeiger bereitstellen, der nicht NULL ist. 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 zugewiesen hat.

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 Scatter/Gather-Liste zuordnet.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL