SerCx2InitializeDevice 函数 (sercx.h)

项目
02/27/2024

SerCx2InitializeDevice 方法完成串行控制器的框架设备对象的初始化。

语法

NTSTATUS SerCx2InitializeDevice(
  [in] WDFDEVICE      Device,
  [in] PSERCX2_CONFIG Config
);

参数

[in] Device

表示串行控制器的框架设备对象的 WDFDEVICE 句柄。有关详细信息，请参阅“备注”。

[in] Config

指向调用方分配的SERCX2_CONFIG 结构的指针，该结构包含指向串行控制器驱动程序实现的一组事件回调函数的指针。 (SerCx2 的串行框架控制器版本 2) 调用这些函数来配置串行控制器，并执行独立于驱动程序支持的 I/O 事务类型 (PIO、系统 DMA 或自定义) 的基本操作。

返回值

如果调用成功，则 SerCx2InitializeDevice 返回STATUS_SUCCESS。可能的错误返回值包括以下状态代码。

返回代码	说明
STATUS_INVALID_DEVICE_REQUEST	方法是在错误的 IRQL 下调用的，或者 Device 参数不是有效的 WDFDEVICE 句柄。
STATUS_INFO_LENGTH_MISMATCH	“配置大小”->值不等于 (SERCX2_CONFIG) 的大小。
STATUS_INVALID_PARAMETER	RequestAttributes 成员无效，或者函数指针列表中缺少所需的回调函数。有关详细信息，请参阅“备注”。
STATUS_INSUFFICIENT_RESOURCES	资源不足，无法执行请求的操作。

注解

在调用此方法之前，串行控制器驱动程序必须先调用 SerCx2InitializeDeviceInit 方法。

串行控制器驱动程序必须在为串行控制器创建框架设备对象后，从其 EvtDriverDeviceAdd 回调函数调用此方法。驱动程序通常调用 WdfDeviceCreate 等方法来创建框架设备对象并获取此对象的 WDFDEVICE 句柄。

SerCx2 需要 SERCX2_CONFIG 结构中的三个函数指针。驱动程序必须实现 EvtSerCx2PurgeFifos、 EvtSerCx2Control 和 EvtSerCx2ApplyConfig 回调函数。否则， SerCx2InitializeDevice 调用将失败并返回STATUS_INVALID_PARAMETER。

如果 SERCX2_CONFIG 结构的 RequestAttributes 成员设置为 WDF_NO_OBJECT_ATTRIBUTES 以外的值，则驱动程序不得覆盖由 WDF_OBJECT_ATTRIBUTES_INIT 函数写入到此结构的 ParentObject、ExecutionLevel 和 SynchronizationScope 成员的值。否则， SerCx2InitializeDevice 调用将失败并返回STATUS_INVALID_PARAMETER。

如果驱动程序调用 WdfDeviceInitSetRequestAttributes 方法来设置要用于请求对象的属性，则在此调用中指定的请求属性必须与驱动程序在 调用 SerCx2InitializeDevice 中指定的请求属性匹配。有关详细信息，请参阅 SerCx2 Custom-Receive 事务和 SerCx2 Custom-Transmit 事务。