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

Artigo
03/05/2024

A função de retorno de chamada de evento EvtSerCx2CustomReceiveTransactionStart é chamada pela versão 2 da extensão da estrutura serial (SerCx2) para iniciar uma transação de recebimento personalizado.

Sintaxe

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START EvtSercx2CustomReceiveTransactionStart;

void EvtSercx2CustomReceiveTransactionStart(
  [in] SERCX2CUSTOMRECEIVETRANSACTION CustomReceiveTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Parâmetros

[in] CustomReceiveTransaction

Um identificador SERCX2CUSTOMRECEIVETRANSACTION para um objeto custom-receive-transaction. O driver do controlador serial anteriormente chamou o método SerCx2CustomReceiveTransactionCreate para criar esse objeto.

[in] Request

Um identificador para o objeto de solicitação de estrutura associado à transação de recebimento personalizado. O driver é responsável por concluir essa solicitação. Essa solicitação pode não ser a solicitação IRP_MJ_READ enviada pelo cliente e, portanto, o driver do controlador serial não deve tentar usar essa solicitação para acessar o buffer de leitura. Essa solicitação é usada principalmente para cancelamento, conclusão e encaminhamento de fila (se necessário). Para acessar o buffer de leitura para a solicitação de leitura do cliente, use os parâmetros Mdl, Offset e Length .

[in] Mdl

Um ponteiro para um MDL que descreve as páginas de memória que são estendidas pelo buffer de leitura para a transação de recebimento personalizado. A lista de dispersão/coleta para a transferência de dados usará a região dessa memória especificada pelos parâmetros Offset e Length .

[in] Offset

O deslocamento inicial para a transferência de dados. Esse parâmetro é um deslocamento de bytes do início da região do buffer descrita pelo MDL. Se o MDL especificar um total de N bytes de espaço em buffer, os valores possíveis de Offset estarão no intervalo de 0 a N–1.

[in] Length

O tamanho, em bytes, da transferência de dados. Se o MDL especificar um total de N bytes de espaço em buffer, os valores possíveis de Length estarão no intervalo de 1 a N–Offset.

Retornar valor

Nenhum

Comentários

O driver do controlador serial deverá implementar essa função se ele criar um objeto custom-receive-transaction. O driver registra a função na chamada SerCx2CustomReceiveTransactionCreate que cria esse objeto.

Depois que o SerCx2 chama a função EvtSerCx2CustomReceiveTransactionStart , o driver do controlador serial inicia a transação programando o mecanismo de transferência de dados personalizado para mover dados do FIFO de recebimento no hardware do controlador serial para o buffer na solicitação de leitura. A menos que a solicitação possa ser concluída imediatamente, antes que a função EvtSerCx2CustomReceiveTransactionStart retorne, o driver deve chamar um método como WdfRequestMarkCancelableEx para marcar a solicitação como cancelável.

Depois que a função EvtSerCx2CustomReceiveTransactionStart inicia a transação, SerCx2 chama periodicamente a função de retorno de chamada de evento EvtSerCx2CustomReceiveTransactionQueryProgress para monitorar o progresso feito pelo driver do controlador serial na execução dessa transação. Depois que a transação for concluída e o driver concluir a solicitação de leitura pendente, SerCx2 chamará a função de retorno de chamada de evento EvtSerCx2CustomReceiveTransactionCleanup se o driver implementar essa função.

Se o driver do controlador serial implementar uma função de retorno de chamada de evento EvtSerCx2CustomReceiveTransactionInitialize , SerCx2 chamará essa função antes de chamar a função EvtSerCx2CustomReceiveTransactionStart . Pouco antes da chamada EvtSerCx2CustomReceiveTransactionStart e após o retorno da chamada EvtSerCx2CustomReceiveTransactionInitialize , SerCx2 inicia o temporizador que detecta se a solicitação de leitura atinge o tempo limite. Para obter mais informações, consulte a discussão sobre o total de tempos limite em SERIAL_TIMEOUTS.

Se o mecanismo de transferência de dados personalizado for um dispositivo DMA master barramento, a função EvtSerCx2CustomReceiveTransactionStart poderá chamar um método como WdfDmaTransactionInitializeUsingOffset para iniciar uma transação DMA que usa o buffer de leitura descrito pelos parâmetros Mdl, Offset e Length.

Se o objeto de solicitação identificado pelo parâmetro Request contiver armazenamento para um contexto privado, esse armazenamento poderá não ser inicializado na primeira vez que o driver do controlador serial acessar o contexto. No primeiro acesso, o driver normalmente deve preencher o contexto com zeros e, se necessário, definir explicitamente todos os campos no contexto que exijam valores iniciais diferentes de zero.

Para obter mais informações, consulte SerCx2 Custom-Receive Transactions.

Exemplos

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

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START  MyCustomReceiveTransactionStart;

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

_Use_decl_annotations_
VOID
  MyCustomReceiveTransactionStart(
    SERCX2CUSTOMRECEIVETRANSACTION  CustomReceiveTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

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