PGET_SCATTER_GATHER_LIST_EX Rückruffunktion (wdm.h)

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

Hinweis 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 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 zu kündigen, muss der Anrufer den DMA-Transferkontext für die Anforderung an die CancelAdapterChannel-Routine angeben.

[in] Mdl

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

[in] Offset

Der Startsatz für die Punkt-/Sammel-DMA-Übertragung. Dieser Parameter ist ein Byte-Offset vom Anfang des Puffers in der ersten MDL-Kette. Wenn die MDLs in der MDL-Kette eine Summe von N-Bytes pufferraum angeben, befinden sich gültige Werte des Offsets im Bereich 0 bis N–1.

[in] Length

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

[in] Flags

Die Adapterkanalzuordnungs-Flags. 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 DMA_SYNCHRONOUS_CALLBACK-Flag festgelegt ist, ist der ExecutionRoutine-Parameter optional und kann NULL sein. Wenn dieses Flag nicht festgelegt ist, muss ExecutionRoutine ein gültiger, nicht NULL-Zeiger sein. 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 I/O-Manager ruft die AdapterListControl-Routine auf, nachdem die erforderlichen Ressourcen für das Adapterobjekt zugewiesen wurden. Nachdem die AdapterListControl-Routine zurückgegeben wurde, wird der I/O-Manager automatisch das Adapterobjekt und die Ressourcen freigelassen, die für dieses Objekt zugewiesen wurden.

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

[in, optional] Context

Der treiberbestimmte, Adaptersteuerungskontext. Dieser Kontext wird an die AdapterListControl-Routine als Kontextparameter übergeben.

[in] WriteToDevice

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

[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 der die Routine einen Zeiger auf die zugeordnete Punkt-/Sammelliste schreibt. Dieser Parameter verweist auf eine SCATTER_GATHER_LIST Struktur. Die Routine weist diese Struktur und das SCATTER_GATHER_ELEMENT Array zu, das darauf verweist.

Der Parameter " ScatterGatherList " ist optional und kann NULL sein, wenn der ExecutionRoutine-Parameter nicht NULL ist.

Wenn das DMA_SYNCHRONOUS_CALLBACK-Flag festgelegt ist und der ExecutionRoutine-ParameterNULL ist, muss ScatterGatherList ein gültiger, nicht NULL-Zeiger sein. Wenn ExecutionRoutine nicht NULL ist, ist ScatterGatherList optional und kann NULL sein, wenn der aufrufende Treiber die Punkt-/Sammelliste 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ückgabewerte umfassen die folgenden Statuscodes.

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

Bemerkungen

GetScatterGatherListEx ist keine Systemroutine, die direkt nach Name aufgerufen werden kann. Diese Routine kann nur durch Zeiger aus der in einer DMA_OPERATIONS Struktur zurückgegebenen Adresse aufgerufen werden . Treiber erhalten die Adresse dieser Routine, indem Sie IoGetDmaAdapter mit dem Versionsmitglied des DeviceDescription-Parameters auf DEVICE_DESCRIPTION_VERSION3 festlegen. 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 Vorgänge zu kombinieren, die von der AllocateAdapterChannelEx - und MapTransferEx-Routine in einen Anruf ausgeführt werden. GetScatterGatherListEx führt die folgenden Vorgänge aus:

  1. Weist die Ressourcen zu, die für die DMA-Übertragung erforderlich sind.
  2. Erstellt eine Punkt-/Sammelliste basierend auf den Werten der Mdl-, Offset- und Längenparameter .
  3. Ruft die vom Treiber bereitgestellte AdapterListControl-Routine auf und stellt die Punkt-/Sammelliste dieser Routine als Parameter bereit.
Die zugewiesenen Ressourcen werden automatisch veröffentlicht, nachdem die AdapterListControl-Routine zurückgegeben wird. Wenn GetScatterGatherListEx synchron aufgerufen wird (das heißt, wenn das DMA_SYNCHRONOUS_CALLBACK Flag festgelegt ist), kann die AdapterListControl-Routine weggelassen werden. In diesem Fall verwendet der Aufrufer die zugewiesenen Ressourcen, um die DMA-Übertragung zu initiieren, nachdem GetScatterGatherListEx zurückgegeben wird. Der Aufrufer muss diese Ressourcen explizit freigeben.

Standardmäßig gibt GetScatterGatherListEx asynchron zurück, ohne auf die angeforderte Ressourcenzuweisung zu warten. Nach dieser Rückgabe kann der Anrufer ggf. die ausstehende Zuordnungsanforderung abbrechen, indem die CancelAdapterChannel-Routine aufgerufen wird.

Wenn der Anruftreiber 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-/Sammelliste 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 angeben, 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 Aufrufthreads aufgerufen werden soll, bevor GetScatterGatherListEx zurückgegeben wird.
  • Wenn der Treiber keine AdapterListControl-Routine angibt, kann der Treiber die zugewiesenen Ressourcen und Punkt-/Sammelliste verwenden, nachdem GetScatterGatherListEx zurückgegeben wird. In diesem Fall muss der Treiber einen gültigen, nicht NULL ScatterGatherList-Zeiger angeben. Nachdem der Treiber die DMA-Übertragung initiiert hat, muss der Treiber die FreeAdapterObject-Routine aufrufen, um die Ressourcen freizugeben, die GetScatterGatherListEx für das Adapterobjekt zugewiesen 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 , außer dass GetScatterGatherListEx automatisch den Puffer für die Punkt-/Sammelliste zuordnet.

Anforderungen

   
Unterstützte Mindestversion (Client) Ab Windows 8 verfügbar.
Zielplattform Power BI Desktop
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL <= DISPATCH_LEVEL

Weitere Informationen

AdapterListControl

AllocateAdapterChannelEx

BuildScatterGatherListEx

CancelAdapterChannel

DEVICE_OBJECT

DMA_ADAPTER

DmaCompletionRoutine

FreeAdapterChannel

GetScatterGatherList

InitializeDmaTransferContext

IoGetDmaAdapter

MapTransferEx

SCATTER_GATHER_LIST