PFLUSH_ADAPTER_BUFFERS_EX funzione di callback (wdm.h)

Articolo
02/07/2025

Il FlushAdapterBuffersEx scarica tutti i dati che rimangono nella cache dei dati alla fine di un'operazione di trasferimento DMA eseguita da un controller DMA di sistema o da un dispositivo master del bus.

Sintassi

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
)
{...}

Parametri

[in] DmaAdapter

Puntatore a una struttura DMA_ADAPTER. Questa struttura è l'oggetto adapter che rappresenta il canale DMA di sistema del driver o il dispositivo bus-master. Il chiamante ha ottenuto questo puntatore da una chiamata precedente alla routine IoGetDmaAdapter.

[in] Mdl

Puntatore alla catena MDL che descrive le pagine di memoria da scaricare. Impostare questo parametro in modo che punti alla catena MDL usata per il trasferimento DMA. Per altre informazioni, vedere la descrizione del parametro Mdl in GetScatterGatherListEx, BuildScatterGatherListExo MapTransferEx.

[in] MapRegisterBase

Handle per i registri della mappa allocati in precedenza per l'oggetto adapter.

[in] Offset

Offset iniziale relativo all'inizio della catena MDL da utilizzare per l'operazione di scaricamento. Impostare questo parametro sul valore utilizzato come offset iniziale per il trasferimento DMA. Per altre informazioni, vedere la descrizione del parametro Offset in GetScatterGatherListEx, BuildScatterGatherListExo MapTransferEx.

[in] Length

Numero di byte di dati da scaricare. Impostare questo parametro sul valore usato come lunghezza di trasferimento per il trasferimento DMA. Per altre informazioni, vedere la descrizione del parametro Length in GetScatterGatherListEx, BuildScatterGatherListExo MapTransferEx.

[in] WriteToDevice

Direzione del trasferimento DMA. Impostare questo parametro sul valore usato come direzione di trasferimento per il trasferimento DMA. Per altre informazioni, vedere la descrizione del parametro WriteToDevice in GetScatterGatherListEx, BuildScatterGatherListExo MapTransferEx.

Valore restituito

FlushAdapterBuffersEx restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti di errore possibili includono i codici di stato seguenti.

Codice restituito	Descrizione
STATUS_INVALID_PARAMETERS	La routine non è riuscita a causa di valori di parametro non validi passati dal chiamante.

Osservazioni

FlushAdapterBuffersEx non è una routine di sistema che può essere chiamata direttamente per nome. Questa routine può essere chiamata solo dal puntatore dall'indirizzo restituito in una struttura DMA_OPERATIONS. Driver ottengono l'indirizzo di questa routine chiamando IoGetDmaAdapter con il membro version del parametro DEVICE_DESCRIPTION_VERSION3 DeviceDescription impostato su DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter restituisce NULL, la routine non è disponibile nella piattaforma.

FlushAdapterBuffersEx abilita la coesistenza della cache del processore nelle piattaforme hardware che non implementano la coesistenza della cache applicata dall'hardware (snooping del bus). Inoltre, per un trasferimento DMA di sistema, FlushAdapterBuffersEx scarica tutti i dati che rimangono nella cache interna del controller DMA di sistema.

Il driver che avvia un trasferimento DMA a dispersione/raccolta deve garantire che tutti i dati trasferiti vengano scaricati dalla cache al termine del trasferimento. Il driver deve chiamare FlushAdapterBuffersEx prima che il driver completi l'IRP che ha richiesto il trasferimento DMA e prima che il driver liberi i registri della mappa. Per altre informazioni, vedere scaricamento dei dati memorizzati nella cache durante le operazioni DMA.

FlushAdapterBuffersEx è una versione estesa della routine FlushAdapterBuffers. FlushAdapterBuffersEx può scaricare un intero elenco a dispersione/raccolta in una sola chiamata. Al contrario, per usare FlushAdapterBuffers per scaricare un elenco a dispersione/raccolta, è necessaria una chiamata separata per ogni MDL nella catena MDL.

FlushAdapterBuffersEx può essere usato al posto di FlushAdapterBuffers per scaricare il buffer per un trasferimento DMA a un pacchetto. In questo caso, la catena MDL a cui punta il parametro Mdl contiene un solo MDL. Un vantaggio dell'uso di FlushAdapterBuffersEx in questo modo è che il chiamante può specificare un offset nel linguaggio MDL.

Se FlushAdapterBuffersEx viene chiamato prima del completamento dell'operazione di trasferimento DMA, questa chiamata potrebbe annullare il trasferimento prima che possa terminare o causare un comportamento non definito.

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile a partire da Windows 8.
piattaforma di destinazione	Desktop
intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL