функция обратного вызова EVT_SERCX_APPLY_CONFIG (sercx.h)

Статья
08/07/2023

Функция обратного вызова события EvtSerCxApplyConfig указывает драйверу последовательного контроллера применить список параметров конфигурации к оборудованию последовательного контроллера.

Синтаксис

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

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

Параметры

[in] Device

Дескриптор WDFDEVICE для объекта устройства платформы, представляющего последовательный контроллер.

[in] ConnectionParameters

Указатель на структуру параметров подключения. Эта функция должна привести этот параметр к соответствующему типу указателя, проанализировать структуру данных для получения параметров конфигурации и применить эти параметры к оборудованию последовательного контроллера. Структура параметров подключения определяется поставщиком аппаратной платформы и непрозрачна как для расширения последовательной платформы (SerCx), так и для операционной системы.

Возвращаемое значение

Функция EvtSerCxApplyConfig возвращает STATUS_SUCCESS, если вызов выполнен успешно. В противном случае возвращается соответствующий код состояния ошибки.

SerCx вызывает эту функцию во время инициализации последовательного контроллера, чтобы убедиться, что оборудование находится в допустимом начальном состоянии. Кроме того, эта функция вызывается всякий раз, когда клиент отправляет контроллеру IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION управляющий запрос ввода-вывода.

SerCx получает эти параметры конфигурации из дескриптора ресурсов ACPI для устройства последовательного контроллера. Формат данных, который встроенное ПО ACPI использует для хранения этих параметров конфигурации, должен совпадать с форматом данных, ожидаемым драйвером последовательного контроллера.

Когда клиент отправляет запрос IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION на последовательный порт, управляемый SerCx, SerCx определяет, поддерживает ли драйвер последовательного контроллера для последовательного порта обратный вызов EvtSerCxApplyConfig и предоставляет ли дескриптор ресурса ACPI для последовательного порта параметры подключения по умолчанию. В противном случае SerCx завершает запрос с кодом состояния ошибки STATUS_NOT_SUPPORTED. В противном случае SerCx передает параметры подключения функции обратного вызова EvtSerCxApplyConfig драйвера. После возврата этого обратного вызова SerCx завершает запрос и использует возвращаемое значение обратного вызова в качестве кода состояния для запроса.

Если драйверу последовательного контроллера необходимо получить параметры подключения по умолчанию за время, отличное от времени обратного вызова EvtSerCxApplyConfig , драйвер может вызвать метод SerCxGetConnectionParameters .

Чтобы зарегистрировать функцию обратного вызова EvtSerCxApplyConfig , драйвер должен вызвать метод SerCxInitialize .

Примеры

Тип функции для этого обратного вызова объявлен в Sercx.h, как показано ниже.

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

Чтобы определить функцию обратного вызова EvtSerCxApplyConfig с именем MyEvtSerCxApplyConfig, необходимо сначала предоставить объявление функции, которое требуется для статического средства проверки драйверов (SDV) и других средств проверки, как показано ниже.

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

Затем реализуйте функцию обратного вызова, как показано ниже.

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

Дополнительные сведения о требованиях SDV для объявлений функций см. в статье Объявление функций с помощью типов ролей функций для драйверов KMDF.

В следующем примере кода показана частичная реализация функции EvtSerCxApplyConfig для 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;
}

Типы указателей PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER и PPNP_SERIAL_BUS_DESCRIPTOR в предыдущем примере кода определяются в файле заголовка Reshub.h.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.
Целевая платформа	Персональный компьютер
Верхняя часть	sercx.h
IRQL	Вызывается в IRQL <= DISPATCH_LEVEL

См. также раздел

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize

Поделиться через