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

Artigo
08/07/2023

A função de retorno de chamada de evento EvtSerCx2PioTransmitWriteBuffer é chamada pela versão 2 da extensão da estrutura serial (SerCx2) para usar API (E/S) programada para transferir o conteúdo de um buffer de gravação para o FIFO de transmissão no controlador serial.

Sintaxe

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER EvtSercx2PioTransmitWriteBuffer;

ULONG EvtSercx2PioTransmitWriteBuffer(
  [in] SERCX2PIOTRANSMIT PioTransmit,
  [in] PUCHAR Buffer,
  [in] ULONG Length
)
{...}

Parâmetros

[in] PioTransmit

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

[in] Buffer

Um ponteiro para o buffer de gravação. Esse parâmetro é o endereço virtual de um buffer bloqueado na memória do sistema.

[in] Length

O número de bytes no buffer de gravação que estão disponíveis para serem transmitidos.

Retornar valor

A função EvtSerCx2PioTransmitWriteBuffer retorna o número de bytes de dados transferidos com êxito do buffer de gravação para o FIFO de transmissão no hardware do controlador serial.

Comentários

O driver do controlador serial deve implementar essa função. O driver registra a função na chamada SerCx2PioTransmitCreate que cria o objeto pio-transmit.

SerCx2 pode chamar a função EvtSerCx2PioTransmitWriteBuffer mais de uma vez durante uma transação de transmissão de PIO. Uma única chamada EvtSerCx2PioTransmitWriteBuffer será suficiente se essa chamada puder transferir o conteúdo completo do buffer de gravação para o FIFO de transmissão. Caso contrário, o SerCx2 continuará a chamar essa função, à medida que mais espaço se torna disponível no FIFO de transmissão, até que o buffer de gravação seja esvaziado.

Começando com o primeiro byte no buffer de gravação, a função EvtSerCx2PioTransmitWriteBuffer usa PIO para transferir o máximo de bytes possível do buffer para o FIFO de transmissão. A função continua a transferir dados do buffer enquanto o buffer não estiver vazio e a linha status registro (LSR) indicar que o FIFO pode aceitar mais dados. Se o LSR indicar que o FIFO não pode aceitar mais dados, a função retornará sem esvaziar o buffer. Caso contrário, a função transferirá todos os bytes no buffer e retornará. Em ambos os casos, o valor retornado por essa função é o número de bytes de dados que foram transferidos com êxito do buffer de gravação para o FIFO de transmissão.

Normalmente, a função EvtSerCx2PioTransmitWriteBuffer não habilita interrupções. Em vez disso, se a função não puder transferir todo o conteúdo do buffer de gravação para o FIFO de transmissão, SerCx2 chamará a função de retorno de chamada de evento EvtSerCx2PioTransmitEnableReadyNotification para habilitar uma notificação pronta e essa função habilitará uma interrupção que ocorre quando o FIFO de transmissão fica vazio.

Para cada chamada sucessiva para a função EvtSerCx2PioTransmitWriteBuffer , SerCx2 ajusta Buffer para apontar para os dados restantes no buffer e define Length como o número de bytes de dados que permanecem no buffer.

A notificação pronta nunca é habilitada quando SerCx2 chama a função EvtSerCx2PioTransmitEnableReadyNotification . No entanto, SerCx2 pode chamar essa função do mesmo thread do qual o driver chamou o método SerCx2PioTransmitReady .

Se o driver implementar uma função EvtSerCx2PioTransmitInitializeTransaction , SerCx2 chamará essa função no início de uma transação de transmissão de PIO, antes da primeira chamada para a função EvtSerCx2PioTransmitWriteBuffer . Se o driver implementar uma função EvtSerCx2PioTransmitCleanupTransaction , SerCx2 chamará essa função no final de uma transação de transmissão de PIO, após a última chamada EvtSerCx2PioTransmitWriteBuffer e depois de qualquer chamada para as funções EvtSerCx2PioTransmitDrainFifo, EvtSerCx2PioTransmitCancelDrainFifo e EvtSerCx2PioTransmitPurgeFifo , se forem implementadas.

Para obter mais informações sobre transações de transmissão de PIO, consulte SerCx2 PIO-Transmit Transactions.

Exemplos

Para definir uma função de retorno de chamada EvtSerCx2PioTransmitWriteBuffer , 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 escrever drivers para o sistema operacional Windows.

Por exemplo, para definir uma função de retorno de chamada EvtSerCx2PioTransmitWriteBuffer chamada MyPioTransmitWriteBuffer, use o tipo de função EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER , conforme mostrado neste exemplo de código:

EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER  MyPioTransmitWriteBuffer;

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

_Use_decl_annotations_
ULONG
  MyPioTransmitWriteBuffer(
    SERCX2PIOTRANSMIT  PioTransmit,
    PUCHAR Buffer,
    ULONG Length
    )
  {...}

O tipo de função EVT_SERCX2_PIO_TRANSMIT_WRITE_BUFFER é 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_WRITE_BUFFER 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 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.