PMAP_TRANSFER_EX Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die MapTransferEx Routine richtet Kartenregister ein, um die physischen Adressen in einer Punkt-/Sammelliste den logischen Adressen zuzuordnen, die zum Ausführen einer DMA-Übertragung erforderlich sind.

Syntax

PMAP_TRANSFER_EX PmapTransferEx;

NTSTATUS PmapTransferEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PMDL Mdl,
  [in]            PVOID MapRegisterBase,
  [in]            ULONGLONG Offset,
  [in]            ULONG DeviceOffset,
  [in, out]       PULONG Length,
  [in]            BOOLEAN WriteToDevice,
  [out, optional] PSCATTER_GATHER_LIST ScatterGatherBuffer,
  [in]            ULONG ScatterGatherBufferLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext
)
{...}

Parameter

[in] DmaAdapter

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

[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] MapRegisterBase

Ein Handle für die Kartenregister, die für das Adapterobjekt zugeordnet sind. Der Aufrufer hat dieses Handle zuvor aus der AllocateAdapterChannelEx Routine abgerufen.

[in] Offset

Ein Byteoffset vom Anfang des Speichers, der von der MDL-Kette beschrieben wird. Dieser Offset gibt den Anfang des E/A-Datenpuffers an, der für die DMA-Übertragung verwendet wird. Wenn dem Aufrufer eine Punkt-/Gather-Liste bereitgestellt wird, bestimmt dieser Offset die Startadresse des ersten Pufferfragments in der Liste. Wenn die MDLs in der MDL-Kette eine Gesamtmenge von N Bytes Arbeitsspeicher beschreiben, befinden sich gültige Werte von Offset- im Bereich 0 bis N-1. Weitere Informationen finden Sie in den Hinweisen.

[in] DeviceOffset

Der Byteoffset des Datenregisters des Zielgeräts oder FIFO aus der Basisadresse des Geräts. Dieser Parameter gilt für Geräte mit mehreren FIFOs, auf die von einem System-DMA-Controller zugegriffen werden kann. Dieser Parameter wird nur für System-DMA-Übertragungen verwendet. Legen Sie für Busmasterübertragungen diesen Parameter auf Null fest.

[in, out] Length

Ein Zeiger auf eine Variable, die die Länge des E/A-Datenpuffers enthält, der für die DMA-Übertragung verwendet wird. Bei der Eingabe enthält diese Variable die vom aufrufenden Treiber angeforderte Länge. Vor dem Zurückgeben schreibt die Routine die tatsächliche Länge des zugeordneten Puffers in diese Variable. Der Wert von *Length für die Rückgabe von MapTransferEx- gibt an, wie viele Bytes zugeordnet wurden. Wenn die Anzahl der Kartenregister und die Punkt/Gather-Puffergröße ausreichen, um die gesamte vom Aufrufer angeforderte Länge zuzuordnen, sind die Eingabe- und Ausgabewerte von *Length identisch. Wenn die MDLs in der MDL-Kette eine Gesamtmenge von N Bytes Arbeitsspeicher beschreiben, liegen gültige Werte von *Length im Bereich 0 bis N –Offset.

[in] WriteToDevice

Die Richtung der DMA-Übertragung. Legen Sie diesen Parameter auf TRUE- für einen Schreibvorgang fest, der Daten aus dem Arbeitsspeicher 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.

[out, optional] ScatterGatherBuffer

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, in den die Routine die Punkt/Gather-Liste für die DMA-Übertragung schreibt. Diese Liste beginnt mit einer SCATTER_GATHER_LIST Struktur, auf die unmittelbar ein SCATTER_GATHER_ELEMENT Array folgt. Für einen Treiber, der ein Busmaster-DMA-Gerät verwendet, ist ScatterGatherBuffer ein erforderlicher Parameter. Für einen Treiber, der einen System-DMA-Controller verwendet, ist der ScatterGatherBuffer Parameter optional und kann NULL-sein. Weitere Informationen finden Sie in den Hinweisen.

[in] ScatterGatherBufferLength

Die Größe des Puffers, auf den der ScatterGatherBuffer Parameter verweist. Die zugeordnete Puffergröße muss groß genug sein, um die Punkt/Erfassungsliste sowie interne Daten zu enthalten, die vom Betriebssystem in diesem Puffer gespeichert werden. Rufen Sie zum Ermitteln der erforderlichen Puffergröße die GetDmaTransferInfo oder CalculateScatterGatherList-Routine auf. Wenn ScatterGatherBuffer-NULL-ist, legen Sie ScatterGatherBufferLength- auf Null fest.

[in, optional] DmaCompletionRoutine

Ein Zeiger auf einen von einem Aufrufer bereitgestellten DmaCompletionRoutine Routine aufgerufen werden soll, wenn die DMA-Übertragung abgeschlossen ist. Diese Routine wird aufgerufen, wenn das Zielgerät einen System-DMA-Controller verwendet, der einen DMA-Abschlussunterbruch generiert. Die DmaCompletionRoutine Routine wird nach Abschluss der DMA-Übertragung an DISPATCH_LEVEL aufgerufen. Für einen System-DMA-Adapter ist dieser Parameter optional und kann NULL-sein. Legen Sie für einen Busmasteradapter diesen Parameter auf NULL-fest.

[in, optional] CompletionContext

Der vom Treiber ermittelte Kontext für die DmaCompletionRoutine Routine. Dieser Kontext wird als CompletionContext Parameter an die DmaCompletionRoutine Routine bereitgestellt. Wenn der DmaCompletionRoutine Parameter NULL-ist, legen Sie CompletionContext auf NULL-fest.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETERS	Fehler der Routine aufgrund ungültiger Parameterwerte, die vom Aufrufer übergeben werden.
STATUS_BUFFER_TOO_SMALL	Der vom Aufrufer bereitgestellte Puffer in ScatterGatherBuffer- ist zu klein, um die Punkt/Gather-Liste zu enthalten.
STATUS_INSUFFICIENT_RESOURCES	Die Routine konnte ressourcen, die für die DMA-Übertragung erforderlich sind, nicht zuordnen.
STATUS_CANCELLED	Diese Übertragung wurde abgebrochen.

Bemerkungen

MapTransferEx ist keine Systemroutine, die direkt nach Namen 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 Member des DeviceDescription-Parameters aufrufen, der auf DEVICE_DESCRIPTION_VERSION3 festgelegt ist. Wenn IoGetDmaAdapterNULL-zurückgibt, ist die Routine auf Ihrer Plattform nicht verfügbar.

Bei einer Übertragung, die einen System-DMA-Controller verwendet, kann der Aufrufer als Option eine DmaCompletionRoutine Rückrufroutine bereitstellen, die aufgerufen wird, wenn die Übertragung abgeschlossen ist. Das Betriebssystem plant diesen Rückruf als Reaktion auf die DMA-Fertigstellungsunterbrechung vom DMA-Controller des Systems.

Die Anzahl der Kartenregister, die von MapTransferEx- eingerichtet werden können, darf nicht das Maximum überschreiten, das der Treiber aus IoGetDmaAdapterabgerufen hat.

Die parameter Mdl, Offsetund Length Parameter beschreiben den E/A-Datenpuffer für die angeforderte DMA-Übertragung. Die Anzahl der zugeordneten Zuordnungsregister reicht möglicherweise nicht aus, um den gesamten Speicher in diesem Puffer zuzuordnen, oder der Punkt/Gather-Puffer, auf den ScatterGatherBu ffer verweist, ist möglicherweise nicht groß genug, um den gesamten Puffer zu beschreiben. MapTransferEx schreibt einen Ausgabewert in *Length, um dem Treiber mitzuteilen, wie viel Pufferspeicher für die angeforderte DMA-Übertragung von der Routine zugeordnet wurde. Die Routine schreibt eine Punkt-/Gather-Liste in den Puffer, auf den ScatterGatherBufferverweist. In dieser Liste werden die Pufferfragmente beschrieben, die von der Routine erfolgreich zugeordnet wurden.

Wenn ein Aufruf von MapTransferEx- erfolgreich ist, schreibt MapTransferEx den Ausgabewert *Length, bevor er zurückgegeben wird. Wenn der Aufrufer eine DmaCompletionRoutineangibt, wird der aktualisierte *Length Ausgabewert immer vor ausführung der DmaCompletionRou tine geschrieben. Weitere Informationen finden Sie unter Mehrere Aufrufe von MapTransferEx.

Der Offset Parameter gibt den Anfangsoffset in der MDL-Kette an, der den Speicher im E/A-Datenpuffer beschreibt. Angenommen, die MDL-Kette enthält zwei MDLs, MDL₁ und MDL₁ und dass MDL₁ N₁ Bytes des Arbeitsspeichers beschreibt, und MDL beschreibt Nnimmt Bytes. Wenn Offset = N, wobei N₁ < N < N₁ + Nnimmt, enthält der Puffer keinen speicher, der von MDL₁ beschrieben wird, und beginnt mit einem Offset von N - N₁ Bytes im speicher, der von MDL offset beschrieben wird.

Wenn die Übertragung einen System-DMA-Controller verwendet, kann der Aufrufer ScatterGatherBuffer = NULL festlegen, in diesem Fall verwendet MapTransferEx einen intern zugewiesenen Standardpuffer, um die Punkt/Gather-Liste zu speichern. Der Standardpuffer ist garantiert groß genug, um eine Punkt/Gather-Liste von mindestens einem Element zu enthalten. Wenn der Standardpuffer für eine X/Gather-Übertragung vieler Elemente verwendet wird, sind möglicherweise viele Aufrufe an MapTransferEx erforderlich. Wenn die DMA-Controllerhardware Punkt-/Sammelübertragungen unterstützt, kann die Verwendung des Standardpuffers die Leistung beeinträchtigen.

Wenn ScatterGatherBuffer- ungleich NULL ist und ScatterGatherBufferSize- eine Größe angibt, die zu klein ist, um eine Punkt/Gather-Liste von mindestens einem Element zu enthalten, schlägt MapTransferEx fehl und gibt STATUS_INVALID_PARAMETER zurück.

MapTransferEx ist eine erweiterte Version der MapTransfer Routine. Die erweiterte Version hat folgende Vorteile:

MapTransferEx- kann alle Pufferfragmente in einer MDL-Kette in einem Aufruf verarbeiten, aber MapTransfer- kann pro Aufruf nur ein physisch zusammenhängendes Pufferfragment verarbeiten.
MapTransferEx- kann eine gesamte Punkt-/Sammelliste in einem Aufruf generieren, aber MapTransfer kann pro Aufruf nur ein Punkt/Gather-Listenelement generieren.
MapTransferEx- kann alle Pufferfragmente in einer Punkt-/Sammelliste in einem Aufruf zuordnen, aber MapTransfer- kann pro Aufruf nur ein physisch zusammenhängendes Pufferfragment zuordnen.
MapTransferEx- erfordert nur den Anfangsoffset für die gesamte Punkt/Gather-Liste, aber MapTransfer- erfordert eine virtuelle Startadresse für jedes physisch zusammenhängende Pufferfragment.
Ein MapTransferEx--Aufruf kann einen Puffer zuordnen, der sich über mindestens eine MDLs erstreckt. Ein MapTransfer- Aufruf kann jedoch nur ein physisch zusammenhängendes Pufferfragment im Speicher zuordnen, das von einer MDL beschrieben wird.
Bei einer System-DMA-Übertragung ermöglicht MapTransferEx- dem Aufrufer das Bereitstellen einer DmaCompletionRoutine Rückrufroutine, um Benachrichtigungen nach Abschluss der Übertragung zu empfangen, aber MapTransfer bietet keine Möglichkeit, den Anrufer zu benachrichtigen, wenn eine DMA-Übertragung abgeschlossen ist.

Jedem erfolgreichen Aufruf von MapTransferEx muss ein entsprechender Aufruf der FlushAdapterBuffersEx-Routine folgen. Der FlushAdapterBuffersEx-Aufruf, der einem MapTransferEx-aufruf folgt, muss erfolgen, bevor der nächste MapTransferEx-Aufruf aufgerufen wird. Der FlushAdapterBuffersEx-Aufruf ist erforderlich, auch wenn ein Aufruf der CancelMappedTransfer Routine erfolgreich war, die zugeordnete Übertragung abzubrechen, die vom vorherigen MapTransferEx Aufruf angefordert wurde.

Weitere Informationen finden Sie unter Using the MapTransferEx Routine.

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