PBUILD_SCATTER_GATHER_LIST_EX Rückruffunktion (wdm.h)

Artikel
02/27/2024

Die BuildScatterGatherListEx-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

PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;

NTSTATUS PbuildScatterGatherListEx(
  [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]            PVOID ScatterGatherBuffer,
  [in]            ULONG ScatterGatherLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PVOID ScatterGatherList
)
{...}

Parameter

[in] DmaAdapter

Ein Zeiger auf eine DMA_ADAPTER-Struktur . Diese Struktur ist das Adapterobjekt, das den Bus-master DMA-Gerät oder System-DMA-Kanal 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 Größe 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 BuildScatterGatherListEx-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 ExecutionRoutine optional und kann NULL sein. Wenn ExecutionRoutineNULL ist, kann der Aufrufer die von BuildScatterGatherListEx zugeordneten Ressourcen verwenden. 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] ScatterGatherBuffer

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, in den die Routine die Punkt-/Sammlungsliste für die DMA-Übertragung schreibt. Diese Liste beginnt mit einer SCATTER_GATHER_LIST-Struktur , auf die ein SCATTER_GATHER_ELEMENT Array folgt.

[in] ScatterGatherLength

Die Größe des Puffers in Bytes, der im ScatterGatherBuffer-Parameter übergeben wird. Die zugeordnete Puffergröße muss groß genug sein, um die Punkt-/Sammlungsliste sowie interne Daten zu enthalten, die das Betriebssystem in diesem Puffer speichert. Um die erforderliche Puffergröße zu berechnen, rufen Sie die Routine GetDmaTransferInfo oder CalculateScatterGatherList auf.

[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 Scatter/Gather-Liste für die DMA-Übertragung schreibt. Diese Liste beginnt mit einer SCATTER_GATHER_LIST-Struktur , die einen Zeiger auf ein SCATTER_GATHER_ELEMENT Array enthält. Dieser Ausgabezeiger entspricht immer dem ScatterGatherBuffer-Parameterwert .

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 BuildScatterGatherListEx-Aufruf schlägt fehl, wenn das DMA_SYNCHRONOUS_CALLBACK-Flag festgelegt ist und ScatterGatherList und ExecutionRoutinebeide NULL sind, oder wenn das flag DMA_SYNCHRONOUS_CALLBACK nicht festgelegt ist und ExecutionRoutineNULL ist.

Rückgabewert

BuildScatterGatherListEx 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_BUFFER_TOO_SMALL	Der vom Aufrufer bereitgestellte Puffer in ScatterGatherBuffer ist zu klein, um die Scatter/Gather-Liste zu enthalten.
STATUS_INSUFFICIENT_RESOURCES	Die Routine konnte die für die DMA-Übertragung erforderlichen Ressourcen nicht zuordnen.

Hinweise

BuildScatterGatherListEx* ist keine Systemroutine, die direkt nach Namen aufgerufen werden kann. Diese Routine kann nur durch einen 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 BuildScatterGatherListEx nur für Bus-master-Adapter. Verwenden Sie diese Routine nicht für einen System-DMA-Adapter.

BuildScatterGatherListEx ähnelt der GetScatterGatherListEx-Routine , mit der Ausnahme, dass der Aufrufer den Puffer für die Scatter/Gather-Liste ordnet.

Beispielsweise kann ein Treiber während der Geräteinitialisierung einen oder mehrere Punkt-/Sammlungspuffer vorab allocatieren. Später kann ein BuildScatterGatherListEx-Aufruf , der einen solchen Puffer verwendet, unter Bedingungen mit geringer Arbeitsspeicherverfügbarkeit erfolgreich sein, was dazu führen kann, dass ein GetScatterGatherListEx-Aufruf fehlschlägt.

Standardmäßig wird BuildScatterGatherListEx asynchron zurückgegeben, 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 BuildScatterGatherListEx-Routine wie folgt:

Wenn die angeforderten Ressourcen nicht sofort verfügbar sind, wartet BuildScatterGatherListEx nicht auf Ressourcen, erstellt keine Punkt-/Sammlungsliste und ruft die AdapterListControl-Routine nicht auf. Stattdessen schlägt BuildScatterGatherListEx 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 flag DMA_SYNCHRONOUS_CALLBACK an, dass diese Routine im Kontext des aufrufenden Threads aufgerufen werden soll, bevor BuildScatterGatherListEx zurückgegeben wird.
Wenn der Treiber keine AdapterListControl-Routine angibt, kann der Treiber die zugeordneten Ressourcen und die Scatter/Gather-Liste verwenden, nachdem BuildScatterGatherListEx 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 nach Abschluss der vom Treiber initiierten DMA-Übertragung die FreeAdapterObject-Routine aufrufen, um die Ressourcen freizugeben, die BuildScatterGatherListEx für das Adapterobjekt zugewiesen hat.

BuildScatterGatherListEx ist eine erweiterte Version der BuildScatterGatherList-Routine . In der folgenden Liste sind die Features zusammengefasst, die nur in der erweiterten Version verfügbar sind:

Funktion	BESCHREIBUNG
Startoffset	Der aufrufende Treiber kann einen Startoffset für eine Scatter-/Gather-DMA-Übertragung angeben, anstatt die Übertragung an der ersten Pufferadresse am Anfang der MDL-Kette zu starten.
Abbruch der Zuordnungsanforderung	Der Treiber kann CancelAdapterChannel aufrufen, um eine ausstehende Zuordnungsanforderung abzubrechen, wenn der DMA-Adapter in die Warteschlange gestellt wird, um auf DMA-Ressourcen zu warten.
Synchroner Rückruf	Der Treiber kann das DMA_SYNCHRONOUS_CALLBACK-Flag festlegen, um anzufordern, dass die vom Treiber bereitgestellte AdapterListControl-Routine im aufrufenden Thread aufgerufen wird, bevor BuildScatterGatherListEx zurückgegeben wird.

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