PFLUSH_ADAPTER_BUFFERS_EX função de retorno de chamada (wdm.h)

Artigo
02/27/2024

A rotina FlushAdapterBuffersEx libera todos os dados que permanecem no cache de dados no final de uma operação de transferência de DMA executada por um controlador DMA do sistema ou dispositivo de barramento master.

Sintaxe

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

Parâmetros

[in] DmaAdapter

Um ponteiro para uma estrutura DMA_ADAPTER . Essa estrutura é o objeto do adaptador que representa o canal DMA do sistema do driver ou o dispositivo master barramento. O chamador obteve esse ponteiro de uma chamada anterior para a rotina IoGetDmaAdapter .

[in] Mdl

Um ponteiro para a cadeia de MDL que descreve as páginas de memória que devem ser liberadas. Defina esse parâmetro para apontar para a cadeia de MDL que foi usada para a transferência de DMA. Para obter mais informações, consulte a descrição do parâmetro Mdl em GetScatterGatherListEx, BuildScatterGatherListEx ou MapTransferEx.

[in] MapRegisterBase

Um identificador para os registros de mapa que foram alocados anteriormente para o objeto do adaptador.

[in] Offset

O deslocamento inicial relativo ao início da cadeia de MDL a ser usado para a operação de liberação. Defina esse parâmetro como o valor que foi usado como o deslocamento inicial para a transferência de DMA. Para obter mais informações, consulte a descrição do parâmetro Offset em GetScatterGatherListEx, BuildScatterGatherListEx ou MapTransferEx.

[in] Length

O número de bytes de dados a serem liberados. Defina esse parâmetro como o valor que foi usado como o comprimento de transferência para a transferência de DMA. Para obter mais informações, consulte a descrição do parâmetro Length em GetScatterGatherListEx, BuildScatterGatherListEx ou MapTransferEx.

[in] WriteToDevice

A direção da transferência de DMA. Defina esse parâmetro como o valor que foi usado como a direção de transferência para a transferência de DMA. Para obter mais informações, consulte a descrição do parâmetro WriteToDevice em GetScatterGatherListEx, BuildScatterGatherListEx ou MapTransferEx.

Retornar valor

FlushAdapterBuffersEx retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os possíveis valores retornados por erro incluem os seguintes códigos de status.

Código de retorno	Descrição
STATUS_INVALID_PARAMETERS	A rotina falhou devido a valores de parâmetro inválidos passados pelo chamador.

Comentários

FlushAdapterBuffersEx não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina só pode ser chamada pelo ponteiro do endereço retornado em uma estrutura DMA_OPERATIONS. Os drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter com o membro Version do parâmetro DeviceDescription definido como DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter retornar NULL, a rotina não estará disponível em sua plataforma.

FlushAdapterBuffersEx permite a coerência de cache do processador em plataformas de hardware que não implementam a coerência de cache imposta por hardware (bisbilhotagem de barramento). Além disso, para uma transferência de DMA do sistema, FlushAdapterBuffersEx libera todos os dados que permanecem no cache interno do controlador de DMA do sistema.

O driver que inicia uma transferência de DMA de dispersão/coleta deve garantir que todos os dados transferidos sejam liberados do cache após a conclusão da transferência. O driver deve chamar FlushAdapterBuffersEx antes que o driver conclua o IRP que solicitou a transferência de DMA e antes que o driver libere os registros de mapa. Para obter mais informações, consulte Liberando dados armazenados em cache durante operações de DMA.

FlushAdapterBuffersEx é uma versão estendida da rotina FlushAdapterBuffers . FlushAdapterBuffersEx pode liberar uma lista inteira de dispersão/coleta em uma chamada. Por outro lado, usar FlushAdapterBuffers para liberar uma lista de dispersão/coleta requer uma chamada separada para cada MDL na cadeia de MDL.

FlushAdapterBuffersEx pode ser usado no lugar de FlushAdapterBuffers para liberar o buffer para uma transferência de DMA de um pacote. Nesse caso, a cadeia MDL para a qual o parâmetro Mdl aponta contém apenas um MDL. Um benefício de usar FlushAdapterBuffersEx dessa maneira é que o chamador pode especificar um deslocamento para o MDL.

Se FlushAdapterBuffersEx for chamado antes da conclusão da operação de transferência de DMA, essa chamada poderá cancelar a transferência antes de ser concluída ou pode causar um comportamento indefinido.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 8.
Plataforma de Destino	Área de Trabalho
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL