PFLUSH_ADAPTER_BUFFERS_EX Rückruffunktion (wdm.h)

Artikel
08/08/2023

Die FlushAdapterBuffersEx-Routine löscht alle Daten, die am Ende eines DMA-Übertragungsvorgangs von einem System-DMA-Controller oder einem Bus-master-Gerät im Datencache verbleiben.

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 den DMA-Systemkanal oder das Bus-master-Gerät 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 Speicherseiten beschreibt, die geleert werden sollen. Legen Sie diesen Parameter so fest, dass er auf die MDL-Kette verweist, die für die DMA-Übertragung verwendet wurde. Weitere Informationen finden Sie in der Beschreibung des Mdl-Parameters in GetScatterGatherListEx, BuildScatterGatherListEx oder MapTransferEx.

[in] MapRegisterBase

Ein Handle für die Kartenregister, die zuvor dem Adapterobjekt zugeordnet wurden.

[in] Offset

Der Startoffset relativ zum Start der MDL-Kette, die für den Spülvorgang 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 Offset-Parameters in GetScatterGatherListEx, BuildScatterGatherListEx oder MapTransferEx.

[in] Length

Die Anzahl der zu leerenden Datenbytes. 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 Length-Parameters in GetScatterGatherListEx, BuildScatterGatherListEx oder 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, BuildScatterGatherListEx oder MapTransferEx.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETERS	Fehler bei der Routine aufgrund ungültiger Parameterwerte, die vom Aufrufer übergeben wurden.

Hinweise

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

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

Der Treiber, der eine Scatter/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 die IRP abgeschlossen hat, die die DMA-Übertragung angefordert hat, und bevor der Treiber die Kartenregister freigibt. Weitere Informationen finden Sie unter Leeren zwischengespeicherter Daten während DMA-Vorgängen.

FlushAdapterBuffersEx ist eine erweiterte Version der FlushAdapterBuffers-Routine . FlushAdapterBuffersEx kann eine gesamte Scatter/Gather-Liste in einem Aufruf löschen. Im Gegensatz dazu erfordert die Verwendung von FlushAdapterBuffers zum Leeren einer Scatter/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 auf diese Weise ist, 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 abgeschlossen werden kann, oder zu nicht definiertem Verhalten führen.

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