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

Artigo
08/07/2023

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 custom-transmit-transaction. 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 a solicitação IRP_MJ_WRITE 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 para a solicitação de gravação 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 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 Offset e Length . 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 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-transmit-transaction. Se implementado, o driver registra 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, SerCx2 chamará a função de retorno de chamada de evento EvtSerCx2CustomTransmitTransactionCleanup , se o driver implementar essa função.

Se o driver do controlador serial implementar uma função de retorno de chamada de evento EvtSerCx2CustomTransmitTransactionInitialize , SerCx2 chamará essa função antes de chamar a função EvtSerCx2CustomTransmitTransactionStart . Pouco antes da chamada EvtSerCx2CustomTransmitTransactionStart e após o retorno da chamada EvtSerCx2CustomTransmitTransactionInitialize , 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 total de tempos limite 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 nenhuma 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 master barramento, a função EvtSerCx2CustomTransmitTransactionStart poderá chamar um método como WdfDmaTransactionInitializeUsingOffset para iniciar uma transação DMA que usa o buffer de gravação descrito pelos parâmetros Mdl, Offset e Length.

Para obter mais informações sobre os parâmetros Mdl, Offset e 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 diferentes de zero.

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

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 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 EvtSerCx2CustomTransmitTransactionStart chamada 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 a 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 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.