PFLUSH_ADAPTER_BUFFERS_EX funzione di callback (wdm.h)

Articolo
08/08/2023

La routine 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 del sistema del driver o il dispositivo master del bus. 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 per puntare alla catena MDL usata per il trasferimento DMA. Per altre informazioni, vedere la descrizione del parametro Mdl in GetScatterGatherListEx, BuildScatterGatherListEx o 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 usare per l'operazione di scaricamento. Impostare questo parametro sul valore usato come offset iniziale per il trasferimento DMA. Per altre informazioni, vedere la descrizione del parametro Offset in GetScatterGatherListEx, BuildScatterGatherListEx o 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, BuildScatterGatherListEx o 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, BuildScatterGatherListEx o MapTransferEx.

Valore restituito

FlushAdapterBuffersEx restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti degli errori 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.

Commenti

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. I driver ottengono l'indirizzo di questa routine chiamando IoGetDmaAdapter con il membro Version del parametro 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 coherency 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 del sistema.

Il driver che avvia un trasferimento DMA a dispersione/raccolta deve assicurarsi che tutti i dati trasferiti vengano scaricati dalla cache dopo il completamento 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 libera 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 di dispersione/raccolta in una chiamata. Al contrario, per usare FlushAdapterBuffers per scaricare un elenco di 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 che il parametro Mdl punta a contiene solo un MDL. Un vantaggio dell'uso di FlushAdapterBuffersEx in questo modo è che il chiamante può specificare un offset nel 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.

Requisiti

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