EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO função de retorno de chamada (sercx.h)

Artigo
08/07/2023

A função de retorno de chamada de evento EvtSerCx2PioTransmitDrainFifo é chamada pela versão 2 da extensão da estrutura serial (SerCx2) para esvaziar o FIFO de transmissão no hardware do controlador serial.

Sintaxe

EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO EvtSercx2PioTransmitDrainFifo;

void EvtSercx2PioTransmitDrainFifo(
  [in] SERCX2PIOTRANSMIT PioTransmit
)
{...}

Parâmetros

[in] PioTransmit

Um identificador de SERCX2PIOTRANSMIT para um objeto de transmissão de PIO. O driver do controlador serial anteriormente chamou o método SerCx2PioTransmitCreate para criar esse objeto.

Retornar valor

Nenhum

Comentários

O driver do controlador serial pode, como opção, implementar essa função. Se o driver implementar essa função, ele também deverá implementar as funções de retorno de chamada de evento EvtSerCx2PioTransmitCancelDrainFifo e EvtSerCx2PioTransmitPurgeFifo . Um driver que implementa essas funções as registra na chamada SerCx2PioTransmitCreate que cria o objeto pio-transmit.

SerCx2 chama a função EvtSerCx2PioTransmitDrainFifo , se ela for implementada, para esvaziar o FIFO de transmissão no hardware do controlador serial no final de uma transação de transmissão de PIO. Essa função garante que todos os bytes de dados que permanecem no FIFO de transmissão sejam transmitidos para o dispositivo periférico conectado serialmente. Depois que o último byte é transmitido do FIFO, a função EvtSerCx2PioTransmitDrainFifo chama o método SerCx2PioTransmitDrainFifoComplete para notificar o SerCx2.

Se o driver do controlador serial implementar uma função EvtSerCx2PioTransmitDrainFifo , o SerCx2 não concluirá uma solicitação de gravação pendente (IRP_MJ_WRITE) até que o driver chame SerCx2PioTransmitDrainFifoComplete.

Se o controlador serial tiver um FIFO de hardware (ou um mecanismo de buffer semelhante) para armazenar dados de transmissão, o driver deverá implementar uma função EvtSerCx2PioTransmitDrainFifo . Caso contrário, o SerCx2 não poderá confirmar se o FIFO de transmissão foi esvaziado antes que a solicitação de gravação pendente seja concluída. Em vez disso, o SerCx2 conclui essa solicitação depois que o último byte no buffer de gravação é gravado no FIFO de transmissão. Não pode haver nenhuma garantia de que os dados gravados no FIFO de transmissão serão transmitidos sem um atraso significativo. Todos os dados que permanecem no FIFO após a conclusão da solicitação de gravação podem ser perdidos antes que possam ser transmitidos para o dispositivo periférico conectado serialmente. Essa perda inesperada de dados em uma solicitação de gravação concluída com êxito pode criar problemas de confiabilidade para o driver periférico.

Por exemplo, um driver periférico pode enviar solicitações de gravação para uma porta serial à qual um dispositivo periférico está conectado. Até que todas as solicitações de gravação pendentes sejam concluídas, esse driver deve atrasar o envio de um IOCTL para alterar a taxa de bugigangas na qual a porta serial transmite dados. No entanto, se nenhuma função EvtSerCx2PioTransmitDrainFifo for implementada, uma solicitação de gravação para transmitir 100 bytes de dados poderá ser concluída enquanto 50 bytes de dados ainda permanecerão no FIFO de transmissão. Se o driver periférico enviar um IOCTL para definir uma nova taxa de baud, alguns dos bytes restantes no FIFO poderão ser transmitidos na nova taxa de baud, causando um erro.

Da mesma forma, se uma solicitação de gravação para transmitir 100 bytes de dados for concluída enquanto 50 bytes de dados ainda permanecerem no FIFO de transmissão e o controlador serial sair D0 para entrar em um estado de dispositivo de baixa potência antes que os bytes restantes no FIFO possam ser transmitidos, o driver periférico não saberá que esses bytes foram perdidos.

Para obter mais informações, consulte SerCx2 PIO-Transmit Transactions.

Exemplos

Para definir uma função de retorno de chamada EvtSerCx2PioTransmitDrainFifo , primeiro você deve fornecer uma declaração de função que identifique o tipo de função 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 função de retorno de chamada EvtSerCx2PioTransmitDrainFifo chamada MyPioTransmitDrainFifo, use o tipo de função EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO , conforme mostrado neste exemplo de código:

EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO  MyPioTransmitDrainFifo;

Em seguida, implemente a função de retorno de chamada da seguinte maneira:

_Use_decl_annotations_
VOID
  MyPioTransmitDrainFifo(
    SERCX2PIOTRANSMIT  PioTransmit
    )
  {...}

O tipo de função EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO é definido no arquivo de cabeçalho Sercx.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 EVT_SERCX2_PIO_TRANSMIT_DRAIN_FIFO 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 KMDF. Para obter mais 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.1.
Plataforma de Destino	Área de Trabalho
Cabeçalho	sercx.h
IRQL	Chamado em IRQL <= DISPATCH_LEVEL.