PGET_DMA_TRANSFER_INFO Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die GetDmaTransferInfo Routine berechnet die Zuordnungsanforderungen für eine X/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 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 die MDL-Kette, die die zu übertragenden Speicherseiten beschreibt. Weitere Informationen finden Sie im Abschnitt "Hinweise".

[in] Offset

Der Startoffset für die XY/Gather-DMA-Übertragung. Dieser Parameter ist ein Byte-Offset vom Anfang des Puffers in der ersten MDL in der MDL-Kette. Wenn die MDLs in der MDL-Kette eine Gesamtmenge von N Bytes Pufferspeicher angeben, befinden sich gültige Werte von Offset- im Bereich 0 bis N-1.

[in] Length

Die Länge der DMA-Übertragung in Bytes. Wenn die MDL-Kette insgesamt N Bytes Pufferraum angibt, befinden sich gültige Werte Length im Bereich 1 bis N –Offset.

[in] WriteOnly

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

[in, out] TransferInfo

Ein Zeiger auf eine vom Aufrufer zugewiesene DMA_TRANSFER_INFO Struktur. Der Aufrufer muss das Version Member der Struktur auf DMA_TRANSFER_INFO_VERSION1 festlegen, bevor GetDmaTransferInfoaufgerufen wird.

Rückgabewert

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

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

Bemerkungen

GetDmaTransferInfo ist keine Systemroutine, die direkt anhand des Namens 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.

Verwenden Sie GetDmaTransferInfo-, um die Größe des Punkt/Gather-Puffers zu berechnen, um die BuildScatterGatherListEx- und MapTransferEx Routinen zuzuordnen.

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

Die Mdl, Offsetund Length Parameter geben zusammen eine Sammlung von physischen Speicherbereichen an, die als Puffer für eine X/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. Diese Anforderungen umfassen Folgendes:

Die Anzahl der Elemente in der Punkt-/Gather-Liste. Jedes Element ist eine SCATTER_GATHER_ELEMENT Struktur, die einen physisch zusammenhängenden Speicherblock beschreibt.
Die Menge des Speichers, der für die angegebene Punkt/Gather-Liste zugewiesen werden soll. (Diese Speicherzuordnung enthält den für die Punkt/Gather-Liste erforderlichen Speicherplatz, der 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 Punkt-/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 physischen Speicherseiten, die einen gesperrten, zusammenhängenden Block des virtuellen Speichers zugrunde legen. In der Regel sind diese physischen Speicherseiten nicht zusammenhängend. Eine MDL-Kette ist eine sortierte Sammlung von MDLs, die speicherbeschreibt, die zum Puffern von E/A-Daten verwendet werden können. In der Regel sind die von den MDLs in der Kette beschriebenen virtuellen Speicherbereiche nicht zusammenhängend. Weitere Informationen zu MDLs und MDL-Ketten finden Sie unter Verwenden von MDLs.

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