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

Artigo
10/30/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 da solicitação de leitura do cliente, use os parâmetros Mdl, Offsete 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 Deslocamento 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–Deslocamento.

Valor de retorno

Nenhum

Observações

O driver do controlador serial deve implementar essa função se ele criar um objeto de transação de recebimento personalizado. 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, o SerCx2 chama periodicamente o EvtSerCx2CustomReceiveTransactionQueryProgress função de retorno de chamada de evento 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, o SerCx2 chamará o EvtSerCx2CustomReceiveTransactionCleanup função de retorno de chamada de evento, se o driver implementar essa função.

Se o driver do controlador serial implementar uma função de retorno de chamada de evento EvtSerCx2CustomReceiveTransactionInitialize função de retorno de chamada de evento, o SerCx2 chamará essa função antes de chamar a função EvtSerCx2CustomReceiveTransactionStart. Pouco antes da chamada EvtSerCx2CustomReceiveTransactionStart, e após a chamada EvtSerCx2CustomReceiveTransactionInitialize retorna, o 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 tempo limite total em SERIAL_TIMEOUTS.

Se o mecanismo de transferência de dados personalizado for um dispositivo DMA mestre de barramento, a função EvtSerCx2CustomReceiveTransactionStart pode chamar um método como WdfDmaTransactionIniti O de iniciar uma transação de DMA que usa o buffer de leitura descrito pelos parâmetros Mdl, Offsete 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 não zero.

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

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 encontram erros e é um requisito para gravar 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 sua 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 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
de cliente com suporte mínimo	Disponível a partir do Windows 8.1.
da Plataforma de Destino	Área de trabalho
cabeçalho	sercx.h
IRQL	Chamado no <DO IRQL = DISPATCH_LEVEL.