SerCx2CustomTransmitCreate 函数 (sercx.h)

项目
03/05/2024

SerCx2CustomTransmitCreate 方法创建一个自定义传输对象，该对象的串行框架扩展 (SerCx2) 使用该对象通过自定义数据传输机制将传输数据写入串行控制器。

语法

NTSTATUS SerCx2CustomTransmitCreate(
  [in]  WDFDEVICE                      Device,
  [in]  PSERCX2_CUSTOM_TRANSMIT_CONFIG CustomTransmitConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES         Attributes,
  [out] SERCX2CUSTOMTRANSMIT           *CustomTransmit
);

参数

[in] Device

表示串行控制器的框架设备对象的 WDFDEVICE 句柄。串行控制器驱动程序在其 EvtDriverDeviceAdd 回调函数中创建此对象。有关详细信息，请参阅 SerCx2InitializeDevice。

[in] CustomTransmitConfig

指向 SERCX2_CUSTOM_TRANSMIT_CONFIG 结构的指针。调用此方法之前，调用方必须调用 SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT 函数来初始化结构。此结构包含指向由串行控制器驱动程序实现的一组事件回调例程的指针。 SerCx2 调用这些函数来执行自定义传输事务。

[in] Attributes

指向 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构描述要分配给新的自定义传输对象的属性。调用此方法之前，调用方必须调用 WDF_OBJECT_ATTRIBUTES_INIT 函数来初始化结构。此参数是可选的，如果串行控制器驱动程序不需要将属性分配给对象，则可以指定为WDF_NO_OBJECT_ATTRIBUTES。有关详细信息，请参阅“备注”。

[out] CustomTransmit

指向此方法将 SERCX2CUSTOMTRANSMIT 句柄写入新创建的自定义传输对象的位置的指针。 SerCx2 和串行控制器驱动程序在后续调用中使用此句柄来引用此对象。

返回值

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

返回代码	说明
STATUS_INVALID_DEVICE_REQUEST	以前的 SerCx2CustomTransmitCreate 调用中已存在自定义传输对象;或来自以前的 SerCx2SystemDmaTransmitCreate 调用的 system-DMA-transmit 对象;或来自以前的 SerCx2SystemDmaTransmitCreate 调用的 system-DMA-transmit 对象;或尚未调用 SerCx2PioTransmitCreate 来创建 PIO 传输对象。
STATUS_INVALID_PARAMETER	参数值无效。
STATUS_INFO_LENGTH_MISMATCH	“配置大小”->值不等于 (SERCX2_CUSTOM_TRANSMIT_CONFIG) 的大小。
STATUS_INSUFFICIENT_RESOURCES	没有足够的资源可用于创建自定义传输对象。

注解

串行控制器驱动程序调用此方法以创建自定义传输对象。 SerCx2 使用此对象执行自定义传输事务，即使用自定义数据传输机制将传输数据写入串行控制器的事务。

在调用 SerCx2CustomTransmitCreate 之前，串行控制器驱动程序必须成功调用 SerCx2InitializeDevice 和 SerCx2PioTransmitCreate 方法。

在调用 SerCx2CustomTransmitCreate 之前，串行控制器驱动程序必须调用 SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT 函数来初始化 CustomTransmitConfig 指向的 SERCX2_CUSTOM_TRANSMIT_CONFIG 结构。此函数将结构的以下成员设置为零：

对齐方式
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit
独占

如有必要，串行控制器驱动程序可以在初始化函数返回后将这些成员中的任何一个设置为非零值。但是，为方便起见，如果这些成员为零， 则 SerCx2CustomTransmitCreate 使用以下默认值：

如果 Alignment 为零，SerCx2 会将数据对齐值设置为 1，这意味着写入缓冲区可以在内存中的任意字节边界上启动。
如果 MinimumTransactionLength 为零，则 SerCx2 将最小事务长度设置为一个字节。
如果 MaximumTransactionLength 为零，则 SerCx2 将最大事务长度设置为 ( (ULONG) -1) 。
如果 MinimumTransferUnit 为零，则 SerCx2 将最小传输单位设置为一个字节。
如果 Exclusive 为零 (FALSE) ，则禁用独占模式。

如果调用驱动程序将 Exclusive 设置为 TRUE，则 MinimumTransferUnit、 Alignment 和 MinimumTransactionLength 成员必须为零。有关详细信息，请参阅 SERCX2_CUSTOM_TRANSMIT_CONFIG。

作为选项，串行控制器驱动程序可以使用 Attributes 参数为自定义传输对象创建上下文，并提供指向 EvtCleanupCallback 和 EvtDestroyCallback 函数的指针，这些函数将调用这些函数来准备要删除的对象。有关详细信息，请参阅 WDF_OBJECT_ATTRIBUTES。

如果 Attributes 参数指向 WDF_OBJECT_ATTRIBUTES 结构，则调用方不得覆盖 WDF_OBJECT_ATTRIBUTES_INIT 初始化函数写入此结构的 ParentObject、 ExecutionLevel 和 SynchronizationScope 成员的值。

有关创建自定义传输对象的详细信息，请参阅 SERCX2CUSTOMTRANSMIT。有关自定义传输事务的详细信息，请参阅 SerCx2 Custom-Transmit 事务。