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

Artigo
10/30/2024

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

Sintaxe

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START EvtSercx2CustomTransmitTransactionStart;

void EvtSercx2CustomTransmitTransactionStart(
  [in] SERCX2CUSTOMTRANSMITTRANSACTION CustomTransmitTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

Parâmetros

[in] CustomTransmitTransaction

Um identificador SERCX2CUSTOMTRANSMITTRANSACTION para um objeto de transação de transmissão personalizada. O driver do controlador serial anteriormente chamou o método SerCx2CustomTransmitTransactionCreate para criar esse objeto.

[in] Request

Um identificador para o objeto de solicitação de estrutura associado à transação de transmissão personalizada. O driver é responsável por concluir essa solicitação. Essa solicitação pode não ser o IRP_MJ_WRITE solicitação enviada pelo cliente e, portanto, o driver do controlador serial não deve tentar usar essa solicitação para acessar o buffer de gravação. Essa solicitação é usada principalmente para cancelamento, conclusão e encaminhamento de fila (se necessário). Para acessar o buffer de gravação da solicitação de gravação 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 gravação para a transação de transmissão personalizada. A lista de dispersão/coleta para a transferência de DMA usará a região dessa memória especificada pelos parâmetros de Deslocamento e Comprimento. Para obter mais informações sobre cadeias de MDL, consulte Usando MDLs.

[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 deverá implementar essa função se ele criar um objeto de transação de transmissão personalizada. Se implementado, o driver registrará a função na chamada SerCx2CustomTransmitTransactionCreate que cria esse objeto.

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

Depois que a transação for concluída e o driver concluir a solicitação de gravação pendente, o SerCx2 chamará o EvtSerCx2CustomTransmitTransactionCleanup 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 EvtSerCx2CustomTransmitTransactionInitialize função de retorno de chamada de evento, SerCx2 chamará essa função antes de chamar a função EvtSerCx2CustomTransmitTransactionStart. Pouco antes da chamada do EvtSerCx2CustomTransmitTransactionStart, e depois que o EvtSerCx2CustomTransmitTransactionInitialize chamada retorna, o SerCx2 inicia o temporizador que detecta se a solicitação de gravação atinge o tempo limite. Para obter mais informações, consulte a discussão sobre o tempo limite total em SERIAL_TIMEOUTS.

O driver do controlador serial deve concluir a solicitação de gravação pendente somente depois que o último byte no FIFO de transmissão tiver sido transmitido para o dispositivo periférico conectado serialmente. Não pode haver garantia de que os dados gravados no FIFO de transmissão serão transmitidos sem um atraso significativo e um driver de controlador serial que pressupõe que essa garantia exista pode causar problemas de confiabilidade para drivers periféricos.

Se o mecanismo de transferência de dados personalizado for um dispositivo DMA mestre de barramento, a função EvtSerCx2CustomTransmitTransactionStart pode chamar um método como WdfDmaTransactionIn O de inicialização de uma transação de DMA que usa o buffer de gravação descrito pelos parâmetros Mdl, Offsete Length.

Para obter mais informações sobre os parâmetros Mdl, Offsete Length, consulte Comentários em EvtSerCx2CustomTransmitTransactionInitialize.

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-Transmit SerCx2.

Exemplos

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

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START  MyCustomTransmitTransactionStart;

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

_Use_decl_annotations_
VOID
  MyCustomTransmitTransactionStart(
    SERCX2CUSTOMTRANSMITTRANSACTION  CustomTransmitTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

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