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

Artigo
08/07/2023

A função de retorno de chamada de evento EvtSerCx2SelectNextTransmitTransactionType é chamada pela versão 2 da extensão de estrutura serial (SerCx2) para determinar qual mecanismo de transferência de dados usar para a próxima operação de gravação.

Sintaxe

EVT_SERCX2_SELECT_NEXT_TRANSMIT_TRANSACTION_TYPE EvtSercx2SelectNextTransmitTransactionType;

SERCX2_TRANSACTION_TYPE EvtSercx2SelectNextTransmitTransactionType(
  [in]  WDFDEVICE Device,
  [in]  PMDL Mdl,
  [in]  ULONG Offset,
  [in]  ULONG RemainingLength,
  [out] SERCX2CUSTOMTRANSMIT *CustomTransmit,
  [out] PULONG NextTransactionLength
)
{...}

Parâmetros

[in] Device

Um identificador WDFDEVICE para o objeto de dispositivo de estrutura que representa o controlador serial. O driver do controlador serial criou esse objeto em sua função de retorno de chamada EvtDriverDeviceAdd . Para obter mais informações, consulte SerCx2InitializeDevice.

[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 próxima transação de transmissão. 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 .

[in] Offset

O deslocamento inicial para a próxima transferência de dados. Esse parâmetro é um deslocamento de bytes desde o início da região de 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] RemainingLength

O número total de bytes de dados que permanecem a ser transferidos na solicitação de gravação atual (IRP_MJ_WRITE). 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.

[out] CustomTransmit

Um ponteiro para um local no qual a função grava o identificador SERCX2CUSTOMTRANSMIT no objeto de transmissão personalizada. Se a função retornar SerCx2TransactionTypeCustom, a função deverá fornecer o identificador de objeto que o driver do controlador serial criou em uma chamada anterior para o método SerCx2CustomTransmitCreate . Se o valor retornado não for SerCx2TransactionTypeCustom, esse valor de saída será ignorado por SerCx2.

[out] NextTransactionLength

Um ponteiro para um local no qual a função grava o número de bytes a serem transferidos na próxima transação de transmissão. Se o valor retornado for SerCx2TransactionTypeDefault, esse valor de saída será ignorado por SerCx2.

Retornar valor

A função EvtSerCx2SelectNextTransmitTransactionType retorna uma constante de enumeração SERCX2_TRANSACTION_TYPE para indicar se deve usar um tipo de transação selecionado pelo driver (E/S programado (PIO), DMA do sistema ou transferência de dados personalizada) ou para permitir que o SerCx2 escolha qual tipo de transação usar para a próxima transação de transmissão.

Comentários

O driver do controlador serial pode, como opção, implementar essa função. Se implementado, o driver registra essa função na chamada para o método SerCx2InitializeDevice que conclui a inicialização do objeto de dispositivo de estrutura para o controlador serial.

Se o driver do controlador serial não implementar uma função EvtSerCx2SelectNextTransmitTransactionType , o SerCx2 sempre decidirá qual tipo de mecanismo de transferência de dados (PIO, DMA do sistema ou personalizado) usar para a próxima transação de transmissão. O SerCx2 baseia suas decisões nas informações de configuração de E/S fornecidas pelo driver do controlador serial. Um driver que dá suporte a transações de transmissão de DMA do sistema fornece uma estrutura SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG que contém essas informações. Um driver que dá suporte a transações de transmissão personalizada fornece uma estrutura SERCX2_CUSTOM_TRANSMIT_CONFIG que contém essas informações.

Se o driver do controlador serial implementar uma função EvtSerCx2SelectNextTransmitTransactionType , o SerCx2 chamará essa função para determinar que tipo de mecanismo de transferência de dados (PIO, DMA do sistema ou personalizado) usar para a próxima transação de transmissão. Talvez você queira implementar essa função se o controlador serial tiver recursos de hardware especiais que não podem ser descritos adequadamente pelas informações de configuração de E/S nas estruturas SERCX2_XXX_TRANSMIT_CONFIG .

Nota Mesmo que um driver de controlador serial implemente uma função EvtSerCx2SelectNextTransmitTransactionType , o SerCx2 usa transações de transmissão de PIO para executar determinados tipos de transferências de dados sem chamar essa função primeiro.

Para obter mais informações, consulte Visão geral das transações de E/S do SerCx2.

Exemplos

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

EVT_SERCX2_CUSTOM_TRANSMIT_SELECT_NEXT_TRANSACTION_TYPE  MyCustomTransmitTransactionStart;

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

_Use_decl_annotations_
SERCX2_TRANSACTION_TYPE
  EvtSerCx2SelectNextTransmitTransactionType(
    WDFDEVICE  Device,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  RemainingLength,
    SERCX2CUSTOMTRANSMIT  *CustomTransmit,
    PULONG  NextTransactionLength
    )
  {...}

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