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

Artigo
03/08/2023

A rotina de retorno de chamada DmaCompletionRoutine 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 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.

Retornar valor

Nenhum

Comentários

Como opção, um driver pode implementar uma rotina 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 DmaCompletionRoutine de um driver é chamada somente se a transferência de DMA solicitada pelo driver usar um controlador de 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 master 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 DmaCompletionRoutine como um parâmetro opcional para a rotina 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 a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada DmaCompletionRoutine chamada 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 _Use_decl_annotations_ anotação à sua definição de função. A _Use_decl_annotations_ anotação 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
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	Chamado em DISPATCH_LEVEL.