PMAP_TRANSFER_EX Rückruffunktion (wdm.h)
Die MapTransferEx-Routine richtet Kartenregister ein, um die physischen Adressen in einer Scatter/Gather-Liste den logischen Adressen zuzuordnen, die für eine 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 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] Mdl
Ein Zeiger auf eine MDL-Kette, der das physische Seitenlayout für eine Sammlung gesperrter Puffer im virtuellen Speicher beschreibt. Die Scatter/Gather-Liste 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] MapRegisterBase
Ein Handle für die Zuordnungsregister, die dem Adapterobjekt zugeordnet sind. Der Aufrufer hat dieses Handle zuvor aus der AllocateAdapterChannelEx-Routine abgerufen.
[in] Offset
Ein Byteoffset vom Anfang des Arbeitsspeichers, der von der MDL-Kette beschrieben wird. Dieser Offset gibt den Beginn des E/A-Datenpuffers an, der für die DMA-Übertragung verwendet wird. Wenn dem Aufrufer eine Punkt-/Sammlungsliste angegeben 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, liegen die gültigen Werte von Offset im Bereich von 0 bis N–1. Weitere Informationen finden Sie in den Hinweisen.
[in] DeviceOffset
Der Byteoffset des Datenregisters des Zielgeräts oder des FIFO von der Basisadresse des Geräts. Dieser Parameter gilt für Geräte mit mehreren FIFOs, auf die ein System-DMA-Controller zugreifen kann. Dieser Parameter wird nur für DMA-Systemübertragungen verwendet. Legen Sie für Bus-master-Übertragungen diesen Parameter auf Null fest.
[in, out] Length
Ein Zeiger auf eine Variable, die die Länge des E/A-Datenpuffers in Bytes enthält, der für die DMA-Übertragung verwendet wird. Beim Eintrag enthält diese Variable die vom aufrufenden Treiber angeforderte Länge. Vor der Rückgabe schreibt die Routine die tatsächliche Länge des zugeordneten Puffers in diese Variable. Der Wert von *Length bei Rückgabe von MapTransferEx gibt an, wie viele Bytes zugeordnet wurden. Wenn die Anzahl der Kartenregister und die Größe des Punkt-/Erfassungspuffers ausreichen, um die gesamte vom Aufrufer angeforderte Länge abzubilden, sind die Eingabe- und Ausgabewerte von *Length identisch. Wenn die MDLs in der MDL-Kette eine Gesamtmenge von N Bytes Arbeitsspeicher beschreiben, liegen die gültigen Werte von *Length im Bereich von 0 bis N–Offset.
[in] WriteToDevice
Die Richtung der DMA-Übertragung. Legen Sie diesen Parameter für einen Schreibvorgang auf TRUE fest, der Daten aus dem Arbeitsspeicher an 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.
[out, optional] ScatterGatherBuffer
Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, in den die Routine die Scatter/Gather-Liste für die DMA-Übertragung schreibt. Diese Liste beginnt mit einer SCATTER_GATHER_LIST-Struktur , der unmittelbar ein SCATTER_GATHER_ELEMENT Array folgt. Für einen Treiber, der ein Bus-master 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 in Bytes, auf den der ScatterGatherBuffer-Parameter verweist. 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 ermitteln, rufen Sie die Routine GetDmaTransferInfo oder CalculateScatterGatherList auf. Wenn ScatterGatherBufferNULL ist, legen Sie ScatterGatherBufferLength auf Null fest.
[in, optional] DmaCompletionRoutine
Ein Zeiger auf eine vom Aufrufer bereitgestellte DmaCompletionRoutine-Routine , die aufgerufen werden soll, wenn die DMA-Übertragung abgeschlossen ist. Diese Routine wird aufgerufen, wenn das Zielgerät einen DMA-Systemcontroller verwendet, der einen DMA-Vervollständigungs-Interrupt generiert. Die DmaCompletionRoutine-Routine wird am DISPATCH_LEVEL aufgerufen, nachdem die DMA-Übertragung abgeschlossen ist. Für einen System-DMA-Adapter ist dieser Parameter optional und kann NULL sein. Legen Sie für einen Bus-master-Adapter diesen Parameter auf NULL fest.
[in, optional] CompletionContext
Der vom Treiber bestimmte Kontext für die DmaCompletionRoutine-Routine . Dieser Kontext wird als CompletionContext-Parameter für die DmaCompletionRoutine-Routine bereitgestellt. Wenn der DmaCompletionRoutine-ParameterNULL ist, legen Sie CompletionContext auf NULL fest.
Rückgabewert
MapTransferEx gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte umfassen die folgenden status-Codes.
| Rückgabecode | Beschreibung |
|---|---|
|
Fehler bei der Routine aufgrund ungültiger Parameterwerte, die vom Aufrufer übergeben wurden. |
|
Der vom Aufrufer bereitgestellte Puffer in ScatterGatherBuffer ist zu klein, um die Scatter/Gather-Liste zu enthalten. |
|
Die Routine konnte die für die DMA-Übertragung erforderlichen Ressourcen nicht zuordnen. |
|
Diese Übertragung wurde abgebrochen. |
Hinweise
MapTransferEx ist keine Systemroutine, die direkt mit dem Namen aufgerufen werden kann. Diese Routine kann nur durch 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 das Versionselement des DeviceDescription-Parameters 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 optional eine DmaCompletionRoutine-Rückrufroutine-Routine bereitstellen, die aufgerufen wird, wenn die Übertragung abgeschlossen ist. Das Betriebssystem plant diesen Rückruf als Reaktion auf den DMA-Abschluss-Interrupt vom System-DMA-Controller.
Die Anzahl von Kartenregistern, die von MapTransferEx eingerichtet werden können, darf nicht das Maximum überschreiten, das der Treiber aus IoGetDmaAdapter abgerufen hat.
Die Parameter Mdl, Offset und Length beschreiben den E/A-Datenpuffer für die angeforderte DMA-Übertragung. Die Anzahl der zugeordneten Kartenregister reicht möglicherweise nicht aus, um den gesamten Speicher in diesem Puffer zuzuordnen, oder der von ScatterGatherBuffer angezeigte Scatter/Gather-Puffer 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 Scatter/Gather-Liste in den Puffer, auf den ScatterGatherBuffer verweist. 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 DmaCompletionRoutine angibt, wird der aktualisierte *Length-Ausgabewert immer geschrieben, bevor DmaCompletionRoutine ausgeführt wird. Weitere Informationen finden Sie unter Mehrere Aufrufe von MapTransferEx.
Der Offset-Parameter gibt den Startoffset in der MDL-Kette an, der den Arbeitsspeicher im E/A-Datenpuffer beschreibt. Angenommen, die MDL-Kette enthält zwei MDLs, MDL₁ und MDL₂, und dass MDL₁ N₁-Bytes des Arbeitsspeichers und MDL₂ N₂-Bytes beschreibt. Bei Offset = N, wobei N₁ < N < ₁ + N₂, enthält der Puffer keinen von MDL₁ beschriebenen Speicher und beginnt mit einem Offset von N - N₁ Bytes im von MDL₂ beschriebenen Speicher.
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 Scatter/Gather-Liste zu halten. Der Standardpuffer ist garantiert groß genug, um eine Punkt-/Sammlungsliste mit mindestens einem Element zu enthalten. Wenn der Standardpuffer für eine Scatter-/Gather-Übertragung vieler Elemente verwendet wird, sind möglicherweise viele Aufrufe von MapTransferEx erforderlich, um die Übertragung abzuschließen. Wenn die DMA-Controllerhardware Scatter/Gather-Übertragungen unterstützt, kann die Verwendung des Standardpuffers die Leistung beeinträchtigen.
Wenn ScatterGatherBuffer nicht NULL ist und ScatterGatherBufferSize eine Größe angibt, die zu klein ist, um eine Scatter/Gather-Liste mit 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 bietet folgende Vorteile:
- MapTransferEx kann alle Pufferfragmente in einer MDL-Kette in einem Aufruf verarbeiten, aber MapTransfer kann nur ein physisch zusammenhängendes Pufferfragment pro Aufruf verarbeiten.
- MapTransferEx kann eine gesamte Scatter/Gather-Liste in einem Aufruf generieren, aber MapTransfer kann nur ein Scatter/Gather-Listenelement pro Aufruf generieren.
- MapTransferEx kann alle Pufferfragmente in einer Punkt-/Sammlungsliste in einem Aufruf zuordnen, aber MapTransfer kann nur ein physisch zusammenhängendes Pufferfragment pro Aufruf zuordnen.
- MapTransferEx erfordert nur den Startoffset für die gesamte Scatter/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 eine oder mehrere MDLs erstreckt, aber ein MapTransfer-Aufruf kann 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, eine DmaCompletionRoutine-Rückrufroutine-Rückrufroutine bereitzustellen, um nach Abschluss der Übertragung Benachrichtigungen zu erhalten. MapTransfer bietet jedoch keine Möglichkeit, den Aufrufer zu benachrichtigen, wenn eine DMA-Übertragung abgeschlossen ist.
Weitere Informationen finden Sie unter Verwenden der MapTransferEx-Routine.
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 |