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

Статья
08/07/2023

Функция обратного вызова событий EvtSerCerCx2ApplyConfig вызывается версией 2 расширения последовательной платформы (SerCx2), чтобы предоставить драйвер последовательного контроллера со списком параметров конфигурации для конкретного устройства, применяемых к оборудованию последовательного контроллера.

Синтаксис

EVT_SERCX2_APPLY_CONFIG EvtSercx2ApplyConfig;

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

Параметры

[in] Device

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

[in] ConnectionParameters

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

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

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

Замечания

Драйвер последовательного контроллера должен реализовать эту функцию. Драйвер регистрирует функцию в вызове метода SerCx2InitializeDevice, который завершает инициализацию объекта устройства платформы для последовательного контроллера.

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

SerCx2 получает параметры конфигурации из поля данных, определенного поставщиком, в дескрипторе ресурса ACPI для устройства последовательного контроллера. Формат данных, который встроенное ПО ACPI использует для хранения этих параметров конфигурации, должен быть одинаковым форматом данных, ожидаемым драйвером последовательного контроллера. Дополнительные сведения см. в описании дескриптора подключения последовательной шины UART в спецификации ACPI 5.0.

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

Примеры

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

Например, чтобы определить функцию обратного вызова EvtSerCx2ApplyConfig с именем MyApplyConfig, используйте тип функции EVT_SERCX2_APPLY_CONFIG, как показано в следующем примере кода:

EVT_SERCX2_APPLY_CONFIG  MyApplyConfig;

Затем реализуйте функцию обратного вызова следующим образом:

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

Тип функции EVT_SERCX2_APPLY_CONFIG определен в файле заголовка Sercx.h. Чтобы более точно определить ошибки при запуске средств анализа кода, обязательно добавьте в определение функции заметку Use_decl_annotations. Заметка Use_decl_annotations гарантирует, что используются заметки, применяемые к типу функции EVT_SERCX2_APPLY_CONFIG в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в объявлении функций с помощью типов ролей функций для драйверов KMDF. Дополнительные сведения о Use_decl_annotationsсм. в поведению функции.

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

Файлы заголовков pshpack1.h и poppack.h в предыдущем примере кода управляют режимом выравнивания структуры, используемым компилятором. Типы указателей PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER и PPNP_SERIAL_BUS_DESCRIPTOR — это указатели на RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER и структуры PNP_SERIAL_BUS_DESCRIPTOR. Дополнительные сведения о членах структуры PNP_UART_SERIAL_BUS_DESCRIPTOR см. в таблице 6-193 в спецификации ACPI 5.0.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 8.1.
целевая платформа	Настольный
заголовка	sercx.h
IRQL	Звонил в PASSIVE_LEVEL.

См. также

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

PNP_SERIAL_BUS_DESCRIPTOR

RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER

SerCx2InitializeDevice

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