PFLUSH_ADAPTER_BUFFERS_EX Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die FlushAdapterBuffersEx- Routine löscht alle Daten, die am Ende eines DMA-Übertragungsvorgangs im Datencache verbleiben, der von einem System-DMA-Controller oder einem Busmastergerät ausgeführt wird.

Syntax

PFLUSH_ADAPTER_BUFFERS_EX PflushAdapterBuffersEx;

NTSTATUS PflushAdapterBuffersEx(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PMDL Mdl,
  [in] PVOID MapRegisterBase,
  [in] ULONGLONG Offset,
  [in] ULONG Length,
  [in] BOOLEAN WriteToDevice
)
{...}

Parameter

[in] DmaAdapter

Ein Zeiger auf eine DMA_ADAPTER Struktur. Diese Struktur ist das Adapterobjekt, das das DMA-Kanal- oder Busmastergerät 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 leerenden Speicherseiten beschreibt. Legen Sie diesen Parameter so fest, dass er auf die MDL-Kette zeigt, die für die DMA-Übertragung verwendet wurde. Weitere Informationen finden Sie in der Beschreibung des Mdl Parameters in GetScatterGatherListEx, BuildScatterGatherListExoder MapTransferEx.

[in] MapRegisterBase

Ein Handle für die Kartenregister, die zuvor für das Adapterobjekt zugewiesen wurden.

[in] Offset

Der Startoffset relativ zum Anfang der MDL-Kette, die für den Löschvorgang verwendet werden soll. Legen Sie diesen Parameter auf den Wert fest, der als Startoffset für die DMA-Übertragung verwendet wurde. Weitere Informationen finden Sie in der Beschreibung des parameters Offset in GetScatterGatherListEx, BuildScatterGatherListExoder MapTransferEx.

[in] Length

Die Anzahl der zu leerenden Daten. Legen Sie diesen Parameter auf den Wert fest, der als Übertragungslänge für die DMA-Übertragung verwendet wurde. Weitere Informationen finden Sie in der Beschreibung des parameters Length in GetScatterGatherListEx, BuildScatterGatherListExoder MapTransferEx.

[in] WriteToDevice

Die Richtung der DMA-Übertragung. Legen Sie diesen Parameter auf den Wert fest, der als Übertragungsrichtung für die DMA-Übertragung verwendet wurde. Weitere Informationen finden Sie in der Beschreibung des WriteToDevice- Parameters in GetScatterGatherListEx, BuildScatterGatherListExoder MapTransferEx.

Rückgabewert

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

Bemerkungen

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

FlushAdapterBuffersEx- ermöglicht die Prozessorcachekohärenz auf Hardwareplattformen, die keine hardwaregestützte Cachekohärenz (Bussnooping) implementieren. Darüber hinaus löscht FlushAdapterBuffersEx für eine System-DMA-Übertragung alle Daten, die im internen Cache des DMA-Controllers des Systems verbleiben.

Der Treiber, der eine XY/Gather-DMA-Übertragung initiiert, muss sicherstellen, dass alle übertragenen Daten nach Abschluss der Übertragung aus dem Cache geleert werden. Der Treiber sollte FlushAdapterBuffersEx- aufrufen, bevor der Treiber das IRP abgeschlossen hat, das die DMA-Übertragung angefordert hat, und bevor der Treiber die Kartenregister freigibt. Weitere Informationen finden Sie unter Leeren zwischengespeicherter Daten während der DMA-Vorgänge.

FlushAdapterBuffersEx ist eine erweiterte Version der FlushAdapterBuffers Routine. FlushAdapterBuffersEx- kann eine gesamte Punkt-/Sammelliste in einem Aufruf leeren. Im Gegensatz dazu erfordert die Verwendung von FlushAdapterBuffers- zum Leeren einer Punkt/Gather-Liste einen separaten Aufruf für jede MDL in der MDL-Kette.

FlushAdapterBuffersEx- kann anstelle von FlushAdapterBuffers verwendet werden, um den Puffer für eine DMA-Übertragung mit einem Paket zu leeren. In diesem Fall enthält die MDL-Kette, auf die der Mdl Parameter verweist, nur eine MDL. Ein Vorteil der Verwendung von FlushAdapterBuffersEx- besteht darin, dass der Aufrufer einen Offset in der MDL angeben kann.

Wenn FlushAdapterBuffersEx- aufgerufen wird, bevor der DMA-Übertragungsvorgang abgeschlossen ist, kann dieser Aufruf die Übertragung abbrechen, bevor sie beendet werden kann oder zu einem nicht definierten Verhalten führen kann.

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