通过

EVT_SERCX2_APPLY_CONFIG回调函数 （sercx.h）

  • 项目

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

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

例子

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

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

下面的代码示例演示 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。

要求

要求 价值
最低支持的客户端 从Windows 8.1开始可用。
目标平台 桌面
标头 sercx.h
IRQL 在PASSIVE_LEVEL调用。

另请参阅

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

PNP_SERIAL_BUS_DESCRIPTOR

RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER

SerCx2InitializeDevice