PGET_DMA_TRANSFER_INFO Rückruffunktion (wdm.h)

Artikel
08/08/2023

Die GetDmaTransferInfo-Routine berechnet die Zuordnungsanforderungen für eine Scatter/Gather-DMA-Übertragung.

Syntax

PGET_DMA_TRANSFER_INFO PgetDmaTransferInfo;

NTSTATUS PgetDmaTransferInfo(
  [in]      PDMA_ADAPTER DmaAdapter,
  [in]      PMDL Mdl,
  [in]      ULONGLONG Offset,
  [in]      ULONG Length,
  [in]      BOOLEAN WriteOnly,
  [in, out] PDMA_TRANSFER_INFO TransferInfo
)
{...}

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 die MDL-Kette, der die zu übertragenden Speicherseiten beschreibt. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[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 Bytes Pufferspeicher angeben, liegen die gültigen Werte von Offset im Bereich 0 bis N–1.

[in] Length

Die Länge der DMA-Übertragung in Bytes. Wenn die MDL-Kette eine Gesamtmenge von N Bytes Pufferspeicher angibt, liegen die gültigen Werte von Length im Bereich von 1 bis N–Offset.

[in] WriteOnly

Gibt an, ob es sich bei der Übertragung um einen schreibgeschützten Vorgang handelt (also eine Übertragung aus dem Arbeitsspeicher auf das Gerät). Wenn WriteOnly TRUE ist, sind die zurückgegebenen Informationen zur Übertragung möglicherweise für eine Lesetransaktion ungültig. Dieser Parameter weist möglicherweise darauf hin, dass zusätzliche Cachesteuerungsvorgänge an Puffergrenzen erforderlich sind, um die Cachekohärenz zu erzwingen.

[in, out] TransferInfo

Ein Zeiger auf eine aufruferseitig zugeordnete DMA_TRANSFER_INFO-Struktur . Der Aufrufer muss das Versionselement der Struktur auf DMA_TRANSFER_INFO_VERSION1 festlegen, bevor GetDmaTransferInfo aufgerufen wird.

Rückgabewert

GetDmaTransferInfo gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte umfassen die folgenden status-Codes.

Rückgabecode	Beschreibung
STATUS_NOT_SUPPORTED	Die Routine unterstützt die angegebene Version der DMA_TRANSFER_INFO_XXX-Struktur nicht.

Hinweise

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

Verwenden Sie GetDmaTransferInfo , um die Größe des Scatter/Gather-Puffers zu berechnen, der für die BuildScatterGatherListEx - und MapTransferEx-Routinen zugewiesen werden soll.

GetDmaTransferInfo ersetzt die CalculateScatterGatherList-Routine und ist bequemer für die Verwendung mit BuildScatterGatherListEx.

Die Parameter Mdl, Offset und Length geben zusammen eine Sammlung von physischen Speicherbereichen an, die als Puffer für eine Scatter/Gather-DMA-Übertragung verwendet werden sollen. Jeder physische Speicherbereich ist in der Regel eine Seite oder ein Teil einer Seite. GetDmaTransferInfo bestimmt die Zuordnungsanforderungen für diese Übertragung. Zu diesen Anforderungen gehören die folgenden:

Die Anzahl der Elemente in der Punkt-/Sammlungsliste. Jedes Element ist eine SCATTER_GATHER_ELEMENT Struktur, die einen physisch zusammenhängenden Speicherblock beschreibt.
Die Menge an Arbeitsspeicher, die für die angegebene Punkt-/Sammlungsliste zugewiesen werden soll. (Diese Speicherzuordnung umfasst den Speicherplatz, der für die Scatter/Gather-Liste erforderlich ist, die den E/A-Puffer beschreibt, aber nicht für den E/A-Puffer selbst.)
Die Anzahl der Kartenregister, die erforderlich sind, um die physischen Adressen in der Scatter/Gather-Liste in logische Adressen zu übersetzen.

Informationen zu den DMA-Übertragungsinformationen, die von Version 1 der DMA_TRANSFER_INFO_XXX-Struktur bereitgestellt werden, finden Sie unter DMA_TRANSFER_INFO_V1.

Eine MDL beschreibt die Seiten des physischen Arbeitsspeichers, die einem gesperrten, zusammenhängenden Block des virtuellen Arbeitsspeichers zugrunde gehen. In der Regel sind diese Seiten des physischen Arbeitsspeichers nicht zusammenhängend. Eine MDL-Kette ist eine geordnete Sammlung von MDLs, die Arbeitsspeicher beschreibt, der zum Puffern von E/A-Daten verwendet werden kann. In der Regel sind die durch die MDLs in der Kette beschriebenen regionen des virtuellen Arbeitsspeichers nicht zusammenhängend. Weitere Informationen zu MDLs und MDL-Ketten finden Sie unter Verwenden von MDLs.

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