PMAP_TRANSFER Rückruffunktion (wdm.h)

Artikel
02/27/2024

Die MapTransfer-Routine richtet Kartenregister für ein Adapterobjekt ein, um eine DMA-Übertragung aus einem gesperrten Puffer zuzuordnen.

Syntax

PMAP_TRANSFER PmapTransfer;

PHYSICAL_ADDRESS PmapTransfer(
  [in]      PDMA_ADAPTER DmaAdapter,
  [in]      PMDL Mdl,
  [in]      PVOID MapRegisterBase,
  [in]      PVOID CurrentVa,
  [in, out] PULONG Length,
  [in]      BOOLEAN WriteToDevice
)
{...}

Parameter

[in] DmaAdapter

Zeiger auf das DMA-Adapterobjekt, das von IoGetDmaAdapter zurückgegeben und zuvor für die Übertragungsanforderung des aktuellen IRP an AllocateAdapterChannel übergeben wurde.

[in] Mdl

Zeiger auf eine der folgenden Optionen: die MDL, die den Puffer bei MdlAddress im aktuellen IRP beschreibt, oder die MDL, die den allgemeinen Puffer beschreibt, der vom Treiber eines untergeordneten Geräts eingerichtet wird (Autoinitialisierungsmodus).

[in] MapRegisterBase

Gibt die Zuordnungsregister an, die dem DMA-Vorgang zugeordnet sind. Das System übergibt diesen Wert an die AdapterControl-Routine des Treibers.

[in] CurrentVa

Zeiger auf die aktuelle virtuelle Adresse der Daten, die für einen DMA-Übertragungsvorgang übertragen werden sollen.

[in, out] Length

Gibt die Länge in Bytes an, die zugeordnet werden soll. Wenn der Treiber beim Aufrufen von IoGetDmaAdapter angegeben hat, dass sein Gerät ein Bus master mit Scatter-/Gather-Unterstützung ist, gibt der Wert length bei Rückgabe von MapTransfer an, wie viele Bytes zugeordnet wurden. Andernfalls sind die Eingabe- und Ausgabewerte von Length identisch.

[in] WriteToDevice

Gibt die Richtung des Übertragungsvorgangs an: TRUE für eine Übertragung vom gesperrten Puffer zum Gerät.

Rückgabewert

MapTransfer gibt die logische Adresse der zugeordneten Region zurück, die der Treiber eines Bus-master-Adapters verwenden kann. Treiber von Geräten, die einen DMA-Systemcontroller verwenden, können diesen Wert nicht verwenden und sollten ihn ignorieren.

Hinweise

MapTransfer 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.

Der DmaAdapter muss bereits als Ergebnis des vorherigen Aufrufs des Treibers an AllocateAdapterChannel zugeordnet worden sein.

Die Anzahl der Zuordnungsregister, die eingerichtet werden können, darf nicht das Maximum überschreiten, das beim Aufrufen des Treibers IoGetDmaAdapter zurückgegeben wird.

Ein Treiber kann die anfängliche CurrentVa für den Start einer paketbasierten DMA-Übertragung abrufen, indem MmGetMdlVirtualAddress aufgerufen wird. Der zurückgegebene Wert ist jedoch ein Index in der Mdl und nicht eine gültige virtuelle Adresse. Wenn der Treiber eine große Übertragungsanforderung in mehr als einen DMA-Vorgang aufteilen muss, müssen CurrentVa und Length für jeden DMA-Vorgang aktualisiert werden.

Der Treiber eines Bus-master-Geräts mit Scatter-/Gather-Unterstützung kann die zurückgegebene logische Adresse und den aktualisierten Length-Wert verwenden, um eine Punkt-/Sammlungsliste zu erstellen, wobei MapTransfer wiederholt aufgerufen wird, bis alle verfügbaren Kartenregister für den Übertragungsvorgang verwendet wurden. Ein solcher Treiber könnte jedoch einfacher die GetScatterGatherList-Routine verwenden.

Anforderungen

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