EVT_SERCX2_APPLY_CONFIG回调函数 (sercx.h)

项目
08/07/2023

串行框架扩展版本 2 (SerCx2) 调用 EvtSerCx2ApplyConfig 事件回调函数，为串行控制器驱动程序提供适用于串行控制器硬件的设备特定配置设置列表。

语法

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 固件用于存储这些配置设置的数据格式应与串行控制器驱动程序预期的数据格式相同。有关详细信息，请参阅 ACPI 5.0 规范中 UART 串行总线连接描述符的说明。

当客户端将 IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 请求发送到由 SerCx2 管理的串行端口时，SerCx2 调用 EvtSerCx2ApplyConfig 函数，以将配置参数传递给串行控制器驱动程序。在此回调返回后，SerCx2 将完成请求，并使用回调中的返回值作为请求的状态代码。

示例

若要定义 EvtSerCx2ApplyConfig 回调函数，必须首先提供一个函数声明，用于标识要定义的回调函数的类型。 Windows 为驱动程序提供了一组回调函数类型。使用回调函数类型声明函数可帮助驱动程序的代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，这是为 Windows 操作系统编写驱动程序的要求。

例如，若要定义名为 MyApplyConfig的 EvtSerCx2ApplyConfig 回调函数，请使用 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的详细信息，请参阅批注函数行为。

下面的代码示例演示了针对 UART 的 EvtSerCx2ApplyConfig 函数的部分实现：

//
// 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 结构的成员的详细信息，请参阅 ACPI 5.0 规范中的表 6-193。