DMA_COMPLETION_ROUTINE função de retorno de chamada (wdm.h)
O DmaCompletionRoutine rotina de retorno de chamada notifica o driver que solicitou anteriormente uma transferência de DMA do sistema para que essa transferência fosse concluída.
Sintaxe
DMA_COMPLETION_ROUTINE DmaCompletionRoutine;
void DmaCompletionRoutine(
[in] PDMA_ADAPTER DmaAdapter,
[in] PDEVICE_OBJECT DeviceObject,
[in] PVOID CompletionContext,
[in] DMA_COMPLETION_STATUS Status
)
{...}
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.
[in] DeviceObject
Um ponteiro para uma estrutura DEVICE_OBJECT. Essa estrutura é o PDO (objeto de dispositivo físico) que representa o dispositivo de destino para a operação de DMA solicitada.
[in] CompletionContext
Um ponteiro para um contexto determinado pelo driver para a rotina de DmaCompletionRoutine. Esse contexto é o valor do parâmetro CompletionContext que o driver passou anteriormente para a chamada MapTransferEx que iniciou a transferência de DMA do sistema.
[in] Status
O status de conclusão da transferência de DMA. Esse parâmetro é um valor de enumeração DMA_COMPLETION_STATUS que indica se a transferência de DMA foi concluída com êxito.
Valor de retorno
Nenhum
Observações
Como opção, um driver pode implementar uma rotina de DmaCompletionRoutine. Quando o driver solicita uma transferência de DMA do sistema, o driver pode fornecer um ponteiro para essa rotina com a solicitação. Após a conclusão da transferência de DMA, a rotina DmaCompletionRoutine é chamada automaticamente para notificar o driver.
A rotina de DmaCompletionRoutine de um driver é chamada somente se a transferência de DMA solicitada pelo driver usar um controlador DMA do sistema que pode gerar uma interrupção após a conclusão de uma transferência de DMA. Um driver que usa um dispositivo DMA mestre de barramento ou que usa um controlador DMA do sistema que não gera interrupções, deve usar outros meios para determinar quando uma transferência de DMA é concluída. Por exemplo, esse driver pode usar uma interrupção de temporizador para sondar periodicamente o status da transferência de DMA.
Um driver pode fornecer um ponteiro para uma rotina de DmaCompletionRoutine como um parâmetro opcional para a rotina de MapTransferEx.
Exemplos
Para definir uma rotina de retorno de chamada DmaCompletionRoutine, primeiro você deve fornecer uma declaração de função que identifique o tipo de rotina de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a análise de código para drivers, SDV (Verificador de Driver Estático) e outras ferramentas de verificação encontram erros e é um requisito para gravar drivers para o sistema operacional Windows.
Por exemplo, para definir uma rotina de retorno de chamada DmaCompletionRoutine denominada MyDmaCompletionRoutine, use o tipo DMA_COMPLETION_ROUTINE conforme mostrado neste exemplo de código:
DMA_COMPLETION_ROUTINE MyDmaCompletionRoutine;
Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:
_Use_decl_annotations_
VOID
MyDmaCompletionRoutine(
PDMA_ADAPTER DmaAdapter,
PDEVICE_OBJECT DeviceObject,
PVOID CompletionContext,
DMA_COMPLETION_STATUS Status
)
{
// Function body
}
O tipo de função DMA_COMPLETION_ROUTINE é definido no arquivo de cabeçalho Wdm.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação _Use_decl_annotations_ à sua definição de função. A anotação _Use_decl_annotations_ garante que as anotações aplicadas ao tipo de função DMA_COMPLETION_ROUTINE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers WDM. Para obter informações sobre _Use_decl_annotations_, consulte Anotando o comportamento da função.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível a partir do Windows 8. |
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Chamado no DISPATCH_LEVEL. |