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

Artigo
08/07/2023

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

Sintaxe

EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType;

SERCX2_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType(
  [in]  WDFDEVICE Device,
  [in]  PMDL Mdl,
  [in]  ULONG Offset,
  [in]  ULONG RemainingLength,
  [out] SERCX2CUSTOMRECEIVE *CustomReceive,
  [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 leitura para a próxima transação de recebimento. 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 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] RemainingLength

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

Um ponteiro para um local no qual a função grava o identificador SERCX2CUSTOMRECEIVE no objeto de recebimento personalizado. 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 SerCx2CustomReceiveCreate . 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 recebimento. Se o valor retornado for SerCx2TransactionTypeDefault, esse valor de saída será ignorado por SerCx2.

Retornar valor

A função EvtSerCx2SelectNextReceiveTransactionType retorna uma constante de enumeração SERCX2_TRANSACTION_TYPE para indicar se um tipo de transação selecionado por driver (PIO (E/S programado), 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 recebimento.

Comentários

O driver do controlador serial pode, como uma 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 EvtSerCx2SelectNextReceiveTransactionType , o SerCx2 sempre decidirá que tipo de mecanismo de transferência de dados (PIO, DMA do sistema ou personalizado) usar para a próxima transação de recebimento. 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 system-DMA-receive fornece uma estrutura SERCX2_SYSTEM_DMA_RECEIVE_CONFIG que contém essas informações. Um driver que dá suporte a transações de recebimento personalizado fornece uma estrutura SERCX2_CUSTOM_RECEIVE_CONFIG que contém essas informações.

Se o driver do controlador serial implementar uma função EvtSerCx2SelectNextReceiveTransactionType , 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 recebimento. Talvez você queira implementar essa função se o controlador serial tiver recursos especiais de hardware que não podem ser descritos adequadamente pelas informações de configuração de E/S nas estruturas SERCX2_XXX_RECEIVE_CONFIG .

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

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 EvtSerCx2CustomReceiveSelectNextTransactionType , 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 EvtSerCx2CustomReceiveSelectNextTransactionType chamada MyCustomReceiveSelectNextTransactionType, use o tipo de função EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE , conforme mostrado neste exemplo de código:

EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE  MyCustomReceiveTransactionStart;

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

_Use_decl_annotations_
SERCX2_TRANSACTION_TYPE
  EvtSerCx2SelectNextReceiveTransactionType(
    WDFDEVICE  Device,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  RemainingLength,
    SERCX2CUSTOMRECEIVE  *CustomReceive,
    PULONG  NextTransactionLength
    )
  {...}

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