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

Artigo
12/15/2024

A função de retorno de chamada de evento EvtSerCxApplyConfig instrui o driver do controlador serial a aplicar uma lista de configurações ao hardware do controlador serial.

Sintaxe

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

NTSTATUS EvtSercxApplyConfig(
  [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.

[in] ConnectionParameters

Um ponteiro para a estrutura de parâmetros de conexão. Essa função deve converter esse parâmetro 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 a extensão da estrutura serial (SerCx) quanto para o sistema operacional.

Valor de retorno

A função EvtSerCxApplyConfig 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 SerCx chama essa função 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 de controle de E/S IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION ao controlador.

O SerCx obtém esses parâmetros de configuração do 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.

Quando um cliente envia uma solicitação IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION para uma porta serial gerenciada pelo SerCx, o SerCx determina se o driver do controlador serial para a porta serial dá suporte ao retorno de chamada EvtSerCxApplyConfig e se o descritor de recursos acpi para a porta serial fornece configurações de conexão padrão. Caso contrário, o SerCx concluirá a solicitação com o código de status de erro STATUS_NOT_SUPPORTED. Caso contrário, o SerCx passa os parâmetros de conexão para a função de retorno de chamada EvtSerCxApplyConfig do driver. Depois que esse retorno de chamada é retornado, o SerCx conclui a solicitação e usa o valor retornado do retorno de chamada como o código de status da solicitação.

Se um driver de controlador serial precisar obter os parâmetros de conexão padrão em um momento diferente de durante um EvtSerCxApplyConfig retorno de chamada, o driver poderá chamar o método SerCxGetConnectionParameters .

Para registrar uma função de retorno de chamada EvtSerCxApplyConfig, o driver deve chamar o método SerCxInitialize.

Exemplos

O tipo de função para esse retorno de chamada é declarado em Sercx.h, da seguinte maneira.

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

Para definir uma função de retorno de chamada EvtSerCxApplyConfig denominada MyEvtSerCxApplyConfig, primeiro você deve fornecer uma declaração de função que SDV (Static Driver Verifier) e outras ferramentas de verificação exigem, da seguinte maneira.

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

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

NTSTATUS
  MyEvtSerCxApplyConfig(
    __in WDFDEVICE Device
    )
{ ... }

Para obter mais informações sobre os requisitos de SDV para declarações de função, consulte Declarando funções usando tipos de função para drivers KMDF.

O exemplo de código a seguir mostra uma implementação parcial de uma função EvtSerCxApplyConfig 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


//
// 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;

EVT_SERCX_APPLY_CONFIG UartEvtApplyConfig;

//
// Implementation of an EvtSerCxApplyConfig callback function
//
NTSTATUS
  UartEvtApplyConfig(
    __in WDFDEVICE Device,
    __in 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 configuration settings from
        // the UART descriptor.
        ...
    }

    return status;
}

Os tipos de ponteiro PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER e PPNP_SERIAL_BUS_DESCRIPTOR no exemplo de código anterior são definidos no arquivo de cabeçalho Reshub.h.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível a partir do Windows 8.
da Plataforma de Destino	Área de trabalho
cabeçalho	sercx.h
IRQL	Chamado no <DO IRQL = DISPATCH_LEVEL

Consulte também

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize

Compartilhar via