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

Artigo
08/07/2023

A função de retorno de chamada de evento EvtSerCx2PioReceiveReadBuffer é chamada pela versão 2 da extensão da estrutura serial (SerCx2) para usar a E/S (E/S) programada para transferir dados do FIFO de recebimento no controlador serial para um buffer de leitura.

Sintaxe

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER EvtSercx2PioReceiveReadBuffer;

ULONG EvtSercx2PioReceiveReadBuffer(
  [in]  SERCX2PIORECEIVE PioReceive,
  [out] PUCHAR Buffer,
  [in]  ULONG Length
)
{...}

Parâmetros

[in] PioReceive

Um identificador SERCX2PIORECEIVE para um objeto de recebimento de PIO. O driver do controlador serial anteriormente chamou o método SerCx2PioReceiveCreate para criar esse objeto.

[out] Buffer

Um ponteiro para o buffer de leitura. 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 leitura que estão disponíveis para armazenar dados recebidos.

Retornar valor

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

Comentários

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

SerCx2 pode chamar a função EvtSerCx2PioReceiveReadBuffer mais de uma vez durante uma transação de recebimento de PIO. Uma única chamada EvtSerCx2PioReceiveReadBuffer será suficiente se essa chamada puder preencher o buffer de leitura com dados do FIFO de recebimento. Caso contrário, o SerCx2 continuará a chamar essa função, à medida que mais dados ficam disponíveis no FIFO de recebimento, até que o buffer de leitura seja preenchido.

A função EvtSerCx2PioReceiveReadBuffer usa PIO para transferir o máximo de bytes possível do FIFO de recebimento para o buffer de leitura. A função continua a transferir dados do FIFO enquanto o buffer passado para essa função não estiver cheio e a linha status registro (LSR) indicar que mais dados estão disponíveis no FIFO. Se o LSR indicar que o FIFO está vazio, a função retornará sem preencher o buffer. Caso contrário, a função preencherá o 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 para o buffer de leitura do FIFO de recebimento.

Normalmente, a função EvtSerCx2PioReceiveReadBuffer não habilita interrupções. Em vez disso, se o FIFO de recebimento ficar sem dados antes que a função possa preencher o buffer de leitura, SerCx2 chamará a função de retorno de chamada de evento EvtSerCx2PioReceiveEnableReadyNotification para habilitar uma notificação pronta, e essa função habilitará uma interrupção que ocorre quando mais dados estão disponíveis no FIFO de recebimento.

Para cada chamada sucessiva para a função EvtSerCx2PioReceiveReadBuffer , o SerCx2 ajusta Buffer para apontar para a próxima região de buffer a ser preenchida e define Length como o número de bytes de espaço não preenchido que permanecem no buffer.

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

Se o driver implementar uma função EvtSerCx2PioReceiveInitializeTransaction , SerCx2 chamará essa função no início de uma transação pio-transmit, antes da primeira chamada para a função EvtSerCx2PioReceiveReadBuffer . Se o driver implementar uma função EvtSerCx2PioReceiveCleanupTransaction , SerCx2 chamará essa função no final de uma transação pio-receive, após a chamada final para a função EvtSerCx2PioReceiveReadBuffer .

Além de chamar a função EvtSerCx2PioReceiveReadBuffer durante transações de recebimento de PIO, o SerCx2 chama essa função para salvar o estado do FIFO de recebimento pouco antes do controlador serial sair do estado de energia do dispositivo D0. Para obter mais informações, consulte SerCx2SaveReceiveFifoOnD0Exit.

Para obter mais informações sobre transações de recebimento de PIO, consulte SerCx2 PIO-Receive Transactions.

Exemplos

Para definir uma função de retorno de chamada EvtSerCx2PioReceiveReadBuffer , 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 EvtSerCx2PioReceiveReadBuffer chamada MyPioReceiveReadBuffer, use o tipo de função EVT_SERCX2_PIO_RECEIVE_READ_BUFFER , conforme mostrado neste exemplo de código:

EVT_SERCX2_PIO_RECEIVE_READ_BUFFER  MyPioReceiveReadBuffer;

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

_Use_decl_annotations_
ULONG
  MyPioReceiveReadBuffer(
    SERCX2PIORECEIVE  PioReceive,
    PUCHAR  Buffer,
    ULONG  Length

    )
  {...}

O tipo de função EVT_SERCX2_PIO_RECEIVE_READ_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_RECEIVE_READ_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 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.