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

Artigo
10/30/2024

A função de retorno de chamada de evento EvtSerCx2ApplyConfig é chamada pela versão 2 da extensão da estrutura serial (SerCx2) para fornecer ao driver do controlador serial uma lista de configurações específicas do dispositivo a serem aplicadas ao hardware do controlador serial.

Sintaxe

EVT_SERCX2_APPLY_CONFIG EvtSercx2ApplyConfig;

NTSTATUS EvtSercx2ApplyConfig(
  [in] WDFDEVICE Device,
  [in] PVOID ConnectionParameters
)
{...}

Parâmetros

[in] Device

Um identificador WDFDEVICE para o objeto de dispositivo da 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] ConnectionParameters

Um ponteiro para a estrutura de parâmetros de conexão. Essa função deve converter o ponteiro para o tipo de ponteiro apropriado, analisar a estrutura de dados para obter as configurações e aplicar essas configurações ao hardware do controlador serial. A estrutura de parâmetros de conexão é definida pelo fornecedor da plataforma de hardware e é opaca tanto para o SerCx2 quanto para o sistema operacional. Para obter mais informações, consulte Comentários.

Valor de retorno

A função EvtSerCx2ApplyConfig retornará STATUS_SUCCESS se a chamada for bem-sucedida. Caso contrário, ele retornará um código de status de erro apropriado.

Observações

O driver do controlador serial deve implementar essa função. O driver registra a função na chamada para o método SerCx2InitializeDevice que conclui a inicialização do objeto de dispositivo da estrutura para o controlador serial.

O SerCx2 chama a função EvtSerCx2ApplyConfig durante a inicialização do controlador serial para garantir que o hardware esteja em um estado inicial válido. Além disso, essa função é chamada sempre que um cliente envia uma solicitação IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION para o controlador serial.

O SerCx2 obtém os parâmetros de configuração do campo de dados definido pelo fornecedor no descritor de recursos ACPI para o dispositivo do controlador serial. O formato de dados que o firmware ACPI usa para armazenar essas configurações deve ser o mesmo formato de dados esperado pelo driver do controlador serial. Para obter mais informações, consulte a descrição do de descritor de conexão de barramento serial UART na especificação ACPI 5.0.

Quando um cliente envia uma solicitação IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION para uma porta serial gerenciada pelo SerCx2, o SerCx2 chama a função EvtSerCx2ApplyConfig para passar os parâmetros de configuração para o driver do controlador serial. Depois que esse retorno de chamada é retornado, o SerCx2 conclui a solicitação e usa o valor retornado do retorno de chamada como o código de status da solicitação.

Exemplos

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

EVT_SERCX2_APPLY_CONFIG  MyApplyConfig;

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

_Use_decl_annotations_
NTSTATUS
  MyApplyConfig(
    WDFDEVICE  Device,
    PVOID  ConnectionParameters
    )
  {...}

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

O exemplo de código a seguir mostra uma implementação parcial de uma função EvtSerCx2ApplyConfig para um UART:

//
// Define the UART ACPI descriptor, plus any vendor-specific
// data that is needed by the serial controller (UART) driver.
//

#define ANYSIZE_ARRAY 1
#include <pshpack1.h>

//
// Common resource name descriptor
//
typedef struct _PNP_IO_DESCRIPTOR_RESOURCE_NAME {
    UCHAR ResourceIndex;
    UCHAR ResourceName[ANYSIZE_ARRAY];
} PNP_IO_DESCRIPTOR_RESOURCE_NAME, *PPNP_IO_DESCRIPTOR_RESOURCE_NAME;

//
// Bus descriptor for a UART
//
typedef struct _PNP_UART_SERIAL_BUS_DESCRIPTOR {
    PNP_SERIAL_BUS_DESCRIPTOR SerialBusDescriptor;
    ULONG BaudRate;
    USHORT RxBufferSize;
    USHORT TxBufferSize;
    UCHAR Parity;
    // Include any optional vendor data here:
    ...
    // Append the PNP_IO_DESCRIPTOR_RESOURCE_NAME here:
    ....
} PNP_UART_SERIAL_BUS_DESCRIPTOR, *PPNP_UART_SERIAL_BUS_DESCRIPTOR;

#include <poppack.h>

EVT_SERCX_APPLY_CONFIG MyApplyConfig;

//
// Implementation of an EvtSerCx2ApplyConfig callback function
//
_Use_decl_annotations_
VOID
  MyApplyConfig(
    WDFDEVICE Device,
    PVOID ConnectionParameters
    )
{
    NTSTATUS status = STATUS_SUCCESS; 
    PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER connection;
    PPNP_SERIAL_BUS_DESCRIPTOR descriptor;
    PPNP_UART_SERIAL_BUS_DESCRIPTOR uartDescriptor;

    if (ConnectionParameters == NULL)
    {
        status = STATUS_INVALID_PARAMETER; 
    }

    if (NT_SUCCESS(status))
    {
        connection = (PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER)ConnectionParameters;

        if (connection->PropertiesLength < sizeof(PNP_SERIAL_BUS_DESCRIPTOR))
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        descriptor = (PPNP_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties;

        if (descriptor->SerialBusType != UART_SERIAL_BUS_TYPE)
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        uartDescriptor = (PPNP_UART_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties; 

        // Apply the platform-specific configuration settings
        // from the UART descriptor here:
        ...
    }

    return status;
}

Os arquivos de cabeçalho pshpack1.h e poppack.h no exemplo de código anterior controlam o modo de alinhamento da estrutura usado pelo compilador. Os tipos de ponteiro PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER e PPNP_SERIAL_BUS_DESCRIPTOR são ponteiros para estruturas RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER e PNP_SERIAL_BUS_DESCRIPTOR. Para obter mais informações sobre os membros da estrutura de PNP_UART_SERIAL_BUS_DESCRIPTOR, consulte a Tabela 6-193 na especificação ACPI 5.0.

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 PASSIVE_LEVEL.

Consulte também

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

PNP_SERIAL_BUS_DESCRIPTOR

RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER

SerCx2InitializeDevice

Compartilhar via